spawnp()--Spawn Process with Path

 #include <spawn.h>

 pid_t spawnp(const char                *file,
              const int                 fd_count,
              const int                 fd_map[],   
              const struct inheritance  *inherit,  
              char * const              argv[],
              char * const              envp[]);

The spawnp() function creates a child process that inherits specific attributes from the parent. The attributes inherited by the child process are file descriptors, the signal mask, the signal action vector, and environment variables, among others. spawnp() takes the file parameter and searches the environment variable PATH. The file parameter is concatenated to each path defined in the PATH environment variable. It uses the first occurrence of the file parameter that is found with a mode of execute.

If the PATH environment variable does not contain a value, an error occurs. If the file parameter contains a "/" character, the value of file is used as a path and a search of the PATH or library list is not performed. Specifying a file parameter containing a "/" is the same as calling spawn().

To search the library list, a special value for the PATH environment variable is used. The string %LIBL% can be the entire PATH value or a component of the PATH value. When the string %LIBL% is encountered, the library list is searched. For example, the following path searches the directory /usr/bin first, searches the library list next, and then searches the /tobrien/bin directory for the file:

PATH=/usr/bin:%LIBL%:/tobrien/bin

Parameters

file

(Input) A file name used with the search path to find an executable file that will run in the new (child) process. The file name is expected to be in the CCSID of the job.

See QlgSpawnp()--Spawn Process with Path (using NLS-enabled file name) for a description and an example of supplying the file in any CCSID.

fd_count

(Input) The number of file descriptors the child process can inherit. It can have a value from zero to the value returned from a call to sysconf(_SC_OPEN_MAX).

fd_map[]

(Input) An array that maps the parent process file descriptor numbers to the child process file descriptor numbers. If this value is NULL, it indicates simple inheritance. Simple inheritance means that the child process inherits all eligible open file descriptors of the parent process. In addition, the file descriptor number in the child process is the same as the file descriptor number in the parent process. Refer to Attributes Inherited for details of file descriptor inheritance.

inherit

(Input) A pointer to an area of type struct inheritance. If the pointer is NULL, an error occurs. The inheritance structure contains control information to indicate attributes the child process should inherit from the parent. The following is an example of the inheritance structure, as defined in the <spawn.h> header file:

struct inheritance {
                    flagset_t  flags;
                    int        pgroup;
                    sigset_t   sigmask;
                    sigset_t   sigdefault;
};

The flags field specifies the manner in which the child process should be created. Only the constants defined in <spawn.h> are allowed; otherwise, spawnp() returns -1 with errno set to EINVAL. The allowed constants follow:

