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