Commit | Line | Data |
---|---|---|
ef0a718e KB |
1 | .\" Copyright (c) 1991 The Regents of the University of California. |
2 | .\" All rights reserved. | |
6db60273 | 3 | .\" |
ef0a718e | 4 | .\" %sccs.include.redist.man% |
6db60273 | 5 | .\" |
ef0a718e KB |
6 | .\" @(#)exec.3 6.3 (Berkeley) %G% |
7 | .\" | |
8 | .TH EXEC 3 "" | |
6db60273 KM |
9 | .UC 5 |
10 | .SH NAME | |
ef0a718e | 11 | execl, execlp, execle, exect, execv, execvp \- execute a file |
6db60273 KM |
12 | .SH SYNOPSIS |
13 | .nf | |
ef0a718e KB |
14 | .ft B |
15 | extern char **environ; | |
16 | .sp | |
17 | execl(const char *path, const char *arg, ...); | |
18 | execlp(const char *file, const char *arg, ...); | |
19 | execle(const char *path, const char *arg, ..., | |
20 | .ti +5 | |
21 | char *const envp[]); | |
22 | exect(const char *path, char *const argv[], | |
23 | .ti +5 | |
24 | char *const envp[]); | |
25 | execv(const char *path, char *const argv[]); | |
26 | execvp(const char *file, char *const argv[]); | |
27 | .ft R | |
6db60273 KM |
28 | .fi |
29 | .SH DESCRIPTION | |
ef0a718e KB |
30 | The exec family of functions replaces the current process image with a |
31 | new process image. | |
32 | The functions described in this manual page are front-ends for the function | |
33 | .IR execve (2). | |
34 | (See the manual page for | |
35 | .I execve | |
36 | for detailed information about the replacement of the current process.) | |
6db60273 | 37 | .PP |
ef0a718e KB |
38 | The initial argument for these functions is the pathname of a file which |
39 | is to be executed. | |
6db60273 | 40 | .PP |
ef0a718e KB |
41 | The ``const char *arg'' and subsequent ellipses in the |
42 | .IR execl , | |
43 | .IR execlp , | |
44 | and | |
45 | .I execle | |
46 | functions can be thought of as | |
47 | .IR arg0 , | |
48 | .IR arg1 , | |
49 | \&..., | |
50 | .IR argn . | |
51 | Together they describe a list of one or more pointers to null-terminated | |
52 | strings that represent the argument list available to the executed program. | |
53 | The first argument, by convention, should point to the file name associated | |
54 | with the file being executed. | |
55 | The list of arguments | |
56 | .B must | |
57 | be terminated by a NULL pointer. | |
6db60273 KM |
58 | .PP |
59 | The | |
ef0a718e KB |
60 | .IR exect , |
61 | .IR execv , | |
62 | and | |
63 | .I execvp | |
64 | functions provide an array of pointers to null-terminated strings that | |
65 | represent the argument list available to the new program. | |
66 | The first argument, by convention, should point to the file name associated | |
67 | with the file begin executed. | |
68 | The array of pointers | |
69 | .B must | |
70 | be terminated by a NULL pointer. | |
6db60273 KM |
71 | .PP |
72 | The | |
ef0a718e KB |
73 | .I execle |
74 | and | |
6db60273 | 75 | .I exect |
ef0a718e KB |
76 | functions also specify the environment of the executed process by following |
77 | the NULL pointer that terminates the list of arguments in the parameter list | |
78 | or the pointer to the argv array with an additional parameter. | |
79 | This additional parameter is an array of pointers to null-terminated strings | |
80 | and | |
81 | .B must | |
82 | be terminated by a NULL pointer. | |
83 | The other functions take the environment for the new process image from the | |
84 | external variable | |
85 | .I environ | |
86 | in the current process. | |
6db60273 | 87 | .PP |
ef0a718e | 88 | Some of these functions have special semantics. |
6db60273 | 89 | .PP |
ef0a718e KB |
90 | The functions |
91 | .I execlp | |
6db60273 | 92 | and |
ef0a718e KB |
93 | .I execvp |
94 | will duplicate the actions of the shell in searching for an executable file | |
95 | if the specified file name does not contain a slash (``/'') character. | |
96 | The search path is the path specified in the environment by ``PATH'' variable. | |
97 | If this variable isn't specified, the default path ``/bin:/usr/bin:'' is | |
98 | used. | |
99 | In addtion, certain errors are treated specially. | |
6db60273 | 100 | .PP |
ef0a718e KB |
101 | If permission is denied for a file (the attempted |
102 | .I execve | |
103 | returned EACCES), these functions will continue searching the rest of | |
104 | the search path. | |
105 | If no other file is found, however, they will return with | |
106 | .I errno | |
107 | set to EACCES. | |
6db60273 | 108 | .PP |
ef0a718e KB |
109 | If the header of a file isn't recognized (the attempted |
110 | .I execve | |
111 | returned ENOEXEC), these functions will execute the shell with the path of | |
112 | the file as its first argument. | |
113 | (If this attempt fails, no further searching is done.) | |
114 | .PP | |
115 | If the file is currently busy (the attempted | |
116 | .I execve | |
117 | returned ETXTBUSY), these functions will sleep for several seconds, | |
118 | periodically re-attempting to execute the file. | |
6db60273 | 119 | .PP |
ef0a718e KB |
120 | The function |
121 | .I exect | |
122 | executes a file with the program tracing facilities enabled (see | |
123 | .IR ptrace (2)). | |
124 | .SH "RETURN VALUE" | |
125 | If any of the | |
126 | .I exec | |
127 | functions returns, an error will have occurred. | |
128 | The return value is -1, and | |
129 | .I errno | |
130 | will be set to indicate the error. | |
131 | .SH ERRORS | |
132 | .IR Execl , | |
133 | .IR execle , | |
134 | .I execlp | |
6db60273 KM |
135 | and |
136 | .I execvp | |
ef0a718e KB |
137 | may fail and set |
138 | .I errno | |
139 | for any of the errors specified for the library functions | |
140 | .IR execve (2) | |
6db60273 | 141 | and |
ef0a718e KB |
142 | .IR malloc (3). |
143 | .PP | |
144 | .I Exect | |
145 | and | |
146 | .I execv | |
147 | may fail and set | |
148 | .I errno | |
149 | for any of the errors specified for the library function | |
150 | .IR execve (2). | |
6db60273 | 151 | .SH FILES |
ef0a718e KB |
152 | /bin/sh The shell. |
153 | .SH "SEE ALSO" | |
154 | sh(1), execve(2), fork(2), ptrace(2), environ(7), | |
155 | .SH COMPATIBILITY | |
156 | Historically, the default path for the | |
6db60273 | 157 | .I execlp |
ef0a718e | 158 | and |
6db60273 | 159 | .I execvp |
ef0a718e KB |
160 | functions was ``:/bin:/usr/bin''. |
161 | This was changed to place the current directory last to enhance system | |
162 | security. | |
163 | .PP | |
164 | The behavior of | |
165 | .I execlp | |
166 | and | |
167 | .I execvp | |
168 | when errors occur while attempting to execute the file is historic | |
169 | practice, but has not traditionally been documented and is not specified | |
170 | by the POSIX standard. | |
171 | .PP | |
172 | Traditionally, the functions | |
173 | .I execlp | |
174 | and | |
6db60273 | 175 | .I execvp |
ef0a718e KB |
176 | ignored all errors except for the ones described above and ENOMEM and |
177 | E2BIG, upon which they returned. | |
178 | They now return if any error other than the ones described above occurs. | |
179 | .SH STANDARDS | |
180 | .IR Execl , | |
181 | .IR execv , | |
182 | .IR execle , | |
183 | .IR execlp | |
6db60273 | 184 | and |
ef0a718e KB |
185 | .I execvp |
186 | conform to IEEE Std 1003.1-1988 (``POSIX''). |