We already have a precedent of function documentation in C files,
where it is closer to the implementation (witness libvirt.h vs.
libvirt.c); maintaining docs in both files risks docs going stale.
While I was at it, I used consistent doxygen style on all comments.
* src/util/command.h: Remove duplicate docs, and move unique
documentation...
* src/util/command.c: ...here.
Suggested by Matthias Bolte.
---
src/util/command.c | 371 ++++++++++++++++++++++++++++++++++++++++------------
src/util/command.h | 223 ++------------------------------
2 files changed, 299 insertions(+), 295 deletions(-)
diff --git a/src/util/command.c b/src/util/command.c
index e2ece78..f3c35ed 100644
--- a/src/util/command.c
+++ b/src/util/command.c
@@ -130,23 +130,25 @@ static int virClearCapabilities(void)
# endif
-/* virFork() - fork a new process while avoiding various race/deadlock
- conditions
-
- @pid - a pointer to a pid_t that will receive the return value from
- fork()
-
- on return from virFork(), if *pid < 0, the fork failed and there is
- no new process. Otherwise, just like fork(), if *pid == 0, it is the
- child process returning, and if *pid > 0, it is the parent.
-
- Even if *pid >= 0, if the return value from virFork() is < 0, it
- indicates a failure that occurred in the parent or child process
- after the fork. In this case, the child process should call
- _exit(EXIT_FAILURE) after doing any additional error reporting.
-
+/**
+ * virFork:
+ * @pid - a pointer to a pid_t that will receive the return value from
+ * fork()
+ *
+ * fork a new process while avoiding various race/deadlock conditions
+ *
+ * on return from virFork(), if *pid < 0, the fork failed and there is
+ * no new process. Otherwise, just like fork(), if *pid == 0, it is the
+ * child process returning, and if *pid > 0, it is the parent.
+ *
+ * Even if *pid >= 0, if the return value from virFork() is < 0, it
+ * indicates a failure that occurred in the parent or child process
+ * after the fork. In this case, the child process should call
+ * _exit(EXIT_FAILURE) after doing any additional error reporting.
*/
-int virFork(pid_t *pid) {
+int
+virFork(pid_t *pid)
+{
sigset_t oldmask, newmask;
struct sigaction sig_action;
int saved_errno, ret = -1;
@@ -573,6 +575,7 @@ virExecWithHook(const char *const*argv,
}
/**
+ * virRun:
* @argv NULL terminated argv to run
* @status optional variable to return exit status in
*
@@ -645,8 +648,13 @@ virFork(pid_t *pid)
#endif /* WIN32 */
-/*
- * Create a new command for named binary
+/**
+ * virCommandNew:
+ * @binary: program to run
+ *
+ * Create a new command for named binary. If @binary is relative,
+ * it will be found via a PATH search of the parent's PATH (and not
+ * any altered PATH set by virCommandAddEnv* commands).
*/
virCommandPtr
virCommandNew(const char *binary)
@@ -656,9 +664,13 @@ virCommandNew(const char *binary)
return virCommandNewArgs(args);
}
-/*
+/**
+ * virCommandNewArgs:
+ * @args: array of arguments
+ *
* Create a new command with a NULL terminated
- * set of args, taking binary from args[0]
+ * set of args, taking binary from args[0]. More arguments can
+ * be added later. @args[0] is handled like @binary of virCommandNew.
*/
virCommandPtr
virCommandNewArgs(const char *const*args)
@@ -684,9 +696,14 @@ virCommandNewArgs(const char *const*args)
return cmd;
}
-/*
+/**
+ * virCommandNewArgList:
+ * @binary: program to run
+ * @...: additional arguments
+ *
* Create a new command with a NULL terminated
- * list of args, starting with the binary to run
+ * list of args, starting with the binary to run. More arguments can
+ * be added later. @binary is handled as in virCommandNew.
*/
virCommandPtr
virCommandNewArgList(const char *binary, ...)
@@ -730,9 +747,13 @@ virCommandKeepFD(virCommandPtr cmd, int fd, bool transfer)
FD_SET(fd, &cmd->transfer);
}
-/*
+/**
+ * virCommandPreserveFD:
+ * @cmd: the command to modify
+ * @fd: fd to mark for inheritance into child
+ *
* Preserve the specified file descriptor
- * in the child, instead of closing it.
+ * in the child, instead of closing it on exec.
* The parent is still responsible for managing fd.
*/
void
@@ -741,9 +762,13 @@ virCommandPreserveFD(virCommandPtr cmd, int fd)
return virCommandKeepFD(cmd, fd, false);
}
-/*
+/**
+ * virCommandTransferFD:
+ * @cmd: the command to modify
+ * @fd: fd to reassign to the child
+ *
* Transfer the specified file descriptor
- * to the child, instead of closing it.
+ * to the child, instead of closing it on exec.
* Close the fd in the parent during Run/RunAsync/Free.
*/
void
@@ -753,8 +778,13 @@ virCommandTransferFD(virCommandPtr cmd, int fd)
}
-/*
- * Save the child PID in a pidfile
+/**
+ * virCommandSetPidFile:
+ * @cmd: the command to modify
+ * @pidfile: filename to use
+ *
+ * Save the child PID in a pidfile. The pidfile will be populated
+ * before the exec of the child.
*/
void
virCommandSetPidFile(virCommandPtr cmd, const char *pidfile)
@@ -769,8 +799,11 @@ virCommandSetPidFile(virCommandPtr cmd, const char *pidfile)
}
-/*
- * Remove all capabilities from the child
+/**
+ * virCommandClearCaps:
+ * @cmd: the command to modify
+ *
+ * Remove all capabilities from the child, after any hooks have been run.
*/
void
virCommandClearCaps(virCommandPtr cmd)
@@ -783,7 +816,11 @@ virCommandClearCaps(virCommandPtr cmd)
#if 0 /* XXX Enable if we have a need for capability management. */
-/*
+/**
+ * virCommandAllowCap:
+ * @cmd: the command to modify
+ * @capability: what to allow
+ *
* Re-allow a specific capability
*/
void
@@ -799,8 +836,13 @@ virCommandAllowCap(virCommandPtr cmd,
#endif /* 0 */
-/*
- * Daemonize the child process
+/**
+ * virCommandDaemonize:
+ * @cmd: the command to modify
+ *
+ * Daemonize the child process. The child will have a current working
+ * directory of /, and must be started with virCommandRun, which will
+ * complete as soon as the daemon grandchild has started.
*/
void
virCommandDaemonize(virCommandPtr cmd)
@@ -811,7 +853,10 @@ virCommandDaemonize(virCommandPtr cmd)
cmd->flags |= VIR_EXEC_DAEMON;
}
-/*
+/**
+ * virCommandNonblockingFDs:
+ * @cmd: the command to modify
+ *
* Set FDs created by virCommandSetOutputFD and virCommandSetErrorFD
* as non-blocking in the parent.
*/
@@ -824,8 +869,13 @@ virCommandNonblockingFDs(virCommandPtr cmd)
cmd->flags |= VIR_EXEC_NONBLOCK;
}
-/*
- * Add an environment variable to the child created by a printf-style format
+/**
+ * virCommandAddEnvFormat:
+ * @cmd: the command to modify
+ * @format: format of arguments, end result must be in name=value format
+ * @...: arguments to be formatted
+ *
+ * Add an environment variable to the child created by a printf-style format.
*/
void
virCommandAddEnvFormat(virCommandPtr cmd, const char *format, ...)
@@ -854,7 +904,12 @@ virCommandAddEnvFormat(virCommandPtr cmd, const char *format, ...)
cmd->env[cmd->nenv++] = env;
}
-/*
+/**
+ * virCommandAddEnvPair:
+ * @cmd: the command to modify
+ * @name: variable name, must not contain =
+ * @value: value to assign to name
+ *
* Add an environment variable to the child
* using separate name & value strings
*/
@@ -865,7 +920,11 @@ virCommandAddEnvPair(virCommandPtr cmd, const char *name, const char *value)
}
-/*
+/**
+ * virCommandAddEnvString:
+ * @cmd: the command to modify
+ * @str: name=value format
+ *
* Add an environment variable to the child
* using a preformatted env string FOO=BAR
*/
@@ -893,7 +952,11 @@ virCommandAddEnvString(virCommandPtr cmd, const char *str)
}
-/*
+/**
+ * virCommandAddEnvBuffer:
+ * @cmd: the command to modify
+ * @buf: buffer that contains name=value string, which will be reset on return
+ *
* Convert a buffer containing preformatted name=value into an
* environment variable of the child.
* Correctly transfers memory errors or contents from buf to cmd.
@@ -918,7 +981,11 @@ virCommandAddEnvBuffer(virCommandPtr cmd, virBufferPtr buf)
}
-/*
+/**
+ * virCommandAddEnvPass:
+ * @cmd: the command to modify
+ * @name: the name to look up in current environment
+ *
* Pass an environment variable to the child
* using current process' value
*/
@@ -935,9 +1002,12 @@ virCommandAddEnvPass(virCommandPtr cmd, const char *name)
}
-/*
+/**
+ * virCommandAddEnvPassCommon:
+ * @cmd: the command to modify
+ *
* Set LC_ALL to C, and propagate other essential environment
- * variables from the parent process.
+ * variables (such as PATH) from the parent process.
*/
void
virCommandAddEnvPassCommon(virCommandPtr cmd)
@@ -960,7 +1030,11 @@ virCommandAddEnvPassCommon(virCommandPtr cmd)
virCommandAddEnvPass(cmd, "TMPDIR");
}
-/*
+/**
+ * virCommandAddArg:
+ * @cmd: the command to modify
+ * @val: the argument to add
+ *
* Add a command line argument to the child
*/
void
@@ -987,7 +1061,11 @@ virCommandAddArg(virCommandPtr cmd, const char *val)
}
-/*
+/**
+ * virCommandAddArgBuffer:
+ * @cmd: the command to modify
+ * @buf: buffer that contains argument string, which will be reset on return
+ *
* Convert a buffer into a command line argument to the child.
* Correctly transfers memory errors or contents from buf to cmd.
*/
@@ -1011,8 +1089,13 @@ virCommandAddArgBuffer(virCommandPtr cmd, virBufferPtr buf)
}
-/*
- * Add a command line argument created by a printf-style format
+/**
+ * virCommandAddArgFormat:
+ * @cmd: the command to modify
+ * @format: format of arguments, end result must be in name=value format
+ * @...: arguments to be formatted
+ *
+ * Add a command line argument created by a printf-style format.
*/
void
virCommandAddArgFormat(virCommandPtr cmd, const char *format, ...)
@@ -1041,7 +1124,12 @@ virCommandAddArgFormat(virCommandPtr cmd, const char *format, ...)
cmd->args[cmd->nargs++] = arg;
}
-/*
+/**
+ * virCommandAddArgPair:
+ * @cmd: the command to modify
+ * @name: left half of argument
+ * @value: right half of argument
+ *
* Add "NAME=VAL" as a single command line argument to the child
*/
void
@@ -1050,7 +1138,11 @@ virCommandAddArgPair(virCommandPtr cmd, const char *name, const char *val)
virCommandAddArgFormat(cmd, "%s=%s", name, val);
}
-/*
+/**
+ * virCommandAddArgSet:
+ * @cmd: the command to modify
+ * @vals: array of arguments to add
+ *
* Add a NULL terminated list of args
*/
void
@@ -1086,8 +1178,12 @@ virCommandAddArgSet(virCommandPtr cmd, const char *const*vals)
}
}
-/*
- * Add a NULL terminated list of args
+/**
+ * virCommandAddArgList:
+ * @cmd: the command to modify
+ * @...: list of arguments to add
+ *
+ * Add a NULL terminated list of args.
*/
void
virCommandAddArgList(virCommandPtr cmd, ...)
@@ -1125,7 +1221,11 @@ virCommandAddArgList(virCommandPtr cmd, ...)
va_end(list);
}
-/*
+/**
+ * virCommandSetWorkingDirectory:
+ * @cmd: the command to modify
+ * @pwd: directory to use
+ *
* Set the working directory of a non-daemon child process, rather
* than the parent's working directory. Daemons automatically get /
* without using this call.
@@ -1147,8 +1247,13 @@ virCommandSetWorkingDirectory(virCommandPtr cmd, const char *pwd)
}
-/*
- * Feed the child's stdin from a string buffer
+/**
+ * virCommandSetInputBuffer:
+ * @cmd: the command to modify
+ * @inbuf: string to feed to stdin
+ *
+ * Feed the child's stdin from a string buffer. This requires the use
+ * of virCommandRun().
*/
void
virCommandSetInputBuffer(virCommandPtr cmd, const char *inbuf)
@@ -1168,11 +1273,16 @@ virCommandSetInputBuffer(virCommandPtr cmd, const char *inbuf)
}
-/*
+/**
+ * virCommandSetOutputBuffer:
+ * @cmd: the command to modify
+ * @outbuf: address of variable to store malloced result buffer
+ *
* Capture the child's stdout to a string buffer. *outbuf is
* guaranteed to be allocated after successful virCommandRun or
* virCommandWait, and is best-effort allocated after failed
* virCommandRun; caller is responsible for freeing *outbuf.
+ * This requires the use of virCommandRun.
*/
void
virCommandSetOutputBuffer(virCommandPtr cmd, char **outbuf)
@@ -1192,11 +1302,16 @@ virCommandSetOutputBuffer(virCommandPtr cmd, char **outbuf)
}
-/*
+/**
+ * virCommandSetErrorBuffer:
+ * @cmd: the command to modify
+ * @errbuf: address of variable to store malloced result buffer
+ *
* Capture the child's stderr to a string buffer. *errbuf is
* guaranteed to be allocated after successful virCommandRun or
* virCommandWait, and is best-effort allocated after failed
* virCommandRun; caller is responsible for freeing *errbuf.
+ * This requires the use of virCommandRun.
*/
void
virCommandSetErrorBuffer(virCommandPtr cmd, char **errbuf)
@@ -1216,7 +1331,11 @@ virCommandSetErrorBuffer(virCommandPtr cmd, char **errbuf)
}
-/*
+/**
+ * virCommandSetInputFD:
+ * @cmd: the command to modify
+ * @infd: the descriptor to use
+ *
* Attach a file descriptor to the child's stdin
*/
void
@@ -1240,8 +1359,14 @@ virCommandSetInputFD(virCommandPtr cmd, int infd)
}
-/*
- * Attach a file descriptor to the child's stdout
+/**
+ * virCommandSetOutputFD:
+ * @cmd: the command to modify
+ * @outfd: location of output fd
+ *
+ * Attach a file descriptor to the child's stdout. If *@outfd is -1 on
+ * entry, then a pipe will be created and returned in this variable when
+ * the child is run. Otherwise, *@outfd is used as the output.
*/
void
virCommandSetOutputFD(virCommandPtr cmd, int *outfd)
@@ -1259,8 +1384,15 @@ virCommandSetOutputFD(virCommandPtr cmd, int *outfd)
}
-/*
- * Attach a file descriptor to the child's stderr
+/**
+ * virCommandSetErrorFD:
+ * @cmd: the command to modify
+ * @errfd: location of error fd
+ *
+ * Attach a file descriptor to the child's stderr. If *@errfd is -1 on
+ * entry, then a pipe will be created and returned in this variable when
+ * the child is run. Otherwise, *@errfd is used for error collection,
+ * and may be the same as outfd given to virCommandSetOutputFD().
*/
void
virCommandSetErrorFD(virCommandPtr cmd, int *errfd)
@@ -1278,10 +1410,18 @@ virCommandSetErrorFD(virCommandPtr cmd, int *errfd)
}
-/*
+/**
+ * virCommandSetPreExecHook:
+ * @cmd: the command to modify
+ * @hook: the hook to run
+ * @opaque: argument to pass to the hook
+ *
* Run HOOK(OPAQUE) in the child as the last thing before changing
* directories, dropping capabilities, and executing the new process.
* Force the child to fail if HOOK does not return zero.
+ *
+ * Since @hook runs in the child, it should be careful to avoid
+ * any functions that are not async-signal-safe.
*/
void
virCommandSetPreExecHook(virCommandPtr cmd, virExecHook hook, void *opaque)
@@ -1299,7 +1439,11 @@ virCommandSetPreExecHook(virCommandPtr cmd, virExecHook hook, void *opaque)
}
-/*
+/**
+ * virCommandWriteArgLog:
+ * @cmd: the command to log
+ * @logfd: where to log the results
+ *
* Call after adding all arguments and environment settings, but before
* Run/RunAsync, to immediately output the environment and arguments of
* cmd to logfd. If virCommandRun cannot succeed (because of an
@@ -1337,7 +1481,10 @@ virCommandWriteArgLog(virCommandPtr cmd, int logfd)
}
-/*
+/**
+ * virCommandToString:
+ * @cmd: the command to convert
+ *
* Call after adding all arguments and environment settings, but before
* Run/RunAsync, to return a string representation of the environment and
* arguments of cmd. If virCommandRun cannot succeed (because of an
@@ -1382,10 +1529,13 @@ virCommandToString(virCommandPtr cmd)
}
-/*
+/**
+ * virCommandTranslateStatus:
+ * @status: child exit status to translate
+ *
* Translate an exit status into a malloc'd string. Generic helper
- * for virCommandRun, virCommandWait, and virPidWait status argument,
- * as well as raw waitpid and older virRun status.
+ * for virCommandRun(), virCommandWait(), virRun(), and virPidWait()
+ * status argument, as well as raw waitpid().
*/
char *
virCommandTranslateStatus(int status)
@@ -1551,10 +1701,13 @@ cleanup:
return ret;
}
-/*
+/**
+ * virCommandExec:
+ * @cmd: command to run
+ *
* Exec the command, replacing the current process. Meant to be called
- * after already forking / cloning, so does not attempt to daemonize or
- * preserve any FDs.
+ * in the hook after already forking / cloning, so does not attempt to
+ * daemonize or preserve any FDs.
*
* Returns -1 on any error executing the command.
* Will not return on success.
@@ -1587,11 +1740,16 @@ int virCommandExec(virCommandPtr cmd ATTRIBUTE_UNUSED)
}
#endif
-/*
+/**
+ * virCommandRun:
+ * @cmd: command to run
+ * @exitstatus: optional status collection
+ *
* Run the command and wait for completion.
* Returns -1 on any error executing the
* command. Returns 0 if the command executed,
- * with the exit status set
+ * with the exit status set. If @exitstatus is NULL, then the
+ * child must exit with status 0 for this to succeed.
*/
int
virCommandRun(virCommandPtr cmd, int *exitstatus)
@@ -1803,7 +1961,11 @@ virCommandHook(void *data)
}
-/*
+/**
+ * virCommandRunAsync:
+ * @cmd: command to start
+ * @pid: optional variable to track child pid
+ *
* Run the command asynchronously
* Returns -1 on any error executing the
* command. Returns 0 if the command executed.
@@ -1909,11 +2071,16 @@ virCommandRunAsync(virCommandPtr cmd, pid_t *pid)
}
-/*
+/**
+ * virPidWait:
+ * @pid: child to wait on
+ * @exitstatus: optional status collection
+ *
* Wait for a child process to complete.
* Return -1 on any error waiting for
* completion. Returns 0 if the command
- * finished with the exit status set
+ * finished with the exit status set. If @exitstatus is NULL, then the
+ * child must exit with status 0 for this to succeed.
*/
int
virPidWait(pid_t pid, int *exitstatus)
@@ -1951,11 +2118,16 @@ virPidWait(pid_t pid, int *exitstatus)
return 0;
}
-/*
- * Wait for the async command to complete.
- * Return -1 on any error waiting for
+/**
+ * virCommandWait:
+ * @cmd: command to wait on
+ * @exitstatus: optional status collection
+ *
+ * Wait for the command previously started with virCommandRunAsync()
+ * to complete. Return -1 on any error waiting for
* completion. Returns 0 if the command
- * finished with the exit status set
+ * finished with the exit status set. If @exitstatus is NULL, then the
+ * child must exit with status 0 for this to succeed.
*/
int
virCommandWait(virCommandPtr cmd, int *exitstatus)
@@ -2006,11 +2178,15 @@ virCommandWait(virCommandPtr cmd, int *exitstatus)
#ifndef WIN32
-/*
+/**
+ * virPidAbort:
+ * @pid: child process to kill
+ *
* Abort a child process if PID is positive and that child is still
* running, without issuing any errors or affecting errno. Designed
* for error paths where some but not all paths to the cleanup code
- * might have started the child process.
+ * might have started the child process. If @pid is 0 or negative,
+ * this does nothing.
*/
void
virPidAbort(pid_t pid)
@@ -2063,7 +2239,10 @@ cleanup:
errno = saved_errno;
}
-/*
+/**
+ * virCommandAbort:
+ * @cmd: command to abort
+ *
* Abort an async command if it is running, without issuing
* any errors or affecting errno. Designed for error paths
* where some but not all paths to the cleanup code might
@@ -2096,6 +2275,15 @@ virCommandAbort(virCommandPtr cmd ATTRIBUTE_UNUSED)
#endif
+/**
+ * virCommandRequireHandshake:
+ * @cmd: command to modify
+ *
+ * Request that the child perform a handshake with
+ * the parent when the hook function has completed
+ * execution. The child will not exec() until the
+ * parent has notified
+ */
void virCommandRequireHandshake(virCommandPtr cmd)
{
if (!cmd || cmd->has_error)
@@ -2125,6 +2313,13 @@ void virCommandRequireHandshake(virCommandPtr cmd)
cmd->handshake = true;
}
+/**
+ * virCommandHandshakeWait:
+ * @cmd: command to wait on
+ *
+ * Wait for the child to complete execution of its
+ * hook function. To be called in the parent.
+ */
int virCommandHandshakeWait(virCommandPtr cmd)
{
char c;
@@ -2178,6 +2373,13 @@ int virCommandHandshakeWait(virCommandPtr cmd)
return 0;
}
+/**
+ * virCommandHandshakeNotify:
+ * @cmd: command to resume
+ *
+ * Notify the child that it is OK to exec() the
+ * real binary now. To be called in the parent.
+ */
int virCommandHandshakeNotify(virCommandPtr cmd)
{
char c = '1';
@@ -2208,10 +2410,13 @@ int virCommandHandshakeNotify(virCommandPtr cmd)
}
-/*
+/**
+ * virCommandFree:
+ * @cmd: optional command to free
+ *
* Release all resources. The only exception is that if you called
* virCommandRunAsync with a non-null pid, then the asynchronous child
- * is not reaped, and you must call virPidWait() yourself.
+ * is not reaped, and you must call virPidWait() or virPidAbort() yourself.
*/
void
virCommandFree(virCommandPtr cmd)
diff --git a/src/util/command.h b/src/util/command.h
index f766839..1386d57 100644
--- a/src/util/command.h
+++ b/src/util/command.h
@@ -30,34 +30,18 @@ typedef struct _virCommand virCommand;
typedef virCommand *virCommandPtr;
/* This will execute in the context of the first child
- * after fork() but before execve() */
+ * after fork() but before execve(). As such, it is unsafe to
+ * call any function that is not async-signal-safe. */
typedef int (*virExecHook)(void *data);
-/*
- * Fork wrapper with extra error checking
- */
int virFork(pid_t *pid) ATTRIBUTE_RETURN_CHECK;
-/*
- * Simple synchronous command wrapper
- */
int virRun(const char *const*argv, int *status) ATTRIBUTE_RETURN_CHECK;
-/*
- * Create a new command for named binary
- */
virCommandPtr virCommandNew(const char *binary) ATTRIBUTE_NONNULL(1);
-/*
- * Create a new command with a NULL terminated
- * set of args, taking binary from argv[0]
- */
virCommandPtr virCommandNewArgs(const char *const*args) ATTRIBUTE_NONNULL(1);
-/*
- * Create a new command with a NULL terminated
- * list of args, starting with the binary to run
- */
virCommandPtr virCommandNewArgList(const char *binary, ...)
ATTRIBUTE_NONNULL(1) ATTRIBUTE_SENTINEL;
@@ -65,310 +49,125 @@ virCommandPtr virCommandNewArgList(const char *binary, ...)
* delayed until the Run/RunAsync methods
*/
-/*
- * Preserve the specified file descriptor
- * in the child, instead of closing it.
- * The parent is still responsible for managing fd.
- */
void virCommandPreserveFD(virCommandPtr cmd,
int fd);
-/*
- * Transfer the specified file descriptor
- * to the child, instead of closing it.
- * Close the fd in the parent during Run/RunAsync/Free.
- */
void virCommandTransferFD(virCommandPtr cmd,
int fd);
-/*
- * Save the child PID in a pidfile
- */
void virCommandSetPidFile(virCommandPtr cmd,
const char *pidfile) ATTRIBUTE_NONNULL(2);
-/*
- * Remove all capabilities from the child
- */
void virCommandClearCaps(virCommandPtr cmd);
# if 0
-/*
- * Re-allow a specific capability
- */
void virCommandAllowCap(virCommandPtr cmd,
int capability);
# endif
-/*
- * Daemonize the child process
- */
void virCommandDaemonize(virCommandPtr cmd);
-/*
- * Set FDs created by virCommandSetOutputFD and virCommandSetErrorFD
- * as non-blocking in the parent.
- */
void virCommandNonblockingFDs(virCommandPtr cmd);
-/*
- * Add an environment variable to the child created by a printf-style format
- */
-void
-virCommandAddEnvFormat(virCommandPtr cmd, const char *format, ...)
- ATTRIBUTE_NONNULL(2) ATTRIBUTE_FMT_PRINTF(2, 3);
+void virCommandAddEnvFormat(virCommandPtr cmd, const char *format, ...)
+ ATTRIBUTE_NONNULL(2) ATTRIBUTE_FMT_PRINTF(2, 3);
-/*
- * Add an environment variable to the child
- * using separate name & value strings
- */
void virCommandAddEnvPair(virCommandPtr cmd,
const char *name,
const char *value) ATTRIBUTE_NONNULL(2);
-/*
- * Add an environemnt variable to the child
- * using a preformated env string FOO=BAR
- */
void virCommandAddEnvString(virCommandPtr cmd,
const char *str) ATTRIBUTE_NONNULL(2);
-/*
- * Convert a buffer containing preformatted name=value into an
- * environment variable of the child.
- * Correctly transfers memory errors or contents from buf to cmd.
- */
void virCommandAddEnvBuffer(virCommandPtr cmd,
virBufferPtr buf);
-/*
- * Pass an environment variable to the child
- * using current process' value
- */
void virCommandAddEnvPass(virCommandPtr cmd,
const char *name) ATTRIBUTE_NONNULL(2);
-/*
- * Pass a common set of environment variables
- * to the child using current process' values
- */
+
void virCommandAddEnvPassCommon(virCommandPtr cmd);
-/*
- * Add a command line argument to the child
- */
void virCommandAddArg(virCommandPtr cmd,
const char *val) ATTRIBUTE_NONNULL(2);
-/*
- * Convert a buffer into a command line argument to the child.
- * Correctly transfers memory errors or contents from buf to cmd.
- */
void virCommandAddArgBuffer(virCommandPtr cmd,
virBufferPtr buf);
-/*
- * Add a command line argument created by a printf-style format
- */
void virCommandAddArgFormat(virCommandPtr cmd,
const char *format, ...)
ATTRIBUTE_NONNULL(2) ATTRIBUTE_FMT_PRINTF(2, 3);
-/*
- * Add a command line argument to the child
- */
void virCommandAddArgPair(virCommandPtr cmd,
const char *name,
const char *val)
ATTRIBUTE_NONNULL(2) ATTRIBUTE_NONNULL(3);
-/*
- * Add a NULL terminated array of args
- */
+
void virCommandAddArgSet(virCommandPtr cmd,
const char *const*vals) ATTRIBUTE_NONNULL(2);
-/*
- * Add a NULL terminated list of args
- */
+
void virCommandAddArgList(virCommandPtr cmd,
... /* const char *arg, ..., NULL */)
ATTRIBUTE_SENTINEL;
-/*
- * Set the working directory of a non-daemon child process, rather
- * than the parent's working directory. Daemons automatically get /
- * without using this call.
- */
void virCommandSetWorkingDirectory(virCommandPtr cmd,
const char *pwd) ATTRIBUTE_NONNULL(2);
-/*
- * Feed the child's stdin from a string buffer.
- *
- * NB: Only works with virCommandRun()
- */
void virCommandSetInputBuffer(virCommandPtr cmd,
const char *inbuf) ATTRIBUTE_NONNULL(2);
-/*
- * Capture the child's stdout to a string buffer
- *
- * NB: Only works with virCommandRun()
- */
+
void virCommandSetOutputBuffer(virCommandPtr cmd,
char **outbuf) ATTRIBUTE_NONNULL(2);
-/*
- * Capture the child's stderr to a string buffer
- *
- * NB: Only works with virCommandRun()
- */
+
void virCommandSetErrorBuffer(virCommandPtr cmd,
char **errbuf) ATTRIBUTE_NONNULL(2);
-/*
- * Set a file descriptor as the child's stdin
- */
void virCommandSetInputFD(virCommandPtr cmd,
int infd);
-/*
- * Set a file descriptor as the child's stdout
- */
+
void virCommandSetOutputFD(virCommandPtr cmd,
int *outfd) ATTRIBUTE_NONNULL(2);
-/*
- * Set a file descriptor as the child's stderr
- */
+
void virCommandSetErrorFD(virCommandPtr cmd,
int *errfd) ATTRIBUTE_NONNULL(2);
-/*
- * A hook function to run between fork + exec
- */
void virCommandSetPreExecHook(virCommandPtr cmd,
virExecHook hook,
void *opaque) ATTRIBUTE_NONNULL(2);
-/*
- * Call after adding all arguments and environment settings, but before
- * Run/RunAsync, to immediately output the environment and arguments of
- * cmd to logfd. If virCommandRun cannot succeed (because of an
- * out-of-memory condition while building cmd), nothing will be logged.
- */
void virCommandWriteArgLog(virCommandPtr cmd,
int logfd);
-/*
- * Call after adding all arguments and environment settings, but before
- * Run/RunAsync, to return a string representation of the environment and
- * arguments of cmd. If virCommandRun cannot succeed (because of an
- * out-of-memory condition while building cmd), NULL will be returned.
- * Caller is responsible for freeing the resulting string.
- */
char *virCommandToString(virCommandPtr cmd) ATTRIBUTE_RETURN_CHECK;
-/*
- * Translate an exit status into a malloc'd string.
- */
char *virCommandTranslateStatus(int exitstatus) ATTRIBUTE_RETURN_CHECK;
-/*
- * Exec the command, replacing the current process. Meant to be called
- * after already forking / cloning, so does not attempt to daemonize or
- * preserve any FDs.
- *
- * Returns -1 on any error executing the command.
- * Will not return on success.
- */
int virCommandExec(virCommandPtr cmd) ATTRIBUTE_RETURN_CHECK;
-/*
- * Run the command and wait for completion.
- * Returns -1 on any error executing the
- * command. Returns 0 if the command executed,
- * with the exit status set
- */
int virCommandRun(virCommandPtr cmd,
int *exitstatus) ATTRIBUTE_RETURN_CHECK;
-/*
- * Run the command asynchronously
- * Returns -1 on any error executing the
- * command. Returns 0 if the command executed.
- *
- * There are two approaches to child process cleanup.
- * 1. Use auto-cleanup, by passing NULL for pid. The child will be
- * auto-reaped by virCommandFree, unless you reap it earlier via
- * virCommandWait or virCommandAbort. Good for where cmd is in
- * scope for the duration of the child process.
- * 2. Use manual cleanup, by passing the address of a pid_t variable
- * for pid. While cmd is still in scope, you may reap the child via
- * virCommandWait or virCommandAbort. But after virCommandFree, if
- * you have not yet reaped the child, then it continues to run until
- * you call virPidWait or virPidAbort.
- */
int virCommandRunAsync(virCommandPtr cmd,
pid_t *pid) ATTRIBUTE_RETURN_CHECK;
-/*
- * Wait for a child process to complete.
- * Return -1 on any error waiting for
- * completion. Returns 0 if the command
- * finished with the exit status set.
- */
int virPidWait(pid_t pid,
int *exitstatus) ATTRIBUTE_RETURN_CHECK;
-/*
- * Wait for the async command to complete.
- * Return -1 on any error waiting for
- * completion. Returns 0 if the command
- * finished with the exit status set
- */
int virCommandWait(virCommandPtr cmd,
int *exitstatus) ATTRIBUTE_RETURN_CHECK;
-/*
- * Request that the child perform a handshake with
- * the parent when the hook function has completed
- * execution. The child will not exec() until the
- * parent has notified
- */
void virCommandRequireHandshake(virCommandPtr cmd);
-/*
- * Wait for the child to complete execution of its
- * hook function
- */
int virCommandHandshakeWait(virCommandPtr cmd)
ATTRIBUTE_RETURN_CHECK;
-/*
- * Notify the child that it is OK to exec() the
- * real binary now
- */
int virCommandHandshakeNotify(virCommandPtr cmd)
ATTRIBUTE_RETURN_CHECK;
-/*
- * Abort a child process if PID is positive and that child is still
- * running, without issuing any errors or affecting errno. Designed
- * for error paths where some but not all paths to the cleanup code
- * might have started the child process.
- */
void virPidAbort(pid_t pid);
-/*
- * Abort an async command if it is running, without issuing
- * any errors or affecting errno. Designed for error paths
- * where some but not all paths to the cleanup code might
- * have started the child process.
- */
void virCommandAbort(virCommandPtr cmd);
-/*
- * Release all resources. The only exception is that if you called
- * virCommandRunAsync with a non-null pid, then the asynchronous child
- * is not reaped, and you must call virPidWait() yourself.
- */
void virCommandFree(virCommandPtr cmd);
-
#endif /* __VIR_COMMAND_H__ */
--
1.7.4.4
--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list