[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.2.2.1

1.2.2.1 ! sborrill    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
1.2.2.1 ! sborrill  185: The maximum number of
        !           186: .Fa file_actions
        !           187: objects is limited to the
        !           188: .Dv RLIMIT_NOFILE
        !           189: rlimit times 2.
        !           190: .Pp
1.1       martin    191: The
                    192: .Vt posix_spawnattr_t
                    193: spawn attributes object type is defined in
                    194: .In spawn.h .
                    195: It contains the attributes defined below.
                    196: .Pp
                    197: If the
                    198: .Dv POSIX_SPAWN_SETPGROUP
                    199: flag is set in the spawn-flags attribute of the object referenced by
                    200: .Fa attrp ,
                    201: and the spawn-pgroup attribute of the same object is non-zero, then the
                    202: child's process group is as specified in the spawn-pgroup
                    203: attribute of the object referenced by
                    204: .Fa attrp .
                    205: .Pp
                    206: As a special case, if the
                    207: .Dv POSIX_SPAWN_SETPGROUP
                    208: flag is set in the spawn-flags attribute of the object referenced by
                    209: .Fa attrp ,
                    210: and the spawn-pgroup attribute of the same object is set to zero, then
                    211: the child is in a new process group with a process group ID equal
                    212: to its process ID.
                    213: .Pp
                    214: If the
                    215: .Dv POSIX_SPAWN_SETPGROUP
                    216: flag is not set in the spawn-flags attribute of the object referenced by
                    217: .Fa attrp ,
                    218: the new child process inherits the parent's process group.
                    219: .Pp
                    220: If the
                    221: .Dv POSIX_SPAWN_SETSCHEDPARAM
                    222: flag is set in the spawn-flags attribute of the object referenced by
                    223: .Fa attrp ,
                    224: but
                    225: .Dv POSIX_SPAWN_SETSCHEDULER
                    226: is not set, the new process image initially has the scheduling
                    227: policy of the calling process with the scheduling parameters specified
                    228: in the spawn-schedparam attribute of the object referenced by
                    229: .Fa attrp .
                    230: .Pp
                    231: If the
                    232: .Dv POSIX_SPAWN_SETSCHEDULER
                    233: flag is set in the spawn-flags attribute of the object referenced by
                    234: .Fa attrp
                    235: (regardless of the setting of the
                    236: .Dv POSIX_SPAWN_SETSCHEDPARAM
                    237: flag), the new process image initially has the scheduling policy
                    238: specified in the spawn-schedpolicy attribute of the object referenced by
                    239: .Fa attrp
                    240: and the scheduling parameters specified in the spawn-schedparam
                    241: attribute of the same object.
                    242: .Pp
                    243: The
                    244: .Dv POSIX_SPAWN_RESETIDS
                    245: flag in the spawn-flags attribute of the object referenced by
                    246: .Fa attrp
                    247: governs the effective user ID of the child process.
                    248: If this flag is not set, the child process inherits the parent
                    249: process' effective user ID.
                    250: If this flag is set, the child process' effective user ID is reset
                    251: to the parent's real user ID.
                    252: In either case, if the set-user-ID mode bit of the new process image
                    253: file is set, the effective user ID of the child process becomes
                    254: that file's owner ID before the new process image begins execution.
                    255: .Pp
                    256: The
                    257: .Dv POSIX_SPAWN_RESETIDS
                    258: flag in the spawn-flags attribute of the object referenced by
                    259: .Fa attrp
                    260: also governs the effective group ID of the child process.
                    261: If this flag is not set, the child process inherits the parent
                    262: process' effective group ID.
                    263: If this flag is set, the child process' effective group ID is
                    264: reset to the parent's real group ID.
                    265: In either case, if the set-group-ID mode bit of the new process image
                    266: file is set, the effective group ID of the child process becomes
                    267: that file's group ID before the new process image begins execution.
                    268: .Pp
                    269: If the
                    270: .Dv POSIX_SPAWN_SETSIGMASK
                    271: flag is set in the spawn-flags attribute of the object referenced by
                    272: .Fa attrp ,
                    273: the child process initially has the signal mask specified in the
                    274: spawn-sigmask attribute of the object referenced by
                    275: .Fa attrp .
                    276: .Pp
                    277: If the
                    278: .Dv POSIX_SPAWN_SETSIGDEF
                    279: flag is set in the spawn-flags attribute of the object referenced by
                    280: .Fa attrp ,
                    281: the signals specified in the spawn-sigdefault attribute of the same
                    282: object is set to their default actions in the child process.
                    283: Signals set to the default action in the parent process is set to
                    284: the default action in the child process.
                    285: .Pp
                    286: Signals set to be caught by the calling process is set to the
                    287: default action in the child process.
                    288: .Pp
                    289: Signals set to be ignored by the calling process image is set to
                    290: be ignored by the child process, unless otherwise specified by the
                    291: .Dv POSIX_SPAWN_SETSIGDEF
                    292: flag being set in the spawn-flags attribute of the object referenced by
                    293: .Fa attrp
                    294: and the signals being indicated in the spawn-sigdefault attribute
                    295: of the object referenced by
                    296: .Fa attrp .
                    297: .Pp
                    298: If the value of the
                    299: .Fa attrp
                    300: pointer is
                    301: .Dv NULL ,
                    302: then the default values are used.
                    303: .Pp
                    304: All process attributes, other than those influenced by the attributes
                    305: set in the object referenced by
                    306: .Fa attrp
                    307: as specified above or by the file descriptor manipulations specified in
                    308: .Fa file_actions ,
                    309: appear in the new process image as though
                    310: .Fn vfork
                    311: had been called to create a child process and then
                    312: .Fn execve
                    313: had been called by the child process to execute the new process image.
                    314: .Pp
                    315: The implementation uses vfork(), thus the fork handlers are not run when
                    316: .Fn posix_spawn
                    317: or
                    318: .Fn posix_spawnp
                    319: is called.
                    320: .Sh RETURN VALUES
                    321: Upon successful completion,
                    322: .Fn posix_spawn
                    323: and
                    324: .Fn posix_spawnp
                    325: return the process ID of the child process to the parent process,
                    326: in the variable pointed to by a
                    327: .Pf non- Dv NULL
                    328: .Fa pid
                    329: argument, and return zero as the function return value.
                    330: Otherwise, no child process is created, no value is stored into
                    331: the variable pointed to by
                    332: .Fa pid ,
                    333: and an error number is returned as the function return value to
                    334: indicate the error.
                    335: If the
                    336: .Fa pid
                    337: argument is a null pointer, the process ID of the child is not returned
                    338: to the caller.
                    339: .Sh ERRORS
                    340: .Bl -enum
                    341: .It
                    342: If
                    343: .Fn posix_spawn
                    344: and
                    345: .Fn posix_spawnp
                    346: fail for any of the reasons that would cause
                    347: .Fn vfork
                    348: or one of the
                    349: .Nm exec
                    350: to fail, an error value is returned as described by
                    351: .Fn vfork
                    352: and
                    353: .Nm exec ,
                    354: respectively (or, if the error occurs after the calling process successfully
                    355: returns, the child process exits with exit status 127).
                    356: .It
                    357: If
                    358: .Nm POSIX_SPAWN_SETPGROUP
                    359: is set in the spawn-flags attribute of the object referenced by attrp, and
                    360: .Fn posix_spawn
                    361: or
                    362: .Fn posix_spawnp
                    363: fails while changing the child's process group, an error value is returned as
                    364: described by
                    365: .Fn setpgid
                    366: (or, if the error occurs after the calling process successfully returns,
                    367: the child process exits with exit status 127).
                    368: .It
                    369: If
                    370: .Nm POSIX_SPAWN_SETSCHEDPARAM
                    371: is set and
                    372: .Nm POSIX_SPAWN_SETSCHEDULER
                    373: is not set in the spawn-flags attribute of the object referenced by attrp, then
                    374: if
                    375: .Fn posix_spawn
                    376: or
                    377: .Fn posix_spawnp
                    378: fails for any of the reasons that would cause
                    379: .Fn sched_setparam
                    380: to fail, an error value is returned as described by
                    381: .Fn sched_setparam
                    382: (or, if the error occurs after the calling process successfully returns, the
                    383: child process exits with exit status 127).
                    384: .It
                    385: If
                    386: .Nm POSIX_SPAWN_SETSCHEDULER
                    387: is set in the spawn-flags attribute of the object referenced by attrp, and if
                    388: .Fn posix_spawn
                    389: or
                    390: .Fn posix_spawnp
                    391: fails for any of the reasons that would cause
                    392: .Fn sched_setscheduler
                    393: to fail, an error value is returned as described by
                    394: .Fn sched_setscheduler
                    395: (or, if the error occurs after the calling process successfully returns,
                    396: the child process exits with exit status 127).
                    397: .It
                    398: If the
                    399: .Fa file_actions
                    400: argument is not
                    401: .Dv NULL ,
                    402: and specifies any
                    403: .Fn close ,
                    404: .Fn dup2 ,
                    405: or
                    406: .Fn open
                    407: actions to be performed, and if
                    408: .Fn posix_spawn
                    409: or
                    410: .Fn posix_spawnp
                    411: fails for any of the reasons that would cause
                    412: .Fn close ,
                    413: .Fn dup2 ,
                    414: or
                    415: .Fn open
                    416: to fail, an error value is returned as described by
                    417: .Fn close ,
                    418: .Fn dup2 ,
                    419: and
                    420: .Fn open ,
                    421: respectively (or, if the error occurs after the calling process successfully
                    422: returns, the child process exits with exit status 127). An open file action
                    423: may, by itself, result in any of the errors described by
                    424: .Fn close
                    425: or
                    426: .Fn dup2 ,
                    427: in addition to those described by
                    428: .Fn open .
1.2.2.1 ! sborrill  429: Finally, if the number of
        !           430: .Fa file_actions
        !           431: objects exceeds the allowed limit,
        !           432: .Er EINVAL
        !           433: is returned.
1.1       martin    434: .El
                    435: .Sh SEE ALSO
                    436: .Xr close 2 ,
                    437: .Xr dup2 2 ,
                    438: .Xr execve 2 ,
                    439: .Xr fcntl 2 ,
                    440: .Xr open 2 ,
                    441: .Xr setpgid 2 ,
                    442: .Xr vfork 2 ,
                    443: .Xr posix_spawn_file_actions_addclose 3 ,
                    444: .Xr posix_spawn_file_actions_adddup2 3 ,
                    445: .Xr posix_spawn_file_actions_addopen 3 ,
                    446: .Xr posix_spawn_file_actions_destroy 3 ,
                    447: .Xr posix_spawn_file_actions_init 3 ,
                    448: .Xr posix_spawnattr_destroy 3 ,
                    449: .Xr posix_spawnattr_getflags 3 ,
                    450: .Xr posix_spawnattr_getpgroup 3 ,
                    451: .Xr posix_spawnattr_getschedparam 3 ,
                    452: .Xr posix_spawnattr_getschedpolicy 3 ,
                    453: .Xr posix_spawnattr_getsigdefault 3 ,
                    454: .Xr posix_spawnattr_getsigmask 3 ,
                    455: .Xr posix_spawnattr_init 3 ,
                    456: .Xr posix_spawnattr_setflags 3 ,
                    457: .Xr posix_spawnattr_setpgroup 3 ,
                    458: .Xr posix_spawnattr_setschedparam 3 ,
                    459: .Xr posix_spawnattr_setschedpolicy 3 ,
                    460: .Xr posix_spawnattr_setsigdefault 3 ,
1.2       njoly     461: .Xr posix_spawnattr_setsigmask 3 ,
                    462: .Xr sched_setparam 3 ,
                    463: .Xr sched_setscheduler 3
1.1       martin    464: .Sh STANDARDS
                    465: The
                    466: .Fn posix_spawn
                    467: and
                    468: .Fn posix_spawnp
                    469: functions conform to
                    470: .St -p1003.1-2001 .
                    471: .Sh HISTORY
                    472: The
                    473: .Fn posix_spawn
                    474: and
                    475: .Fn posix_spawnp
                    476: functions first appeared in
                    477: .Fx 8.0 .
                    478: The library parts were ported and a kernel implementation of
                    479: .Fn posix_spawn
                    480: added for
                    481: .Nx 6
                    482: during Google Summer of Code by Charles Zhang and Martin Husemann.
                    483: .Sh AUTHORS
                    484: .An Ed Schouten Aq ed@FreeBSD.org

CVSweb <webmaster@jp.NetBSD.org>