mirror of https://github.com/mkerrisk/man-pages
296 lines
8.8 KiB
Groff
296 lines
8.8 KiB
Groff
.\" 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:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" 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
|
|
.\"
|
|
.\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu
|
|
.\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com
|
|
.\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\" Added note on casting NULL
|
|
.\"
|
|
.TH EXEC 3 2017-09-15 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
execl, execlp, execle, execv, execvp, execvpe \- execute a file
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <unistd.h>
|
|
.PP
|
|
.B extern char **environ;
|
|
.PP
|
|
.BI "int execl(const char *" path ", const char *" arg ", ..."
|
|
.B " /* (char *) NULL */);"
|
|
.BI "int execlp(const char *" file ", const char *" arg ", ..."
|
|
.B " /* (char *) NULL */);"
|
|
.BI "int execle(const char *" path ", const char *" arg ", ..."
|
|
.BI " /*, (char *) NULL, char * const " envp "[] */);"
|
|
.BI "int execv(const char *" path ", char *const " argv "[]);"
|
|
.BI "int execvp(const char *" file ", char *const " argv "[]);"
|
|
.BI "int execvpe(const char *" file ", char *const " argv "[],"
|
|
.BI " char *const " envp "[]);"
|
|
.fi
|
|
.PP
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.PP
|
|
.BR execvpe ():
|
|
_GNU_SOURCE
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR exec ()
|
|
family of functions replaces the current process image with a new process
|
|
image.
|
|
The functions described in this manual page are front-ends for
|
|
.BR execve (2).
|
|
(See the manual page for
|
|
.BR execve (2)
|
|
for further details about the replacement of the current process image.)
|
|
.PP
|
|
The initial argument for these functions is the name of a file that is
|
|
to be executed.
|
|
.PP
|
|
The
|
|
.I "const char\ *arg"
|
|
and subsequent ellipses in the
|
|
.BR execl (),
|
|
.BR execlp (),
|
|
and
|
|
.BR execle ()
|
|
functions can be thought of as
|
|
.IR arg0 ,
|
|
.IR arg1 ,
|
|
\&...,
|
|
.IR argn .
|
|
Together they describe a list of one or more pointers to null-terminated
|
|
strings that represent the argument list available to the executed program.
|
|
The first argument, by convention, should point to the filename associated
|
|
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" .
|
|
.PP
|
|
The
|
|
.BR execv (),
|
|
.BR execvp (),
|
|
and
|
|
.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.
|
|
.PP
|
|
The
|
|
.BR execle ()
|
|
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 calling process.
|
|
.SS Special semantics for execlp() and execvp()
|
|
.PP
|
|
The
|
|
.BR execlp (),
|
|
.BR execvp (),
|
|
and
|
|
.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 file is sought in the colon-separated list of directory pathnames
|
|
specified in the
|
|
.B PATH
|
|
environment variable.
|
|
If this variable isn't defined, the path list defaults to
|
|
a list that includes the directories returned by
|
|
.IR confstr(_CS_PATH)
|
|
(which typically returns the value "/bin:/usr/bin")
|
|
and possibly also the current working directory;
|
|
see NOTES for further details.
|
|
.PP
|
|
If the specified filename includes a slash character, then
|
|
.B PATH
|
|
is ignored, and the file at the specified pathname is executed.
|
|
.PP
|
|
In addition, certain errors are treated specially.
|
|
.PP
|
|
If permission is denied for a file (the attempted
|
|
.BR execve (2)
|
|
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
|
|
.I errno
|
|
set to
|
|
.BR EACCES .
|
|
.PP
|
|
If the header of a file isn't recognized (the attempted
|
|
.BR execve (2)
|
|
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
|
|
The
|
|
.BR exec ()
|
|
functions return only if an error has occurred.
|
|
The return value is \-1, and
|
|
.I errno
|
|
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
|
|
.BR execve (2).
|
|
.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.
|
|
.PP
|
|
The
|
|
.BR execvpe ()
|
|
function is a GNU extension.
|
|
.SH NOTES
|
|
The default search path (used when the environment
|
|
does not contain the variable \fBPATH\fR)
|
|
shows some variation across systems.
|
|
It generally includes
|
|
.I /bin
|
|
and
|
|
.IR /usr/bin
|
|
(in that order) and may also include the current working directory.
|
|
On some other systems, the current working is included after
|
|
.I /bin
|
|
and
|
|
.IR /usr/bin ,
|
|
as an anti-Trojan-horse measure.
|
|
The glibc implementation long followed the traditional default where
|
|
the current working directory is included at the start of the search path.
|
|
However, some code refactoring during the development of glibc 2.24
|
|
.\" glibc commit 1eb8930608705702d5746e5491bab4e4429fcb83
|
|
caused the current working directory to be dropped altogether
|
|
from the default search path.
|
|
This accidental behavior change is considered mildly beneficial,
|
|
and won't be reverted.
|
|
.PP
|
|
The behavior of
|
|
.BR execlp ()
|
|
and
|
|
.BR execvp ()
|
|
when errors occur while attempting to execute the file is historic
|
|
practice, but has not traditionally been documented and is not specified by
|
|
the POSIX standard.
|
|
BSD (and possibly other systems) do an automatic
|
|
sleep and retry if
|
|
.B ETXTBSY
|
|
is encountered.
|
|
Linux treats it as a hard
|
|
error and returns immediately.
|
|
.PP
|
|
Traditionally, the functions
|
|
.BR execlp ()
|
|
and
|
|
.BR execvp ()
|
|
ignored all errors except for the ones described above and
|
|
.B ENOMEM
|
|
and
|
|
.BR E2BIG ,
|
|
upon which they returned.
|
|
They now return if any error other than the ones
|
|
described above occurs.
|
|
.SH BUGS
|
|
Before glibc 2.24,
|
|
.BR execl ()
|
|
and
|
|
.BR execle ()
|
|
employed
|
|
.BR realloc (3)
|
|
internally and were consequently not async-signal-safe,
|
|
in violation of the requirements of POSIX.1.
|
|
.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534
|
|
This was fixed in glibc 2.24.
|
|
.\"
|
|
.SS Architecture-specific details
|
|
On sparc/sparc64,
|
|
.BR execv ()
|
|
is provided as a system call by the kernel
|
|
(with the prototype shown above)
|
|
for compatibility with SunOS.
|
|
.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)
|