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
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 24 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Added note on casting NULL
|
|
|
|
.\"
|
|
|
|
.TH EXEC 3 1993-11-29 "BSD MANPAGE" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
execl, execlp, execle, execv, execvp \- execute a file
|
|
|
|
.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 "[]);"
|
|
|
|
.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
|
|
|
|
image. The functions described in this manual page are front-ends for the
|
|
|
|
function
|
|
|
|
.BR execve (2).
|
|
|
|
(See the manual page for
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR execve ()
|
2004-11-03 13:51:07 +00:00
|
|
|
for detailed information about the replacement of the current process.)
|
|
|
|
.PP
|
|
|
|
The initial argument for these functions is the pathname of a file which is
|
|
|
|
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
|
2004-11-03 13:51:07 +00:00
|
|
|
with the file being executed. The list of arguments
|
|
|
|
.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
|
|
|
|
.BR "(char *) NULL" .
|
|
|
|
.PP
|
|
|
|
The
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR execv ()
|
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
|
|
|
functions provide an array of pointers to null-terminated strings that
|
|
|
|
represent the argument list available to the new program. The first
|
2006-02-12 22:15:41 +00:00
|
|
|
argument, by convention, should point to the filename associated with the
|
2004-11-03 13:51:07 +00:00
|
|
|
file being executed. The array of pointers
|
|
|
|
.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 ()
|
2004-11-03 13:51:07 +00:00
|
|
|
function also specifies the environment of the executed process by following
|
2005-11-02 13:55:25 +00:00
|
|
|
the NULL
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
|
|
|
.I must
|
2005-11-02 13:55:25 +00:00
|
|
|
be terminated by a NULL pointer.
|
|
|
|
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
|
|
|
|
in the current process.
|
|
|
|
.PP
|
|
|
|
Some of these functions have special semantics.
|
|
|
|
.PP
|
|
|
|
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
|
|
|
will duplicate the actions of the shell in searching for an executable file
|
2006-02-12 22:15:41 +00:00
|
|
|
if the specified filename does not contain a slash (/) character. The
|
2004-11-03 13:51:07 +00:00
|
|
|
search path is the path specified in the environment by 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
|
|
|
|
If permission is denied for a file (the attempted
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR execve ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returned
|
|
|
|
.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
|
|
|
|
.I errno
|
|
|
|
set to
|
|
|
|
.BR EACCES .
|
|
|
|
.PP
|
|
|
|
If the header of a file isn't recognized (the attempted
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR execve ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returned
|
|
|
|
.BR ENOEXEC ),
|
|
|
|
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
|
2005-10-19 07:29:28 +00:00
|
|
|
.BR exec ()
|
2004-11-03 13:51:07 +00:00
|
|
|
functions returns, an error will have occurred. The return value is \-1,
|
|
|
|
and the global variable
|
|
|
|
.I errno
|
|
|
|
will be set to indicate the error.
|
|
|
|
.SH FILES
|
|
|
|
.I /bin/sh
|
|
|
|
.SH ERRORS
|
|
|
|
All of these functions may fail and set
|
|
|
|
.I errno
|
|
|
|
for any of the errors specified for the library function
|
|
|
|
.BR execve (2).
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR sh (1),
|
|
|
|
.BR execve (2),
|
|
|
|
.BR fork (2),
|
|
|
|
.BR ptrace (2),
|
2006-03-06 04:55:51 +00:00
|
|
|
.BR fexecve (3),
|
2006-04-21 00:45:46 +00:00
|
|
|
.BR environ (7)
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH COMPATIBILITY
|
|
|
|
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
|
|
|
|
and
|
|
|
|
.IR /usr/bin ,
|
|
|
|
as an anti-Trojan-horse measure. Linux uses here the
|
|
|
|
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
|
|
|
|
the POSIX standard. BSD (and possibly other systems) do an automatic
|
|
|
|
sleep and retry if ETXTBSY is encountered. Linux treats it as a hard
|
|
|
|
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 ,
|
|
|
|
upon which they returned. They now return if any error other than the ones
|
|
|
|
described above occurs.
|
|
|
|
.SH "CONFORMING TO"
|
2006-08-03 13:57:30 +00:00
|
|
|
POSIX.1-2001.
|