summaryrefslogtreecommitdiffstats
path: root/lib/libc/gen/posix_spawn.3
diff options
context:
space:
mode:
Diffstat (limited to 'lib/libc/gen/posix_spawn.3')
-rw-r--r--lib/libc/gen/posix_spawn.3455
1 files changed, 0 insertions, 455 deletions
diff --git a/lib/libc/gen/posix_spawn.3 b/lib/libc/gen/posix_spawn.3
deleted file mode 100644
index 7569239..0000000
--- a/lib/libc/gen/posix_spawn.3
+++ /dev/null
@@ -1,455 +0,0 @@
-.\" 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 March 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@FreeBSD.org
OpenPOWER on IntegriCloud