EXEC(3) BSD Programmer's Manual EXEC(3) NNAAMMEE eexxeeccll, eexxeeccllpp, eexxeeccllee, eexxeecctt, eexxeeccvv, eexxeeccvvpp - execute a file SSYYNNOOPPSSIISS ##iinncclluuddee <> _e_x_t_e_r_n _c_h_a_r _*_*_e_n_v_i_r_o_n_; _i_n_t eexxeeccll(_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, _._._.); _i_n_t eexxeeccllpp(_c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_o_n_s_t _c_h_a_r _*_a_r_g, _._._.); _i_n_t eexxeeccllee(_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, _._._., _c_h_a_r _*_c_o_n_s_t _e_n_v_p_[_]); _i_n_t eexxeecctt(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_c_o_n_s_t _a_r_g_v_[_]); _i_n_t eexxeeccvv(_c_o_n_s_t _c_h_a_r _*_p_a_t_h, _c_h_a_r _*_c_o_n_s_t _a_r_g_v_[_]); _i_n_t eexxeeccvvpp(_c_o_n_s_t _c_h_a_r _*_f_i_l_e, _c_h_a_r _*_c_o_n_s_t _a_r_g_v_[_]); DDEESSCCRRIIPPTTIIOONN The eexxeecc family of functions replaces the current process image with a new process image. The functions described in this manual page are front-ends for the function execve(2). (See the manual page for execve for detailed information about the replacement of the current process.) The initial argument for these functions is the pathname of a file which is to be executed. The _c_o_n_s_t _c_h_a_r _*_a_r_g and subsequent ellipses in the eexxeeccll(), eexxeeccllpp(), and eexxeeccllee() functions can be thought of as _a_r_g_0, _a_r_g_1, ..., _a_r_g_n. Together they describe a list of one or more pointers to null-terminated strings that represent the argument list available to the executed program. The first argument, by convention, should point to the file name associated with the file being executed. The list of arguments _m_u_s_t be terminated by a NULL pointer. The eexxeecctt(), eexxeeccvv(), and eexxeeccvvpp() functions provide an array of pointers to null-terminated strings that represent the argument list available to the new program. The first argument, by convention, should point to the file name associated with the file begin executed. The array of pointers mmuusstt be terminated by a NULL pointer. The eexxeeccllee() and eexxeecctt() functions also specify the environment of the executed process by following the NULL pointer that terminates the list of arguments in the parameter list or the pointer to the argv array with an additional parameter. This additional parameter is an array of point- ers to null-terminated strings and _m_u_s_t be terminated by a NULL pointer. The other functions take the environment for the new process image from the external variable _e_n_v_i_r_o_n in the current process. Some of these functions have special semantics. The functions eexxeeccllpp() and eexxeeccvvpp() will duplicate the actions of the shell in searching for an executable file if the specified file name does not contain a slash ``/'' character. The search path is the path speci- fied in the environment by ``PATH'' variable. If this variable isn't specified, the default path ``/bin:/usr/bin:'' is used. In addtion, cer- tain errors are treated specially. If permission is denied for a file (the attempted execve returned EACCES), these functions will continue searching the rest of the search path. If no other file is found, however, they will return with the global variable _e_r_r_n_o set to EACCES. If the header of a file isn't recognized (the attempted execve returned ENOEXEC), these functions will execute the shell with the path of the file as its first argument. (If this attempt fails, no further searching is done.) If the file is currently busy (the attempted execve returned ETXTBUSY), these functions will sleep for several seconds, periodically re- attempting to execute the file. The function eexxeecctt() executes a file with the program tracing facilities enabled (see ptrace(2)). RREETTUURRNN VVAALLUUEESS If any of the exec functions returns, an error will have occurred. The return value is -1, and the global variable _e_r_r_n_o will be set to indicate the error. FFIILLEESS /bin/sh The shell. EERRRROORRSS EExxeeccll(), eexxeeccllee(), eexxeeccllpp() and eexxeeccvvpp() may fail and set _e_r_r_n_o for any of the errors specified for the library functions execve(2) and malloc(3). EExxeecctt() and eexxeeccvv() may fail and set _e_r_r_n_o for any of the errors speci- fied for the library function execve(2). SSEEEE AALLSSOO sh(1), execve(2), fork(2), trace(2), environ(7), ptrace(2), environ(7), CCOOMMPPAATTIIBBIILLIITTYY Historically, the default path for the eexxeeccllpp() and eexxeeccvvpp() functions was ``_:_/_b_i_n_:_/_u_s_r_/_b_i_n''. This was changed to place the current directory last to enhance system security. The behavior of eexxeeccllpp() and eexxeeccvvpp() when errors occur while attempting to execute the file is historic practice, but has not traditionally been documented and is not specified by the POSIX standard. Traditionally, the functions eexxeeccllpp() and eexxeeccvvpp() ignored all errors ex- cept for the ones described above and ENOMEM and E2BIG, upon which they returned. They now return if any error other than the ones described above occurs. SSTTAANNDDAARRDDSS EExxeeccll(), eexxeeccvv(), eexxeeccllee(), eexxeeccllpp() and eexxeeccvvpp() conform to IEEE Std1003.1-1988 (``POSIX''). 4.4BSD June 4, 1993 2