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