exec.3: Document execpe()

This function was added to glibc in version 2.11.
Also various other small rewrites in the page.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Michael Kerrisk 2010-09-25 08:22:31 +02:00
parent 91e1b56b2e
commit c63619503f
1 changed files with 37 additions and 24 deletions

View File

@ -36,9 +36,9 @@
.\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Added note on casting NULL
.\"
.TH EXEC 3 2010-09-23 "GNU" "Linux Programmer's Manual"
.TH EXEC 3 2010-09-25 "GNU" "Linux Programmer's Manual"
.SH NAME
execl, execlp, execle, execv, execvp \- execute a file
execl, execlp, execle, execv, execvp, execvpe \- execute a file
.SH SYNOPSIS
.B #include <unistd.h>
.sp
@ -55,6 +55,10 @@ execl, execlp, execle, execv, execvp \- execute a file
.BI "int execv(const char *" path ", char *const " argv "[]);"
.br
.BI "int execvp(const char *" file ", char *const " argv "[]);"
.br
.BI "int execvpe(const char *" file ", char *const " argv "[],"
.br
.BI " char *const " envp "[]);"
.SH DESCRIPTION
The
.BR exec ()
@ -66,7 +70,7 @@ The functions described in this manual page are front-ends for
.BR execve (2)
for further details about the replacement of the current process image.)
.PP
The initial argument for these functions is the pathname of a file which is
The initial argument for these functions is the name of a file that is
to be executed.
.PP
The
@ -92,9 +96,10 @@ pointer, and, since these are variadic functions, this pointer must be cast
.IR "(char *) NULL" .
.PP
The
.BR execv ()
.BR execv (),
.BR execvp (),
and
.BR execvp ()
.BR execvpe ()
functions provide an array of pointers to null-terminated strings that
represent the argument list available to the new program.
The first argument, by convention, should point to the filename
@ -105,26 +110,27 @@ be terminated by a NULL pointer.
.PP
The
.BR execle ()
function also specifies the environment of the executed process by following
the NULL
pointer that terminates the list of arguments in the argument list or the
pointer to the
.I argv
array with an additional argument.
This additional
and
.BR execvpe ()
functions allow the caller to specify the environment of the
executed program via the argument
.IR envp .
The
.I envp
argument is an array of pointers to null-terminated strings and
.I must
be terminated by a NULL pointer.
The other functions take the environment for the new process
image from the external variable
.I environ
in the current process.
in the calling process.
.SS Special semantics for execlp() and execvp()
.PP
The
.BR execlp ()
.BR execlp (),
.BR execvp (),
and
.BR execvp ()
.BR execvpe ()
functions duplicate the actions of the shell in
searching for an executable file
if the specified filename does not contain a slash (/) character.
@ -139,10 +145,9 @@ the current directory followed by the list of directories returned by
.BR confstr (3)
call typically returns the value "/bin:/usr/bin".)
If the specified filename includes a slash character,
then
If the specified filename includes a slash character, then
.B PATH
is ignored, and file at the specified pathname is executed.
is ignored, and the file at the specified pathname is executed.
In addition, certain errors are treated specially.
@ -166,21 +171,29 @@ these functions will execute the shell
with the path of the file as its first argument.
(If this attempt fails, no further searching is done.)
.SH "RETURN VALUE"
If any of the
The
.BR exec ()
functions returns, an error will have occurred.
functions only return if an error has have occurred.
The return value is \-1, and
.I errno
will be set to indicate the error.
is set to indicate the error.
.SH ERRORS
All of these functions may fail and set
.I errno
for any of the errors specified for the library function
for any of the errors specified for
.BR execve (2).
.SH
The
.BR execvpe ()
function first appeared in glibc 2.11.
.SH "CONFORMING TO"
POSIX.1-2001.
POSIX.1-2001, POSIX.1-2008.
The
.BR execvpe ()
function is a GNU extension.
.SH NOTES
On some other systems the default path (used when the environment
On some other systems, the default path (used when the environment
does not contain the variable \fBPATH\fR) has the current working
directory listed after
.I /bin