SPAWN_SETPGROUP	If this flag is set ON, spawnp() sets the process group ID of the child process to the value in pgroup. In this case, the process group field, pgroup, must be valid. If it is not valid, an error occurs. If this flag is set OFF, the pgroup field is checked to determine what the process group ID of the child process is set to. If the pgroup field is set to the constant SPAWN_NEWPGROUP, the child process group ID is set to the child process ID. If the pgroup field is not set to SPAWN_NEWPGROUP and the flags field is not set to SPAWN_SETPGROUP, the process group ID of the child process is set to the process group ID of the parent process. If the pgroup field is set to SPAWN_NEWPGROUP and the flags field is set to SPAWN_SETPGROUP, an error occurs.
SPAWN_SETSIGMASK	If this flag is set ON, spawnp() sets the signal blocking mask of the child process to the value in sigmask. In this case, the signal blocking mask must be valid. If it is not valid, an error occurs. If this flag is set OFF, spawnp() sets the signal blocking mask of the child process to the signal blocking mask of the calling thread.
SPAWN_SETSIGDEF	If this flag is set ON, spawnp() sets the child process' signals identified in sigdefault to the default actions. The sigdefault must be valid. If it is not valid, an error occurs. If this flag is set OFF, spawnp() sets the child process' signal actions to those of the parent process. Any signals of the parent process that have a catcher specified are set to default in the child process. The child process' signal actions inherit the parent process' ignore and default signal actions.
SPAWN_SETTHREAD_NP	If this flag is set ON, spawnp() will create the child process as multithread capable. The child process will be allowed to create threads. If this flag is set OFF, the child process will not be allowed to create threads.
SPAWN_SETPJ_NP	If this flag is set ON, spawnp() attempts to use available i5/OS prestart jobs. The prestart job entries that may be used follow: QSYS/QP0ZSPWP, if the flag SPAWN_SETTHREAD_NP is set OFF. QSYS/QP0ZSPWT, if the flag SPAWN_SETTHREAD_NP is set ON. The i5/OS prestart jobs must have been started using either QSYS/QP0ZSPWP or QSYS/QP0ZSPWT as the program that identifies a prestart job entry for the i5/OS subsystem that the parent process is running under. If a prestart job entry is not defined, the child process will run as a batch immediate job under the same subsystem as the parent process. If this flag (SPAWN_SETPJ_NP) is set OFF, the child process will run as a batch immediate job under the same subsystem as the parent process. Note:In order to more closely emulate POSIX semantics, spawnp() will ignore the Maximum number of uses (MAXUSE) value specified for the prestart job entry. The prestart job will only be used once, behaving as if MAXUSE(1) was specified.
SPAWN_SETCOMPMSG_NP	If this flag is set ON, spawnp() causes the child process to send a completion message to the user's message queue when the child process ends. If this flag is set OFF, no completion message is sent to the user's message queue when the child process ends. If both the SPAWN_SETCOMPMSG_NP and SPAWN_SETPJ_NP flags are set ON, an error occurs.
SPAWN_SETJOBNAMEPARENT_NP	If this flag is set ON, spawnp() sets the child's i5/OS simple job name to that of the parent's. If this flag is set OFF, spawnp() sets the child's i5/OS simple job name based on the file parameter.
SPAWN_SETJOBNAMEARGV_NP	If this flag is set ON, spawnp() sets the child's i5/OS simple job name to the name found in argv[0] of the argv[] parameter. If this flag is set OFF, spawnp() sets the child's i5/OS simple job name based on the file parameter.
SPAWN_SETLOGJOBMSGABN_NP	If this flag is set ON, the child process does not log the job started (CPF1124) message and will only log the job ended (CPF1164) message when the job ends abnormally (job ending code 30 or greater). This applies to the job log as well as the system history log (QHST). If this flag is set OFF, the child process logs the job started (CPF1124) and the job ended (CPF1164) messages.
SPAWN_SETLOGJOBMSGNONE_NP	If this flag is set ON, the child process does not log the job started (CPF1124) and the job ended (CPF1164) messages to either the job log or to the system history log (QHST). If this flag is set OFF, the child process logs the job started (CPF1124) and the job ended (CPF1164) messages.
SPAWN_SETAFFINITYID_NP	If this flag is set ON, spawnp() sets the resources affinity identifier of the child process to the 4-byte integer value, treated as an unsigned int, that immediately follows the inheritance structure in memory. A value of 0 indicates i5/OS selects the resources affinity identifier. The caller must ensure the value immediately follows the inheritance structure. For example: struct extended_inheritance { struct inheritance inherit; unsigned int affinityID; }; struct extended_inheritance extended_inherit; If this flag is set OFF, i5/OS selects the resources affinity identifier of the child process.
SPAWN_SETTHREADRUNPTY_NP	If this flag is set ON, spawnp() sets the run priority of the child process to the current thread's run priority. If this flag is set OFF, spawnp() sets the run priority of the child process to the current process' run priority.

argv[]

(Input) An array of pointers to strings that contain the argument list for the executable file. The last element in the array must be the NULL pointer. If this parameter is NULL, an error occurs.

envp[]

(Input) An array of pointers to strings that contain the environment variable lists for the executable file. The last element in the array must be the NULL pointer. If this parameter is NULL, an error occurs.

Authorities

Authorization Required for spawnp()

Return Value

Error Conditions

If spawnp() is not successful, errno usually indicates one of the following errors. Under some conditions, errno could indicate an error other than those listed here.

[E2BIG]

Argument list too long.

[EACCES]

Permission denied.

An attempt was made to access an object in a way forbidden by its object access permissions.

The thread does not have access to the specified file, directory, component, or path.

