uexec(PCI)                     6 January 1993                     uexec(PCI)


 Name

    uexec -  execute UNIX operating system command

 Syntax


    #include <pcilib.h>


    #include <memmdl.h>

    long uexec(drvnum, ucmdname, argv, envp,
    savestatus, error_code)
    int drvnum;
    char *ucmdname, *argv[], *envp[];
    int savestatus, *error_code;


 Description

    uexec is a DOS function call that starts the execution of a UNIX operat-
    ing system command on a host and returns the process ID.  The UNIX oper-
    ating system stdout, stderr, and stdin are all directed to /dev/null.

    drvnum is the drive number of the host on which the command is executed.
    Drive letters and numbers correspond in the following way:  A: = 1, B: =
    2, and so forth. If drvnum is 0, the program is executed on the host
    associated with the current drive.

    ucmdname points to a path name that identifies the UNIX operating system
    and the file to be executed. This can be a load module or a shell command
    file.  If the name contains no slash (/), the directories in the PATH
    environment variable of the new process are searched in order.

    argv is an array of character pointers to the arguments for the command.
    By convention, argv[0] points to the command name.  argv is terminated by
    a null pointer.

    envp is an array of character pointers to null-terminated strings.  These
    strings are combined with the environment strings of the server process
    to constitute the environment for the new process.  If one of the
    environment strings in envp defines an environment variable with the same
    name as an environment variable already in the server, the string in envp
    overrides the string inherited by the server.  envp is terminated by a
    null pointer.

    savestatus is an integer taking the following values:

       1       Save exit status on termination.
       0       Do not save exit status on termination.

    When the process exits, the exit status is optionally saved depending on
    the value of the savestatus flag.  The DOS uwait function may be used to
    poll for the exit status of the process.

 Return value

    On successful completion, the process ID of the child process returns.
    If the call fails for any reason, a value of -1 returns, and errorcode
    is set to indicate the error.

    The error codes for this call are:

       1       Error in request service (network error).
       2       The specified drvnum is not connected to a host.
       3       UNIX operating system exec failed.
       4       Invalid format.
       5       DOS memory allocation error.

    If the UNIX operating system file server process exits because the user
    logs out, any UNIX operating system processes started with uexec are
    killed unless they take steps to avoid this.  (See signal(S) for more in-
    formation.)

    When using shell features such as I/O redirection, use sh or csh as the
    cmdname and -c as the first argument.  The command line being executed by
    the shell should be the second argument.

    _________________________________________________________________________
       NOTE  The return value is a 32-bit integer.
    _________________________________________________________________________


 Example


               :
               :
       int  driveNum;
       long pid;
       int  saveStatus;
       int  errorCode;
               :
               :
       /*
       ** UNIX command to execute:
       **                who | sort > /tmp/result
       **
       ** Since our command has shell features, (i.e. "|" and ">")
       ** we need to UEXEC the Shell ("/bin/sh") and then pass
       ** our command as an argument to it.
       ** If we had a simple UNIX command which had no shell features,
       ** (for example "touch  filename") we would have simply UEXEC'ed
       ** the command itself, and there would have been no need for shell.
       */

       /* UNIX command being UEXEC'ed */
       char *uCommand = "/bin/sh";

       /* Create UEXEC argument string (i.e.: sh -c args) */
       char *args[] = {
                       "sh",
                       "-c",
                       "who | sort > /tmp/result",
                       NULL
                       };

       /* Set environment */
       char *envs[] = {
                       "PATH=.:/bin:/usr/bin:/usr/lbin:",
                       "TZ=PST8PDT",
                       NULL
                       };

               :
               :
       /*
       ** Execute the UNIX command on virtual drive
       ** D: (4), saving its exit status (saveStatus=1).
       */
       driveNum = 4;
       saveStatus = 1;
       if ((pid = uexec(driveNum,uCommand,args,envs,saveStatus,&errorCode))
               == -1L)
               errorHandler();
       else

               :
               :


 See also

    ukill(PCI), uwait(PCI)