Correct annotation last entry
[binutils.git] / libiberty / pexecute.txh
blob269f031cc727c292055345ecb7547ebd92b6cf97
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)
3 Executes a program.
5 @var{program} and @var{argv} are the arguments to
6 @code{execv}/@code{execvp}.
8 @var{this_pname} is name of the calling program (i.e., @code{argv[0]}).
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}.
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.
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.
29 The result is the @code{WEXITSTATUS} on systems like MS-DOS where we
30 @code{spawn} and wait for the child here.
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.
37 @end deftypefn
39 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
41 Waits for a program started by @code{pexecute} to finish.
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.
48 The result is the pid of the child reaped, or -1 for failure
49 (@code{errno} says why).
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.
56 @end deftypefn
58 @undocumented pfinish
60 pfinish: finish generation of script
62 pfinish is necessary for systems like MPW where a script is generated
63 that runs the requested programs.