If you are accessing a remote file through the Network File System, update operations to file permissions at the server are not reflected at the client until updates to data that is stored locally by the Network File System take place. (Several options on the Add Mounted File System (ADDMFS) command determine the time between refresh operations of local data.) Access to a remote file may also fail due to different mappings of user IDs (UID) or group IDs (GID) on the local and remote systems.

[EAPAR]

Possible APAR condition or hardware failure.

[EBADFUNC]

Function parameter in the signal function is not set.

A given file descriptor or directory pointer is not valid for this operation. The specified descriptor is incorrect, or does not refer to an open file.

[EBADNAME]

The object name specified is not correct.

[ECANCEL]

Operation canceled.

[ECONVERT]

Conversion error.

One or more characters could not be converted from the source CCSID to the target CCSID.

The specified path name is not in the CCSID of the job.

[EFAULT]

The address used for an argument is not correct.

In attempting to use an argument in a call, the system detected an address that is not valid.

While attempting to access a parameter passed to this function, the system detected an address that is not valid.

[EINVAL]

The value specified for the argument is not correct.

A function was passed incorrect argument values, or an operation was attempted on an object and the operation specified is not supported for that type of object.

An argument value is not valid, out of range, or NULL.

The flags field in the inherit parameter contains an invalid value.

[EIO]

Input/output error.

A physical I/O error occurred.

A referenced object may be damaged.

[ELOOP]

A loop exists in the symbolic links.

This error is issued if the number of symbolic links encountered is more than POSIX_SYMLOOP (defined in the limits.h header file). Symbolic links are encountered during resolution of the directory or path name.

[ENAMETOOLONG]

A path name is too long.

A path name is longer than PATH_MAX characters or some component of the name is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the name string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using the pathconf() function.

[ENFILE]

Too many open files in the system.

A system limit has been reached for the number of files that are allowed to be concurrently open in the system.

The entire system has too many other file descriptors already open.

[ENOENT]

No such path or directory.

The directory or a component of the path name specified does not exist.

A named file or directory does not exist or is an empty string.

[ENOMEM]

Storage allocation request failed.

A function needed to allocate storage, but no storage is available.

There is not enough memory to perform the requested function.

[ENOTDIR]

Not a directory.

A component of the specified path name existed, but it was not a directory when a directory was expected.

Some component of the path name is not a directory, or is an empty string.

[ENOTSAFE]

Function is not allowed in a job that is running with multiple threads.

[ENOTSUP]

Operation not supported.

The operation, though supported in general, is not supported for the requested object or the requested arguments.

[ETERM]

Operation terminated.

[ENOSYSRSC]

System resources not available to complete request.

The child process failed to start. The maximum active jobs in a subsystem may have been reached. CHGSBSD and CHGJOBQE CL commands can be used to change the maximum active jobs.

[EUNKNOWN]

Unknown system state.

The operation failed because of an unknown system state. See any messages in the job log and correct any errors that are indicated, then retry the operation.

Usage Notes

1. spawnp() is threadsafe, except this function will fail and errno ENOTSAFE will be set if it is called in any of the following ways:
   
   
   • From a multithreaded process and file refers to a shell script that does not exist in a threadsafe file system.
   • From a multithreaded process with a current working directory that is not in a threadsafe file system, and the PATH environment variable causes spawnp() to check the current working directory.
   
   
2. There are performance considerations when using spawn() and spawnp() concurrently among threads in the same process. spawn() and spawnp() serialize against other spawn() and spawnp() calls from other threads in the same process.
   
   
3. The child process is enabled for signals. A side effect of this function is that the parent process is also enabled for signals if it was not enabled for signals before this function was called.
   
   
4. If this function is called from a program running in user state and it specifies a system-domain program as the executable program for the child process, an exception occurs. In this case, spawnp() returns the process ID of the child process. On a subsequent call to wait() or waitpid(), the status information returned indicates that an exception occurred in the child process.
   
   
5. The program that will be run in the child process must be either a program object in the QSYS.LIB file system or an independent ASP QSYS.LIB file system (*PGM object) or a shell script (see About Shell Scripts). The syntax of the name of the file to run must be the proper syntax for the file system in which the file resides. For example, if the program MYPROG resides in the QSYS.LIB file system and in library MYLIB, the specification for spawnp(). would be the following:

      MYPROG.PGM
   

   See QlgSpawn()--Spawn Process (using NLS-enabled path name) for an example specifying the program using the Qlg_Path_Name_T structure. The Qlg_Path_Name_T structure is supported by QlgSpawn() and allows the program name to be specified in any CCSID.

   Note: For more information about path syntaxes for the different file systems, see the Integrated file system information in the Files and file systems topic.

