1EXECVE(2) 386BSD Programmer's Manual EXECVE(2) 2 3NNAAMMEE 4 eexxeeccvvee - execute a file 5 6SSYYNNOOPPSSIISS 7 ##iinncclluuddee <<uunniissttdd..hh>> 8 9 _i_n_t 10 eexxeeccvvee(_c_o_n_s_t _c_h_a_r *_p_a_t_h, _c_o_n_s_t * _c_h_a_r *_a_r_g_v, _c_o_n_s_t * _c_h_a_r *_e_n_v_p) 11 12DDEESSCCRRIIPPTTIIOONN 13 EExxeeccvvee() transforms the calling process into a new process. The new 14 process is constructed from an ordinary file, whose name is pointed to by 15 _p_a_t_h, called the _n_e_w _p_r_o_c_e_s_s _f_i_l_e. This file is either an executable 16 object file, or a file of data for an interpreter. An executable object 17 file consists of an identifying header, followed by pages of data 18 representing the initial program (text) and initialized data pages. 19 Additional pages may be specified by the header to be initialized with 20 zero data; see a.out(5). 21 22 An interpreter file begins with a line of the form: 23 24 ##!! _i_n_t_e_r_p_r_e_t_e_r [_a_r_g] 25 26 When an interpreter file is eexxeeccvvee()'d, the system eexxeeccvvee()'s the 27 specified _i_n_t_e_r_p_r_e_t_e_r. If the optional _a_r_g is specified, it becomes the 28 first argument to the _i_n_t_e_r_p_r_e_t_e_r, and the name of the originally 29 eexxeeccvvee()'d file becomes the second argument; otherwise, the name of the 30 originally eexxeeccvvee()'d file becomes the first argument. The original 31 arguments are shifted over to become the subsequent arguments. The 32 zeroth argument, normally the name of the eexxeeccvvee()'d file, is left 33 unchanged. 34 35 The argument _a_r_g_v is a pointer to a null-terminated array of character 36 pointers to null-terminated character strings. These strings construct 37 the argument list to be made available to the new process. At least one 38 argument must be present in the array; by custom, the first element 39 should be the name of the executed program (for example, the last 40 component of _p_a_t_h). 41 42 The argument _e_n_v_p is also a pointer to a null-terminated array of 43 character pointers to null-terminated strings. A pointer to this array 44 is normally stored in the global variable _e_n_v_i_r_o_n. These strings pass 45 information to the new process that is not directly an argument to the 46 command (see environ(7)). 47 48 File descriptors open in the calling process image remain open in the new 49 process image, except for those for which the close-on-exec flag is set 50 (see close(2) and fcntl(2)). Descriptors that remain open are unaffected 51 by eexxeeccvvee(). 52 53 Signals set to be ignored in the calling process are set to be ignored in 54 the new process. Signals which are set to be caught in the calling 55 process image are set to default action in the new process image. 56 Blocked signals remain blocked regardless of changes to the signal 57 action. The signal stack is reset to be undefined (see sigaction(2) for 58 more information). 59 60 If the set-user-ID mode bit of the new process image file is set (see 61 chmod(2)), the effective user ID of the new process image is set to the 62 owner ID of the new process image file. If the set-group-ID mode bit of 63 the new process image file is set, the effective group ID of the new 64 process image is set to the group ID of the new process image file. The 65 real user ID, real group ID and supplementary group IDs of the new 66 process image remain the same as the calling process image. 67 68 The new process also inherits the following attributes from the calling 69 process: 70 71 process ID see getpid(2) 72 parent process ID see getppid(2) 73 process group ID see getpgrp(2) 74 access groups see getgroups(2) 75 working directory see chdir(2) 76 root directory see chroot(2) 77 control terminal see termios(4) 78 resource usages see getrusage(2) 79 interval timers see getitimer(2) 80 resource limits see getrlimit(2) 81 file mode mask see umask(2) 82 signal mask see sigvec(2), sigsetmask(2) 83 84 When a program is executed as a result of an eexxeeccvvee() call, it is entered 85 as follows: 86 87 main(argc, argv, envp) 88 int argc; 89 char **argv, **envp; 90 91 where _a_r_g_c is the number of elements in _a_r_g_v (the ``arg count'') and _a_r_g_v 92 points to the array of character pointers to the arguments themselves. 93 94RREETTUURRNN VVAALLUUEESS 95 As the eexxeeccvvee() function overlays the current process image with a new 96 process image the successful call has no process to return to. If 97 eexxeeccvvee() does return to the calling process an error has occurred; the 98 return value will be -1 and the global variable _e_r_r_n_o is set to indicate 99 the error. 100 101EERRRROORRSS 102 EExxeeccvvee() will fail and return to the calling process if: 103 104 [ENOTDIR] A component of the path prefix is not a directory. 105 106 [EINVAL] The pathname contains a character with the high-order bit 107 set. 108 109 [ENAMETOOLONG] A component of a pathname exceeded 255 characters, or an 110 entire path name exceeded 1023 characters. 111 112 [ENOENT] The new process file does not exist. 113 114 [ELOOP] Too many symbolic links were encountered in translating 115 the pathname. 116 117 [EACCES] Search permission is denied for a component of the path 118 prefix. 119 120 [EACCES] The new process file is not an ordinary file. 121 122 [EACCES] The new process file mode denies execute permission. 123 124 [ENOEXEC] The new process file has the appropriate access 125 permission, but has an invalid magic number in its 126 header. 127 128 [ETXTBSY] The new process file is a pure procedure (shared text) 129 file that is currently open for writing or reading by 130 131 132 some process. 133 134 [ENOMEM] The new process requires more virtual memory than is 135 allowed by the imposed maximum (getrlimit(2)). 136 137 [E2BIG] The number of bytes in the new process's argument list is 138 larger than the system-imposed limit. The limit in the 139 system as released is 20480 bytes (NCARGS in 140 <_s_y_s/_p_a_r_a_m._h>. 141 142 [EFAULT] The new process file is not as long as indicated by the 143 size values in its header. 144 145 [EFAULT] _P_a_t_h, _a_r_g_v, or _e_n_v_p point to an illegal address. 146 147 [EIO] An I/O error occurred while reading from the file system. 148 149CCAAVVEEAATT 150 If a program is _s_e_t_u_i_d to a non-super-user, but is executed when the real 151 _u_i_d is ``root'', then the program has some of the powers of a super-user 152 as well. 153 154SSEEEE AALLSSOO 155 exit(2), fork(2), execl(3), environ(7) 156 157HHIISSTTOORRYY 158 The eexxeeccvvee function call appeared in 4.2BSD. 159 1604th Berkeley Distribution March 10, 1991 3 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199