[BACK]Return to posix_spawn.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / gen

Annotation of src/lib/libc/gen/posix_spawn.3, Revision 1.3

1.3     ! njoly       1: .\" $NetBSD: posix_spawn.3,v 1.2 2012/02/13 16:35:59 njoly Exp $
1.1       martin      2: .\"
                      3: .\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
                      4: .\" All rights reserved.
                      5: .\"
                      6: .\" Redistribution and use in source and binary forms, with or without
                      7: .\" modification, are permitted provided that the following conditions
                      8: .\" are met:
                      9: .\" 1. Redistributions of source code must retain the above copyright
                     10: .\"    notice, this list of conditions and the following disclaimer.
                     11: .\" 2. Redistributions in binary form must reproduce the above copyright
                     12: .\"    notice, this list of conditions and the following disclaimer in the
                     13: .\"    documentation and/or other materials provided with the distribution.
                     14: .\"
                     15: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
                     16: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
                     17: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
                     18: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
                     19: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
                     20: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
                     21: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
                     22: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
                     23: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
                     24: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
                     25: .\" SUCH DAMAGE.
                     26: .\"
                     27: .\" Portions of this text are reprinted and reproduced in electronic form
                     28: .\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
                     29: .\" Portable Operating System Interface (POSIX), The Open Group Base
                     30: .\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
                     31: .\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
                     32: .\" event of any discrepancy between this version and the original IEEE and
                     33: .\" The Open Group Standard, the original IEEE and The Open Group Standard is
                     34: .\" the referee document.  The original Standard can be obtained online at
                     35: .\"    http://www.opengroup.org/unix/online.html.
                     36: .\"
                     37: .\" $FreeBSD: src/lib/libc/gen/posix_spawn.3,v 1.2.2.1.4.1 2010/06/14 02:09:06 kensmith Exp $
                     38: .\"
                     39: .Dd December 20, 2011
                     40: .Dt POSIX_SPAWN 3
                     41: .Os
                     42: .Sh NAME
                     43: .Nm posix_spawn ,
                     44: .Nm posix_spawnp
                     45: .Nd "spawn a process"
                     46: .Sh LIBRARY
                     47: .Lb libc
                     48: .Sh SYNOPSIS
                     49: .In spawn.h
                     50: .Ft int
                     51: .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]"
                     52: .Ft int
                     53: .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]"
                     54: .Sh DESCRIPTION
                     55: The
                     56: .Fn posix_spawn
                     57: and
                     58: .Fn posix_spawnp
                     59: functions create a new process (child process) from the specified
                     60: process image.
                     61: The new process image is constructed from a regular executable
                     62: file called the new process image file.
                     63: .Pp
                     64: When a C program is executed as the result of this call, it is
                     65: entered as a C-language function call as follows:
                     66: .Bd -literal -offset indent
                     67: int main(int argc, char *argv[]);
                     68: .Ed
                     69: .Pp
                     70: where
                     71: .Fa argc
                     72: is the argument count and
                     73: .Fa argv
                     74: is an array of character pointers to the arguments themselves.
                     75: In addition, the variable:
                     76: .Bd -literal -offset indent
                     77: extern char **environ;
                     78: .Ed
                     79: .Pp
                     80: points to an array of character pointers to
                     81: the environment strings.
                     82: .Pp
                     83: The argument
                     84: .Fa argv
                     85: is an array of character pointers to null-terminated
                     86: strings.
                     87: The last member of this array is a null pointer and is not counted
                     88: in
                     89: .Fa argc .
                     90: These strings constitute the argument list available to the new process
                     91: image.
                     92: The value in
                     93: .Fa argv Ns [0]
                     94: should point to
                     95: a filename that is associated with the process image being started by
                     96: the
                     97: .Fn posix_spawn
                     98: or
                     99: .Fn posix_spawnp
                    100: function.
                    101: .Pp
                    102: The argument
                    103: .Fa envp
                    104: is an array of character pointers to null-terminated strings.
                    105: These strings constitute the environment for the new process image.
                    106: The environment array is terminated by a null pointer.
                    107: .Pp
                    108: The
                    109: .Fa path
                    110: argument to
                    111: .Fn posix_spawn
                    112: is a pathname that identifies the new process image file to execute.
                    113: .Pp
                    114: The
                    115: .Fa file
                    116: parameter to
                    117: .Fn posix_spawnp
                    118: is used to construct a pathname that identifies the new process
                    119: image file.
                    120: If the file parameter contains a slash character, the file parameter
                    121: is used as the pathname for the new process image file.
                    122: Otherwise, the path prefix for this file is obtained by a search
                    123: of the directories passed as the environment variable
                    124: .Dq Ev PATH .
                    125: If this variable is not specified,
                    126: the default path is set according to the
                    127: .Dv _PATH_DEFPATH
                    128: definition in
                    129: .In paths.h ,
                    130: which is set to
                    131: .Dq Ev /usr/bin:/bin .
                    132: .Pp
                    133: If
                    134: .Fa file_actions
                    135: is a null pointer, then file descriptors open in the
                    136: calling process remain open in the child process, except for those
                    137: whose close-on-exec flag
                    138: .Dv FD_CLOEXEC
                    139: is set (see
                    140: .Fn fcntl ) .
                    141: For those
                    142: file descriptors that remain open, all attributes of the corresponding
                    143: open file descriptions, including file locks (see
                    144: .Fn fcntl ) ,
                    145: remain unchanged.
                    146: .Pp
                    147: If
                    148: .Fa file_actions
                    149: is not
                    150: .Dv NULL ,
                    151: then the file descriptors open in the child process are
                    152: those open in the calling process as modified by the spawn file
                    153: actions object pointed to by
                    154: .Fa file_actions
                    155: and the
                    156: .Dv FD_CLOEXEC
                    157: flag of each remaining open file descriptor after the spawn file actions
                    158: have been processed.
                    159: The effective order of processing the spawn file actions are:
                    160: .Bl -enum
                    161: .It
                    162: The set of open file descriptors for the child process initially
                    163: are the same set as is open for the calling process.
                    164: All attributes of the corresponding open file descriptions, including
                    165: file locks (see
                    166: .Fn fcntl ) ,
                    167: remain unchanged.
                    168: .It
                    169: The signal mask, signal default actions, and the effective user and
                    170: group IDs for the child process are changed as specified in the
                    171: attributes object referenced by
                    172: .Fa attrp .
                    173: .It
                    174: The file actions specified by the spawn file actions object are
                    175: performed in the order in which they were added to the spawn file
                    176: actions object.
                    177: .It
                    178: Any file descriptor that has its
                    179: .Dv FD_CLOEXEC
                    180: flag set (see
                    181: .Fn fcntl )
                    182: is closed.
                    183: .El
                    184: .Pp
                    185: The
                    186: .Vt posix_spawnattr_t
                    187: spawn attributes object type is defined in
                    188: .In spawn.h .
                    189: It contains the attributes defined below.
                    190: .Pp
                    191: If the
                    192: .Dv POSIX_SPAWN_SETPGROUP
                    193: flag is set in the spawn-flags attribute of the object referenced by
                    194: .Fa attrp ,
                    195: and the spawn-pgroup attribute of the same object is non-zero, then the
                    196: child's process group is as specified in the spawn-pgroup
                    197: attribute of the object referenced by
                    198: .Fa attrp .
                    199: .Pp
                    200: As a special case, if the
                    201: .Dv POSIX_SPAWN_SETPGROUP
                    202: flag is set in the spawn-flags attribute of the object referenced by
                    203: .Fa attrp ,
                    204: and the spawn-pgroup attribute of the same object is set to zero, then
                    205: the child is in a new process group with a process group ID equal
                    206: to its process ID.
                    207: .Pp
                    208: If the
                    209: .Dv POSIX_SPAWN_SETPGROUP
                    210: flag is not set in the spawn-flags attribute of the object referenced by
                    211: .Fa attrp ,
                    212: the new child process inherits the parent's process group.
                    213: .Pp
                    214: If the
                    215: .Dv POSIX_SPAWN_SETSCHEDPARAM
                    216: flag is set in the spawn-flags attribute of the object referenced by
                    217: .Fa attrp ,
                    218: but
                    219: .Dv POSIX_SPAWN_SETSCHEDULER
                    220: is not set, the new process image initially has the scheduling
                    221: policy of the calling process with the scheduling parameters specified
                    222: in the spawn-schedparam attribute of the object referenced by
                    223: .Fa attrp .
                    224: .Pp
                    225: If the
                    226: .Dv POSIX_SPAWN_SETSCHEDULER
                    227: flag is set in the spawn-flags attribute of the object referenced by
                    228: .Fa attrp
                    229: (regardless of the setting of the
                    230: .Dv POSIX_SPAWN_SETSCHEDPARAM
                    231: flag), the new process image initially has the scheduling policy
                    232: specified in the spawn-schedpolicy attribute of the object referenced by
                    233: .Fa attrp
                    234: and the scheduling parameters specified in the spawn-schedparam
                    235: attribute of the same object.
                    236: .Pp
                    237: The
                    238: .Dv POSIX_SPAWN_RESETIDS
                    239: flag in the spawn-flags attribute of the object referenced by
                    240: .Fa attrp
                    241: governs the effective user ID of the child process.
                    242: If this flag is not set, the child process inherits the parent
                    243: process' effective user ID.
                    244: If this flag is set, the child process' effective user ID is reset
                    245: to the parent's real user ID.
                    246: In either case, if the set-user-ID mode bit of the new process image
                    247: file is set, the effective user ID of the child process becomes
                    248: that file's owner ID before the new process image begins execution.
                    249: .Pp
                    250: The
                    251: .Dv POSIX_SPAWN_RESETIDS
                    252: flag in the spawn-flags attribute of the object referenced by
                    253: .Fa attrp
                    254: also governs the effective group ID of the child process.
                    255: If this flag is not set, the child process inherits the parent
                    256: process' effective group ID.
                    257: If this flag is set, the child process' effective group ID is
                    258: reset to the parent's real group ID.
                    259: In either case, if the set-group-ID mode bit of the new process image
                    260: file is set, the effective group ID of the child process becomes
                    261: that file's group ID before the new process image begins execution.
                    262: .Pp
                    263: If the
                    264: .Dv POSIX_SPAWN_SETSIGMASK
                    265: flag is set in the spawn-flags attribute of the object referenced by
                    266: .Fa attrp ,
                    267: the child process initially has the signal mask specified in the
                    268: spawn-sigmask attribute of the object referenced by
                    269: .Fa attrp .
                    270: .Pp
                    271: If the
                    272: .Dv POSIX_SPAWN_SETSIGDEF
                    273: flag is set in the spawn-flags attribute of the object referenced by
                    274: .Fa attrp ,
                    275: the signals specified in the spawn-sigdefault attribute of the same
                    276: object is set to their default actions in the child process.
                    277: Signals set to the default action in the parent process is set to
                    278: the default action in the child process.
                    279: .Pp
                    280: Signals set to be caught by the calling process is set to the
                    281: default action in the child process.
                    282: .Pp
                    283: Signals set to be ignored by the calling process image is set to
                    284: be ignored by the child process, unless otherwise specified by the
                    285: .Dv POSIX_SPAWN_SETSIGDEF
                    286: flag being set in the spawn-flags attribute of the object referenced by
                    287: .Fa attrp
                    288: and the signals being indicated in the spawn-sigdefault attribute
                    289: of the object referenced by
                    290: .Fa attrp .
                    291: .Pp
                    292: If the value of the
                    293: .Fa attrp
                    294: pointer is
                    295: .Dv NULL ,
                    296: then the default values are used.
                    297: .Pp
                    298: All process attributes, other than those influenced by the attributes
                    299: set in the object referenced by
                    300: .Fa attrp
                    301: as specified above or by the file descriptor manipulations specified in
                    302: .Fa file_actions ,
                    303: appear in the new process image as though
                    304: .Fn vfork
                    305: had been called to create a child process and then
                    306: .Fn execve
                    307: had been called by the child process to execute the new process image.
                    308: .Pp
                    309: The implementation uses vfork(), thus the fork handlers are not run when
                    310: .Fn posix_spawn
                    311: or
                    312: .Fn posix_spawnp
                    313: is called.
                    314: .Sh RETURN VALUES
                    315: Upon successful completion,
                    316: .Fn posix_spawn
                    317: and
                    318: .Fn posix_spawnp
                    319: return the process ID of the child process to the parent process,
                    320: in the variable pointed to by a
                    321: .Pf non- Dv NULL
                    322: .Fa pid
                    323: argument, and return zero as the function return value.
                    324: Otherwise, no child process is created, no value is stored into
                    325: the variable pointed to by
                    326: .Fa pid ,
                    327: and an error number is returned as the function return value to
                    328: indicate the error.
                    329: If the
                    330: .Fa pid
                    331: argument is a null pointer, the process ID of the child is not returned
                    332: to the caller.
                    333: .Sh ERRORS
                    334: .Bl -enum
                    335: .It
                    336: If
                    337: .Fn posix_spawn
                    338: and
                    339: .Fn posix_spawnp
                    340: fail for any of the reasons that would cause
                    341: .Fn vfork
                    342: or one of the
                    343: .Nm exec
                    344: to fail, an error value is returned as described by
                    345: .Fn vfork
                    346: and
                    347: .Nm exec ,
                    348: respectively (or, if the error occurs after the calling process successfully
                    349: returns, the child process exits with exit status 127).
                    350: .It
                    351: If
                    352: .Nm POSIX_SPAWN_SETPGROUP
                    353: is set in the spawn-flags attribute of the object referenced by attrp, and
                    354: .Fn posix_spawn
                    355: or
                    356: .Fn posix_spawnp
                    357: fails while changing the child's process group, an error value is returned as
                    358: described by
                    359: .Fn setpgid
                    360: (or, if the error occurs after the calling process successfully returns,
                    361: the child process exits with exit status 127).
                    362: .It
                    363: If
                    364: .Nm POSIX_SPAWN_SETSCHEDPARAM
                    365: is set and
                    366: .Nm POSIX_SPAWN_SETSCHEDULER
                    367: is not set in the spawn-flags attribute of the object referenced by attrp, then
                    368: if
                    369: .Fn posix_spawn
                    370: or
                    371: .Fn posix_spawnp
                    372: fails for any of the reasons that would cause
                    373: .Fn sched_setparam
                    374: to fail, an error value is returned as described by
                    375: .Fn sched_setparam
                    376: (or, if the error occurs after the calling process successfully returns, the
                    377: child process exits with exit status 127).
                    378: .It
                    379: If
                    380: .Nm POSIX_SPAWN_SETSCHEDULER
                    381: is set in the spawn-flags attribute of the object referenced by attrp, and if
                    382: .Fn posix_spawn
                    383: or
                    384: .Fn posix_spawnp
                    385: fails for any of the reasons that would cause
                    386: .Fn sched_setscheduler
                    387: to fail, an error value is returned as described by
                    388: .Fn sched_setscheduler
                    389: (or, if the error occurs after the calling process successfully returns,
                    390: the child process exits with exit status 127).
                    391: .It
                    392: If the
                    393: .Fa file_actions
                    394: argument is not
                    395: .Dv NULL ,
                    396: and specifies any
                    397: .Fn close ,
                    398: .Fn dup2 ,
                    399: or
                    400: .Fn open
                    401: actions to be performed, and if
                    402: .Fn posix_spawn
                    403: or
                    404: .Fn posix_spawnp
                    405: fails for any of the reasons that would cause
                    406: .Fn close ,
                    407: .Fn dup2 ,
                    408: or
                    409: .Fn open
                    410: to fail, an error value is returned as described by
                    411: .Fn close ,
                    412: .Fn dup2 ,
                    413: and
                    414: .Fn open ,
                    415: respectively (or, if the error occurs after the calling process successfully
                    416: returns, the child process exits with exit status 127). An open file action
                    417: may, by itself, result in any of the errors described by
                    418: .Fn close
                    419: or
                    420: .Fn dup2 ,
                    421: in addition to those described by
                    422: .Fn open .
                    423: .El
                    424: .Sh SEE ALSO
                    425: .Xr close 2 ,
                    426: .Xr dup2 2 ,
                    427: .Xr execve 2 ,
                    428: .Xr fcntl 2 ,
                    429: .Xr open 2 ,
                    430: .Xr setpgid 2 ,
                    431: .Xr vfork 2 ,
                    432: .Xr posix_spawn_file_actions_addclose 3 ,
                    433: .Xr posix_spawn_file_actions_adddup2 3 ,
                    434: .Xr posix_spawn_file_actions_addopen 3 ,
                    435: .Xr posix_spawn_file_actions_destroy 3 ,
                    436: .Xr posix_spawn_file_actions_init 3 ,
                    437: .Xr posix_spawnattr_destroy 3 ,
                    438: .Xr posix_spawnattr_getflags 3 ,
                    439: .Xr posix_spawnattr_getpgroup 3 ,
                    440: .Xr posix_spawnattr_getschedparam 3 ,
                    441: .Xr posix_spawnattr_getschedpolicy 3 ,
                    442: .Xr posix_spawnattr_getsigdefault 3 ,
                    443: .Xr posix_spawnattr_getsigmask 3 ,
                    444: .Xr posix_spawnattr_init 3 ,
                    445: .Xr posix_spawnattr_setflags 3 ,
                    446: .Xr posix_spawnattr_setpgroup 3 ,
                    447: .Xr posix_spawnattr_setschedparam 3 ,
                    448: .Xr posix_spawnattr_setschedpolicy 3 ,
                    449: .Xr posix_spawnattr_setsigdefault 3 ,
1.2       njoly     450: .Xr posix_spawnattr_setsigmask 3 ,
                    451: .Xr sched_setparam 3 ,
                    452: .Xr sched_setscheduler 3
1.1       martin    453: .Sh STANDARDS
                    454: The
                    455: .Fn posix_spawn
                    456: and
                    457: .Fn posix_spawnp
                    458: functions conform to
                    459: .St -p1003.1-2001 .
                    460: .Sh HISTORY
                    461: The
                    462: .Fn posix_spawn
                    463: and
                    464: .Fn posix_spawnp
                    465: functions first appeared in
                    466: .Fx 8.0 .
                    467: The library parts were ported and a kernel implementation of
                    468: .Fn posix_spawn
                    469: added for
1.3     ! njoly     470: .Nx 6.0
1.1       martin    471: during Google Summer of Code by Charles Zhang and Martin Husemann.
                    472: .Sh AUTHORS
                    473: .An Ed Schouten Aq ed@FreeBSD.org

CVSweb <webmaster@jp.NetBSD.org>