2004-11-03 13:51:07 +00:00
|
|
|
.\" Copyright (c) 1991 The Regents of the University of California.
|
|
|
|
.\" All rights reserved.
|
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
|
|
|
.\" @(#)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
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added note on casting NULL
|
|
|
|
.\"
|
2010-09-25 06:22:31 +00:00
|
|
|
.TH EXEC 3 2010-09-25 "GNU" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2010-09-25 06:22:31 +00:00
|
|
|
execl, execlp, execle, execv, execvp, execvpe \- execute a file
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.sp
|
|
|
|
.B extern char **environ;
|
|
|
|
.sp
|
|
|
|
.BI "int execl(const char *" path ", const char *" arg ", ...);"
|
|
|
|
.br
|
|
|
|
.BI "int execlp(const char *" file ", const char *" arg ", ...);"
|
|
|
|
.br
|
2006-03-05 22:59:17 +00:00
|
|
|
.BI "int execle(const char *" path ", const char *" arg ,
|
|
|
|
.br
|
|
|
|
.BI " ..., char * const " envp "[]);"
|
2004-11-03 13:51:07 +00:00
|
|
|
.br
|
|
|
|
.BI "int execv(const char *" path ", char *const " argv "[]);"
|
|
|
|
.br
|
|
|
|
.BI "int execvp(const char *" file ", char *const " argv "[]);"
|
2010-09-25 06:22:31 +00:00
|
|
|
.br
|
|
|
|
.BI "int execvpe(const char *" file ", char *const " argv "[],"
|
|
|
|
.br
|
|
|
|
.BI " char *const " envp "[]);"
|
2010-09-25 16:01:45 +00:00
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.sp
|
|
|
|
.BR execvpe ():
|
|
|
|
_GNU_SOURCE
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
The
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR exec ()
|
2004-11-03 13:51:07 +00:00
|
|
|
family of functions replaces the current process image with a new process
|
2007-04-12 22:42:49 +00:00
|
|
|
image.
|
2008-07-09 09:51:47 +00:00
|
|
|
The functions described in this manual page are front-ends for
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR execve (2).
|
|
|
|
(See the manual page for
|
2007-05-12 00:30:29 +00:00
|
|
|
.BR execve (2)
|
2008-07-09 09:51:47 +00:00
|
|
|
for further details about the replacement of the current process image.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2010-09-25 06:22:31 +00:00
|
|
|
The initial argument for these functions is the name of a file that is
|
2004-11-03 13:51:07 +00:00
|
|
|
to be executed.
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I "const char *arg"
|
|
|
|
and subsequent ellipses in the
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execl (),
|
|
|
|
.BR execlp (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execle ()
|
2004-11-03 13:51:07 +00:00
|
|
|
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.
|
2006-02-12 22:15:41 +00:00
|
|
|
The first argument, by convention, should point to the filename associated
|
2007-04-12 22:42:49 +00:00
|
|
|
with the file being executed.
|
|
|
|
The list of arguments
|
2004-11-03 13:51:07 +00:00
|
|
|
.I must
|
2005-11-02 13:55:25 +00:00
|
|
|
be terminated by a NULL
|
2004-11-03 13:51:07 +00:00
|
|
|
pointer, and, since these are variadic functions, this pointer must be cast
|
2008-07-09 09:51:47 +00:00
|
|
|
.IR "(char *) NULL" .
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The
|
2010-09-25 06:22:31 +00:00
|
|
|
.BR execv (),
|
|
|
|
.BR execvp (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2010-09-25 06:22:31 +00:00
|
|
|
.BR execvpe ()
|
2004-11-03 13:51:07 +00:00
|
|
|
functions provide an array of pointers to null-terminated strings that
|
2007-04-12 22:42:49 +00:00
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
.I must
|
2005-11-02 13:55:25 +00:00
|
|
|
be terminated by a NULL pointer.
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execle ()
|
2010-09-25 06:22:31 +00:00
|
|
|
and
|
|
|
|
.BR execvpe ()
|
|
|
|
functions allow the caller to specify the environment of the
|
|
|
|
executed program via the argument
|
|
|
|
.IR envp .
|
|
|
|
The
|
|
|
|
.I envp
|
2008-07-10 20:53:08 +00:00
|
|
|
argument is an array of pointers to null-terminated strings and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I must
|
2007-04-12 22:42:49 +00:00
|
|
|
be terminated by a NULL pointer.
|
2005-11-02 13:55:25 +00:00
|
|
|
The other functions take the environment for the new process
|
2004-11-03 13:51:07 +00:00
|
|
|
image from the external variable
|
|
|
|
.I environ
|
2010-09-25 06:22:31 +00:00
|
|
|
in the calling process.
|
2007-05-21 09:16:32 +00:00
|
|
|
.SS Special semantics for execlp() and execvp()
|
2004-11-03 13:51:07 +00:00
|
|
|
.PP
|
2010-09-23 15:23:59 +00:00
|
|
|
The
|
2010-09-25 06:22:31 +00:00
|
|
|
.BR execlp (),
|
|
|
|
.BR execvp (),
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2010-09-25 06:22:31 +00:00
|
|
|
.BR execvpe ()
|
2010-09-23 15:23:59 +00:00
|
|
|
functions duplicate the actions of the shell in
|
|
|
|
searching for an executable file
|
2007-04-12 22:42:49 +00:00
|
|
|
if the specified filename does not contain a slash (/) character.
|
2010-09-23 15:23:59 +00:00
|
|
|
The file is sought in the colon-separated list of directory pathnames
|
|
|
|
specified in the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B PATH
|
2010-09-23 15:23:59 +00:00
|
|
|
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".)
|
|
|
|
|
2010-09-25 06:22:31 +00:00
|
|
|
If the specified filename includes a slash character, then
|
2010-09-23 15:35:16 +00:00
|
|
|
.B PATH
|
2010-09-25 06:22:31 +00:00
|
|
|
is ignored, and the file at the specified pathname is executed.
|
2010-09-23 15:35:16 +00:00
|
|
|
|
|
|
|
In addition, certain errors are treated specially.
|
2010-09-23 15:33:20 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
If permission is denied for a file (the attempted
|
2007-05-21 17:45:30 +00:00
|
|
|
.BR execve (2)
|
2008-08-19 15:26:42 +00:00
|
|
|
failed with the error
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR EACCES ),
|
2007-04-12 22:42:49 +00:00
|
|
|
these functions will continue searching the rest of the search path.
|
|
|
|
If no other file is found, however,
|
2009-02-23 02:34:12 +00:00
|
|
|
they will return with
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
set to
|
|
|
|
.BR EACCES .
|
2010-09-23 15:33:20 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
If the header of a file isn't recognized (the attempted
|
2007-05-21 17:45:30 +00:00
|
|
|
.BR execve (2)
|
2008-08-19 15:26:42 +00:00
|
|
|
failed with the error
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR ENOEXEC ),
|
2007-06-21 22:55:04 +00:00
|
|
|
these functions will execute the shell
|
2007-05-21 09:16:32 +00:00
|
|
|
.RI ( /bin/sh )
|
|
|
|
with the path of the file as its first argument.
|
2007-04-12 22:42:49 +00:00
|
|
|
(If this attempt fails, no further searching is done.)
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2010-09-25 06:22:31 +00:00
|
|
|
The
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR exec ()
|
2010-09-25 06:22:31 +00:00
|
|
|
functions only return if an error has have occurred.
|
2009-02-23 02:34:12 +00:00
|
|
|
The return value is \-1, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
2010-09-25 06:22:31 +00:00
|
|
|
is set to indicate the error.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH ERRORS
|
|
|
|
All of these functions may fail and set
|
|
|
|
.I errno
|
2010-09-25 06:22:31 +00:00
|
|
|
for any of the errors specified for
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR execve (2).
|
2010-09-25 16:02:26 +00:00
|
|
|
.SH VERSIONS
|
2010-09-25 06:22:31 +00:00
|
|
|
The
|
|
|
|
.BR execvpe ()
|
|
|
|
function first appeared in glibc 2.11.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SH "CONFORMING TO"
|
2010-09-25 06:22:31 +00:00
|
|
|
POSIX.1-2001, POSIX.1-2008.
|
|
|
|
|
|
|
|
The
|
|
|
|
.BR execvpe ()
|
|
|
|
function is a GNU extension.
|
2007-05-16 17:35:34 +00:00
|
|
|
.SH NOTES
|
2010-09-25 06:22:31 +00:00
|
|
|
On some other systems, the default path (used when the environment
|
2004-11-03 13:51:07 +00:00
|
|
|
does not contain the variable \fBPATH\fR) has the current working
|
|
|
|
directory listed after
|
|
|
|
.I /bin
|
|
|
|
and
|
|
|
|
.IR /usr/bin ,
|
2007-04-12 22:42:49 +00:00
|
|
|
as an anti-Trojan-horse measure.
|
|
|
|
Linux uses here the
|
2004-11-03 13:51:07 +00:00
|
|
|
traditional "current directory first" default path.
|
|
|
|
.PP
|
|
|
|
The behavior of
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execlp ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execvp ()
|
2004-11-03 13:51:07 +00:00
|
|
|
when errors occur while attempting to execute the file is historic
|
|
|
|
practice, but has not traditionally been documented and is not specified by
|
2007-04-12 22:42:49 +00:00
|
|
|
the POSIX standard.
|
|
|
|
BSD (and possibly other systems) do an automatic
|
2007-06-22 19:42:52 +00:00
|
|
|
sleep and retry if
|
|
|
|
.B ETXTBSY
|
|
|
|
is encountered.
|
2007-04-12 22:42:49 +00:00
|
|
|
Linux treats it as a hard
|
2004-11-03 13:51:07 +00:00
|
|
|
error and returns immediately.
|
|
|
|
.PP
|
|
|
|
Traditionally, the functions
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execlp ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execvp ()
|
2004-11-03 13:51:07 +00:00
|
|
|
ignored all errors except for the ones described above and
|
|
|
|
.B ENOMEM
|
|
|
|
and
|
|
|
|
.BR E2BIG ,
|
2007-04-12 22:42:49 +00:00
|
|
|
upon which they returned.
|
|
|
|
They now return if any error other than the ones
|
2004-11-03 13:51:07 +00:00
|
|
|
described above occurs.
|
2007-05-16 18:25:50 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR sh (1),
|
|
|
|
.BR execve (2),
|
|
|
|
.BR fork (2),
|
|
|
|
.BR ptrace (2),
|
|
|
|
.BR fexecve (3),
|
|
|
|
.BR environ (7)
|