Print this page
9842 man page typos and spelling
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/exec.2.man.txt
+++ new/usr/src/man/man2/exec.2.man.txt
1 1 EXEC(2) System Calls EXEC(2)
2 2
3 3
4 4
5 5 NAME
6 6 exec, execl, execle, execlp, execv, execve, execvp - execute a file
7 7
8 8 SYNOPSIS
9 9 #include <unistd.h>
10 10
11 11 int execl(const char *path, const char *arg0, ...
12 12 /* const char *argn, (char *)0 */);
13 13
14 14
15 15 int execv(const char *path, char *const argv[]);
16 16
17 17
18 18 int execle(const char *path, const char *arg0, ...
19 19 /* const char *argn, (char *)0,char *const envp[]*/);
20 20
21 21
22 22 int execve(const char *path, char *const argv[],
23 23 char *const envp[]);
24 24
25 25
26 26 int execlp(const char *file, const char *arg0, ...
27 27 /* const char *argn, (char *)0 */);
28 28
29 29
30 30 int execvp(const char *file, char *const argv[]);
31 31
32 32
33 33 DESCRIPTION
34 34 Each of the functions in the exec family replaces the current process
35 35 image with a new process image. The new image is constructed from a
36 36 regular, executable file called the new process image file. This file
37 37 is either an executable object file or a file of data for an
38 38 interpreter. There is no return from a successful call to one of these
39 39 functions because the calling process image is overlaid by the new
40 40 process image.
41 41
42 42
43 43 An interpreter file begins with a line of the form
44 44
45 45 #! pathname [arg]
46 46
47 47
48 48
49 49 where pathname is the path of the interpreter, and arg is an optional
50 50 argument. When an interpreter file is executed, the system invokes the
51 51 specified interpreter. The pathname specified in the interpreter file
52 52 is passed as arg0 to the interpreter. If arg was specified in the
53 53 interpreter file, it is passed as arg1 to the interpreter. The
54 54 remaining arguments to the interpreter are arg0 through argn of the
55 55 originally exec'd file. The interpreter named by pathname may also be
56 56 an interpreter file. There can be up to four nested interpreter files
57 57 before the final interpreter. The setid bits on nested interpreters
58 58 are silently ignored.
59 59
60 60
61 61 When a C-language program is executed as a result of this call, it is
62 62 entered as a C-language function call as follows:
63 63
64 64 int main (int argc, char *argv[]);
65 65
66 66
67 67
68 68 where argc is the argument count and argv is an array of character
69 69 pointers to the arguments themselves. In addition, the following
70 70 variable:
71 71
72 72 extern char **environ;
73 73
74 74
75 75
76 76 is initialized as a pointer to an array of character pointers to the
77 77 environment strings. The argv and environ arrays are each terminated by
78 78 a null pointer. The null pointer terminating the argv array is not
79 79 counted in argc.
80 80
81 81
82 82 The value of argc is non-negative, and if greater than 0, argv[0]
83 83 points to a string containing the name of the file. If argc is 0,
84 84 argv[0] is a null pointer, in which case there are no arguments.
85 85 Applications should verify that argc is greater than 0 or that argv[0]
86 86 is not a null pointer before dereferencing argv[0].
87 87
88 88
89 89 The arguments specified by a program with one of the exec functions are
90 90 passed on to the new process image in the main() arguments.
91 91
92 92
93 93 The path argument points to a path name that identifies the new process
94 94 image file.
95 95
96 96
97 97 The file argument is used to construct a pathname that identifies the
98 98 new process image file. If the file argument contains a slash
99 99 character, it is used as the pathname for this file. Otherwise, the
100 100 path prefix for this file is obtained by a search of the directories
101 101 passed in the PATH environment variable (see environ(5)). The
102 102 environment is supplied typically by the shell. If the process image
103 103 file is not a valid executable object file, execlp() and execvp() use
104 104 the contents of that file as standard input to the shell. In this case,
105 105 the shell becomes the new process image. The standard to which the
106 106 caller conforms determines which shell is used. See standards(5).
107 107
108 108
109 109 The arguments represented by arg0... are pointers to null-terminated
110 110 character strings. These strings constitute the argument list available
111 111 to the new process image. The list is terminated by a null pointer.
112 112 The arg0 argument should point to a filename that is associated with
113 113 the process being started by one of the exec functions.
114 114
115 115
116 116 The argv argument is an array of character pointers to null-terminated
117 117 strings. The last member of this array must be a null pointer. These
118 118 strings constitute the argument list available to the new process
119 119 image. The value in argv[0] should point to a filename that is
120 120 associated with the process being started by one of the exec functions.
121 121
122 122
123 123 The envp argument is an array of character pointers to null-terminated
124 124 strings. These strings constitute the environment for the new process
125 125 image. The envp array is terminated by a null pointer. For execl(),
126 126 execv(), execvp(), and execlp(), the C-language run-time start-off
127 127 routine places a pointer to the environment of the calling process in
128 128 the global object extern char **environ, and it is used to pass the
129 129 environment of the calling process to the new process image.
130 130
131 131
132 132 The number of bytes available for the new process's combined argument
133 133 and environment lists is ARG_MAX. It is implementation-dependent
134 134 whether null terminators, pointers, and/or any alignment bytes are
135 135 included in this total.
136 136
137 137
138 138 File descriptors open in the calling process image remain open in the
139 139 new process image, except for those whose close-on-exec flag FD_CLOEXEC
140 140 is set; see fcntl(2). For those file descriptors that remain open, all
141 141 attributes of the open file description, including file locks, remain
142 142 unchanged.
143 143
144 144
145 145 The preferred hardware address translation size (see memcntl(2)) for
146 146 the stack and heap of the new process image are set to the default
147 147 system page size.
148 148
149 149
150 150 Directory streams open in the calling process image are closed in the
151 151 new process image.
152 152
153 153
154 154 The state of conversion descriptors and message catalogue descriptors
155 155 in the new process image is undefined. For the new process, the
156 156 equivalent of:
157 157
158 158 setlocale(LC_ALL, "C")
159 159
160 160
161 161
162 162 is executed at startup.
163 163
164 164
165 165 Signals set to the default action (SIG_DFL) in the calling process
166 166 image are set to the default action in the new process image (see
167 167 signal(3C)). Signals set to be ignored (SIG_IGN) by the calling
168 168 process image are set to be ignored by the new process image. Signals
169 169 set to be caught by the calling process image are set to the default
170 170 action in the new process image (see signal.h(3HEAD)). After a
171 171 successful call to any of the exec functions, alternate signal stacks
172 172 are not preserved and the SA_ONSTACK flag is cleared for all signals.
173 173
174 174
175 175 After a successful call to any of the exec functions, any functions
176 176 previously registered by atexit(3C) are no longer registered.
177 177
178 178
179 179 The saved resource limits in the new process image are set to be a copy
180 180 of the process's corresponding hard and soft resource limits.
181 181
182 182
183 183 If the ST_NOSUID bit is set for the file system containing the new
184 184 process image file, then the effective user ID and effective group ID
185 185 are unchanged in the new process image. If the set-user-ID mode bit of
186 186 the new process image file is set (see chmod(2)), the effective user ID
187 187 of the new process image is set to the owner ID of the new process
188 188 image file. Similarly, if the set-group-ID mode bit of the new process
189 189 image file is set, the effective group ID of the new process image is
190 190 set to the group ID of the new process image file. The real user ID and
191 191 real group ID of the new process image remain the same as those of the
192 192 calling process image. The effective user ID and effective group ID of
193 193 the new process image are saved (as the saved set-user-ID and the saved
194 194 set-group-ID for use by setuid(2).
195 195
196 196
197 197 The privilege sets are changed according to the following rules:
198 198
199 199 1. The inheritable set, I, is intersected with the limit set,
200 200 L. This mechanism enforces the limit set for processes.
201 201
202 202 2. The effective set, E, and the permitted set, P, are made
203 203 equal to the new inheritable set.
204 204
205 205
206 206 The system attempts to set the privilege-aware state to non-PA both
207 207 before performing any modifications to the process IDs and privilege
208 208 sets as well as after completing the transition to new UIDs and
209 209 privilege sets, following the rules outlined in privileges(5).
210 210
211 211
212 212 If the {PRIV_PROC_OWNER} privilege is asserted in the effective set,
213 213 the set-user-ID and set-group-ID bits will be honored when the process
214 214 is being controlled by ptrace(3C). Additional restriction can apply
215 215 when the traced process has an effective UID of 0. See privileges(5).
216 216
217 217
218 218 Any shared memory segments attached to the calling process image will
219 219 not be attached to the new process image (see shmop(2)). Any mappings
220 220 established through mmap() are not preserved across an exec. Memory
221 221 mappings created in the process are unmapped before the address space
222 222 is rebuilt for the new process image. See mmap(2).
223 223
224 224
225 225 Memory locks established by the calling process via calls to
226 226 mlockall(3C) or mlock(3C) are removed. If locked pages in the address
227 227 space of the calling process are also mapped into the address spaces
228 228 the locks established by the other processes will be unaffected by the
229 229 call by this process to the exec function. If the exec function fails,
230 230 the effect on memory locks is unspecified.
231 231
232 232
233 233 If _XOPEN_REALTIME is defined and has a value other than -1, any named
234 234 semaphores open in the calling process are closed as if by appropriate
235 235 calls to sem_close(3C)
236 236
237 237
238 238 Profiling is disabled for the new process; see profil(2).
239 239
240 240
241 241 Timers created by the calling process with timer_create(3C) are deleted
242 242 before replacing the current process image with the new process image.
243 243
244 244
245 245 For the SCHED_FIFO and SCHED_RR scheduling policies, the policy and
246 246 priority settings are not changed by a call to an exec function.
247 247
248 248
249 249 All open message queue descriptors in the calling process are closed,
250 250 as described in mq_close(3C).
251 251
252 252
253 253 Any outstanding asynchronous I/O operations may be cancelled. Those
254 254 asynchronous I/O operations that are not canceled will complete as if
255 255 the exec function had not yet occurred, but any associated signal
256 256 notifications are suppressed. It is unspecified whether the exec
257 257 function itself blocks awaiting such I/O completion. In no event,
258 258 however, will the new process image created by the exec function be
259 259 affected by the presence of outstanding asynchronous I/O operations at
260 260 the time the exec function is called.
261 261
262 262
263 263 All active contract templates are cleared (see contract(4)).
264 264
265 265
266 266 The new process also inherits the following attributes from the calling
267 267 process:
268 268
269 269 o controlling terminal
270 270
271 271 o current working directory
272 272
273 273 o file-locks (see fcntl(2) and lockf(3C))
274 274
275 275 o file mode creation mask (see umask(2))
276 276
277 277 o file size limit (see ulimit(2))
278 278
279 279 o limit privilege set
280 280
281 281 o nice value (see nice(2))
282 282
283 283 o parent process ID
284 284
285 285 o pending signals (see sigpending(2))
286 286
287 287 o privilege debugging flag (see privileges(5) and
288 288 getpflags(2))
289 289
290 290 o process ID
291 291
292 292 o process contract (see contract(4) and process(4))
293 293
294 294 o process group ID
295 295
296 296 o process signal mask (see sigprocmask(2))
297 297
298 298 o processor bindings (see processor_bind(2))
299 299
300 300 o processor set bindings (see pset_bind(2))
301 301
302 302 o project ID
303 303
304 304 o real group ID
305 305
306 306 o real user ID
307 307
308 308 o resource limits (see getrlimit(2))
309 309
310 310 o root directory
311 311
312 312 o scheduler class and priority (see priocntl(2))
313 313
314 314 o semadj values (see semop(2))
315 315
316 316 o session membership (see exit(2) and signal(3C))
317 317
318 318 o supplementary group IDs
319 319
320 320 o task ID
321 321
322 322 o time left until an alarm clock signal (see alarm(2))
323 323
324 324 o tms_utime, tms_stime, tms_cutime, and tms_cstime (see
325 325 times(2))
326 326
327 327 o trace flag (see ptrace(3C) request 0)
328 328
329 329
330 330 A call to any exec function from a process with more than one thread
331 331 results in all threads being terminated and the new executable image
332 332 being loaded and executed. No destructor functions will be called.
333 333
334 334
335 335 Upon successful completion, each of the functions in the exec family
336 336 marks for update the st_atime field of the file. If an exec function
337 337 failed but was able to locate the process image file, whether the
338 338 st_atime field is marked for update is unspecified. Should the function
339 339 succeed, the process image file is considered to have been opened with
340 340 open(2). The corresponding close(2) is considered to occur at a time
341 341 after this open, but before process termination or successful
342 342 completion of a subsequent call to one of the exec functions. The
343 343 argv[] and envp[] arrays of pointers and the strings to which those
344 344 arrays point will not be modified by a call to one of the exec
345 345 functions, except as a consequence of replacing the process image.
346 346
347 347
348 348 The saved resource limits in the new process image are set to be a copy
349 349 of the process's corresponding hard and soft limits.
350 350
351 351 RETURN VALUES
352 352 If a function in the exec family returns to the calling process image,
353 353 an error has occurred; the return value is -1 and errno is set to
354 354 indicate the error.
355 355
356 356 ERRORS
357 357 The exec functions will fail if:
358 358
359 359 E2BIG
360 360 The number of bytes in the new process's argument list
361 361 is greater than the system-imposed limit of {ARG_MAX}
362 362 bytes. The argument list limit is sum of the size of
363 363 the argument list plus the size of the environment's
364 364 exported shell variables.
365 365
366 366
367 367 EACCES
368 368 Search permission is denied for a directory listed in
369 369 the new process file's path prefix.
370 370
371 371 The new process file is not an ordinary file.
372 372
373 373 The new process file mode denies execute permission.
374 374
375 375 The {FILE_DAC_SEARCH} privilege overrides the
376 376 restriction on directory searches.
377 377
378 378 The {FILE_DAC_EXECUTE} privilege overrides the lack of
379 379 execute permission.
380 380
381 381
382 382 EAGAIN
383 383 Total amount of system memory available when reading
384 384 using raw I/O is temporarily insufficient.
385 385
386 386
387 387 EFAULT
388 388 An argument points to an illegal address.
389 389
390 390
391 391 EINVAL
392 392 The new process image file has the appropriate
393 393 permission and has a recognized executable binary
394 394 format, but the system does not support execution of a
395 395 file with this format.
396 396
397 397
398 398 EINTR
399 399 A signal was caught during the execution of one of the
400 400 functions in the exec family.
401 401
402 402
403 403 ELOOP
404 404 Too many symbolic links were encountered in translating
405 405 path or file, or too many nested interpreter files.
406 406
407 407
408 408 ENAMETOOLONG
409 409 The length of the file or path argument exceeds
410 410 {PATH_MAX}, or the length of a file or path component
411 411 exceeds {NAME_MAX} while {_POSIX_NO_TRUNC} is in
412 412 effect.
413 413
414 414
415 415 ENOENT
416 416 One or more components of the new process path name of
417 417 the file do not exist or is a null pathname.
418 418
419 419
420 420 ENOLINK
421 421 The path argument points to a remote machine and the
422 422 link to that machine is no longer active.
423 423
424 424
425 425 ENOTDIR
426 426 A component of the new process path of the file prefix
427 427 is not a directory.
428 428
429 429
430 430
431 431 The exec functions, except for execlp() and execvp(), will fail if:
432 432
433 433 ENOEXEC
434 434 The new process image file has the appropriate access
435 435 permission but is not in the proper format.
436 436
437 437
438 438
439 439 The exec functions may fail if:
440 440
441 441 ENAMETOOLONG
442 442 Pathname resolution of a symbolic link produced an
443 443 intermediate result whose length exceeds {PATH_MAX}.
444 444
445 445
446 446 ENOMEM
447 447 The new process image requires more memory than is
448 448 allowed by the hardware or system-imposed by memory
449 449 management constraints. See brk(2).
450 450
451 451
452 452 ETXTBSY
453 453 The new process image file is a pure procedure (shared
454 454 text) file that is currently open for writing by some
455 455 process.
456 456
457 457
458 458 USAGE
459 459 As the state of conversion descriptors and message catalogue
460 460 descriptors in the new process image is undefined, portable
461 461 applications should not rely on their use and should close them prior
462 462 to calling one of the exec functions.
463 463
464 464
465 465 Applications that require other than the default POSIX locale should
466 466 call setlocale(3C) with the appropriate parameters to establish the
467 467 locale of thenew process.
468 468
469 469
470 470 The environ array should not be accessed directly by the application.
471 471
472 472 ATTRIBUTES
473 473 See attributes(5) for descriptions of the following attributes:
474 474
475 475
476 476
477 477
478 478 +--------------------+-------------------+
|
↓ open down ↓ |
478 lines elided |
↑ open up ↑ |
479 479 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
480 480 +--------------------+-------------------+
481 481 |Interface Stability | Committed |
482 482 +--------------------+-------------------+
483 483 |MT-Level | See below. |
484 484 +--------------------+-------------------+
485 485 |Standard | See standards(5). |
486 486 +--------------------+-------------------+
487 487
488 488
489 - The execle() and execve() fucntions are Async-Signal-Safe.
489 + The execle() and execve() functions are Async-Signal-Safe.
490 490
491 491 SEE ALSO
492 492 ksh(1), ps(1), sh(1), alarm(2), brk(2), chmod(2), exit(2), fcntl(2),
493 493 fork(2), getpflags(2), getrlimit(2), memcntl(2), mmap(2), nice(2),
494 494 priocntl(2), profil(2), semop(2), shmop(2), sigpending(2),
495 495 sigprocmask(2), times(2), umask(2), lockf(3C), ptrace(3C),
496 496 setlocale(3C), signal(3C), system(3C), timer_create(3C), a.out(4),
497 497 contract(4), process(4), attributes(5), environ(5), privileges(5),
498 498 standards(5)
499 499
500 500 WARNINGS
501 501 If a program is setuid to a user ID other than the superuser, and the
502 502 program is executed when the real user ID is super-user, then the
503 503 program has some of the powers of a super-user as well.
504 504
505 505
506 506
507 507 October 27, 2015 EXEC(2)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX