home *** CD-ROM | disk | FTP | other *** search
/ Liren Large Software Subsidy 7 / 07.iso / c / c082_144 / 2.ddi / CLIBSRC3.ZIP / SPAWNLE.C < prev    next >
Encoding:
C/C++ Source or Header  |  1992-06-10  |  6.4 KB  |  147 lines
  1. /*-----------------------------------------------------------------------*
  2.  * filename - spawnle.c
  3.  *
  4.  * function(s)
  5.  *        spawnle - creates and runs child processes
  6.  *-----------------------------------------------------------------------*/
  7.  
  8. /*
  9.  *      C/C++ Run Time Library - Version 5.0
  10.  *
  11.  *      Copyright (c) 1987, 1992 by Borland International
  12.  *      All Rights Reserved.
  13.  *
  14.  */
  15.  
  16.  
  17. #include <process.h>
  18. #include <_process.h>
  19. #include <errno.h>
  20. #include <stddef.h>
  21.  
  22. /*--------------------------------------------------------------------------*
  23.  
  24. Name            spawnle - creates and runs child processes
  25.  
  26. Usage           #include <process.h>
  27.                 int spawnle(int modeF, char *pathP, char *arg0, char *arg1,
  28.                             ..., char *argn, NULL, char *envP[]);
  29.  
  30. Prototype in    process.h
  31.  
  32. Description     The  functions  in  the  spawn...  family  create  and  run
  33.                 (execute) other files, known as child processes. There must
  34.                 be  sufficient memory  available for  loading and executing
  35.                 the child process.
  36.  
  37.                 The  value  of  modeP  determines  what  action the calling
  38.                 function  (the parent  process) will  take after  the spawn
  39.                 call. The possible values of modeP are:
  40.  
  41.                         P_WAIT          Puts parent process "on hold" until
  42.                                         child process completes execution.
  43.  
  44.                         P_NOWAIT        Continues  to  run  parent  process
  45.                                         while child process runs.
  46.  
  47.                         P_OVERLAY       Overlays  child  process  in memory
  48.                                         location   formerly   occupied   by
  49.                                         parent. Same as exec... call.
  50.  
  51.                 Note: P_NOWAIT  is currently not  available; using it  will
  52.                 generate an error value.
  53.  
  54.                 pathP is  the file name   of the called  child process. The
  55.                 spawn... functions  search for pathname using  the standard
  56.                 MS-DOS search algorithm:
  57.  
  58.                         . no  extension or no period-search  for exact file
  59.                           name;  if  not  successful,  add  .EXE and search
  60.                           again
  61.  
  62.                         . extension given-search only for exact file name
  63.  
  64.                         . period  given-search only for  file name with  no
  65.                           extension
  66.  
  67.                 The suffixes l,  v, p and e added to  spawn... "family name"
  68.                 specify that  the named function will  operate with certain
  69.                 capabilities.
  70.  
  71.                         p specifies  that the function will  search for the
  72.                           child in  those directories specified by  the DOS
  73.                           PATH environment variable.  Without the p suffix,
  74.                           the  function only  searches the root and current
  75.                           working directory.
  76.  
  77.                         l specifies that the argument pointers (arg0, arg1,
  78.                           ...,  argn)  are  passed  as  separate arguments.
  79.                           Typically, the l suffix is  used when you know in
  80.                           advance the  number of arguments to  be passed. A
  81.                           mandatory  NULL following  argn marks  the end of
  82.                           the list.
  83.  
  84.                         v specifies  that  the argument  pointers (argv[0],
  85.                           argv[1], ..., argv[n]) are  passed as an array of
  86.                           pointers.  Typically,  the  v  suffix  is  used a
  87.                           variable number of arguments is to be passed.
  88.  
  89.                         e specifies that the  argument envp maybe passed to
  90.                           the  child  process,  allowing  you  to alter the
  91.                           environment for the child  process. Without the e
  92.                           suffix, child process inherits the environment of
  93.                           the parent process.  This environment argument is
  94.                           an  array of  char *.  Each element  points to  a
  95.                           null-terminated character string of the form:
  96.  
  97.                                 envar=value
  98.  
  99.                           where  envar  is  the   name  of  an  environment
  100.                           variable, and value is  the string value to which
  101.                           envar is set. The last element of envp[] is NULL.
  102.                           When  envp[0]  is  NULL,  the  child inherits the
  103.                           parent's environment settings.
  104.  
  105.                 The spawn... functions  must have at least one  argument to
  106.                 the child process. This argument  is, by convention, a copy
  107.                 of pathname.  Under MS-DOS 3.x,  pathname is available  for
  108.                 the child process; under earlier versions, the child cannot
  109.                 use the passed value of arg0 (or argv[0]).
  110.  
  111.                 When  an spawn...  function call   is made,  any open  files
  112.                 remain open in the child process.
  113.  
  114. Return value    On a  successful execution, the  return value is  the child
  115.                 process's exit  status (0 for  normal termination). If  the
  116.                 child specifically calls exit with a non-zero argument, its
  117.                 exit status can be set to a non-zero value.
  118.                 On error, the spawn...  functions return -1, and errno  is set
  119.                 to  one of  the following:
  120.                         E2BIG   Argument list too long
  121.                         EINVAL  Invalid argument
  122.                         ENOENT  Path or file name not found
  123.                         ENOEXEC Exec format  error
  124.                         ENOMEM  Not enough core
  125.  
  126. *---------------------------------------------------------------------------*/
  127. int spawnle(int modeF, char *pathP, char *arg0, ...)
  128. {
  129.         register char   **p;
  130.  
  131.         /* Find the end of the argument list */
  132.  
  133.         for (p = &arg0; *p++ != NULL; );
  134.         switch(modeF)
  135.         {
  136.         case P_WAIT :
  137.                 return _LoadProg(_spawn, pathP, &arg0, (char **)*p, 0);
  138.         case P_OVERLAY :
  139.                 return _LoadProg(_exec, pathP, &arg0, (char **)*p, 0);
  140.         default :
  141.                 errno = EINVAL;
  142.                 return (-1);
  143.         }
  144. }
  145.  
  146.  
  147.