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