6. Spawned child processes are batch jobs or prestart jobs. As such, they do not have the ability to do 5250-type interactive I/O.
   
   
7. Spawned child processes that are i5/OS prestart jobs are similar to batch jobs. Due to the nature of prestart jobs, only the following i5/OS-specific attributes are explicitly inherited in a child process when you use prestart jobs:
   
   
   • Library list
   • Language identifier
   • Country or region identifier
   • Coded character set identifier
   • Default coded character set identifier
   • Locale (as specified in the user profile)

   The child process has the same user profile as the calling thread. However, the i5/OS job attributes come from the job description specified for the prestart job entry, and the run attributes come from the class that is associated with the i5/OS subsystem used for the prestart job entry.

   Notes:

   1. The prestart job entry QP0ZSPWP is used with prestart jobs that will not be creating threads. The prestart job entry QP0ZSPWT is used with prestart jobs that will allow multiple threads. Both types of prestart jobs may be used in the same subsystem. The prestart job entry must be defined for the subsystem that the spawnp() parent process runs under in order for it to be used.
      
      
   2. The following example defines a prestart job entry (QP0ZSPWP) for use by spawnp() under the subsystem QINTER. The spawnp() API must have the SPAWN_SETPJ_NP flag set (but not SPAWN_SETTHREAD_NP) in order to use these prestart jobs:

      ADDPJE SBSD(QSYS/QINTER) PGM(QSYS/QP0ZSPWP)
             INLJOBS(20) THRESHOLD(5) ADLJOBS(5)
             JOBD(QGPL/QDFTJOBD) MAXUSE(1)
             CLS(QGPL/QINTER)
      

   3. The following example defines a prestart job entry (QP0ZSPWT) that will create prestart jobs that are multithread capable for use by spawnp() under the subsystem QINTER. The spawnp() API must have both SPAWN_SETPJ_NP and SPAWN_SETTHREAD_NP flags set in order to use these prestart jobs. Also, the JOBD parameter must be a job description that allows multiple threads as follows:

      ADDPJE SBSD(QSYS/QINTER) PGM(QSYS/QP0ZSPWT)
             INLJOBS(20) THRESHOLD(5) ADLJOBS(5)
             JOBD(QSYS/QAMTJOBD) MAXUSE(1)
             CLS(QGPL/QINTER)
      

   Refer to the Work Management topic for complete details on prestart jobs.

8. Shell scripts are allowed for the child process. If a shell script is specified, the appropriate shell interpreter program is called. The shell script must be a text file and must contain the following format on the first line of the file:

      #!interpreter_path <options>
   

   where interpreter_path is the path to the shell interpreter program.

   If the calling process is multithreaded, file (the first parameter to spawnp()) must reference a threadsafe file system.

   spawnp() calls the shell interpreter, passing in the shell options and the arguments passed in as a parameter to spawnp(). The argument list passed into the shell interpreter will look like Arguments to Shell Interpreter.

   Arguments to Shell Interpreter
   

   See About Shell Scripts for an example using spawn() and shell scripts.

