[libvirt] [PATCHv2 01/16] command: move all docs into .c file

Eric Blake eblake at redhat.com
Wed Jul 20 04:20:24 UTC 2011


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.
---

prereq patch to 2/16 (not directly related to bypass-cache, but I
don't want to rebase across this one)

v2: no change from v1, previously posted here:
https://www.redhat.com/archives/libvir-list/2011-July/msg00879.html

 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 5bc6272..11dd7b0 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




More information about the libvir-list mailing list