exec: Improve documentation.

Clarify the documentation of the public para_exec_cmdline_pid()
and dedox the static para_exec().

diff --git a/exec.c b/exec.c
index 364395bd4e1ae0fb3e199471dbbbfa0065d41efb..60496d537cfd6f721c11cdacd663d36abf519632 100644 (file)
--- a/exec.c
+++ b/exec.c
@@ -9,18 +9,7 @@
 #include "fd.h"
 #include "string.h"
 
-/**
- * Spawn a new process and redirect fd 0, 1, and 2.
- *
- * \param pid Will hold the pid of the created process upon return.
- * \param file Path of the executable to execute.
- * \param args The argument array for the command.
- * \param fds a Pointer to a value-result array.
- *
- * \return Standard.
- *
- * \sa null(4), pipe(2), dup2(2), fork(2), exec(3).
- */
+/* Spawn a new process, redirect fds, have the child call execvp(2). */
 static int para_exec(pid_t *pid, const char *file, char *const *const args, int *fds)
 {
        int ret, in[2] = {-1, -1}, out[2] = {-1, -1}, err[2] = {-1, -1},
@@ -115,25 +104,32 @@ err_out:
 }
 
 /**
- * Exec the given command.
+ * Execute a file as a background process, honoring $PATH.
  *
- * \param pid Will hold the pid of the created process upon return.
- * \param cmdline Holds the command and its arguments, separated by spaces.
+ * \param pid Contains the PID of the child process on return.
+ * \param cmdline Path to the file to execute, followed by arguments.
  * \param fds A pointer to a value-result array.
  *
- * This function uses fork/exec to create a new process. \a fds must be a
- * pointer to three integers, corresponding to stdin, stdout and stderr
- * respectively. It specifies how to deal with fd 0, 1, 2 in the child. The
- * contents of \a fds are interpreted as follows:
+ * This function first splits the command line argument by calling \ref
+ * create_argv(), then calls fork(2) to create a new process. The parent
+ * returns without waiting for the child to terminate. The child calls
+ * execvp(2) to replace itself with the process image that corresponds to the
+ * first word of the given command line.
+ *
+ * The fd pointer must point to an array of three integers. Initially, the
+ * integers specify how to deal with fd 0, 1, 2 in the child:
  *
- *     - fd[i] < 0: leave fd \a i alone.
- *     - fd[i] = 0: dup fd \a i to \p /dev/null.
- *     - fd[i] > 0: create a pipe and dup i to one end of that pipe.
- *     Upon return, fd[i] contains the file descriptor of the pipe.
+ *     - < 0: Leave fd alone.
+ *     - == 0: Dup fd to /dev/null.
+ *     - > 0: Create a pipe and dup to one end of that pipe.
  *
- *     In any case, all unneeded file descriptors are closed.
+ * In the third case, the corresponding integer in the fd array is set to the
+ * file descriptor of the pipe that has been created. In any case, all unneeded
+ * file descriptors are closed.
  *
  * \return Standard.
+ *
+ * \sa null(4), pipe(2), dup2(2), fork(2), exec(3).
  */
 int para_exec_cmdline_pid(pid_t *pid, const char *cmdline, int *fds)
 {