spawn2(), spawnp2() — Spawn a new process using enhanced inheritance structure

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.

__spawn2(), __spawnp2() — Spawn a new process using enhanced inheritance structure

Standards

Format

General description

Returned value

Related information

spawn2(), spawnp2() — Spawn a new process using enhanced inheritance structure