Skip to content

L
libvirt

openeuler / libvirt

通知 3
Star 0
Fork 0
L
libvirt
提交 42891145 编写于 作者: E Eric Blake
浏览文件
操作

command: move all docs into .c file 

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.
上级 fbd5465a
隐藏空白更改
内联 并排
Showing with 299 addition and 295 deletion
src/util/command.c
浏览文件 @ 42891145
......@@ -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)
......
src/util/command.h
浏览文件 @ 42891145
......@@ -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__ */
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或