Add manual pages for posix_spawn() functions.

PR:	standards/122051

1 files changed, 455 insertions, 0 deletions

diff --git a/lib/libc/gen/posix_spawn.3 b/lib/libc/gen/posix_spawn.3
new file mode 100644
index 0000000..afa639e
--- /dev/null
+++ b/lib/libc/gen/posix_spawn.3
@@ -0,0 +1,455 @@
+.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" Portions of this text are reprinted and reproduced in electronic form
+.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
+.\" Portable Operating System Interface (POSIX), The Open Group Base
+.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
+.\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
+.\" event of any discrepancy between this version and the original IEEE and
+.\" The Open Group Standard, the original IEEE and The Open Group Standard is
+.\" the referee document.  The original Standard can be obtained online at
+.\"	http://www.opengroup.org/unix/online.html.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd Mar 24, 2008
+.Dt POSIX_SPAWN 3
+.Os
+.Sh NAME
+.Nm posix_spawn ,
+.Nm posix_spawnp
+.Nd "spawn a process"
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In spawn.h
+.Ft int
+.Fn posix_spawn "pid_t *restrict pid" "const char *restrict path" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]"
+.Ft int
+.Fn posix_spawnp "pid_t *restrict pid" "const char *restrict file" "const posix_spawn_file_actions_t *file_actions" "const posix_spawnattr_t *restrict attrp" "char *const argv[restrict]" "char *const envp[restrict]"
+.Sh DESCRIPTION
+The
+.Fn posix_spawn
+and
+.Fn posix_spawnp
+functions create a new process (child process) from the specified
+process image.
+The new process image is constructed from a regular executable
+file called the new process image file.
+.Pp
+When a C program is executed as the result of this call, it is
+entered as a C-language function call as follows:
+.Bd -literal -offset indent
+int main(int argc, char *argv[]);
+.Ed
+.Pp
+where
+.Fa argc
+is the argument count and
+.Fa argv
+is an array of character pointers to the arguments themselves.
+In addition, the variable:
+.Bd -literal -offset indent
+extern char **environ;
+.Ed
+.Pp
+points to an array of character pointers to
+the environment strings.
+.Pp
+The argument
+.Fa argv
+is an array of character pointers to null-terminated
+strings.
+The last member of this array is a null pointer and is not counted
+in
+.Fa argc .
+These strings constitute the argument list available to the new process
+image.
+The value in
+.Fa argv Ns [0]
+should point to
+a filename that is associated with the process image being started by
+the
+.Fn posix_spawn
+or
+.Fn posix_spawnp
+function.
+.Pp
+The argument
+.Fa envp
+is an array of character pointers to null-terminated strings.
+These strings constitute the environment for the new process image.
+The environment array is terminated by a null pointer.
+.Pp
+The
+.Fa path
+argument to
+.Fn posix_spawn
+is a pathname that identifies the new process image file to execute.
+.Pp
+The
+.Fa file
+parameter to
+.Fn posix_spawnp
+is used to construct a pathname that identifies the new process
+image file.
+If the file parameter contains a slash character, the file parameter
+is used as the pathname for the new process image file.
+Otherwise, the path prefix for this file is obtained by a search
+of the directories passed as the environment variable
+.Dq Ev PATH .
+If this variable is not specified,
+the default path is set according to the
+.Dv _PATH_DEFPATH
+definition in
+.In paths.h ,
+which is set to
+.Dq Ev /usr/bin:/bin .
+.Pp
+If
+.Fa file_actions
+is a null pointer, then file descriptors open in the
+calling process remain open in the child process, except for those
+whose close-on-exec flag
+.Dv FD_CLOEXEC
+is set (see
+.Fn fcntl ) .
+For those
+file descriptors that remain open, all attributes of the corresponding
+open file descriptions, including file locks (see
+.Fn fcntl ) ,
+remain unchanged.
+.Pp
+If
+.Fa file_actions
+is not NULL, then the file descriptors open in the child process are
+those open in the calling process as modified by the spawn file
+actions object pointed to by
+.Fa file_actions
+and the
+.Dv FD_CLOEXEC
+flag of each remaining open file descriptor after the spawn file actions
+have been processed.
+The effective order of processing the spawn file actions are:
+.Bl -enum
+.It
+The set of open file descriptors for the child process initially
+are the same set as is open for the calling process.
+All attributes of the corresponding open file descriptions, including
+file locks (see
+.Fn fcntl ) ,
+remain unchanged.
+.It
+The signal mask, signal default actions, and the effective user and
+group IDs for the child process are changed as specified in the
+attributes object referenced by
+.Fa attrp .
+.It
+The file actions specified by the spawn file actions object are 
+performed in the order in which they were added to the spawn file
+actions object.
+.It
+Any file descriptor that has its
+.Dv FD_CLOEXEC
+flag set (see
+.Fn fcntl )
+is closed.
+.El
+.Pp
+The
+.Vt posix_spawnattr_t
+spawn attributes object type is defined in
+.In spawn.h .
+It contains the attributes defined below.
+.Pp
+If the
+.Dv POSIX_SPAWN_SETPGROUP
+flag is set in the spawn-flags attribute of the object referenced by
+.Fa attrp ,
+and the spawn-pgroup attribute of the same object is non-zero, then the
+child's process group is as specified in the spawn-pgroup
+attribute of the object referenced by
+.Fa attrp .
+.Pp
+As a special case, if the
+.Dv POSIX_SPAWN_SETPGROUP
+flag is set in the spawn-flags attribute of the object referenced by
+.Fa attrp ,
+and the spawn-pgroup attribute of the same object is set to zero, then
+the child is in a new process group with a process group ID equal
+to its process ID.
+.Pp
+If the
+.Dv POSIX_SPAWN_SETPGROUP
+flag is not set in the spawn-flags attribute of the object referenced by
+.Fa attrp ,
+the new child process inherits the parent's process group.
+.Pp
+If the
+.Dv POSIX_SPAWN_SETSCHEDPARAM
+flag is set in the spawn-flags attribute of the object referenced by
+.Fa attrp ,
+but
+.Dv POSIX_SPAWN_SETSCHEDULER
+is not set, the new process image initially has the scheduling
+policy of the calling process with the scheduling parameters specified
+in the spawn-schedparam attribute of the object referenced by
+.Fa attrp .
+.Pp
+If the
+.Dv POSIX_SPAWN_SETSCHEDULER
+flag is set in the spawn-flags attribute of the object referenced by
+.Fa attrp
+(regardless of the setting of the
+.Dv POSIX_SPAWN_SETSCHEDPARAM
+flag), the new process image initially has the scheduling policy
+specified in the spawn-schedpolicy attribute of the object referenced by
+.Fa attrp
+and the scheduling parameters specified in the spawn-schedparam
+attribute of the same object.
+.Pp
+The
+.Dv POSIX_SPAWN_RESETIDS
+flag in the spawn-flags attribute of the object referenced by
+.Fa attrp
+governs the effective user ID of the child process.
+If this flag is not set, the child process inherits the parent
+process' effective user ID.
+If this flag is set, the child process' effective user ID is reset
+to the parent's real user ID.
+In either case, if the set-user-ID mode bit of the new process image
+file is set, the effective user ID of the child process becomes
+that file's owner ID before the new process image begins execution.
+.Pp
+The
+.Dv POSIX_SPAWN_RESETIDS
+flag in the spawn-flags attribute of the object referenced by
+.Fa attrp
+also governs the effective group ID of the child process.
+If this flag is not set, the child process inherits the parent
+process' effective group ID.
+If this flag is set, the child process' effective group ID is
+reset to the parent's real group ID.
+In either case, if the set-group-ID mode bit of the new process image
+file is set, the effective group ID of the child process becomes
+that file's group ID before the new process image begins execution.
+.Pp
+If the
+.Dv POSIX_SPAWN_SETSIGMASK
+flag is set in the spawn-flags attribute of the object referenced by
+.Fa attrp ,
+the child process initially has the signal mask specified in the
+spawn-sigmask attribute of the object referenced by
+.Fa attrp .
+.Pp
+If the
+.Dv POSIX_SPAWN_SETSIGDEF
+flag is set in the spawn-flags attribute of the object referenced by
+.Fa attrp ,
+the signals specified in the spawn-sigdefault attribute of the same
+object is set to their default actions in the child process.
+Signals set to the default action in the parent process is set to
+the default action in the child process.
+.Pp
+Signals set to be caught by the calling process is set to the
+default action in the child process.
+.Pp
+Signals set to be ignored by the calling process image is set to
+be ignored by the child process, unless otherwise specified by the
+.Dv POSIX_SPAWN_SETSIGDEF
+flag being set in the spawn-flags attribute of the object referenced by
+.Fa attrp
+and the signals being indicated in the spawn-sigdefault attribute
+of the object referenced by
+.Fa attrp .
+.Pp
+If the value of the
+.Fa attrp
+pointer is NULL, then the default values are used.
+.Pp
+All process attributes, other than those influenced by the attributes
+set in the object referenced by
+.Fa attrp
+as specified above or by the file descriptor manipulations specified in
+.Fa file_actions ,
+appear in the new process image as though
+.Fn vfork
+had been called to create a child process and then
+.Fn execve
+had been called by the child process to execute the new process image.
+.Pp
+The implementation uses vfork(), thus the fork handlers are not run when
+.Fn posix_spawn
+or
+.Fn posix_spawnp
+is called.
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn posix_spawn
+and
+.Fn posix_spawnp
+return the process ID of the child process to the parent process,
+in the variable pointed to by a non-NULL
+.Fa pid
+argument, and return zero as the function return value.
+Otherwise, no child process is created, no value is stored into
+the variable pointed to by
+.Fa pid ,
+and an error number is returned as the function return value to
+indicate the error.
+If the
+.Fa pid
+argument is a null pointer, the process ID of the child is not returned
+to the caller.
+.Sh ERRORS
+.Bl -enum
+.It
+If
+.Fn posix_spawn
+and
+.Fn posix_spawnp
+fail for any of the reasons that would cause
+.Fn vfork
+or one of the
+.Nm exec
+to fail, an error value is returned as described by
+.Fn vfork
+and
+.Nm exec ,
+respectively (or, if the error occurs after the calling process successfully
+returns, the child process exits with exit status 127).
+.It
+If
+.Nm POSIX_SPAWN_SETPGROUP
+is set in the spawn-flags attribute of the object referenced by attrp, and
+.Fn posix_spawn
+or
+.Fn posix_spawnp
+fails while changing the child's process group, an error value is returned as
+described by
+.Fn setpgid
+(or, if the error occurs after the calling process successfully returns,
+the child process exits with exit status 127).
+.It
+If
+.Nm POSIX_SPAWN_SETSCHEDPARAM
+is set and
+.Nm POSIX_SPAWN_SETSCHEDULER
+is not set in the spawn-flags attribute of the object referenced by attrp, then
+if
+.Fn posix_spawn
+or
+.Fn posix_spawnp
+fails for any of the reasons that would cause
+.Fn sched_setparam
+to fail, an error value is returned as described by
+.Fn sched_setparam
+(or, if the error occurs after the calling process successfully returns, the
+child process exits with exit status 127).
+.It
+If
+.Nm POSIX_SPAWN_SETSCHEDULER
+is set in the spawn-flags attribute of the object referenced by attrp, and if
+.Fn posix_spawn
+or
+.Fn posix_spawnp
+fails for any of the reasons that would cause
+.Fn sched_setscheduler
+to fail, an error value is returned as described by
+.Fn sched_setscheduler
+(or, if the error occurs after the calling process successfully returns,
+the child process exits with exit status 127).
+.It
+If the
+.Fa file_actions
+argument is not NULL, and specifies any close, dup2, or open actions to be
+performed, and if
+.Fn posix_spawn
+or
+.Fn posix_spawnp
+fails for any of the reasons that would cause
+.Fn close ,
+.Fn dup2 ,
+or
+.Fn open
+to fail, an error value is returned as described by
+.Fn close ,
+.Fn dup2 ,
+and
+.Fn open ,
+respectively (or, if the error occurs after the calling process successfully
+returns, the child process exits with exit status 127). An open file action
+may, by itself, result in any of the errors described by
+.Fn close
+or
+.Fn dup2 ,
+in addition to those described by
+.Fn open .
+.El
+.Sh SEE ALSO
+.Xr close 2 ,
+.Xr dup2 2 ,
+.Xr execve 2 ,
+.Xr fcntl 2 ,
+.Xr open 2 ,
+.Xr posix_spawn_file_actions_addclose 3 ,
+.Xr posix_spawn_file_actions_adddup2 3 ,
+.Xr posix_spawn_file_actions_addopen 3 ,
+.Xr posix_spawn_file_actions_destroy 3 ,
+.Xr posix_spawn_file_actions_init 3 ,
+.Xr posix_spawnattr_destroy 3 ,
+.Xr posix_spawnattr_getflags 3 ,
+.Xr posix_spawnattr_getpgroup 3 ,
+.Xr posix_spawnattr_getschedparam 3 ,
+.Xr posix_spawnattr_getschedpolicy 3 ,
+.Xr posix_spawnattr_getsigdefault 3 ,
+.Xr posix_spawnattr_getsigmask 3 ,
+.Xr posix_spawnattr_init 3 ,
+.Xr posix_spawnattr_setflags 3 ,
+.Xr posix_spawnattr_setpgroup 3 ,
+.Xr posix_spawnattr_setschedparam 3 ,
+.Xr posix_spawnattr_setschedpolicy 3 ,
+.Xr posix_spawnattr_setsigdefault 3 ,
+.Xr posix_spawnattr_setsigmask 3 ,
+.Xr sched_setparam 2 ,
+.Xr sched_setscheduler 2 ,
+.Xr setpgid 2 ,
+.Xr vfork 2
+.Sh STANDARDS
+The
+.Fn posix_spawn
+and
+.Fn posix_spawnp
+functions conform to
+.St -p1003.1-2001 .
+.Sh HISTORY
+The
+.Fn posix_spawn
+and
+.Fn posix_spawnp
+functions first appeared in
+.Fx 8.0 .
+.Sh AUTHORS
+.An Ed Schouten Aq Ed Schouten ed@FreeBSD.org