.\" Copyright (c) 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
+.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
+.\" %%%LICENSE_END
.\"
.\" @(#)exec.3 6.4 (Berkeley) 4/19/91
.\"
.\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Added note on casting NULL
.\"
-.TH EXEC 3 2008-07-10 "GNU" "Linux Programmer's Manual"
+.TH EXEC 3 2016-03-15 "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
.B extern char **environ;
.sp
-.BI "int execl(const char *" path ", const char *" arg ", ...);"
+.BI "int execl(const char *" path ", const char *" arg ", ..."
.br
-.BI "int execlp(const char *" file ", const char *" arg ", ...);"
+.B " /* (char *) NULL */);"
.br
-.BI "int execle(const char *" path ", const char *" arg ,
+.BI "int execlp(const char *" file ", const char *" arg ", ..."
.br
-.BI " ..., char * const " envp "[]);"
+.B " /* (char *) NULL */);"
+.br
+.BI "int execle(const char *" path ", const char *" arg ", ..."
+.br
+.BI " /*, (char *) NULL, char * const " envp "[] */);"
.br
.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 "[]);"
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR execvpe ():
+_GNU_SOURCE
.SH DESCRIPTION
The
.BR exec ()
.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
-.I "const char *arg"
+.I "const char\ *arg"
and subsequent ellipses in the
.BR execl (),
.BR execlp (),
with the file being executed.
The list of arguments
.I must
-be terminated by a NULL
-pointer, and, since these are variadic functions, this pointer must be cast
-.IR "(char *) NULL" .
+be terminated by a null 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
associated with the file being executed.
The array of pointers
.I must
-be terminated by a NULL pointer.
+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 parameter list or the
-pointer to the argv array with an additional parameter.
-This additional
-parameter is an array of pointers to null-terminated strings and
+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.
+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 functions
-.BR execlp ()
+The
+.BR execlp (),
+.BR execvp (),
and
-.BR execvp ()
-will duplicate the actions of the shell in searching for an executable file
+.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.
-The search path is the path specified in the environment by the
+The file is sought in the colon-separated list of directory pathnames
+specified in the
.B PATH
-variable.
-If this variable isn't specified, the default path
-":/bin:/usr/bin" is used.
-In addition, certain
-errors are treated specially.
-.PP
+environment variable.
+If this variable isn't defined, the path list defaults to
+the current directory followed by the list of directories returned by
+.IR confstr(_CS_PATH) .
+(This
+.BR confstr (3)
+call typically returns the value "/bin:/usr/bin".)
+
+If the specified filename includes a slash character, then
+.B PATH
+is ignored, and the file at the specified pathname is executed.
+
+In addition, certain errors are treated specially.
+
If permission is denied for a file (the attempted
.BR execve (2)
-returned
+failed with the error
.BR EACCES ),
these functions will continue searching the rest of the search path.
If no other file is found, however,
-they will return with the global variable
+they will return with
.I errno
set to
.BR EACCES .
-.PP
+
If the header of a file isn't recognized (the attempted
.BR execve (2)
-returned
+failed with the error
.BR ENOEXEC ),
these functions will execute the shell
.RI ( /bin/sh )
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
+.SH RETURN VALUE
+The
.BR exec ()
-functions returns, an error will have occurred.
-The return value is \-1,
-and the global variable
+functions return only if an error has 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 "CONFORMING TO"
-POSIX.1-2001.
+.SH VERSIONS
+The
+.BR execvpe ()
+function first appeared in glibc 2.11.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbw29 lb lb
+l l l.
+Interface Attribute Value
+T{
+.BR execl (),
+.BR execle (),
+.BR execv ()
+T} Thread safety MT-Safe
+T{
+.BR execlp (),
+.BR execvp (),
+.BR execvpe ()
+T} Thread safety MT-Safe env
+.TE
+.SH CONFORMING TO
+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
upon which they returned.
They now return if any error other than the ones
described above occurs.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR sh (1),
.BR execve (2),
+.BR execveat (2),
.BR fork (2),
.BR ptrace (2),
.BR fexecve (3),
+.BR system (3),
.BR environ (7)
projects / thirdparty / man-pages.git / blobdiff