[deliverable/binutils-gdb.git] / libiberty / pexecute.txh

@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)

Executes a program.

@var{program} and @var{argv} are the arguments to
@code{execv}/@code{execvp}.

@var{this_pname} is name of the calling program (i.e., @code{argv[0]}).

@var{temp_base} is the path name, sans suffix, of a temporary file to
use if needed.  This is currently only needed for MS-DOS ports that
don't use @code{go32} (do any still exist?).  Ports that don't need it
can pass @code{NULL}.

(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH}
should be searched (??? It's not clear that GCC passes this flag
correctly).  (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the
first process in chain.  (@code{@var{flags} & PEXECUTE_FIRST}) is
nonzero for the last process in chain.  The first/last flags could be
simplified to only mark the last of a chain of processes but that
requires the caller to always mark the last one (and not give up
early if some error occurs).  It's more robust to require the caller
to mark both ends of the chain.

The result is the pid on systems like Unix where we
@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
use @code{spawn}.  It is up to the caller to wait for the child.

The result is the @code{WEXITSTATUS} on systems like MS-DOS where we
@code{spawn} and wait for the child here.

Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
text of the error message with an optional argument (if not needed,
@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned.
@code{errno} is available to the caller to use.

@end deftypefn

@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})

Waits for a program started by @code{pexecute} to finish.

@var{pid} is the process id of the task to wait for. @var{status} is
the `status' argument to wait. @var{flags} is currently unused
(allows future enhancement without breaking upward compatibility).
Pass 0 for now.

The result is the pid of the child reaped, or -1 for failure
(@code{errno} says why).

On systems that don't support waiting for a particular child,
@var{pid} is ignored.  On systems like MS-DOS that don't really
multitask @code{pwait} is just a mechanism to provide a consistent
interface for the caller.

@end deftypefn

@undocumented pfinish

pfinish: finish generation of script

pfinish is necessary for systems like MPW where a script is generated
that runs the requested programs.
Commit	Line	Data
5a17353c DD	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.