compiler/clib/spawnvp.c

   1 /*
   2     Copyright © 1995-2003, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     spavnv() function, used to spawn new processes.
   6 */
   7
   8 #include <proto/dos.h>
   9 #include <string.h>
  10 #include <stdlib.h>
  11 #include <errno.h>
  12 #include <aros/debug.h>
  13
  14 #include "__upath.h"
  15 #include "__spawnv.h"
  16
  17 /*****************************************************************************
  18
  19     NAME */
  20 #include <process.h>
  21
  22         int spawnvp(
  23
  24 /*  SYNOPSIS */
  25          int         mode,
  26          const char *command,
  27          char *const argv[])
  28
  29 /*  FUNCTION
  30         Spawn a child process, given a vector of arguments. It's like spawnv(), but
  31         searches the command in the directories specified by the PATH environment
  32         variable.
  33
  34     INPUTS
  35         mode - the way the child process has to be loaded, and how the parent has to behave
  36                after the child process is initiated. Specify one of the following values:
  37
  38                P_WAIT    - the child program is loaded into memory, then it's executed while
  39                            the parent process waits for it to terminate, at which point the
  40                            patent process resumes execution.
  41
  42                P_NOWAIT  - the parent program is executed concurrently with the new child process.
  43
  44                P_OVERLAY - teplace the parent program with the child program in memory and then
  45                            execute the child. The parent program will never be resumed. This
  46                            mode is equivalent to calling one of the exec*() functions.
  47
  48         command - the command to execute. Unless it's an absolute path name, the command
  49                   will be searched in the directories specified by the PATH environment
  50                   variable.
  51
  52         argv - a pointer to a NULL terminated array of strings representing arguments to pass
  53                to the child process. The first entry in the array is conventionally the name of
  54                the program to spawn, but in any case it must _never_ be NULL, and the argv
  55                pointer itself must never be NULL either.
  56
  57     RESULT
  58
  59         If P_WAIT is specified, then the return code of the child program is returned.
  60         If instead P_NOWAIT is used, then the pid of the newly created process is returned.
  61         Finally, if P_OVERLAY is used, the function doesn't return unless an error has occurred,
  62         in which case -1 is returned also for the other modes and the global errno variable will
  63         hold the proper error code.
  64
  65     NOTES
  66
  67         The way the child process behaves regarding parent's file descriptors, signal handlers
  68         and so on is the same way it would behave with one of the exec*(3) functions.
  69         This, for one, means that all filedescriptors are inherited except the ones which have
  70         the close-on-exec flag set.
  71
  72     EXAMPLE
  73
  74     BUGS
  75
  76     SEE ALSO
  77         execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), getenv(),
  78         putenv(), setenv(), spawn(), spawnl(), spawnle(), spawnlp(), spawnlpe(), spawnp(),
  79         spawnve(), spawnvp(), spawnvpe(), wait(), waitpid()
  80
  81     INTERNALS
  82
  83         For now only the stdin, stout and stderr file descriptors are inherited, and signals
  84         are not handled yet.
  85
  86 ******************************************************************************/
  87 {
  88     return __spawnv(mode, command, 1, argv);
  89 }