ctdb/common/run_proc.h

   1 /*
   2    Run a child process and collect the output
   3
   4    Copyright (C) Amitay Isaacs  2016
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 #ifndef __CTDB_RUN_PROC_H__
  21 #define __CTDB_RUN_PROC_H__
  22
  23 #include <talloc.h>
  24 #include <tevent.h>
  25
  26 /**
  27  * @file run_proc.h
  28  *
  29  * @brief Run a process and capture the output
  30  *
  31  * This abstraction allows one to execute scripts with argumunts.
  32  */
  33
  34 /**
  35  * @brief The run process context
  36  */
  37 struct run_proc_context;
  38
  39 /**
  40  * @brief The exit status structure
  41  *
  42  * If the process is terminated due to a signal, sig is set.
  43  * If the process is terminated due to an error, err is set.
  44  * If the process terminates normally, status is set.
  45  */
  46 struct run_proc_result {
  47         int sig;
  48         int err;
  49         int status;
  50 };
  51
  52 /**
  53  * @brief Initialize the context for running processes
  54  *
  55  * @param[in] mem_ctx Talloc memory context
  56  * @param[in] ev Tevent context
  57  * @param[out] result New run_proc context
  58  * @return 0 on success, errno on error
  59  */
  60 int run_proc_init(TALLOC_CTX *mem_ctx, struct tevent_context *ev,
  61                   struct run_proc_context **result);
  62
  63 /**
  64  * @brief Async computation start to run an executable
  65  *
  66  * @param[in] mem_ctx Talloc memory context
  67  * @param[in] ev Tevent context
  68  * @param[in] run_ctx Run_proc context
  69  * @param[in] prog The path to the executable
  70  * @param[in] argv Arguments to the executable
  71  * @param[in] stdin_fd Assign stdin_fd as stdin for the process, -1 if not
  72  * @param[in] timeout How long to wait for execution
  73  * @return new tevent request, or NULL on failure
  74  *
  75  * argv must include program name as argv[0] and must be null terminated.
  76  */
  77 struct tevent_req *run_proc_send(TALLOC_CTX *mem_ctx,
  78                                  struct tevent_context *ev,
  79                                  struct run_proc_context *run_ctx,
  80                                  const char *prog, const char **argv,
  81                                  int stdin_fd, struct timeval timeout);
  82
  83 /**
  84  * @brief Async computation end to run an executable
  85  *
  86  * @param[in] req Tevent request
  87  * @param[out] perr errno in case of failure
  88  * @param[out] result The exit status of the executable
  89  * @param[out] pid The pid of the child process (still running)
  90  * @param[in] mem_ctx Talloc memory context
  91  * @param[out] output The output from the executable (stdio + stderr)
  92  * @return true on success, false on failure
  93  *
  94  * The returned pid is -1 if the process has terminated.
  95  */
  96 bool run_proc_recv(struct tevent_req *req, int *perr,
  97                    struct run_proc_result *result, pid_t *pid,
  98                    TALLOC_CTX *mem_ctx, char **output);
  99
 100 #endif /* __CTDB_RUN_PROC_H__ */