]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)exec.3 6.4 (Berkeley) 4/19/91 | |
33 | .\" | |
34 | .\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu | |
35 | .\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com | |
305a0578 | 36 | .\" Modified, 24 Jun 2004, Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
37 | .\" Added note on casting NULL |
38 | .\" | |
69962544 | 39 | .TH EXEC 3 1993-11-29 "GNU" "Linux Programmer's Manual" |
fea681da MK |
40 | .SH NAME |
41 | execl, execlp, execle, execv, execvp \- execute a file | |
42 | .SH SYNOPSIS | |
43 | .B #include <unistd.h> | |
44 | .sp | |
45 | .B extern char **environ; | |
46 | .sp | |
47 | .BI "int execl(const char *" path ", const char *" arg ", ...);" | |
48 | .br | |
49 | .BI "int execlp(const char *" file ", const char *" arg ", ...);" | |
50 | .br | |
c7da82ff MK |
51 | .BI "int execle(const char *" path ", const char *" arg , |
52 | .br | |
53 | .BI " ..., char * const " envp "[]);" | |
fea681da MK |
54 | .br |
55 | .BI "int execv(const char *" path ", char *const " argv "[]);" | |
56 | .br | |
57 | .BI "int execvp(const char *" file ", char *const " argv "[]);" | |
58 | .SH DESCRIPTION | |
59 | The | |
e1d6264d | 60 | .BR exec () |
fea681da | 61 | family of functions replaces the current process image with a new process |
c13182ef MK |
62 | image. |
63 | The functions described in this manual page are front-ends for the | |
fea681da MK |
64 | function |
65 | .BR execve (2). | |
66 | (See the manual page for | |
fb186734 | 67 | .BR execve (2) |
fea681da MK |
68 | for detailed information about the replacement of the current process.) |
69 | .PP | |
70 | The initial argument for these functions is the pathname of a file which is | |
71 | to be executed. | |
72 | .PP | |
73 | The | |
74 | .I "const char *arg" | |
75 | and subsequent ellipses in the | |
e511ffb6 MK |
76 | .BR execl (), |
77 | .BR execlp (), | |
fea681da | 78 | and |
e511ffb6 | 79 | .BR execle () |
fea681da MK |
80 | functions can be thought of as |
81 | .IR arg0 , | |
82 | .IR arg1 , | |
83 | \&..., | |
84 | .IR argn . | |
85 | Together they describe a list of one or more pointers to null-terminated | |
86 | strings that represent the argument list available to the executed program. | |
2c5f1089 | 87 | The first argument, by convention, should point to the filename associated |
c13182ef MK |
88 | with the file being executed. |
89 | The list of arguments | |
fea681da | 90 | .I must |
8478ee02 | 91 | be terminated by a NULL |
fea681da MK |
92 | pointer, and, since these are variadic functions, this pointer must be cast |
93 | .BR "(char *) NULL" . | |
94 | .PP | |
95 | The | |
e511ffb6 | 96 | .BR execv () |
fea681da | 97 | and |
e511ffb6 | 98 | .BR execvp () |
fea681da | 99 | functions provide an array of pointers to null-terminated strings that |
c13182ef MK |
100 | represent the argument list available to the new program. |
101 | The first argument, by convention, should point to the filename | |
102 | associated with the file being executed. | |
103 | The array of pointers | |
fea681da | 104 | .I must |
8478ee02 | 105 | be terminated by a NULL pointer. |
fea681da MK |
106 | .PP |
107 | The | |
e511ffb6 | 108 | .BR execle () |
fea681da | 109 | function also specifies the environment of the executed process by following |
8478ee02 | 110 | the NULL |
fea681da | 111 | pointer that terminates the list of arguments in the parameter list or the |
c13182ef MK |
112 | pointer to the argv array with an additional parameter. |
113 | This additional | |
fea681da MK |
114 | parameter is an array of pointers to null-terminated strings and |
115 | .I must | |
c13182ef | 116 | be terminated by a NULL pointer. |
8478ee02 | 117 | The other functions take the environment for the new process |
fea681da MK |
118 | image from the external variable |
119 | .I environ | |
120 | in the current process. | |
acffc0bc | 121 | .SS Special semantics for execlp() and execvp() |
fea681da MK |
122 | .PP |
123 | The functions | |
e511ffb6 | 124 | .BR execlp () |
fea681da | 125 | and |
e511ffb6 | 126 | .BR execvp () |
fea681da | 127 | will duplicate the actions of the shell in searching for an executable file |
c13182ef MK |
128 | if the specified filename does not contain a slash (/) character. |
129 | The search path is the path specified in the environment by the | |
fea681da | 130 | .B PATH |
c13182ef MK |
131 | variable. |
132 | If this variable isn't specified, the default path | |
133 | ``:/bin:/usr/bin'' is used. | |
134 | In addition, certain | |
fea681da MK |
135 | errors are treated specially. |
136 | .PP | |
137 | If permission is denied for a file (the attempted | |
a51a49df | 138 | .BR execve (2) |
fea681da MK |
139 | returned |
140 | .BR EACCES ), | |
c13182ef MK |
141 | these functions will continue searching the rest of the search path. |
142 | If no other file is found, however, | |
143 | they will return with the global variable | |
fea681da MK |
144 | .I errno |
145 | set to | |
146 | .BR EACCES . | |
147 | .PP | |
148 | If the header of a file isn't recognized (the attempted | |
a51a49df | 149 | .BR execve (2) |
fea681da MK |
150 | returned |
151 | .BR ENOEXEC ), | |
988db661 | 152 | these functions will execute the shell |
acffc0bc MK |
153 | .RI ( /bin/sh ) |
154 | with the path of the file as its first argument. | |
c13182ef | 155 | (If this attempt fails, no further searching is done.) |
fea681da MK |
156 | .SH "RETURN VALUE" |
157 | If any of the | |
e1d6264d | 158 | .BR exec () |
c13182ef MK |
159 | functions returns, an error will have occurred. |
160 | The return value is \-1, | |
fea681da MK |
161 | and the global variable |
162 | .I errno | |
163 | will be set to indicate the error. | |
fea681da MK |
164 | .SH ERRORS |
165 | All of these functions may fail and set | |
166 | .I errno | |
167 | for any of the errors specified for the library function | |
168 | .BR execve (2). | |
2b2581ee MK |
169 | .SH "CONFORMING TO" |
170 | POSIX.1-2001. | |
8af1ba10 | 171 | .SH NOTES |
fea681da MK |
172 | On some other systems the default path (used when the environment |
173 | does not contain the variable \fBPATH\fR) has the current working | |
174 | directory listed after | |
175 | .I /bin | |
176 | and | |
177 | .IR /usr/bin , | |
c13182ef MK |
178 | as an anti-Trojan-horse measure. |
179 | Linux uses here the | |
fea681da MK |
180 | traditional "current directory first" default path. |
181 | .PP | |
182 | The behavior of | |
e511ffb6 | 183 | .BR execlp () |
fea681da | 184 | and |
e511ffb6 | 185 | .BR execvp () |
fea681da MK |
186 | when errors occur while attempting to execute the file is historic |
187 | practice, but has not traditionally been documented and is not specified by | |
c13182ef MK |
188 | the POSIX standard. |
189 | BSD (and possibly other systems) do an automatic | |
2f0af33b MK |
190 | sleep and retry if |
191 | .B ETXTBSY | |
192 | is encountered. | |
c13182ef | 193 | Linux treats it as a hard |
fea681da MK |
194 | error and returns immediately. |
195 | .PP | |
196 | Traditionally, the functions | |
e511ffb6 | 197 | .BR execlp () |
fea681da | 198 | and |
e511ffb6 | 199 | .BR execvp () |
fea681da MK |
200 | ignored all errors except for the ones described above and |
201 | .B ENOMEM | |
202 | and | |
203 | .BR E2BIG , | |
c13182ef MK |
204 | upon which they returned. |
205 | They now return if any error other than the ones | |
fea681da | 206 | described above occurs. |
e37e3282 MK |
207 | .SH "SEE ALSO" |
208 | .BR sh (1), | |
209 | .BR execve (2), | |
210 | .BR fork (2), | |
211 | .BR ptrace (2), | |
212 | .BR fexecve (3), | |
213 | .BR environ (7) |