9. Only programs that expect arguments as null-terminated character strings can be spawned. The program that is run in the child process is called at it's initial entry point. The arguments explicitly passed to the program start with element argv[1] of the argv[] parameter that was specified during the call to spawnp(). The program language type determines how the arguments passed are seen by that program. For example, if the program language type is ILE C or ILE C++, the linkage can be described as:

     int main(int argc, char *argv[])
     {
     }
   

   where the following are true:

   • argc is the number of arguments in argv[].
   • argv[] is an array of arguments represented as null-terminated character strings.
   • The last entry in the array is NULL.
   • The first element in the array, argv[0], is automatically set to the name of the program. Any value specified for argv[0] during the call to spawnp() will be overwritten.
   • The remaining argv[] elements, if any, will correspond directly to the argv[] elements specified during the call to spawnp().

   The maximum number of arguments that can be specified is dependent on the following:

   • The maximum number of parameters allowed for the program that is run in the child process, as seen by the DSPPGM CL command. Some programs allow up to 65 535 parameters, while others may only allow up to 255 parameters. The value of SPAWN_MAX_NUM_ARGS is 255, in order to maintain compatibility with programs that only allow up to 255 parameters. If the maximum number is exceeded, spawnp() returns -1 with errno set to E2BIG.
   • The total size required for containing the arguments, which includes the array of pointers to strings, and the total size of all the strings. The total size is limited to approximately 16 500 000 bytes. If the total size is exceeded, spawnp() returns -1 with errno set to ENOMEM.
   
   
10. The child process does not inherit any of the environment variables of the parent process. That is, the default environment variable environment is empty. If the child process is to inherit all the parent process' environment variables, the extern variable environ can be used as the value for envp[] when spawnp() is called. If a specific set of environment variables is required in the child process, the user must build the envp[] array with the "name=value" strings. In the child process, spawnp() does the equivalent of a putenv() on each element of the envp[] array. Then the extern variable environ will be set and available to the child process' program.

    Note: If the user of spawnp() specifies the extern variable environ as the envp[] parameter, the user must successfully call one of the following APIs before calling spawnp():

    • getenv()
    • putenv()
    • Qp0zGetEnv()
    • Qp0zInitEnv()
    • Qp0zPutEnv()

    The extern variable environ is not initialized until one of these APIs is called in the current activation group. If environ is used in a call to spawnp() without first calling one of these APIs, spawnp() returns an error.

11. i5/OS handles stdin, stdout, and stderr differently than most UNIX systems. On most UNIX systems, stdin, stdout, and stderr have file descriptors 0, 1, and 2 reserved and allocated for them. On i5/OS, this is not the case. There are two ramifications of this difference:
    
    
    1. File descriptor 0, 1, and 2 are allocated to the first three files that have descriptors allocated to them. If an application writes to file descriptor 1 assuming it is stdout, the result will not be as expected.
       
       
    2. Any API that assumes stdin, stdout, and stderr are file descriptors 0, 1, and 2 will not behave as expected.

    Users and applications can enable descriptor-based standard I/O for child processes by setting environment variable QIBM_USE_DESCRIPTOR_STDIO to the value Y in the child process. This can be accomplished on the call to spawnp() by either of the following:

    1. Specifying the extern variable environ as the envp[] parameter. This assumes that the QIBM_USE_DESCRIPTOR_STDIO environment variable exists in the calling process.

       The environment variable can be set by using one of the following:

       • API putenv("QIBM_USE_DESCRIPTOR_STDIO=Y");
       • Command ADDENVVAR ENVVAR(QIBM_USE_DESCRIPTOR_STDIO) VALUE(Y)
       • Command CHGENVVAR ENVVAR(QIBM_USE_DESCRIPTOR_STDIO) VALUE(Y)
       
       
    2. Explicitly include "QIBM_USE_DESCRIPTOR_STDIO=Y" in the user-defined envp[] array with the "name=value" strings.

    If you enable descriptor-based standard I/O for child processes, file descriptors 0, 1, and 2 are automatically used for stdin, stdout, and stderr, respectively. However, spawnp() must be called using a fd_map that has file descriptors 0, 1, and 2 properly allocated. See About Shell Scripts for an example that enables descriptor-based standard I/O for a child process. Refer to WebSphere Development Studio: ILE C/C++ Programmer's Guide for complete details on this support.

