Standards
Standards / Extensions |
C or C++ |
Dependencies |
XPG4
XPG4.2
|
both |
POSIX(ON) |
Format
#include <spawn.h>
pid_t __spawn2(const char *path,
const int fd_count,
const int fd_map[],
const struct __inheritance *inherit,
const char *argv[],
const char *envp[]);
pid_t __spawnp2(const char *file,
const int fd_count,
const int fd_map[],
const struct __inheritance *inherit,
const char *argv[],
const char *envp[]);
General description
The __spawn2() and
__spawnp2() functions creates a new process from the specified process
image. The new process image is constructed from a regular executable
file called the new process image file.
To execute a C program
as a result of this call, enter the function call as follows:
int main (int argc, char *argv[]);
Where
argc is
the argument count and
argv is an array
of character pointers to the arguments themselves. In addition, the
following variable:
extern char **environ;
is
initialized as a pointer to an array of character pointers to the
environment strings. The
argv and
environ arrays
are each terminated by a NULL pointer. The NULL pointer terminating
the
argv array is not counted in
argc.
Supported
parameters are:
- Parameter
- Description
- path
- Path name used by __spawn2() that identifies the new process image
file to execute.
- file
- Used by __spawnp2() to construct a path name that identifies the
new process image file. If the file parameter contains a slash character,
the file parameter shall be used as a path name for the new process
image file. Otherwise, the path prefix for this file shall be obtained
by a search of the directories passed as the environment variable
PATH.
- fd-count
- Specifies the number of file descriptors the child process shall
inherit. It may take values from zero to OPEN_MAX. Except
those file descriptors designated by SPAWN_FDCLOSED, each of the child's
file descriptors, x, in the range zero to fd_count-1
shall inherit descriptor fd_map(x) from
the parent process.
The files from fd_count through OPEN_MAX are
closed in the child process, as are any elements of fd_map designated
as SPAWN_FDCLOSED.
- fd-map
- If the fd_map parameter is NULL, fd_count and fd_map are
ignored. All file descriptors except those with the FD_CLOEXEC or FD_CLOFORK attribute
are inherited without reordering. File descriptors with the FD_CLOEXEC or FD_CLOFORK attribute
are closed under simple inheritance.
For those file descriptors
that remain open, all other attributes of the associated file descriptor
object and open file description shall remain unchanged by this operation.
Directory
streams open in the calling process image shall be closed in the new
process image, with the effect of the closedir() operation.
If
an element of fd_map refers to an invalid
file descriptor, then the (EBADF) error status shall be posted by
__spawn2() or __spawnp2().
The FD_CLOEXEC and FD_CLOFORK file
descriptor attributes are never inherited.
The FD_CLOEXEC and FD_CLOFORK file
descriptor attributes have no effect on inheritance when the fd_map parameter
is not NULL.
Note: For XTI endpoints, fd_map must
not map to a number greater than 65535 in the child process.
- inherit
- The name of a data area that contains the inheritance structure.
The 'struct __inheritance' is defined as follows:
struct __inheritance {
short flags; -- Flags
pid_t pgroup; -- Process group
sigset_t sigmask; -- Signal mask
sigset_t sigdefault; -- Signals set to SIG_DFL
int ctlttyfd; -- Cntl tty FD for tcsetpgrp()
char *cwdptr; -- Pointer to the users CWD
int cwdlen; -- Length of the users CWD
int acctdatalen; -- Length of account data area
char *acctdataptr; -- Ptr to account data area
int umask; -- Users UMASK
char userid[9]; -- New A.S. user identity
char jobname[9]; -- New A.S. jobname
int regionsize; -- New A.S. region size
int timelimit; -- New A.S. time limit
union { -- New A.S. memlimit # of bytes
#ifdef _LP64
unsigned long memlimit;
#define __memlimit memlimit_u.memlimit
#endif
#ifdef __LL
unsigned long long memlimit_ll;
#define __memlimit_ll memlimit_u.memlimit_ll
#endif
unsigned int memlimit_i[2];
#define __memlimit_h memlimit_u.memlimit_i[0]
#define __memlimit_l memlimit_u.memlimit_i[1]
double memlimit_d;
} memlimit_u;
}
The
inherit.flags effect spawn()
and spawnp() as follows:
- SPAWN_SETGROUP
- If the SPAWN_SETGROUP flag is set in inherit.flags,
then the child's process group shall be as specified in inherit.pgroup.
If the SPAWN_SETGROUP flag is set in inherit.flags and inherit.pgroup is
set to SPAWN_NEWPGROUP, then the child shall be in a new process group
with a process group ID equal to its process ID.
If the SPAWN_SETGROUP
flag is not set in inherit.flags, the new
child shall inherit the parent's process group ID.
- SPAWN_SETSIGMASK
- If the SPAWN_SETSIGMASK flag is set in inherit.flags,
the child process shall initially have the signal mask specified in inherit.sigmask.
- SPAWN_SETSIGDEF
- If the SPAWN_SETSIGDEF flag is set in inherit.flags,
the signals specified in inherit.sigdefault shall
be set to their default actions in the child process. Signals set
the default action in the parent process shall be set to the default
action in the new process.
Signals set to be caught by the calling
process shall be set to the default action in the child process.
Signals
set to be ignored by the calling process shall be set to be ignored
by the new process, unless otherwise specified by the SPAWN_SETSIGDEF
flag being set in inherit_flags and the
signal being indicated inherit.sigdefault.
- SPAWN_SETTCPGRP
- If the SPAWN_SETTCPGRP flag is set in inherit.flag,
the file descriptor specified in inherit.ctlttyfd is
used to set the controlling terminal file descriptor (tcsetpgrp())
for the child's foreground process group. The child's foreground
process group is inherited from the parent, unless the SPAWN_SETGROUP
flag in inherit.flags is set, indicating
that the value specified in inherit.pgroup is
to be used to determine the child's process group.
- argv
- The value in the first element of argv should
point to a file name that is associated with the process being started
by the spawn2() or spawnp2() operation.
The number of bytes available
for the new process's combined argument and environment lists is ARG_MAX.
- envp
- The value envp contains the list of
environmental variables that is to be passed to the specified program.
If the set-user-ID mode bit of the new process
image file is set, the effective user ID of the new process image
shall be set to the owner ID of the new process image file. Similarly,
if the set-group-ID mode bit of the new process image file is set,
the effective group ID of the new process image shall be set to the
group ID of the new process image file. The real user ID, real group
ID, and supplementary group IDs of the new process image shall remain
the same as those of the calling process image. The effective user
ID and effective group ID of the new process image shall be saved
(as the saved set-user-ID and set-group-ID) for use by the setuid()
function.
The new process image shall inherit the following
attributes of the calling process image:
- Process group ID (unless the SPAWN_SETGROUP flag is set in inherit.flags).
- Session membership.
- Real user ID.
- Real group ID.
- Supplementary group IDs.
- Priority.
- Current working
directory.
- File creation mask.
- Signal mask (unless the SPAWN_SETSIGMASK flag is set in inherit.flags).
- Signal actions specified as default (SIG_DFL).
- Signal actions specified as ignore (SIG_IGN) (except as modified
by inherit.sigdefault and the SPAWN_SETSIGDEF
flag set in inherit.flags).
The following are differences between the parent process
and child:
- Signals set to be caught by the calling process shall be set to
the default action (SIG_DFL).
- The process and system utilization times for the child are set
to zero.
- Any file locks previously set by the parent are not inherited
by the child.
- The child process has no alarms set and has no interval timers
set.
- The child has no pending signals.
- Memory mappings established by the parent are not inherited by
the child.
If the process image was read from a writable file system,
then upon successful completion, the __spawn2() and __spawnp2() functions
will mark for update the st_time field of
the new process image file.
If the __spawn2() or __spawnp2()
function is successful, the new child process image file shall be
opened with all the effects of the open() function.
All the
following inherit flags are used by __spawn2() and __spawnp2():
- SPAWN_SETCWD
- Specifies the Current Working
Directory that the child process will run when first created. This
will override the CWD that would normally be set up or propagated
by the child process.
- SPAWN_SETUMASK
- Specifies the UMASK that the child process will run when first
created. This will override the UMASK that would normally be set
up in the child process. The invoker must have superuser privileges
to specify UMASK.
- SPAWN_SETUSERID
- When this flag is set, this attribute will be the equivalent of
the _BPX_USERID environment variable. If specified, the invoking
userid will be checked for daemon authority. If the invoker is authorized
and the userid is valid, the child process will be created with RACF® identity and POSIX permissions
associated with the input USERID. If not authorized or the userid
is invalid, the __spawn2() or __spawnp2() function will fail. If
the USERID value is specified, any value in _BPX_USERID will be ignored.
- SPAWN_SETREGIONSZ
- Specifies the number of megabytes the child process will have
available for private storage. The authority/ranges required will
be as per RLIMIT_AS rules. Unless
the invoker has superuser privileges, the region size range will be
checked and if it exceeds the hard limit, the __spawn2() or __spawnp2()
function will fail. This value will override RLIMIT_AS or the normal
spawn propagation rules.
- SPAWN_SETTIMELIMIT
- Specifies the number of seconds of CPU time that is allowed by
the child process before receiving a SIGXCPU signal. Unless
the invoker has superuser privileges, the time limit range will be
checked and if it exceeds the hard limit, the __spawn2() or __spawnp2()
function will fail. This value will override the RLIMIT_CPU or the
normal spawn propagation rules.
- SPAWN_SETACCTDATA
- Specifies account data of the child process. The format and length
will be as per the _BPX_ACCT_DATA environmental variable. No special
authority is needed to change account data. This will override the
target userid's default account data and any value specified on the
_BPX_ACCT_DATA will be ignored.
- SPAWN_SETJOBNAME
- When this flag is set, it is the equivalent of the _BPX_JOBNAME
environment variable. If specified, the invoking userid will be checked
for superuser authority. If the invoker
is authorized and the jobname is valid, the child process will be
created with the specified jobname. If not authorized or the jobname
is invalid, __spawn2() or __spawnp2() will ignore the JOBNAME attribute
and continue. If the JOBNAME value is specified, any value in _BPX_JOBNAME
will be ignored.
- SPAWN_MUSTBELOCAL
- When this flag is set, it is the equivalent of the _BPX_SHAREAS=MUST
environment variable. If specified, the system will attempt a local
spawn, otherwise the request will fail.
- SPAWN_SETMEMLIMIT
- When this flag is set and not doing a local spawn, inherit.memlimit_u
determines the maximum amount of bytes the child address space is
allowed to obtain above the 2-gigabyte bar. If the specified value
exceeds the current hard limit, the invoking userid must have appropriate
privileges, otherwise the request will fail.
- SPAWN_PROCESS_INITTAB
- If this flag is set, spawn attempts to read the /etc/inittab file
and process the entries found there. This processing involves the
spawning of child shell processes to run each of the commands identified
in the file. Only the SPAWN_SETSIGMASK flag can be
set in combination with this flag. All other flags will be ignored.
Use of this flag implies that only file descriptors 0, 1, and 2 will
be initially opened in the child process. File descriptor 0 will be
initially opened as /dev/null, while file descriptors 1 and 2 will
initially opened as /etc/log. The fd_count and fd_map parameters
will be ignored. This flag is currently restricted to the /usr/sbin/init
process. See z/OS UNIX System Services Planningfor
more information on the /etc/inittab support.
For more information on the use of inheritance
structure flags, see z/OS UNIX System Services Programming: Assembler Callable Services Reference.
Returned value
If successful, __spawn2()
or __spawnp2() returns the process ID of the child process to the
parent.
If unsuccessful, __spawn2() or __spawnp2() returns
-1 to the parent process, no child is created, and they set errno
to one of the following values:
- Error Code
- Description
- E2BIG
- The number of bytes used by the argument and environment list
of the new process image is greater than the system-imposed limit
of ARG_MAX bytes.
- EACCES
- Search permission is denied for a directory in the path of the
new process image file or the new process image file denies execution
permission, or the the new process image file is not a regular file
and the implementation does not support execution of files of its
type.
- EAGAIN
- The system lacked the necessary resources to create another process,
or the system-imposed limit on the total number of processes under
execution by a single user would be exceeded. The resources required
to let another process be created are not available, or you have already
reached the maximum number of processes or UIDs you are allowed to
create. This error will also be generated if _BPX_USERID or INHEUSERID
was specified and the username was not defined to SAF with a segment.
- EBADF
- An entry in the fd_map array refers
to an invalid file descriptor or the controlling terminal file descriptor
specified in the __inheritance structure.
- EFAULT
- The system detected an invalid address while attempting to use
a parameter of the call.
- EINVAL
- One or more of the following conditions were detected:
- The username that was specified on the _BPX_USERID environment
variable has an incorrect length.
- An attribute that was specified in the inheritance structure (BPXYINHE)
is not valid or contains an unsupported value.
- The version number that was specified for the inheritance structure
(BPXYINHE) is not valid.
- The inheritance structure length that was specified by the Inherit_area_len
parameter or within the inheritance structure does not contain a length
that is appropriate for the BPXYINHE version.
- The process group ID that was specified in the inheritance structure
is less than zero or has some other unsupported value.
The following reason codes can accompany the return code:
JROK, JRUserNameLenError, JRJsRacXtr, JRInheUserid, JRInheRegion,
JRInheCPUTime, JRInheDynamber, JRInheAccountData, JRInheCWD, JRInheSetPgrp,
JRInheVersion, and JRInheLength.
- ELOOP
- A loop exists in symbolic links encountered during resolution
of the file name argument. This error is issued if more than 8 symbolic
links are detected.
- EMVSERR
-
The spawn failed for the following reason: Local spawn not
allowed. Either the environment variable _BPX_SHAREAS was set to
MUST (_BPX_SHAREAS=MUST), or the __inheritance structure specified
SPAWN_MUSTBELOCAL.
The following reason code can accompany
the return code: JRLocalSpawnNotAllowed.
- EMVSSAF2ERR
- The executable file is a set-user-ID or set-group-ID file and
the owner's UID or GID is not defined to the Security Authorization
Facility (SAF).
- ENAMETOOLONG
- The length of the path or file parameter, or an element of the
environmental variable PATH prefixed to a file, exceeds PATH_MAX,
or a path name component is longer than NAME_MAX and {_POSIX_N_TRUNC_}
is in effect for that file.
- ENOENT
- One or more components of the path name of the new process image
file do not exist or the path or file parameter is empty.
- ENOEXEC
- The new process image file has the appropriate access permission,
but is not in the proper format.
Note: Reason codes further qualify
the errno. For most of the reason codes, see z/OS UNIX System Services Messages and Codes.
For
ENOEXEC, the reason codes are:
Reason Code |
Explanation |
X'xxxx0C27' |
The target HFS file is not in the correct format to be
an executable file. |
X'xxxx0C31' |
The target HFS file is built at a level that is higher
than that supported by the running system. |
- ENOMEM
- The new process requires more memory than is permitted by the
hardware or operating system.
- ENOTDIR
- A component of the path prefix of the new process image file is
not a directory.
- ENOTTY
- tcsetpgrp() failed for the specified controlling terminal file
descriptor in __inheritance structure. The failure occurred because
the calling process does not have a controlling terminal, or the specified
file descriptor is not associated with the controlling terminal, or
the controlling terminal is no longer associated with the session
of the calling process.
- EPERM
- The spawn failed for one of the following reasons:
- The spawned process is not a process group leader.
- The _BPX_USERID environment variable was specified, and the invoker
does not have appropriate privileges to change the MVS™ identity.
- The invoker does not have the appropriate privileges to change
one or more of the attributes specified in the inheritance structure
(BPXYINHE).
The following reason codes can accompany the return code:
JROK, JRNoChangeIdentity, JRInheUserid, JRInheRegion, JRInheCPUTime,
JRInheUmask, JRInheCWD and JRInheMemLimit.
- ESRCH
- The process group ID specified in the __inheritance structure
is not that of s process group in the calling process's session.