oeattach

oeattach

Create a Child Process as a Subtask

Portability: SAS/C extension

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTIONS
EXAMPLE
RELATED FUNCTIONS

SYNOPSIS

#include <sys/types.h>
#include <lclib.h>

pid_t oeattach(const char *file, char *const argv[]);

DESCRIPTION

The oeattach function creates a new process in the address space of the caller. In OS/390 terms, the new process runs as a subtask of the calling process. oeattach can be used as a high-performance substitute for fork followed by execv . It also provides a way for two processes to communicate using shared memory.

The file argument identifies the HFS file to be executed in the new process. The argv argument is a pointer to an array of pointers to null-terminated strings, to be passed as arguments to the new process. A NULL pointer marks the end of the array. The first argument, argv[0] , is required, and must contain the name of the executable file for the new process.

The environment variables for the new process are the same as the program scope environment variables for the calling process. Also, the new process inherits other attributes (for example, signal mask) from its caller as described for the execl function.

RETURN VALUE

If oeattach is successful, it returns the process ID of the new process. If it is unsuccessful, it returns -1 .

CAUTIONS

Because the process created by oeattach is an OS/390 subtask of the caller, this process is abnormally terminated if the calling process terminates.

Certain restrictions apply in the use of oeattach . For instance, it may not be used to invoke a setuid program. See the description of the BPX1ATX service routine in the Assembler Callable Services for OpenEdition MVS publication (SC23-3020) for further information.

Processes created in TSO by use of oeattach have only partial access to TSO facilities. They can read and write to the TSO terminal and handle TSO attention signals. They cannot use the system function to invoke TSO commands, use the SUBCOM interface, or access TSO EXTERNAL or PERMANENT scope environment variables. The envname function returns "OpenMVS" , not "TSO" , for a process created by oeattach .

EXAMPLE

This example invokes the ls shell command as an OS/390 subtask, and uses a pipe allocated to file descriptor 1 to obtain the output of ls and write it to stderr (which may be a non-HFS terminal or disk file if the example is run in OS/390 batch or TSO). Use of oeattach rather than fork and exec may be a significant performance enhancement.

#include 
#include 
#include 
#include 
#include 
#include 
 
main()
{
   int pipefds[2];
   pid_t pid;
   char *const parmList[] = {"/bin/ls", "-l", "/u/userid/dirname",
                             NULL };
   char lsout[200];           /* buffer for out ls output          */
   int amt;
   int status;                /* status code from ls               */

   fclose(stdout);            /* avoid stdio interfering with fd 1 */
   pipe(pipefds);             /* create both ends of a pipe        */
   dup2(pipefds[1],STDOUT_FILENO);
                              /* make write end of pipe fd 1       */
   if (pipefds[1] != 1) close(pipefds[1]);
                              /* close write end                   */
   pid = oeattach("/bin/ls", parmList);
                              /* run ls command as subtask         */
   close(1);                  /* close write end of pipe in parent */
   for(;;) {                  /* read from the pipe                */
      amt = read(pipefds[0], lsout, sizeof(lsout));
      if (amt <= 0) break;
      fwrite(lsout, 1, amt, stderr);  /* write ls output to stderr */
   }
   wait(&status);             /* wait for ls to complete           */
   close(pipefds[0]);         /* close pipe input end              */
   if (WIFEXITED(status)) exit(WEXITSTATUS(status));
   else             /* if ls failed, use kill to fail the same way */
      kill(0, WTERMSIG(status));
}

RELATED FUNCTIONS

fork , execv , oeattache

Chapter Contents
Previous
Next
Top of Page