spawn (BPX1SPN, BPX4SPN) — Spawn a process

Function

The spawn callable service combines the semantics of the fork and exec callable services to create a child process to run a specified z/OS UNIX executable file.

Requirements

Operation	Environment
Authorization:	Supervisor or problem state, any PSW key, any TCB key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1SPN):	31-bit
AMODE (BPX4SPN):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

CALL BPX1SPN,(Pathname_length,
              Pathname,
              Argument_count,
              Argument_length_list,
              Argument_list,
              Environment_count,
              Environment_data_length,
              Environment_data_list,
              Filedesc_count,
              Filedesc_list,
              Inherit_area_len,
              Inherit_area,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SPN with the same parameters. All parameter addresses and addresses in parameter structures are doublewords.

Parameters

Pathname_length

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the length of the path name of the file. The length of the path name can be up to 1023 bytes.

Pathname

Supplied parameter

Type:: Character string
Character set:: No restriction
Length:: Specified by the Pathname_length parameter

The name of a field that contains the fully qualified path name of the file that is to be run. Each component of the path name (directory name, subdirectory name, or file name) can be up to 255 characters long. The complete path name can be up to 1023 characters long, and does not require an ending NUL character.

Path names can begin with or without a slash.

If the path name begins with a slash, it is an absolute path name; the slash refers to the root directory, and the search for the file starts at the root directory.
If the path name does not begin with a slash, it is a relative path name; the search for the file starts at the working directory.

Argument_count

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the number of pointers in the lists for the Argument_length_list and the Argument_list. If the program needs no arguments, specify 0.

Argument_length_list

Supplied parameter

Type:: Structure
Length:: Variable

The name of a list of 31(64)-bit pointers. Each pointer in the list is the 31(64)-bit address of a fullword that gives the length of an argument that is to be passed to the specified program. If the program needs no arguments, define Argument_length_list as the name of a fullword (doubleword) that contains 0.

If the target executable file arguments require null terminators, the arguments that are supplied to this service must include the null terminator as part of the data string and the length.

Argument_list

Supplied parameter

Type:: Structure
Length:: Variable specified by Argument_length_list

The name of a list of 31(64)-bit pointers. Each pointer in the list is the 31(64)-bit address of a character string that is an argument to be passed to the specified program. Each argument is of the length that is specified by the corresponding element in the Argument_length_list. If the program needs no arguments, define Argument_list as the name of a fullword (doubleword) that contains 0.

Environment_count

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the number of pointers in the lists for Environment_data_length and Environment_data_list. If the program needs no environment data, specify 0.

Environment_data_length

Supplied parameter

Type:: Structure
Length:: Variable

The name of a list of 31(64)-bit pointers. Each 31(64)-bit pointer in the list is the 31(64)-bit address of a fullword that gives the length of an environment variable that is to be passed to the specified program. If the program does not use environment variables, specify 0.

Environment_data_list

Supplied parameter

Type:: Structure
Length:: Variable, specified by Environment_data_length

The name of a list of 31(64)-bit pointers. Each 31(64)-bit pointer in the list is the 31(64)-bit address of a character string that is an environment variable to be passed to the specified program. Each environment variable is of the length that is specified by the corresponding element in Environment_data_length. If the program does not use environment variables, specify 0.

If the target executable file is an IBM® Language Environment®-enabled program, the environment variables that are supplied to this service must include the null terminator as part of the data string and length. Trailing blanks can cause the environment variable to be processed incorrectly. Each environment variable is searched for a null character; if a null character is found, the environment variable is truncated at that point.

Filedesc_count

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword that contains the number of file descriptors the child process is to inherit. It may take values from 0 to OPEN_MAX. If the value is 0, all file descriptors from the parent are inherited without remapping by the child, and the filedesc_list is ignored.

Filedesc_list

Supplied parameter

Type:: Structure
Length:: Variable

The name of an array of fullword file descriptor remap values that indicate how the child's file descriptors are to be remapped from the caller's (parent's) file descriptors. Except for those file descriptors that are designated by SPAWN_FDCLOSED in the supplied array, each of the child's file descriptors in the range zero to Filedesc_count-1 inherits file descriptor remap values filedesc_list(1) to filedesc_list(filedesc_count) from the supplied file descriptor array. The constant SPAWN_FDCLOSED is defined in the BPXYCONS macro.

As an example, assume that the caller supplies an array of 3 entries with the values 7, 5, and 4 respectively. This causes the child's file descriptor 0 to be remapped to the parent's file descriptor 7, the child's file descriptor 1 to be remapped to the parent's file descriptor 5, and the child's file descriptor 2 to be remapped to the parent's file descriptor 4.

Inherit_area_len

Supplied parameter

Type:: Structure
Length:: Fullword

The name of a fullword that contains the length of the inheritance structure that is to follow. If this parameter contains a value of zero, the Inherit_area parameter is ignored.

Inherit_area

Supplied parameter

Type:: Structure
Length:: Specified by Inherit_area_len.

The name of a data area that contains the inheritance structure for the child process. See the BPXYINHE mapping for the details of the inheritance structure (BPXYINHE — Spawn Inheritance Structure).

Return_value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the spawn service returns the process ID of the newly created child process, or -1 if it is not successful.

Return_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the spawn service stores the return code. The spawn service returns Return_code only if Return_value is -1. See bbbbbz/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The spawn service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EACCES	The caller does not have appropriate permissions to run the specified file. It may lack permission to search a directory that is named in the Pathname parameter; it may lack execute permission for the file to be run; or the file to be run is not a regular file and the system cannot run files of its type.
EAGAIN	The resources that are required to let another process be created are not available now; or you have already reached the maximum number of processes or UIDs that you are allowed to create. This error is also generated if _BPX_USERID was specified, and the specified user name was not defined to SAF with an OMVS segment. The following reason codes can accompany the return code: JROK, JRMaxUIDs or JRWlmWonErr.
EBADF	An entry in the filedesc_list is not a valid file descriptor; or the controlling terminal file descriptor that was specified in the inheritance structure is not valid.
EINVAL	One or more of the following conditions were detected: The user name 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. See BPXYINHE — Spawn Inheritance Structure for supported version numbers. 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. See BPXYINHE — Spawn Inheritance Structure for supported lengths. 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, JRInheAccountData, JRInheCWD, JRInheEye, JRInheSetPgrp, JRInheVersion, JRInheLength, and JrInheMemLimit.
ELOOP	A loop exists in symbolic links that were encountered during resolution of the Filename argument. This error is issued if more than 24 symbolic links are detected in the resolution of Filename.
EMVSERR	If EMVSERR is accompanied by reason code JrLocalSpawnNotAllowed, it means that the parameters specify that a local process must be created. It also means that one or more of the current address space's attributes is to be changed. A spawn request is not allowed to change certain attributes of the current address space. A spawn request is required to create a local process when either the environment variable _BPX_SHAREAS is set to MUST (_BPX_SHAREAS=MUST) or when the inheritance structure in the parameter list specifies InheMustBeLocal. When this reason code is given, the spawn request requires a local process to be created and one or both of the following conditions is also present: The environment variables specified on the call include a value for _BPX_USERID that does not match the current user ID. The inheritance structure passed on the call specifies one or more of the following flags: InheSetRegionSz, InheSetMemLimit, InheSetTimeLimit, InheSetAcctData, InheSetJobname.
EMVSSAF2ERR	The executable file is a set-user-ID or set-group-ID file and the file owner's UID or GID is not defined to the Security Access Facility (SAF).
ENAMETOOLONG	File_name is longer than 1023 characters, or some component of the file name is longer than 255 characters. Name truncation is not supported.
ENOENT	No file name was specified, or one or more of the components of the specified Filename were not found.
ENOEXEC	The specified file has execute permission, but it is not in the proper format to be a process image file. Reason_code contains the loader reason code for the error.
ENOMEM	The new process requires more memory than is permitted by the hardware or the operating system.
ENOTDIR	A directory component of Filename is not a directory.
ENOTTY	The tcsetpgrp failed for the specified controlling terminal file descriptor in the 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 (see Authorization) 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, and JRInheCWD.
ESRCH	The specified process group ID in the inheritance structure is not that of a process group in the calling process's session.

Reason_code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the spawn service stores the reason code. The spawn service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For most of the reason codes, see z/OS UNIX System Services Messages and Codes. For the ENOEXEC Return_code, Reason_code contains the loader reason code for the error:

Reason code	Explanation
X'xxxx0C27'	The target z/OS UNIX file is not in the correct format to be an executable file.
X'xxxx0C31'	The target z/OS UNIX file is built at a level that is higher than that supported by the running system.

Usage notes

Aspects of spawn processing are controlled by environment variables. The environment variables that affect spawn processing are the ones that are passed into the spawn syscall, and not the environment variables of the calling process. The environment variables of the calling process do not affect spawn processing, unless they are the same as those that are passed in the Environment_data_list parameter.
The new process (called the child process) inherits the following attributes from the process that calls spawn (called the parent process):
- Session membership
- Real user ID
- Real group ID
- Supplementary group IDs
- Priority
- The region size of the parent is inherited by the child, unless the INHESETREGIONSZ flag in the inheritance structure is set on to indicate that the value specified in INHEREGIONSZ is to be used to determine the child's region size. For more information, see What are soft limits in z/OS UNIX System Services Planning and Inheriting soft limits in z/OS UNIX System Services Planning.
- The MEMLIMIT of the parent is inherited by the child, unless the INHESETMEMLIMIT flag in the inheritance structure is set on to indicate that the value specified in INHEMEMLIMIT is to be used to determine the child's MEMLIMIT.
- The time limit of the parent is inherited by the child, unless the INHESETTIMELIMIT flag in the inheritance structure is set on to indicate that the value specified in INHETIMELIMIT is to be used to determine the child's time limit.
- The accounting data of the parent is inherited by the child, unless the INHESETACCTDATA flag in the inheritance structure is set on to indicate that the data pointed to by INHEACCTDATAPTR is to be used to determine the child's accounting data.
- The current working directory (CWD) of the parent is inherited by the child, unless the INHESETCWD flag in the inheritance structure is set on to indicate that the value pointed to by INHECWDPTR is to be used to determine the child's initial current working directory.
- The root directory of the parent is inherited by the child.
- The file creation mask of the parent is inherited by the child, unless the INHESETUMASK flag in the inheritance structure is set on to indicate that the value specified in INHEUMASK is to be used to determine the child's file creation mask.
- The process group ID of the parent is inherited by the child, unless the INHESETGROUP flag in the inheritance structure is set on to indicate that the value specified in INHEPGROUP is to be used to determine the child's process group. If the value in INHEPGROUP is set to INHE#NEWPGROUP, the child is placed into a new process group with a process group ID set to the child's process ID. Otherwise, the child is placed into the process group that is represented by the value that is specified in INHEPGROUP.
- Signals that are set to be ignored in the parent are set to be ignored in the child, unless the INHESETSIGDEF flag is on and the INHESIGDEF field specifies an overriding value in the supplied inheritance structure.
- The signal mask is inherited from the parent, unless the INHESETSIGMASK flag is set on in the inheritance structure and the INHESIGMASK field specifies an overriding value in the supplied inheritance structure.
- The user syscall trace setting is propagated to the child process.
- Security information from the parent's address space is propagated to the child's address space, and the child has a security environment equivalent to that of the parent, unless:
  - The _BPX_USERID environment variable specifies otherwise.
  - The INHESETUSERID flag in the inheritance structure is set on, and INHEUSERID contains a user ID.
- The TASKLIB, STEPLIB, or JOBLIB DD data set allocations that are active for the current task are propagated to the child's address space, unless the STEPLIB environment variable specifies otherwise. This causes the child's address space to have the same MVS program search order as the calling parent task.
- The jobname of the parent is propagated to the child and appended with a numeric value in the range of 1–9, if the jobname is 7 characters or less. If the jobname is 8 characters, the jobname is propagated as is. When a jobname is appended with a numeric value, the count wraps back to 1 when it exceeds 9.
- If the calling parent task is in a WLM enclave, the child is joined to the same WLM enclave. This allows WLM to manage the parent and child as one "business unit of work" entity for system accounting and management purposes.
The new child process has the following differences from the parent process:
- The child process has a unique process ID (PID) that does not match any active process group ID.
- The child has a different parent process ID (namely, the process ID of the process that called spawn).
- If the filedesc_count parameter specifies a 0 value, the child has its own copy of the parent's file descriptors, except for those files that are marked FCTLCLOEXEC or FCTLCLOFORK and for directories that were opened on a call to the opendir service. The files marked FCTLCLOEXEC or FCTLCLOFORK and open directories are not inherited by the child. If the filedesc_count parameter specifies a value greater than 0, the parent's file descriptors are remapped for the child as specified in the filedesc_list array. Those file descriptors from filedesc_count through OPENMAX in the parent are closed in the child, as are any elements in the filedesc_list array that are designated SPAWN_FDCLOSED. See the description of the BPXYCONS macro for the definition of the SPAWN_FDCLOSED constant ( BPXYCONS — Constants used by services). The FCTLCLOFORK flag and FCTLCLOEXEC flags have no effect on inheritance when the filedesc_list is used to map the child's file descriptors.
- The FCTLCLOEXEC and FCTLCLOFORK flags are not inherited from the parent file descriptors to the child's.
- If the INHESETTCPGRP flag is set in the inheritance structure, INHECTLTTYFD must be set to the file descriptor that is associated with the controlling terminal for this session. The foreground process group for this session is set to the PGID of this child process, thus placing the child process in the foreground process group. (This is done by issuing a tcsetpgrp() syscall as a part of spawn processing.)
- If INHESETTCPGRP is not set, the foreground process group of the session remains unchanged.
- If the INHESETCWD flag is set on in the inheritance structure, the child's initial working directory is set to the directory path described by INHECWDPTR (pointer) and INHECWDLEN (length), provided that the caller has appropriate privileges.
- If the INHESETUMASK flag is set on in the inheritance structure, the child's file mode creation mask (umask) is set to the value in INHEUMASK, provided that the caller has appropriate privileges.
- If the INHESETREGIONSZ flag is set on in the inheritance structure, the child's region size is set to the value in INHEREGIONSZ, provided that the caller has appropriate privileges.
- If the INHESETTIMELIMIT flag is set on in the inheritance structure, the child's CPU time limit is set to the value in INHETIMELIMIT, provided that the caller has appropriate privileges.
- If the INHESETACCTDATA flag is set on in the inheritance structure, the child's accounting data is set to the value specified by INHEACCTDATAPTR (pointer) and INHEACCTDATALEN (length).
- If the INHESETMEMLIMIT flag is set on in the inheritance structure, the child's MEMLIMIT is set to the value indicated in INHEMEMLIMIT, provided that either the caller has appropriate privileges or INHEMEMLIMIT is less than the current hard limit of the target address space.
- The process and system utilization times for the child are set to zero.
- Any file locks that were previously set by the parent are not inherited by the child.
- The child process has no alarms or interval timers set. (This is similar to the results of a call to the alarm service with Wait_time specified as zero.)
- The child has no pending signals.
- The child gets a new process image to run the executable file that is not a copy of the parent's.
- Signals that are set to be caught are reset to their default action.
- Memory mappings that are established by the parent with the shmat or mmap services are not inherited by the child.
- The semaphore adjustment values, semadj, are set to zero.
- If the SSTFNOSUID bit is set for the file system that contains the new process image file, the effective user ID, effective group ID, saved set-user-ID and saved set-group_ID are unchanged in the new process image. Otherwise, if the setuid bit of the new process image file is set, the effective user ID of the new process image is set to the owner id of the new process image file. Similarly, if the setgid bit of the new process image file is set, the effective group ID of the new process image is 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 will remain the same as those of the calling process image. The effective user ID and effective group ID of the new process image are saved (as the saved set-user-ID and the saved set-group-ID) for use by the setuid and setgid functions.
The executable file that is to be run receives control with the following attributes:
- When run in its own address space:
  - Problem program state
  - TCB and PSW key 8
  - AMODE=31(64), taken from the executable
  - Primary ASC mode
- When run in the same address space as the caller of spawn:
  - Problem program state
  - TCB and PSW key equal to the TCB key of the caller of BPX1SPN/BPX4SPN
  - AMODE=31(64), taken from the executable
  - Primary ASC mode
The information that the service passes to the executable file to be run is a parameter list, which is pointed to by register 1. In 31–bit mode, the parameter lists contains a 4–byte addresses; in 64–bit mode the parameter list contains a 64–byte addresses. In 31–bit mode, in the last parameter address the high-order bit is 1. The parameter list consists of the following parameter addresses.
For AMODE 31 callers, the high-order bit in the last parameter address is 1. For AMODE 64 callers, the high-order bit is part of the 64-bit address. There are always n parameters, passed with no end-of-parameter-list indicator.

The last parameter that spawn passes to the executable file identifies the caller of the file as the exec or spawn service.
To support the creation and propagation of a STEPLIB environment to the new process image, the spawn service allows for the specification of a STEPLIB environment variable. The following are the accepted values for the STEPLIB environment variable, and the actions taken for each value:
1. STEPLIB=NONE. No STEPLIB DD is to be created for the new process image.
2. STEPLIB=CURRENT. The TASKLIB, STEPLIB or JOBLIB DD data set allocations that are active for the calling task at the time of the call to the spawn service are propagated to the new process image, if they are found to be cataloged. Uncataloged data sets are not propagated to the new process image.
3. STEPLIB=Dsn1:Dsn2:,...DsnN. The specified data sets, Dsn1:Dsn2:...DsnN, are built into a STEPLIB DD in the new process image.
  The actual name of the DD is not STEPLIB, but a system-generated name that has the same effect as a STEPLIB DD. The data sets are concatenated in the order that is specified. The specified data sets must follow standard MVS data set naming conventions. A data set found to be in violation of this standard is ignored. Also, a data set that follows this standard is still ignored if:
  - The caller does not have the proper security access to a data set, or
  - A data set is uncataloged or is not in load library format.
  Because a data set in error is ignored, the executable file can run without the proper STEPLIB environment. If a data set is in error because of improper security access, a X'913' abnormal end is generated. The dump for this abnormal end can be suppressed by the installation.
If the STEPLIB environment variable is not specified, the default behavior of the spawn service is the same as if STEPLIB=CURRENT were specified.

If the program that is to be invoked is a set-user-ID or set-group-ID file, and the user-ID or group-ID of the file is different from that of the current process image, the data sets that are to be built into the STEPLIB environment for the new process image must be found in the system sanction list for set-user-id and set-group-id programs. Only those data sets that are found in the sanction list are built into the STEPLIB environment for the new process image. See Using sanction lists in z/OS UNIX System Services Planning for detailed information about the sanction list. See Tuning performance in z/OS UNIX System Services Planning for information about STEPLIB performance considerations.
For performance reasons, the spawn service is allowed to create a new image under a specific user ID that is different from that of the invoker. When an invoker with appropriate privileges specifies a user name on the _BPX_USERID environment variable or in the inheritance structure (INHEUSERID), the resulting image runs under the associated MVS user identity. This service allows spawn() to replace the sequence of functions fork(), setgid(), initgroups(), setuid(), and exec(). The following rules apply to spawn()s with user name changes (using either the _BPX_USERID environment variable or the inheritance structure):
1. _BPX_USERID must be a valid 1-8 character XPG4-compliant name with a defined OMVS segment. An incorrect username length results in a failure of the spawn() request with an EINVAL and JRUserNameLenError. An undefined username results in an ERRNOJR of JRJsrRacXtr; an incompletely defined OE username results in an ERRNO of EMVSSAF2ERR and ERRNOJR of the propagated SAF return code and reason code.
2. If the creation of the new address space with the new user identity puts the system over the limit of MAXUIDs, spawn() fails with an ERRNO of EAGAIN and an ERRNOJR of JRMaxUIDs.
3. Authorization to change the username is the same as for the setuid() function. If the caller is not authorized, spawn() fails with an ERRNO of EPERM and an ERRNOJR of JRNoChangeIdentity ( _BPX_USERID) or an ERRNOJR of JRInheUserid (inheritance structure).
4. If _BPX_SHAREAS is active and an identity change is called for, _BPX_SHAREAS is ignored and a new address space is created for the new image.
To allow the caller to control whether the spawned child process runs in a separate address space from the parent address space or in the same address space, the spawn service allows for the specification of the _BPX_SHAREAS environment variable. The following are the accepted values for the _BPX_SHAREAS environment variable, and the actions taken for each value:
1. _BPX_SHAREAS=YES - Indicates that the child process that is to be created is to run in the same address space as the parent. In the following circumstances, the _BPX_SHAREAS=YES value cannot be honored, and the child process is created in its own address space:
  - If the program to be run is a set-user-ID or set-group-ID program that would cause the effective user-ID or group-ID of the child process to be different from that of the parent process.
  - If the program to be run is an APF-authorized z/OS UNIX or MVS program and the caller is not running APF-authorized.
  - If the program to be run is an unauthorized z/OS UNIX or MVS program and the caller is running APF-authorized.
  - If the specified file name represents an external link or a sticky bit file. If, however, the program that is to be run is a shell script and _BPX_SPAWN_SCRIPT=YES is set, the process runs in the same address space.
  - If the parent's address space lacks the necessary resources to create another process within the address space.
  Note that only one local spawned process per TSO address space is supported at a given time. This is done to reduce conflict among multiple shells running in the same address space.
2. _BPX_SHAREAS=MUST - Indicates that the child process that is to be created must run in the same address space as the parent, or the spawn request will fail. In the following circumstances, the _BPX_SHAREAS=MUST value cannot be honored, and the spawn invocation fails:
  - If the program to be run is a set-user-ID or set-group-ID program that would cause the effective user ID or group ID of the child process to be different from that of the parent process.
  - If the program to be run is an APF-authorized z/OS UNIX or MVS program and the caller is not running APF-authorized.
  - If the program to be run is an unauthorized z/OS UNIX or MVS program and the caller is running APF-authorized.
  - If the parent's address space lacks the necessary resources to create another process within the address space.
  - If the list of environment variables specifies a value for _BPX_USERID that is different from the current user ID.
  - If the inheritance structure sets any of the following flag bits: InheSetRegionSz, InheSetMemLimit, InheSetTimeLimit, InheSetAcctData, InheSetJobname.
3. _BPX_SHAREAS=REUSE - This is equivalent to specifying _BPX_SHAREAS=YES.
4. _BPX_SHAREAS=NO - Indicates that the child process that is to be created is to run in a separate address space from the parent's address space. This is the default behavior for the spawn service if the _BPX_SHAREAS environment variable is not specified, or if it contains an unsupported value.
When the parent and child processes are sharing the same address space, special consideration must be given to the resources that are shared in this environment. These considerations include, but are not limited to, the following ones:
- The parent and child share the same data set allocations, and must coordinate usage of these allocations. Programs that have special ddname allocation requirements should not be run in this shared environment.
- The parent and child share the same private area storage; they should be careful not to overreach their own storage bounds, and together they must not exceed the region size of the address space.
- A prior loaded copy of a z/OS UNIX program is reused under the same circumstances that apply to the reuse of a prior loaded MVS unauthorized program from an unauthorized library by the MVS XCTL service, with the following exceptions:
  - If the calling process is in Ptrace debug mode, a prior loaded copy is not reused.
  - If the calling process is not in Ptrace debug mode, but the only prior loaded usable copy of the z/OS UNIX program found is in storage that is modifiable by the caller, the prior copy is not reused.
- If the specified file name represents an external link or a sticky bit file, the program is loaded from the caller's MVS load library search order. For an external link, the external name is used only if the name is eight characters or less; otherwise the caller receives an error from the spawn service. For a sticky bit program, the file name is used if it is eight characters or less. Otherwise, the program is loaded from the z/OS UNIX file system.
- The program that is being spawned should have the APF extended attribute turned on and should be linked AC=1. DLLs that are loaded by APF-authorized applications should have the APF extended attribute set on and should be linked AC=0.
To allow the caller to control whether the spawn service is to treat the specified file as a shell script if it is found not to be in the correct format to be a process image file, the spawn service allows the specification of the _BPX_SPAWN_SCRIPT environment variable. The following are the accepted values for the _BPX_SPAWN_SCRIPT environment variable, and the actions that are taken for each value:
- _BPX_SPAWN_SCRIPT=YES - Indicates that the specified file is to be treated as a shell script if the following are true:
  - The file is not in the correct format to be a process image file, and does not contain the "magic number" (#!) in the first line.
  - The file is not a REXX exec.
  In this case, the spawn service behaves as follows:
  - The z/OS shell executable file that is current in the caller's environment is executed to run the specified file as a shell script. The path name for the shell executable file is determined by extracting the path name from the SHELL environment variable, if the SHELL variable is present in the environment data list that is supplied to spawn. If it is not present, the default path name of /bin/sh is used as the shell executable path name.
  - The argument data list and argument length list that are passed to the shell executable file are to contain the following argument data and corresponding argument data lengths:
    - The shell path name, terminated by a null character (X'00')
    - The string '-S', terminated by a null character (X'00')
    - The string '—', terminated by a null character (X'00')
    The fourth through the last arguments in the list are to contain the list of arguments specified by the caller of the spawn service.
- _BPX_SPAWN_SCRIPT=NO - Indicates that the specified file is NOT to be treated as a shell script if it is found not to be in the correct format to be a process image file, not to contain the file magic number (#!), and not to be a REXX exec. In this case, the spawn service fails and returns the return code ENOEXEC to the caller of spawn. This is the default behavior for the spawn service if the _BPX_SPAWN_SCRIPT environment variable is not specified, or if it contains an unsupported value.
If the specified z/OS UNIX file is not in the correct format to be an executable, but contains the magic number (#!) in the first line, the program that is specified in the magic number header is executed. The expected format of the magic number header is as follows:
```
#! Path String
```
#! is the file magic number. It identifies the first line of the file as a special header that contains the name of the program to be run and any argument data to be supplied to it.

The Path parameter specifies the path name of the file that is to be run. It is separated by blank or tab characters from the #! characters, or can immediately follow the characters.

The String parameter is an optional character string that can be used to pass options to a target command interpreter (shell) that is to run the script. It must be separated from the Path parameter by tab or blank characters, and cannot itself contain tab or blank characters.
The argument data list and argument length list that are passed to the magic number file are to contain the following argument data and corresponding argument data lengths:
- The magic number path name, ended by a null character (X'00')
- The string, if one is supplied, ended by a null character (X'00')
The remaining arguments in the list are to contain the list of arguments specified by the caller of the spawn service.

If the path name that is specified in the magic number header cannot be executed for some reason, the spawn request fails with return code ENOEXEC, regardless of the error. ENOEXEC is returned for compatibility purposes, so that existing scripts can continue to run successfully when invoked from an application such as a command interpreter (shell). The reason code indicates the exact reason the magic number file could not be executed.
If the target executable program is enabled by Language Environment, the environment variables that are supplied to the service must include the null terminator as part of the string and length.
If the _BPX_PTRACE_ATTACH environment variable is set to YES, the target executable program is loaded into user-modifiable storage to allow subsequent debugging. Any additional programs that are loaded into storage during the execution of the target program are also loaded into user-modifiable storage, with the exception of modules that are loaded from the LPA.
The _BPXK_MDUMP environment variable can be used to specify where a SYSMDUMP is to be written. The following are the allowable values:
Value

Description

OFF

The dump is to be written to the current directory. This is the default. This dump is only written if the user allocates a SYSMDUMP data set for the TSO/E session. The system creates a file named coredump.pid in the user's working directory (where pid is the process ID for the process being dumped) and writes the core dump (SYSMDUMP) in hexadecimal format.

MVS data set name

The dump is to be written to an MVS data set. The data set name must be fully qualified and can be up to 44 characters. It can be specified in uppercase, lowercase, or both; it is folded to uppercase.

z/OS UNIX file name

The dump is to be written to a z/OS UNIX file. The file name can be up to 1024 characters and must begin with a slash. The slash refers to the root directory, in which the file is created.
The _BPXK_JOBLOG environment variable can be used to specify that WTO messages are to be written to an open z/OS UNIX job log file. The following are the allowable values:
Value

Description

nn

Job log messages are to be written to open file descriptor nn.

STDERR

Job log messages are to be written to the standard error file descriptor, 2.

NONE

Job log messages are not to be written. This is the default.

The file that is used to capture messages can be changed at any time by calling the oe_env_np service and specifying _BPXK_JOBLOG with a different file descriptor.

Message capturing is turned off if the specified file descriptor is marked for close on a fork or exec.

Message capturing is process-related. All threads under a given process share the same job log file. Message capturing may be initiated by any thread under that process.

Multiple processes in a single address space can each have different files active as the JOBLOG file; some or all of them can share the same file; and some processes can have message capturing active while others do not.

When the file that is used as a job log is shared by several processes (for example, by a parent and child), the file should be opened for append. Failure to do this causes unpredictable results.

Only files that can be represented by file descriptors may be used as job log files; MVS data sets are not supported.

Message capturing is propagated on a fork() or spawn(). If a file descriptor is specified, the physical file must be the same in order for message capturing to continue in the forked or spawned process. If STDERR is specified, the file descriptor may be remapped to a different physical file.

Message capturing may be overridden on exec() or spawn() by specifying the _BPXK_JOBLOG environment variable as a parameter on the exec() or spawn().

Message capturing only works in forked (BPXAS) address spaces.

This is not true joblog support: messages that would normally go to the JESYSMSG data set are captured, but messages that go to JESMSGLG are not.
When the INHESETUSERID or INHESETACCTDATA flags are set on in the inheritance structure, the corresponding environment variables for user name (_BPX_USERID) or accounting data (_BPX_ACCT_DATA) are ignored.

Depending on the attributes and values that are specified in the inheritance structure (BPXYINHE), the caller is required to have different levels of authorization. The following table defines the specific authorization that is required for each attribute. Inheritance structure attributes that are not listed in the table do not require authorization.

BPXYINHE field	Authority required
INHEUSERID	The caller must have daemon authority. See Giving daemon authority to vendor-written programs in z/OS UNIX System Services Planning for information about setting up daemon authority for a user.
INHEREGIONSZ	When the new region size is smaller than the caller's current hard limit for RLIMIT_AS, no authorization is required. To exceed the current hard limit, the caller must have superuser authority (UID=0), or the spawn function will fail.
INHETIMELIMIT	When the new CPU time limit is less than the caller's current hard limit for RLIMIT_CPU, no authorization is required. To exceed the current hard limit, the caller must have superuser authority (UID=0), or the spawn function will fail.
INHEUMASK	The caller must have superuser authority to set the child's file mode creation mask, or the spawn function will fail.
INHECWD	The caller must have superuser authority to set the child's current working directory, or the spawn function will fail.

If the INHESETDEBUGENV flag in the inheritance structure is set on, the target program is under the control of the debugger process.
If the INHEMUSTBELOCAL flag in the inheritance structure is set on, the program must run in the same address space as the caller, or the spawn invocation will fail. (This flag causes the same behavior as _BPX_SHAREAS=MUST.) See Usage Note 8b for conditions that will cause the spawn invocation to fail when the INHEMUSTBELOCAL flag is set on.
If the BPXK_SIGDANGER environment variable is set to YES, the process will receive a SIGDANGER signal rather than a SIGTERM signal when an OMVS shutdown is initiated. This may be advantageous for an application that uses the SIGTERM signal for other purposes.
The _BPX_UNLIMITED_OUTPUT environment variable can be used to specify that default installation limits for sysout output are to be overridden. This environment variable is only processed when it is specified for a non-local spawn. These are the supported values:
- YES - The sysout job limits (BYTES, CARDS, LINES and PAGES) will be set to the maximum values and an action of WARNING. This effectively allows unlimited output for the job that is associated with the newly spawned child.
- NO - The installation defaults will be used for job output limits. This is the default behavior. Any other value will also result in the installation defaults being used.
For non-local spawn to process the _BPX_UNLIMITED_OUTPUT environment variable, the caller must have appropriate privileges:
1. Be a superuser (UID=0) or
2. Be permitted to the BPX.UNLIMITED.OUTPUT resource profile in the FACILITY class with at least READ access.
When the spawn service is called from a __login process in a multiprocess, multiuser environment (environment variable _BPX_SHAREAS=YES is in effect), the newly created child process will have the MVS identity of the address space and the POSIX permissions of its parent process. It is expected that the application program will immediately call the __login service to establish a proper process-level identity in the child process.
The _BPXK_INITTAB_RESPAWN environment variable specifies whether a process is to be dynamically started with the respawn attribute. The following are the allowable values:
Value

Description

YES

Specifies that a process is to be started with the respawn attribute. Setting this to YES after the process has started does not affect the setting of the respawn attribute.

NO

Disables the respawn capability of the process. The process will not be respawned when it ends.
When the executable file to be run is a REXX exec, the first argument should be the path name of the REXX exec. Subsequent arguments for the exec can follow this argument.
The _BPXK_INITTAB_RESPAWN attribute is only allowed for non-local spawns. The _BPXK_INITTAB_RESPAWN setting is ignored if the process is spawned in the same address space. Setting _BPX_SHAREAS=YES, _BPX_SHAREAS=MUST, or INHEMUSTBELOCAL causes the _BPXK_INITTAB_RESPAWN option to be ignored on the spawn call.
z/OS UNIX sets a default message class of “A” for all forked or spawned processes. Unlike JES, z/OS UNIX does not have a method for accepting a user-supplied default message class, and a default had to be supplied to the converter interpreter. Message class A was chosen as the default for BPXAS initiators. There is currently no way to dynamically change this default value. The MSGCLASS for the joblog (JESMSGLG, JESJCL, JESYSMSG) is set to class A before the fork or spawn that associates the process with the BPXAS initiator is begun.
The _BPX_JOBNAME environment variable can be used to change the jobname of the new process image. The jobname change is allowed only if the invoker has appropriate privileges (see Authorization) . If these conditions are not met, the environment variable is ignored. Accepted values are strings of 1–8 alphanumeric characters. Incorrect specifications are ignored.
- A job name can be specified in the INHE structure. If both the INHE JOBNAME and environment variable _BPX_JOBNAME are specified, the value in the INHE structure is used.
- If _BPX_JOBNAME is specified and _BPX_SHAREAS is set to YES, then _BPX_JOBNAME is ignored.
If the caller specifies _BPXK_DISABLE_SHLIB=YES then future loadhfs() and loadhfs_extended() system calls will ignore the st_sharelib attribute and load the program into private storage. If the caller specifies NO (the default) then normal system shared library processing takes place. For more information, see Commonly used environment variables in z/OS UNIX System Services Planning
If the specified file name resolves to an external link or a sticky bit file, the program is loaded from the caller's MVS load library search order. For an external link, the external name is used only if the name is eight characters or less; otherwise the caller receives an error from the spawn service. For a sticky bit program, the file name is used if it is eight characters or less. Otherwise, the program is loaded from the z/OS® UNIX file system. If the specified sticky bit file or link resolves to a MVS program link-edited AC=1 located in an APF-authorized library, the attributes of the sticky bit file or external link must be set up properly to allow this type of invocation. For a sticky bit file, it must be installed with an owning UID of 0 or with the APF extended attribute. The owning UID of 0 requirement would also apply to a symbolic link that resolves to the sticky bit file. For an external link, it must be installed with an owning UID of 0. A sticky bit a file with the APF extended attribute is not allowed if found in a file system that is mounted as NOSETUID. If the specified file name represents a symbolic link to a sticky bit file that has the set-user-id attribute, the symbolic link must have an owning uid of 0 or an owning uid equal to that of the sticky bit file. If the sticky bit file has the set-group-id attribute, the symbolic link must have an owning uid of 0 or an owning GID equal to that of the sticky bit file. A file or link that is found in a file system mounted as NOSECURITY is not considered trusted for this type of invocation, regardless of its attributes. Failure to follow this set up will cause the child process created to run the MVS program to end abnormally with a EC6-xxxxC04A abend when the MVS program is invoked via the spawn service.

Related services

Characteristics and restrictions

Executing a program from z/OS UNIX causes the program environment to become uncontrolled, unless the program is identified as program controlled. (That is, unless the ST_PROGCTL attribute is ON for the z/OS UNIX program file). Running a z/OS UNIX program with the ST_PROGCTL attribute set to OFF prevents future invocations of authorized programs like program access to data sets (PADS) programs. These are programs givenspecial authorization by the installation and by the installed security product (such as RACF®) to read or write to protected data sets. In addition, PADS programs should not attempt to load programs from z/OS UNIX with the ST_PROGCTL attribute OFF, because these programs are considered uncontrolled and could have been modified by users that do not have the same level of authorization as the PADS program.
The _BPXK_TIMEOUT environment variable is processed for this callable service. It allows applications to specify whether a process waiting on terminal input in the shell should be timed out. For more information about the _BPXK_TIMEOUT environment variable, see z/OS UNIX System Services Planning.

Examples

For an example using this callable service, see BPX1SPN (spawn) example.