12. Spawn users have a facility to aid in debugging child processes.

    To help the user start a debug session (when spawnp() is the mechanism used to start the process), the user sets the environment variable QIBM_CHILD_JOB_SNDINQMSG.

    If the environment variable is assigned a numerical value, it indicates the number of descendent levels that will be enabled for debugging. This support can be used to debug applications that create children, grandchildren, great-grandchildren, and so forth. When the environment variable has a value of 1, it enables debugging of all subsequent child processes. A value of 2 enables debugging of all subsequent child processes and grandchild processes.

    When the environment variable has a value less than or equal to 0, or any non-numerical value, debugging will not occur.

    Here are the steps a user would take to debug an application by using spawnp():

    Assume the user wants to debug child processes in an application called CHILDAPP found in library MYAPPLIB.

    • Set the QIBM_CHILD_JOB_SNDINQMSG environment variable to 1.

      The environment variable can be set by using one of the following:

      • API putenv("QIBM_CHILD_JOB_SNDINQMSG=1");
      • Command ADDENVVAR ENVVAR(QIBM_CHILD_JOB_SNDINQMSG) VALUE(1)
      • Command CHGENVVAR ENVVAR(QIBM_CHILD_JOB_SNDINQMSG) VALUE(1)
      
      
    • Call or run the application that specifies CHILDAPP.PGM as the fileon the spawnp() invocation. CHILDAPP will start running, send a CPAA980 *INQUIRY message to the user's message queue, and then will block, waiting for a reply to the message. Issue a Work with Active Jobs (WRKACTJOB) command and find the CHILDAPP in a MSGW job status. Option 7 (Display message) performed against this job will display the CPAA980 *INQUIRY message that was sent. As part of this message, the Qualified Job Name will be displayed in the proper format to pass to the Start Service Job (STRSRVJOB) command (for example, 145778/RANDYR/CHILDAPP).

      Note: Alternatively, a Display Messages (DSPMSG) command can be issued for the user, and the output searched for the specific CPAA980 *INQUIRY message.

      Note: If the job's inquiry message reply specifies using the default message reply, the child process will not block since the default reply for the CPAA980 *INQUIRY message is G.

    • Issue a Start Service Job against the child process: STRSRVJOB JOB(145778/RANDYR/CHILDAPP).
      
      
    • Issue a Start Debug Command: STRDBG PGM(MYAPPLIB/CHILDAPP).
      
      
    • Set whatever breakpoints are needed in CHILDAPP. When ready to continue, find the CPAA980 message and reply with G. This will unblock CHILDAPP, which allows it to run until a breakpoint is reached, at which time CHILDAPP will again stop.

      Note: If you reply with C to the CPAA980 message, the child process is ended before the child process' program ever receives control. In this case, on a subsequent call to wait() or waitpid(), the status information returned indicates WIFEXCEPTION(), which evaluates to a nonzero value, and WEXCEPTNUMBER() will evaluate to 0.

    • The application is now stopped at a breakpoint and debugging can proceed.
    
    
13. By default, the child's i5/OS simple job name is derived directly from the file parameter. If file is a symbolic link to another object, the i5/OS simple job name is derived from the symbolic link itself. For example, if file was set to CHILD.PGM, the child's i5/OS simple job name would be CHILD. If /usr/bin/daughter was a symbolic link to /QSYS.LIB/MYLIB.LIB/CHILD.PGM and file was set to daughter, the child's i5/OS simple job name would be DAUGHTER.

    If SPAWN_SETJOBNAMEPARENT_NP is set in inherit.flags, the child's i5/OS simple job name would be the same as the parent's i5/OS simple job name.

    If SPAWN_SETJOBNAMEARGV_NP is set in inherit.flags, the null-terminated character string represented by argv[0] of the argv[] parameter will be used for the child's i5/OS simple job name. The name can be up to 10 characters, must be uppercase, and must contain only those characters allowed for an i5/OS job name. For example, if file was set to CHILD.PGM, SPAWN_SETJOBNAMEARGV_NP was set ON, and argv[0] was set to SON, the child's i5/OS simple job name would be SON. If the first character of the name is invalid, the file will be used. If any of the remaining characters of the name are invalid, the valid characters up to that point will be used.

14. The _NP used at the end of certain flag names, that can be specified for the flags field of the inherit parameter, indicate the flag is a non-standard, i5/OS-platform-specific extension to the inheritance structure. Applications that wish to avoid using platform-specific extensions should not use these flags.
15. The child process has an associated process ID, which uses system resources. Those resources will remain in use, even after the child process has ended. In order to ensure those resources are reclaimed, the parent process should either successfully call wait() or waitpid(), or the parent process should end.

