Chapter Contents

Previous

Next

spawn

Portability:

POSIX.1 conforming

SYNOPSIS

#include <spawn.h>
pid_t spawn(const char *path, 
            int count, 
            const int fd_map[], 
            struct inheritance *inh, 
            const char *argv[], 
            const char *envp[]);

DESCRIPTION

The spawn function creates a new process to run an executable program in the hierarchical file system. If indicated by an environment variable, an attempt is made to execute the process in the same address space as the caller. spawn permits the calling process to remap file descriptors, alter the signal handling, and change the process group of the new process.

The path argument specifies the name of the HFS file to be executed.

The count specifies the number of file descriptors to be remapped, and fd_map specifies a list of file descriptors that describe the remapping. If fd_map is 0 , no remapping is performed, and the child process receives all file descriptors open in the current process. If fd_map is not 0 , then for n less than count , file descriptor n in the child process is mapped to be the same file as fd_map[n] in the parent process. If fd_map[n] has the value SPAWN_FDCLOSED , file descriptor n will be closed in the child process. All file descriptors greater than or equal to count will be closed in the child process.

The inh argument specifies a pointer to an inheritance structure which defines how signals and process groups should be handled in the child process. The inheritance structure contains the following fields:

flags	bit flags defining required inheritance options
pgroup	an alternate process group for the new process
sigmask	a new signal mask for the child process
sigdefault	a set of signals to restore to default handling
ctlttyfd	a controlling terminal file descriptor for the child process

The inheritance structure can be used to request the following inheritance options.

If the SPAWN_SETGROUP flag is set in inh->flags , the child's process group will be set as specified by inh->pgroup . If inh->pgroup is 0 , the child will be created in a new process group. Otherwise, the new process will be assigned to the specified process group. If SPAWN_SETGROUP is not set, the new process is part of the same process group as the parent.

If the SPAWN_SETSIGDEF flag is set in inh->flags , each signal specified in inh->sigdefault (a value of type sigset_t ) is reset to default handling in the child process. All other signals inherit their handling from the parent process, as with the exec functions.

If the SPAWN_SETSIGDEF flag is not set, all signals inherit their handling from the parent in the manner of exec . If the SPAWN_SETSIGMASK flag is set in inh->flags , the initial signal mask for the new child process is as specified by inh->sigmask (a value of type sigset_t ). If the SPAWN_SETSIGMASK flag is not set, the child process inherits the signal mask of the parent process.

If the SPAWN_SETTCPGRP flag is set in inh->flags , the file descriptor specified by inh->ctlttyfd becomes the controlling terminal for the child process's foreground process group. If the SPAWN_SETTCPGRP flag is not set, the child process inherits the controlling terminal file descriptor from the parent process.

The argv argument to spawn specifies a list of arguments to be passed to the new process. argv is an array of strings, where argv[0] contains the name of the executable file, and the final element of argv is a NULL pointer value.

The envp argument to spawn specifies an array of environment variable values. Each element of the array is a string of the form:

var=value

The last element of the array must be a NULL pointer to indicate the end of the array. If the new process should inherit the environment variables of the calling process, pass the external environment variable pointer environ as envp .

Certain environment variables may be defined in the envp array to modify the operation of spawn . These are as follows:

If the environment variable _BPX_SHAREAS is defined and has the value YES , spawn will attempt to create the new process in the same address space as the parent address space.

Note:   The spawn may be unable to use the same address space for security or performance reasons, in which case a new address space will be created for the process.  

Note:   When several processes run in a single address space, some requirements of the POSIX standards are violated. (For instance, it is not possible for the child process to execute after termination of the parent in this case.)  
If _BPX_SHAREAS is not defined, or has any value other than YES , the child process will be executed in a new address space.

If the environment variable _BPX_SPAWN_SCRIPT is defined and set to YES , the spawn service recognizes an attempt to use spawn to invoke a shell script, and instead spawns a copy of the shell to run the script. If the environment variable is not defined, or has some value other than YES , the script is treated as a non-executable file.

RETURN VALUE

If successful, spawn returns the process id of the new process. If unsuccessful, spawn returns -1 .

USAGE NOTES

The spawn function can only be used with MVS 5.2.2 or a later release.

EXAMPLE

/* This example must be compiled 
   with the posix compiler option */

#include <spawn.h>
#include <unistd.h>
#include <signal.h>

/* posix environment variable ptr */
extern char **environ;

pid_t subprocess(const char *file,
                 int input_fd,
                 int output_fd,
                 int local)
{
  /* 
     This function uses the spawn system 
     call to create a subprocess. The 
     file descriptor specified by 
     input_fd is used as the new process' 
     standard input, and the file 
     descriptor specified by output_fd 
     is used as the new process' standard 
     output. If the flag local is non-zero, 
     the new process is created in the same 
     address space. If local is non-zero, 
     the process is created in a new address 
     space, and the signal SIGHUP is set to 
     be ignored in the new process.
   */

   /* file map for new process */
   int fd_map[3];

   /* inheritance structure */
   struct inheritance inh;

   /* argument vector for new process */
   const char *argv[2];

   /* old handler for SIGHUP */
   void (*hup_hndlr)(int);

   pid_t newpid;

   /* use input_fd as new stdin */
   fd_map[0] = input_fd;

   /* use output_fd as new stdout */
   fd_map[1] = output_fd;

   /* use same file for stderr */
   fd_map[2] = 2;

   inh.flags = SPAWN_SETSIGDEF;

   /* set all signals to default 
      in new process */
   sigfillset(inh.sigdefault);

   /* if spawning non-locally */
   if (local == 0) 
   {
      /* don't default SIGHUP */
      sigdelset(inh.sigdefault, SIGHUP);
      /* temporarily ignore SIGHUP */
      hup_hndlr = signal(SIGHUP, SIG_IGN);
   }

   setenv("_BPX_SHAREAS", 
          local? "YES": "NO");

   /* set up argv for new process, */
   argv[0] = file;

   /* no args */
   argv[1] = 0;

   /* spawn new procdess */
   newpid = spawn(file, 3, fd_map, &inh, 
                  argv, environ);

   /* restore SIGHUP handling 
      if necessary */
   if (local == 0)

      signal(SIGHUP, hup_hndlr);

   /* return id of new process */
   return newpid;
}

RELATED FUNCTIONS

execve , fork , oeattache , spawnp

Chapter Contents

Previous

Next

Top of Page

Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.