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