461 lines
14 KiB
Groff
461 lines
14 KiB
Groff
.\" 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 June 17, 2011
|
|
.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 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 dup2
|
|
or
|
|
.Fn open
|
|
to fail, an error value is returned as described by
|
|
.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 dup2 ,
|
|
in addition to those described by
|
|
.Fn open .
|
|
This implementation ignores any errors from
|
|
.Fn close ,
|
|
including trying to close a descriptor that is not 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 ,
|
|
except that they ignore all errors from
|
|
.Fn close .
|
|
A future update of the Standard is expected to require that these functions
|
|
not fail because a file descriptor to be closed (via
|
|
.Fn posix_spawn_file_actions_addclose )
|
|
is not open.
|
|
.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
|