| 1 | .TH EXEC 2 |
| 2 | .SH NAME |
| 3 | execl, execv, execle, execve, execlp, execvp, exec, exece, environ \- execute a file |
| 4 | .SH SYNOPSIS |
| 5 | .B execl(name, arg0, arg1, ..., argn, 0) |
| 6 | .br |
| 7 | .B char *name, *arg0, *arg1, ..., *argn; |
| 8 | .PP |
| 9 | .B execv(name, argv) |
| 10 | .br |
| 11 | .B char *name, *argv[ ]; |
| 12 | .PP |
| 13 | .B execle(name, arg0, arg1, ..., argn, 0, envp) |
| 14 | .br |
| 15 | .B char *name, *arg0, *arg1, ..., *argn, *envp[ ]; |
| 16 | .PP |
| 17 | .B execve(name, argv, envp); |
| 18 | .br |
| 19 | .B char *name, *argv[ ], *envp[ ]; |
| 20 | .PP |
| 21 | .B extern char **environ; |
| 22 | .SH DESCRIPTION |
| 23 | .I Exec |
| 24 | in all its forms |
| 25 | overlays the calling process with the named file, then |
| 26 | transfers to the |
| 27 | entry point of the core image of the file. |
| 28 | There can be no return from a succussful exec; the calling |
| 29 | core image is lost. |
| 30 | .PP |
| 31 | Files remain open across |
| 32 | .I exec |
| 33 | unless explicit arrangement has been made; |
| 34 | see |
| 35 | .IR ioctl (2). |
| 36 | Ignored signals remain ignored across |
| 37 | these calls, but |
| 38 | signals that are caught (see |
| 39 | .IR signal (2)) |
| 40 | are reset |
| 41 | to their default values. |
| 42 | .PP |
| 43 | Each user has a |
| 44 | .I real |
| 45 | user ID and group ID and an |
| 46 | .I effective |
| 47 | user ID and group ID. |
| 48 | The |
| 49 | real |
| 50 | ID |
| 51 | identifies the person using the system; |
| 52 | the |
| 53 | effective |
| 54 | ID |
| 55 | determines his access privileges. |
| 56 | .I Exec |
| 57 | changes the effective user and group ID to |
| 58 | the owner of the executed file if the file has the `set-user-ID' |
| 59 | or `set-group-ID' |
| 60 | modes. |
| 61 | The |
| 62 | real |
| 63 | user ID is not affected. |
| 64 | .PP |
| 65 | The |
| 66 | .I name |
| 67 | argument |
| 68 | is a pointer to the name of the file |
| 69 | to be executed. |
| 70 | The pointers |
| 71 | .IR arg [ 0 ], |
| 72 | .IR arg [ 1 "] ..." |
| 73 | address null-terminated strings. |
| 74 | Conventionally |
| 75 | .IR arg [ 0 ] |
| 76 | is the name of the |
| 77 | file. |
| 78 | .PP |
| 79 | From C, two interfaces are available. |
| 80 | .I execl |
| 81 | is useful when a known file with known arguments is |
| 82 | being called; |
| 83 | the arguments to |
| 84 | .I execl |
| 85 | are the character strings |
| 86 | constituting the file and the arguments; |
| 87 | the first argument is conventionally |
| 88 | the same as the file name (or its last component). |
| 89 | A 0 argument must end the argument list. |
| 90 | .PP |
| 91 | The |
| 92 | .I execv |
| 93 | version is useful when the number of arguments is unknown |
| 94 | in advance; |
| 95 | the arguments to |
| 96 | .I execv |
| 97 | are the name of the file to be |
| 98 | executed and a vector of strings containing |
| 99 | the arguments. |
| 100 | The last argument string must be followed |
| 101 | by a 0 pointer. |
| 102 | .PP |
| 103 | When a C program is executed, |
| 104 | it is called as follows: |
| 105 | .PP |
| 106 | main(argc, argv, envp) |
| 107 | .br |
| 108 | int argc; |
| 109 | .br |
| 110 | char **argv, **envp; |
| 111 | .PP |
| 112 | where |
| 113 | .IR argc "" |
| 114 | is the argument count |
| 115 | and |
| 116 | .IR argv "" |
| 117 | is an array of character pointers |
| 118 | to the arguments themselves. |
| 119 | As indicated, |
| 120 | .IR argc "" |
| 121 | is conventionally at least one |
| 122 | and the first member of the array points to a |
| 123 | string containing the name of the file. |
| 124 | .PP |
| 125 | .I Argv |
| 126 | is directly usable in another |
| 127 | .I execv |
| 128 | because |
| 129 | .IR argv [ argc ] |
| 130 | is 0. |
| 131 | .PP |
| 132 | .I Envp |
| 133 | is a pointer to an array of strings that constitute |
| 134 | the |
| 135 | .I environment |
| 136 | of the process. |
| 137 | Each string consists of a name, an ``='', and a null-terminated value. |
| 138 | The array of pointers is terminated by a null pointer. |
| 139 | The shell |
| 140 | .IR sh (1) |
| 141 | passes an environment entry for each global shell variable |
| 142 | defined when the program is called. |
| 143 | See |
| 144 | .IR environ (5) |
| 145 | for some conventionally |
| 146 | used names. |
| 147 | The C run-time start-off routine places a copy of |
| 148 | .I envp |
| 149 | in the global cell |
| 150 | .I environ, |
| 151 | which is used |
| 152 | by |
| 153 | .IR execv \ and \ execl |
| 154 | to pass the environment to any subprograms executed by the |
| 155 | current program. |
| 156 | The |
| 157 | .I exec |
| 158 | routines use lower-level routines as follows |
| 159 | to pass an environment explicitly: |
| 160 | .RS |
| 161 | .nf |
| 162 | execve(file, argv, environ); |
| 163 | execle(file, arg0, arg1, . . . , argn, 0, environ); |
| 164 | .fi |
| 165 | .RE |
| 166 | .PP |
| 167 | .I Execlp |
| 168 | and |
| 169 | .I execvp |
| 170 | are called with the same arguments as |
| 171 | .I execl |
| 172 | and |
| 173 | .I execv, |
| 174 | but duplicate the shell's actions in searching for an executable |
| 175 | file in a list of directories. |
| 176 | The directory list is obtained from the environment. |
| 177 | .SH FILES |
| 178 | .ta \w'/bin/sh 'u |
| 179 | /bin/sh shell, invoked if command file found |
| 180 | by |
| 181 | .I execlp |
| 182 | or |
| 183 | .I execvp |
| 184 | .SH "SEE ALSO" |
| 185 | fork(2), environ(5) |
| 186 | .SH DIAGNOSTICS |
| 187 | If the file cannot be found, |
| 188 | if it is not executable, |
| 189 | if it does not start with a valid magic number (see |
| 190 | .IR a.out (5)), |
| 191 | if maximum memory is exceeded, |
| 192 | or if the arguments require too much space, |
| 193 | a return |
| 194 | constitutes the diagnostic; |
| 195 | the return value is \-1. |
| 196 | Even for the super-user, |
| 197 | at least one of the execute-permission bits must be set for |
| 198 | a file to be executed. |
| 199 | .SH BUGS |
| 200 | If |
| 201 | .I execvp |
| 202 | is called to execute a file that turns out to be a shell |
| 203 | command file, |
| 204 | and if it is impossible to execute the shell, |
| 205 | the values of |
| 206 | .I argv[0] |
| 207 | and |
| 208 | .I argv[\-1] |
| 209 | will be modified before return. |
| 210 | .SH "ASSEMBLER (PDP-11)" |
| 211 | .DT |
| 212 | (exec = 11.) |
| 213 | .br |
| 214 | .B sys exec; name; argv |
| 215 | .PP |
| 216 | (exece = 59.) |
| 217 | .br |
| 218 | .B sys exece; name; argv; envp |
| 219 | .PP |
| 220 | Plain |
| 221 | .I exec |
| 222 | is obsoleted by |
| 223 | .I exece, |
| 224 | but remains for historical reasons. |
| 225 | .PP |
| 226 | When the called file starts execution on the PDP11, |
| 227 | the stack pointer points to a word containing the number of arguments. |
| 228 | Just above |
| 229 | this number is a list of pointers to the argument strings, |
| 230 | followed by a null pointer, followed by the pointers to |
| 231 | the environment strings and then another null pointer. |
| 232 | The strings themselves follow; |
| 233 | a 0 word is left at the very top of memory. |
| 234 | .PP |
| 235 | sp\(-> nargs |
| 236 | .br |
| 237 | arg0 |
| 238 | .br |
| 239 | ... |
| 240 | .br |
| 241 | argn |
| 242 | .br |
| 243 | 0 |
| 244 | .br |
| 245 | env0 |
| 246 | .br |
| 247 | ... |
| 248 | .br |
| 249 | envm |
| 250 | .br |
| 251 | 0 |
| 252 | .PP |
| 253 | arg0: <arg0\e0> |
| 254 | .br |
| 255 | ... |
| 256 | .br |
| 257 | env0: <env0\e0> |
| 258 | .br |
| 259 | 0 |
| 260 | .PP |
| 261 | On the Interdata 8/32, |
| 262 | the stack begins at a conventional place |
| 263 | (currently 0xD0000) |
| 264 | and grows upwards. |
| 265 | After |
| 266 | .I exec, |
| 267 | the layout of data on the stack is as follows. |
| 268 | .PP |
| 269 | .nf |
| 270 | int 0 |
| 271 | arg0: byte ... |
| 272 | ... |
| 273 | argp0: int arg0 |
| 274 | ... |
| 275 | int 0 |
| 276 | envp0: int env0 |
| 277 | ... |
| 278 | int 0 |
| 279 | %2\(-> space 40 |
| 280 | int nargs |
| 281 | int argp0 |
| 282 | int envp0 |
| 283 | %3\(-> |
| 284 | .fi |
| 285 | .PP |
| 286 | This arrangement happens to conform well to C calling conventions. |
| 287 | .PP |
| 288 | On a VAX-11, the stack begins at 0x80000000 and grows towards lower- |
| 289 | numbered addresses. After |
| 290 | .IR exec , |
| 291 | the layout of data on the stack is as follows. |
| 292 | .PP |
| 293 | .nf |
| 294 | .ta \w' arg0: 'u |
| 295 | ap \(-> |
| 296 | fp \(-> |
| 297 | sp \(-> .long nargs |
| 298 | .long arg0 |
| 299 | ... |
| 300 | .long argn |
| 301 | .long 0 |
| 302 | .long env0 |
| 303 | ... |
| 304 | .long envn |
| 305 | .long 0 |
| 306 | arg0: .byte "arg0\e0" |
| 307 | ... |
| 308 | envn: .byte "envn\e0" |
| 309 | .long 0 |