Commit | Line | Data |
---|---|---|
8bb980a3 C |
1 | EXEC(3) BSD Programmer's Manual EXEC(3) |
2 | ||
3 | N\bNA\bAM\bME\bE | |
4 | e\bex\bxe\bec\bcl\bl, e\bex\bxe\bec\bcl\blp\bp, e\bex\bxe\bec\bcl\ble\be, e\bex\bxe\bec\bct\bt, e\bex\bxe\bec\bcv\bv, e\bex\bxe\bec\bcv\bvp\bp - execute a file | |
5 | ||
6 | S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS | |
7 | #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<u\bun\bni\bis\bst\btd\bd.\b.h\bh>\b> | |
8 | ||
9 | _\be_\bx_\bt_\be_\br_\bn _\bc_\bh_\ba_\br _\b*_\b*_\be_\bn_\bv_\bi_\br_\bo_\bn_\b; | |
10 | ||
11 | _\bi_\bn_\bt | |
12 | e\bex\bxe\bec\bcl\bl(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\ba_\br_\bg, _\b._\b._\b.); | |
13 | ||
14 | _\bi_\bn_\bt | |
15 | e\bex\bxe\bec\bcl\blp\bp(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\ba_\br_\bg, _\b._\b._\b.); | |
16 | ||
17 | _\bi_\bn_\bt | |
18 | e\bex\bxe\bec\bcl\ble\be(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\ba_\br_\bg, _\b._\b._\b., _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\be_\bn_\bv_\bp_\b[_\b]); | |
19 | ||
20 | _\bi_\bn_\bt | |
21 | e\bex\bxe\bec\bct\bt(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b]); | |
22 | ||
23 | _\bi_\bn_\bt | |
24 | e\bex\bxe\bec\bcv\bv(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bp_\ba_\bt_\bh, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b]); | |
25 | ||
26 | _\bi_\bn_\bt | |
27 | e\bex\bxe\bec\bcv\bvp\bp(_\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\bf_\bi_\bl_\be, _\bc_\bh_\ba_\br _\b*_\bc_\bo_\bn_\bs_\bt _\ba_\br_\bg_\bv_\b[_\b]); | |
28 | ||
29 | D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN | |
30 | The e\bex\bxe\bec\bc family of functions replaces the current process image with a | |
31 | new process image. The functions described in this manual page are | |
32 | front-ends for the function execve(2). (See the manual page for execve | |
33 | for detailed information about the replacement of the current process.) | |
34 | ||
35 | The initial argument for these functions is the pathname of a file which | |
36 | is to be executed. | |
37 | ||
38 | The _\bc_\bo_\bn_\bs_\bt _\bc_\bh_\ba_\br _\b*_\ba_\br_\bg and subsequent ellipses in the e\bex\bxe\bec\bcl\bl(), e\bex\bxe\bec\bcl\blp\bp(), and | |
39 | e\bex\bxe\bec\bcl\ble\be() functions can be thought of as _\ba_\br_\bg_\b0, _\ba_\br_\bg_\b1, ..., _\ba_\br_\bg_\bn. Together | |
40 | they describe a list of one or more pointers to null-terminated strings | |
41 | that represent the argument list available to the executed program. The | |
42 | first argument, by convention, should point to the file name associated | |
43 | with the file being executed. The list of arguments _\bm_\bu_\bs_\bt be terminated | |
44 | by a NULL pointer. | |
45 | ||
46 | The e\bex\bxe\bec\bct\bt(), e\bex\bxe\bec\bcv\bv(), and e\bex\bxe\bec\bcv\bvp\bp() functions provide an array of pointers | |
47 | to null-terminated strings that represent the argument list available to | |
48 | the new program. The first argument, by convention, should point to the | |
49 | file name associated with the file begin executed. The array of pointers | |
50 | m\bmu\bus\bst\bt be terminated by a NULL pointer. | |
51 | ||
52 | The e\bex\bxe\bec\bcl\ble\be() and e\bex\bxe\bec\bct\bt() functions also specify the environment of the | |
53 | executed process by following the NULL pointer that terminates the list | |
54 | of arguments in the parameter list or the pointer to the argv array with | |
55 | an additional parameter. This additional parameter is an array of point- | |
56 | ers to null-terminated strings and _\bm_\bu_\bs_\bt be terminated by a NULL pointer. | |
57 | The other functions take the environment for the new process image from | |
58 | the external variable _\be_\bn_\bv_\bi_\br_\bo_\bn in the current process. | |
59 | ||
60 | Some of these functions have special semantics. | |
61 | ||
62 | The functions e\bex\bxe\bec\bcl\blp\bp() and e\bex\bxe\bec\bcv\bvp\bp() will duplicate the actions of the | |
63 | shell in searching for an executable file if the specified file name does | |
64 | not contain a slash ``/'' character. The search path is the path speci- | |
65 | fied in the environment by ``PATH'' variable. If this variable isn't | |
66 | specified, the default path ``/bin:/usr/bin:'' is used. In addtion, cer- | |
67 | tain errors are treated specially. | |
68 | ||
69 | If permission is denied for a file (the attempted execve returned | |
70 | EACCES), these functions will continue searching the rest of the search | |
71 | path. If no other file is found, however, they will return with the | |
72 | global variable _\be_\br_\br_\bn_\bo set to EACCES. | |
73 | ||
74 | If the header of a file isn't recognized (the attempted execve returned | |
75 | ENOEXEC), these functions will execute the shell with the path of the | |
76 | file as its first argument. (If this attempt fails, no further searching | |
77 | is done.) | |
78 | ||
79 | If the file is currently busy (the attempted execve returned ETXTBUSY), | |
80 | these functions will sleep for several seconds, periodically re- | |
81 | attempting to execute the file. | |
82 | ||
83 | The function e\bex\bxe\bec\bct\bt() executes a file with the program tracing facilities | |
84 | enabled (see ptrace(2)). | |
85 | ||
86 | R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS | |
87 | If any of the exec functions returns, an error will have occurred. The | |
88 | return value is -1, and the global variable _\be_\br_\br_\bn_\bo will be set to indicate | |
89 | the error. | |
90 | ||
91 | F\bFI\bIL\bLE\bES\bS | |
92 | /bin/sh The shell. | |
93 | ||
94 | E\bER\bRR\bRO\bOR\bRS\bS | |
95 | E\bEx\bxe\bec\bcl\bl(), e\bex\bxe\bec\bcl\ble\be(), e\bex\bxe\bec\bcl\blp\bp() and e\bex\bxe\bec\bcv\bvp\bp() may fail and set _\be_\br_\br_\bn_\bo for any | |
96 | of the errors specified for the library functions execve(2) and | |
97 | malloc(3). | |
98 | ||
99 | E\bEx\bxe\bec\bct\bt() and e\bex\bxe\bec\bcv\bv() may fail and set _\be_\br_\br_\bn_\bo for any of the errors speci- | |
100 | fied for the library function execve(2). | |
101 | ||
102 | S\bSE\bEE\bE A\bAL\bLS\bSO\bO | |
103 | sh(1), execve(2), fork(2), trace(2), environ(7), ptrace(2), | |
104 | environ(7), | |
105 | ||
106 | C\bCO\bOM\bMP\bPA\bAT\bTI\bIB\bBI\bIL\bLI\bIT\bTY\bY | |
107 | Historically, the default path for the e\bex\bxe\bec\bcl\blp\bp() and e\bex\bxe\bec\bcv\bvp\bp() functions | |
108 | was ``_\b:_\b/_\bb_\bi_\bn_\b:_\b/_\bu_\bs_\br_\b/_\bb_\bi_\bn''. This was changed to place the current directory | |
109 | last to enhance system security. | |
110 | ||
111 | The behavior of e\bex\bxe\bec\bcl\blp\bp() and e\bex\bxe\bec\bcv\bvp\bp() when errors occur while attempting | |
112 | to execute the file is historic practice, but has not traditionally been | |
113 | documented and is not specified by the POSIX standard. | |
114 | ||
115 | Traditionally, the functions e\bex\bxe\bec\bcl\blp\bp() and e\bex\bxe\bec\bcv\bvp\bp() ignored all errors ex- | |
116 | cept for the ones described above and ENOMEM and E2BIG, upon which they | |
117 | returned. They now return if any error other than the ones described | |
118 | above occurs. | |
119 | ||
120 | S\bST\bTA\bAN\bND\bDA\bAR\bRD\bDS\bS | |
121 | E\bEx\bxe\bec\bcl\bl(), e\bex\bxe\bec\bcv\bv(), e\bex\bxe\bec\bcl\ble\be(), e\bex\bxe\bec\bcl\blp\bp() and e\bex\bxe\bec\bcv\bvp\bp() conform to IEEE | |
122 | Std1003.1-1988 (``POSIX''). | |
123 | ||
124 | 4.4BSD June 4, 1993 2 |