| .\" 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 2016-03-15 "GNU" "Linux Programmer's Manual" |
| .SH NAME |
| 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 ", ..." |
| .br |
| .B " /* (char *) NULL */);" |
| .br |
| .BI "int execlp(const char *" file ", const char *" arg ", ..." |
| .br |
| .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 () |
| 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 |
| 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) |
| 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 . |
| |
| 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. |
| |
| The |
| .BR execvpe () |
| function is a GNU extension. |
| .SH NOTES |
| 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 |
| .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 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) |