Function

spawn invokes the spawn callable service to create a new process, called a child process, to run an executable file. It remaps the calling process's file descriptors for the child process.

Parameters

pathname

A path name for the executable file. path names can begin with or without a slash:

• A path name that begins with a slash is an absolute path name, and the search for the file starts at the root directory.
• A path name that does not begin with a slash is a relative path name, and the search for the file starts at the working directory.

fd_count

The number of file descriptors that can be inherited by the child process. In the new process, all file descriptors greater than or equal to fd_count are closed.

fd_map

A stem variable. The stem index specifies the child's file descriptor; for example, stem.0 specifies the child's file descriptor 0. This array selects the file descriptors to be inherited. The value assigned to the variable indicates the parent's file descriptor that will be mapped to the child's file descriptor. For example, if stem.0 is 4, the child process inherits the parent's file descriptor 4 as its descriptor 0. Any of the stem variables that contains a negative number or a nonnumeric value is closed in the child.

arg_stem

A stem variable. stem.0 contains the number of arguments you are passing to the program. The first argument should always specify the absolute or relative path name of the program to be executed. If a relative path name is used and PATH is specified, PATH is used to resolve the name; otherwise, the name is processed as relative to the current directory. If a PATH environment variable is not passed, the first argument should specify the absolute path name or a relative path name for the program.

env_stem

A stem variable. stem.0 contains the number of environment variables that you want the program to be run with. To propagate the current environment, pass _ _environment. Specify each environment variable as VNAME=value.

Usage notes

1. 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.
   • Working directory.
   • Root directory.
   • File creation mask.
   • The process group ID of the parent is inherited by the child.
   • Signals set to be ignored in the parent are set to be ignored in the child.
   • The signal mask is inherited from the parent.
2. 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 PID (namely, the PID of the process that called spawn).
   • If the fd_count parameter specified 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. The files marked FCTLCLOEXEC or FCTLCLOFORK 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 fd_map stem with a negative number or non-numeric value.
   • The FCTLCLOEXEC and FCTLCLOFORK flags are not inherited from the parent file descriptors to the child's.
   • The foreground process group of the session remains unchanged.
   • 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 (similar to the results of a call to the alarm service with Wait_time specified as zero) and has no interval timers set.
   • The child has no pending signals.
   • The child gets a new process image, which is not a copy of the parent process, to run the executable file.
   • Signals set to be caught are reset to their default action.
   • Memory mappings established by the parent via the shmem or mmap services are not inherited by the child.
   • If the setuid bit of the new executable file is set, the effective user ID and saved set-user-ID mode of the process are set to the owner user ID of the new executable file.
   • If the setgid bit of the new executable file is set, the effective group ID and saved set-group-ID bit of the process are set to the owner user ID of the new executable file.

   The last parameter that spawn passed to the executable file identifies the caller of the file as the exec or spawn service.

3. To control whether the spawned child process runs in a separate address space from the parent address space or in the same address space, you can specify the _BPX_SHAREAS environment variable. If _BPX_SHAREAS is not specified, is set to NO, or contains an unsupported value, the child process to be created will run in a separate address space from the parent process.

   _BPX_SHAREAS=YES indicates that the child process to be created is to run in the same address space as the parent. If the program to be run is a set-user-ID or set-group-ID program that will cause the effective user-ID or group-ID of the child process to be different from that of the parent process, the _BPX_SHAREAS=YES value is ignored and the child process runs in its own address space.

4. In addition to recognizing the _BPX_SHAREAS environment variable, spawn recognizes all of the environment variables that are recognized by the fork and exec callable services.
5. The fd_count parameter can be Ø, which means that all file descriptors are inherited by the child.
6. The fd_count parameter is limited to a maximum value of 1000.
7. 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.