Attributes Inherited

The child process inherits the following POSIX attributes from the parent:

1. File descriptor table (mapped according to fd_map).

   Note: The following file descriptor table information does not apply to any of the scan descriptors which are created by the thread executing one of the scan-related exit programs (or any of its created threads). See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.

   • If fd_map is NULL, all file descriptors are inherited without being reordered.

     Note: File descriptors that have the FD_CLOEXEC file descriptor flag set are not inherited. File descriptors that are created as a result of the opendir() API (to implement open directory streams) are not inherited.

   • If fd_map is not NULL, it is a mapping from the file descriptor table of the parent process to the file descriptor table of the child process. fd_count specifies the number of file descriptors the child process will inherit. Except for those file descriptors designated by SPAWN_FDCLOSED, file descriptor i in the child process is specified by fd_map[i]. For example, fd_map[5]= 7 sets the child process' file descriptor 5 to the parent process' file descriptor 7. File descriptors fd_count through OPEN_MAX are closed in the child process, as are any file descriptors designated by SPAWN_FDCLOSED.

     Note: File descriptors that are specified in the fd_map array are inherited even if they have the FD_CLOEXEC file descriptor flag set. After inheritance, the FD_CLOEXEC flag in the child process' file descriptor is cleared.

   • For files descriptors that remain open, no attributes are changed.
     
     
   • If a file descriptor refers to an open instance in a file system that does not support file descriptors in two different processes pointing to the same open instance of a file, the file descriptor is closed in the child process.

     Only open files managed by the Root, QOpenSys, or user-defined file systems support inheritance of their file descriptors. All other file systems will have their file descriptors closed in the child process.

2. Process group ID
   
   
   • If inherit.flags is set to SPAWN_SETPGROUP, the child process group ID is set to the value in inherit.pgroup.

     Note: i5/OS does not support the ability to set the process group ID for the child process to a user-specified group ID. This is a deviation from the POSIX standard.

   • If inherit.pgroup is set to SPAWN_NEWPGROUP, the child process is put in a new process group with a process group ID equal to the process ID.
     
     
   • If inherit.pgroup is not set to SPAWN_NEWPGROUP, the child process inherits the process group of the parent process.

   If the process group that the child process is attempting to join has received the SIGKILL signal, the child process is ended.

3. Real user ID of the calling thread.
   
   
4. Real group ID of the calling thread.
   
   
5. Supplementary group IDs (group profile list) of the calling thread.
   
   
6. Current working directory of the parent process.
   
   
7. Root directory of the parent process.
   
   
8. File mode creation mask of the parent process.
   
   
9. Signal mask of the calling thread, except if the SPAWN_SETSIGMASK flag is set in inherit.flags. Then the child process will initially have the signal mask specified in inherit.mask.
   
   
10. Signal action vector, as determined by the following:
    
    
    • If the SPAWN_SETSIGDEF flag is set in inherit.flags, the signal specified in inherit.sigdefault is set to the default actions in the child process. Signals set to the default action in the parent process are set to the default action in the child process.
      
      
    • Signals set to be caught in the parent process are set to the default action in the child process.
      
      
    • Signals set to be ignored in the parent process are set to ignore in the child process, unless set to default by the above rules.
    
    
11. Priority of the parent process.

    Note: i5/OS prestart jobs do not inherit priority.

12. Scheduling policy (the i5/OS scheduling policy) of the parent process.
    
    
13. i5/OS-specific attributes of the parent, such as job attributes, run attributes, library list, and user profile.

    Note: i5/OS prestart jobs inherit a subset of i5/OS-specific attributes.

14. Resource limits of the parent process.
    
    

Related Information

• The <spawn.h> file (see Header Files for UNIX-Type Functions)
• QlgSpawnp()--Spawn Process with Path (using NLS-enabled file name)
• spawn()--Spawn Process
• sysconf()--Get System Configuration Variables
• wait()--Wait for Child Process to End
• waitpid()--Wait for Specific Child Process

Example

See Code disclaimer information for information pertaining to code examples.

For an example of using this function, see Using the Spawn Process and Wait for Child Process APIs in the API Examples.