toolchain/binutils/libiberty/pexecute.txh

   1 @deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int flags)
   2
   3 Executes a program.
   4
   5 @var{program} and @var{argv} are the arguments to
   6 @code{execv}/@code{execvp}.
   7
   8 @var{this_pname} is name of the calling program (i.e., @code{argv[0]}).
   9
  10 @var{temp_base} is the path name, sans suffix, of a temporary file to
  11 use if needed.  This is currently only needed for MS-DOS ports that
  12 don't use @code{go32} (do any still exist?).  Ports that don't need it
  13 can pass @code{NULL}.
  14
  15 (@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH}
  16 should be searched (??? It's not clear that GCC passes this flag
  17 correctly).  (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the
  18 first process in chain.  (@code{@var{flags} & PEXECUTE_FIRST}) is
  19 nonzero for the last process in chain.  The first/last flags could be
  20 simplified to only mark the last of a chain of processes but that
  21 requires the caller to always mark the last one (and not give up
  22 early if some error occurs).  It's more robust to require the caller
  23 to mark both ends of the chain.
  24
  25 The result is the pid on systems like Unix where we
  26 @code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
  27 use @code{spawn}.  It is up to the caller to wait for the child.
  28
  29 The result is the @code{WEXITSTATUS} on systems like MS-DOS where we
  30 @code{spawn} and wait for the child here.
  31
  32 Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
  33 text of the error message with an optional argument (if not needed,
  34 @var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned.
  35 @code{errno} is available to the caller to use.
  36
  37 @end deftypefn
  38
  39 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
  40
  41 Waits for a program started by @code{pexecute} to finish.
  42
  43 @var{pid} is the process id of the task to wait for. @var{status} is
  44 the `status' argument to wait. @var{flags} is currently unused
  45 (allows future enhancement without breaking upward compatibility).
  46 Pass 0 for now.
  47
  48 The result is the pid of the child reaped, or -1 for failure
  49 (@code{errno} says why).
  50
  51 On systems that don't support waiting for a particular child,
  52 @var{pid} is ignored.  On systems like MS-DOS that don't really
  53 multitask @code{pwait} is just a mechanism to provide a consistent
  54 interface for the caller.
  55
  56 @end deftypefn
  57
  58 @undocumented pfinish
  59
  60 pfinish: finish generation of script
  61
  62 pfinish is necessary for systems like MPW where a script is generated
  63 that runs the requested programs.