logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

exec.3p (38439B)


  1. '\" et
  2. .TH EXEC "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. environ,
  12. execl,
  13. execle,
  14. execlp,
  15. execv,
  16. execve,
  17. execvp,
  18. fexecve
  19. \(em execute a file
  20. .SH SYNOPSIS
  21. .LP
  22. .nf
  23. #include <unistd.h>
  24. .P
  25. extern char **environ;
  26. int execl(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*, (char *)0 */);
  27. int execle(const char *\fIpath\fP, const char *\fIarg0\fP, ... /*,
  28. (char *)0, char *const \fIenvp\fP[]*/);
  29. int execlp(const char *\fIfile\fP, const char *\fIarg0\fP, ... /*, (char *)0 */);
  30. int execv(const char *\fIpath\fP, char *const \fIargv\fP[]);
  31. int execve(const char *\fIpath\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]);
  32. int execvp(const char *\fIfile\fP, char *const \fIargv\fP[]);
  33. int fexecve(int \fIfd\fP, char *const \fIargv\fP[], char *const \fIenvp\fP[]);
  34. .fi
  35. .SH DESCRIPTION
  36. The
  37. .IR exec
  38. family of functions shall replace the current process image with a new
  39. process image. The new image shall be constructed from a regular,
  40. executable file called the
  41. .IR "new process image file" .
  42. There shall be no return from a successful
  43. .IR exec ,
  44. because the calling process image is overlaid by the new process
  45. image.
  46. .P
  47. The
  48. \fIfexecve\fR()
  49. function shall be equivalent to the
  50. \fIexecve\fR()
  51. function except that the file to be executed is determined by the file
  52. descriptor
  53. .IR fd
  54. instead of a pathname. The file offset of
  55. .IR fd
  56. is ignored.
  57. .P
  58. When a C-language program is executed as a result of a call to one
  59. of the
  60. .IR exec
  61. family of functions, it shall be entered as a C-language function call
  62. as follows:
  63. .sp
  64. .RS 4
  65. .nf
  66. int main (\fIint argc, char *argv\fP[]);
  67. .fi
  68. .P
  69. .RE
  70. .P
  71. where
  72. .IR argc
  73. is the argument count and
  74. .IR argv
  75. is an array of character pointers to the arguments themselves.
  76. In addition, the following variable, which must be declared by the user
  77. if it is to be used directly:
  78. .sp
  79. .RS 4
  80. .nf
  81. extern char **environ;
  82. .fi
  83. .P
  84. .RE
  85. .P
  86. is initialized as a pointer to an array of character pointers to the
  87. environment strings. The
  88. .IR argv
  89. and
  90. .IR environ
  91. arrays are each terminated by a null pointer. The null pointer
  92. terminating the
  93. .IR argv
  94. array is not counted in
  95. .IR argc .
  96. .P
  97. Applications can change the entire environment in a single operation by
  98. assigning the
  99. .IR environ
  100. variable to point to an array of character pointers to the new environment
  101. strings. After assigning a new value to
  102. .IR environ ,
  103. applications should not rely on the new environment strings remaining
  104. part of the environment, as a call to
  105. \fIgetenv\fR(),
  106. \fIputenv\fR(),
  107. \fIsetenv\fR(),
  108. \fIunsetenv\fR(),
  109. or any function that is dependent on an environment variable may, on
  110. noticing that
  111. .IR environ
  112. has changed, copy the environment strings to a new array and assign
  113. .IR environ
  114. to point to it.
  115. .P
  116. Any application that directly modifies the pointers to which the
  117. .IR environ
  118. variable points has undefined behavior.
  119. .P
  120. Conforming multi-threaded applications shall not use the
  121. .IR environ
  122. variable to access or modify any environment variable while any other
  123. thread is concurrently modifying any environment variable. A call to
  124. any function dependent on any environment variable shall be considered
  125. a use of the
  126. .IR environ
  127. variable to access that environment variable.
  128. .P
  129. The arguments specified by a program with one of the
  130. .IR exec
  131. functions shall be passed on to the new process image in the
  132. corresponding
  133. \fImain\fR()
  134. arguments.
  135. .P
  136. The argument
  137. .IR path
  138. points to a pathname that identifies the new process image file.
  139. .P
  140. The argument
  141. .IR file
  142. is used to construct a pathname that identifies the new process image
  143. file. If the
  144. .IR file
  145. argument contains a
  146. <slash>
  147. character, the
  148. .IR file
  149. argument shall be used as the pathname for this file. Otherwise, the
  150. path prefix for this file is obtained by a search of the directories
  151. passed as the environment variable
  152. .IR PATH
  153. (see the Base Definitions volume of POSIX.1\(hy2017,
  154. .IR "Chapter 8" ", " "Environment Variables").
  155. If this environment variable is not present, the results
  156. of the search are implementation-defined.
  157. .P
  158. There are two distinct ways in which the contents of the process image
  159. file may cause the execution to fail, distinguished by the setting of
  160. .IR errno
  161. to either
  162. .BR [ENOEXEC]
  163. or
  164. .BR [EINVAL]
  165. (see the ERRORS section). In the cases where the other members of the
  166. .IR exec
  167. family of functions would fail and set
  168. .IR errno
  169. to
  170. .BR [ENOEXEC] ,
  171. the
  172. \fIexeclp\fR()
  173. and
  174. \fIexecvp\fR()
  175. functions shall execute a command interpreter and the environment of the
  176. executed command shall be as if the process invoked the
  177. .IR sh
  178. utility using
  179. \fIexecl\fR()
  180. as follows:
  181. .sp
  182. .RS 4
  183. .nf
  184. execl(<shell path>, arg0, file, arg1, ..., (char *)0);
  185. .fi
  186. .P
  187. .RE
  188. .P
  189. where <\fIshell\ path\fP> is an unspecified pathname for the
  190. .IR sh
  191. utility,
  192. .IR file
  193. is the process image file, and for
  194. \fIexecvp\fR(),
  195. where
  196. .IR arg 0,
  197. .IR arg 1,
  198. and so on correspond to the values passed to
  199. \fIexecvp\fR()
  200. in
  201. .IR argv [0],
  202. .IR argv [1],
  203. and so on.
  204. .P
  205. The arguments represented by
  206. .IR arg0 ,\|.\|.\|.
  207. are pointers to null-terminated character strings. These strings
  208. shall constitute the argument list available to the new process
  209. image. The list is terminated by a null pointer. The argument
  210. .IR arg0
  211. should point to a filename string that is associated with the process
  212. being started by one of the
  213. .IR exec
  214. functions.
  215. .P
  216. The argument
  217. .IR argv
  218. is an array of character pointers to null-terminated strings. The
  219. application shall ensure that the last member of this array is a null
  220. pointer. These strings shall constitute the argument list available to
  221. the new process image. The value in
  222. .IR argv [0]
  223. should point to a filename string that is associated with the process
  224. being started by one of the
  225. .IR exec
  226. functions.
  227. .P
  228. The argument
  229. .IR envp
  230. is an array of character pointers to null-terminated strings. These
  231. strings shall constitute the environment for the new process image.
  232. The
  233. .IR envp
  234. array is terminated by a null pointer.
  235. .P
  236. For those forms not containing an
  237. .IR envp
  238. pointer (\c
  239. \fIexecl\fR(),
  240. \fIexecv\fR(),
  241. \fIexeclp\fR(),
  242. and
  243. \fIexecvp\fR()),
  244. the environment for the new process image shall be taken from the
  245. external variable
  246. .IR environ
  247. in the calling process.
  248. .P
  249. The number of bytes available for the new process' combined argument
  250. and environment lists is
  251. {ARG_MAX}.
  252. It is implementation-defined whether null terminators, pointers,
  253. and/or any alignment bytes are included in this total.
  254. .P
  255. File descriptors open in the calling process image shall remain open in
  256. the new process image, except for those whose close-on-\c
  257. .IR exec
  258. flag FD_CLOEXEC is set.
  259. For those file descriptors that remain open, all attributes of the open
  260. file description remain unchanged. For any file descriptor that is
  261. closed for this reason, file locks are removed as a result of the close
  262. as described in
  263. \fIclose\fR().
  264. Locks that are not removed by closing of file descriptors remain
  265. unchanged.
  266. .P
  267. If file descriptor 0, 1, or 2 would otherwise be closed after a successful
  268. call to one of the
  269. .IR exec
  270. family of functions, implementations may open an unspecified file for
  271. the file descriptor in the new process image. If a standard utility
  272. or a conforming application is executed with file descriptor 0 not
  273. open for reading or with file descriptor 1 or 2 not open for writing,
  274. the environment in which the utility or application is executed shall
  275. be deemed non-conforming, and consequently the utility or application
  276. might not behave as described in this standard.
  277. .P
  278. Directory streams open in the calling process image shall be closed
  279. in the new process image.
  280. .P
  281. The state of the floating-point environment in the initial thread
  282. of the new process image shall be set to the default.
  283. .P
  284. The state of conversion descriptors
  285. and message catalog descriptors in the new process image is undefined.
  286. .P
  287. For the new process image, the equivalent of:
  288. .sp
  289. .RS 4
  290. .nf
  291. setlocale(LC_ALL, "C")
  292. .fi
  293. .P
  294. .RE
  295. .P
  296. shall be executed at start-up.
  297. .P
  298. Signals set to the default action (SIG_DFL) in the calling process
  299. image shall be set to the default action in the new process image.
  300. Except for SIGCHLD, signals set to be ignored (SIG_IGN) by the calling
  301. process image shall be set to be
  302. ignored by the new process image. Signals set to be caught by the
  303. calling process image shall be set to the default action in the new
  304. process image (see
  305. .IR <signal.h> ).
  306. .P
  307. If the SIGCHLD signal is set to be ignored by the calling process
  308. image, it is unspecified whether the SIGCHLD signal is set to be
  309. ignored or to the default action in the new process image.
  310. .P
  311. After a successful call to any of the
  312. .IR exec
  313. functions, alternate signal stacks are not preserved and the SA_ONSTACK
  314. flag
  315. shall be cleared for all signals.
  316. .P
  317. After a successful call to any of the
  318. .IR exec
  319. functions, any functions previously registered by the
  320. \fIatexit\fR()
  321. or
  322. \fIpthread_atfork\fR()
  323. functions are no longer registered.
  324. .P
  325. If the ST_NOSUID bit is set for the file system containing the new
  326. process
  327. image file, then the effective user ID, effective group ID, saved
  328. set-user-ID, and saved set-group-ID are unchanged in the new process
  329. image. Otherwise,
  330. if the set-user-ID mode bit of the new process image file is set, the
  331. effective user ID of the new process image shall be set to the user ID
  332. of the new process image file. Similarly, if the set-group-ID mode bit
  333. of the new process image file is set, the effective group ID of the new
  334. process image shall be set to the group ID of the new process image
  335. file. The real user ID, real group ID, and supplementary group IDs of
  336. the new process image shall remain the same as those of the calling
  337. process image. The effective user ID and effective group ID of the new
  338. process image shall be saved (as the saved set-user-ID and the saved
  339. set-group-ID) for use by
  340. \fIsetuid\fR().
  341. .P
  342. Any shared memory segments attached to the calling process image
  343. shall not be attached to the new process image.
  344. .P
  345. Any named semaphores open in the calling process shall be closed as
  346. if by appropriate calls to
  347. \fIsem_close\fR().
  348. .P
  349. Any blocks of typed memory that were mapped in the calling process are
  350. unmapped, as if
  351. \fImunmap\fR()
  352. was implicitly called to unmap them.
  353. .P
  354. Memory locks established by the calling process via calls to
  355. \fImlockall\fR()
  356. or
  357. \fImlock\fR()
  358. shall be removed. If locked pages in the address space of the calling
  359. process are also mapped into the address spaces of other processes and
  360. are locked by those processes, the locks established by the other
  361. processes shall be unaffected by the call by this process to the
  362. .IR exec
  363. function. If the
  364. .IR exec
  365. function fails, the effect on memory locks is unspecified.
  366. .P
  367. Memory mappings created in the process are unmapped before the address
  368. space is rebuilt for the new process image.
  369. .P
  370. When the calling process image does not use the SCHED_FIFO, SCHED_RR,
  371. or SCHED_SPORADIC
  372. scheduling policies, the scheduling policy and parameters of the
  373. new process image and the initial thread in that new process image are
  374. implementation-defined.
  375. .P
  376. When the calling process image uses the SCHED_FIFO, SCHED_RR, or
  377. SCHED_SPORADIC scheduling policies, the process policy and scheduling
  378. parameter settings shall not be changed by a call to an
  379. .IR exec
  380. function.
  381. The initial thread in the new process image shall inherit the
  382. process scheduling policy and parameters. It shall have the default
  383. system contention scope, but shall inherit its allocation domain
  384. from the calling process image.
  385. .P
  386. Per-process timers created by the calling process shall be deleted before
  387. replacing the current process image with the new process image.
  388. .P
  389. All open message queue descriptors in the calling process shall be closed,
  390. as described in
  391. \fImq_close\fR().
  392. .P
  393. Any outstanding asynchronous I/O operations may be canceled. Those
  394. asynchronous I/O operations that are not canceled shall complete as if
  395. the
  396. .IR exec
  397. function had not yet occurred, but any associated signal notifications
  398. shall be suppressed. It is unspecified whether the
  399. .IR exec
  400. function itself blocks awaiting such I/O completion. In no event,
  401. however, shall the new process image created by the
  402. .IR exec
  403. function be affected by the presence of outstanding asynchronous I/O
  404. operations at the time the
  405. .IR exec
  406. function is called. Whether any I/O is canceled, and which I/O may be
  407. canceled upon
  408. .IR exec ,
  409. is implementation-defined.
  410. .P
  411. The new process image shall inherit the CPU-time clock of the calling
  412. process image. This inheritance means that the process CPU-time clock
  413. of the process being
  414. .IR exec -ed
  415. shall not be reinitialized or altered as a result of the
  416. .IR exec
  417. function other than to reflect the time spent by the process executing
  418. the
  419. .IR exec
  420. function itself.
  421. .P
  422. The initial value of the CPU-time clock of the initial thread of the
  423. new process image shall be set to zero.
  424. .P
  425. If the calling process is being traced, the new process image shall
  426. continue to be traced into the same trace stream as the original
  427. process image, but the new process image shall not inherit the mapping
  428. of trace event names to trace event type identifiers that was defined
  429. by calls to the
  430. \fIposix_trace_eventid_open\fR()
  431. or the
  432. \fIposix_trace_trid_eventid_open\fR()
  433. functions in the calling process image.
  434. .P
  435. If the calling process is a trace controller process, any trace streams
  436. that were created by the calling process shall be shut down as
  437. described in the
  438. \fIposix_trace_shutdown\fR()
  439. function.
  440. .P
  441. The thread ID of the initial thread in the new process image is
  442. unspecified.
  443. .P
  444. The size and location of the stack on which the initial thread in the
  445. new process image runs is unspecified.
  446. .P
  447. The initial thread in the new process image shall have its cancellation
  448. type set to PTHREAD_CANCEL_DEFERRED and its cancellation state set to
  449. PTHREAD_CANCEL_ENABLED.
  450. .P
  451. The initial thread in the new process image shall have all
  452. thread-specific data values set to NULL and all thread-specific data
  453. keys shall be removed by the call to
  454. .IR exec
  455. without running destructors.
  456. .P
  457. The initial thread in the new process image shall be joinable, as if
  458. created with the
  459. .IR detachstate
  460. attribute set to PTHREAD_CREATE_JOINABLE.
  461. .P
  462. The new process shall inherit at least the following attributes from
  463. the calling process image:
  464. .IP " *" 4
  465. Nice value (see
  466. \fInice\fR())
  467. .IP " *" 4
  468. \fIsemadj\fP values (see
  469. \fIsemop\fR())
  470. .IP " *" 4
  471. Process ID
  472. .IP " *" 4
  473. Parent process ID
  474. .IP " *" 4
  475. Process group ID
  476. .IP " *" 4
  477. Session membership
  478. .IP " *" 4
  479. Real user ID
  480. .IP " *" 4
  481. Real group ID
  482. .IP " *" 4
  483. Supplementary group IDs
  484. .IP " *" 4
  485. Time left until an alarm clock signal (see
  486. \fIalarm\fR())
  487. .IP " *" 4
  488. Current working directory
  489. .IP " *" 4
  490. Root directory
  491. .IP " *" 4
  492. File mode creation mask (see
  493. \fIumask\fR())
  494. .IP " *" 4
  495. File size limit (see
  496. \fIgetrlimit\fR()
  497. and
  498. \fIsetrlimit\fR())
  499. .IP " *" 4
  500. Process signal mask (see
  501. \fIpthread_sigmask\fR())
  502. .IP " *" 4
  503. Pending signal (see
  504. \fIsigpending\fR())
  505. .IP " *" 4
  506. .IR tms_utime ,
  507. .IR tms_stime ,
  508. .IR tms_cutime ,
  509. and
  510. .IR tms_cstime
  511. (see
  512. \fItimes\fR())
  513. .IP " *" 4
  514. Resource limits
  515. .IP " *" 4
  516. Controlling terminal
  517. .IP " *" 4
  518. Interval timers
  519. .P
  520. The initial thread of the new process shall inherit at least the
  521. following attributes from the calling thread:
  522. .IP " *" 4
  523. Signal mask (see
  524. \fIsigprocmask\fR()
  525. and
  526. \fIpthread_sigmask\fR())
  527. .IP " *" 4
  528. Pending signals (see
  529. \fIsigpending\fR())
  530. .P
  531. All other process attributes defined in this volume of POSIX.1\(hy2017 shall be inherited in the
  532. new process image from the old process image. All other thread
  533. attributes defined in this volume of POSIX.1\(hy2017 shall be inherited in the initial thread in
  534. the new process image from the calling thread in the old process image.
  535. The inheritance of process or thread attributes not defined by this volume of POSIX.1\(hy2017 is
  536. implementation-defined.
  537. .P
  538. A call to any
  539. .IR exec
  540. function from a process with more than one thread shall result in all
  541. threads being terminated and the new executable image being loaded and
  542. executed. No destructor functions or cleanup handlers shall be called.
  543. .P
  544. Upon successful completion, the
  545. .IR exec
  546. functions shall mark for update the last data access timestamp
  547. of the file. If an
  548. .IR exec
  549. function failed but was able to locate the process image file, whether the
  550. last data access timestamp is marked for update is unspecified. Should the
  551. .IR exec
  552. function succeed, the process image file shall be considered to have been
  553. opened with
  554. \fIopen\fR().
  555. The corresponding
  556. \fIclose\fR()
  557. shall be considered to occur at a time after this open, but before process
  558. termination or successful completion of a subsequent call to one of the
  559. .IR exec
  560. functions,
  561. \fIposix_spawn\fR(),
  562. or
  563. \fIposix_spawnp\fR().
  564. The
  565. .IR argv [\|]
  566. and
  567. .IR envp [\|]
  568. arrays of pointers and the strings to which those arrays point shall
  569. not be modified by a call to one of the
  570. .IR exec
  571. functions, except as a consequence of replacing the process image.
  572. .P
  573. The saved resource limits in the new process image are set to be a copy
  574. of the process' corresponding hard and soft limits.
  575. .SH "RETURN VALUE"
  576. If one of the
  577. .IR exec
  578. functions returns to the calling process image, an error has occurred;
  579. the return value shall be \-1, and
  580. .IR errno
  581. shall be set to indicate the error.
  582. .SH ERRORS
  583. The
  584. .IR exec
  585. functions shall fail if:
  586. .TP
  587. .BR E2BIG
  588. The number of bytes used by the new process image's argument list and
  589. environment list is greater than the system-imposed limit of
  590. {ARG_MAX}
  591. bytes.
  592. .TP
  593. .BR EACCES
  594. The new process image file is not a regular file and the implementation
  595. does not support execution of files of its type.
  596. .TP
  597. .BR EINVAL
  598. The new process image file has appropriate privileges and has a
  599. recognized executable binary format, but the system does not support
  600. execution of a file with this format.
  601. .P
  602. The
  603. .IR exec
  604. functions, except for
  605. \fIfexecve\fR(),
  606. shall fail if:
  607. .TP
  608. .BR EACCES
  609. Search permission is denied for a directory listed in the new process
  610. image file's path prefix, or the new process image file denies execution
  611. permission.
  612. .TP
  613. .BR ELOOP
  614. A loop exists in symbolic links encountered during resolution of the
  615. .IR path
  616. or
  617. .IR file
  618. argument.
  619. .TP
  620. .BR ENAMETOOLONG
  621. .br
  622. The length of a component of a pathname is longer than
  623. {NAME_MAX}.
  624. .TP
  625. .BR ENOENT
  626. A component of
  627. .IR path
  628. or
  629. .IR file
  630. does not name an existing file or
  631. .IR path
  632. or
  633. .IR file
  634. is an empty string.
  635. .TP
  636. .BR ENOTDIR
  637. A component of the new process image file's path prefix names an existing
  638. file that is neither a directory nor a symbolic link to a directory,
  639. or the new process image file's pathname contains at least one non-\c
  640. <slash>
  641. character and ends with one or more trailing
  642. <slash>
  643. characters and the last pathname component names an existing file that
  644. is neither a directory nor a symbolic link to a directory.
  645. .P
  646. The
  647. .IR exec
  648. functions, except for
  649. \fIexeclp\fR()
  650. and
  651. \fIexecvp\fR(),
  652. shall fail if:
  653. .TP
  654. .BR ENOEXEC
  655. The new process image file has the appropriate access permission but
  656. has an unrecognized format.
  657. .P
  658. The
  659. \fIfexecve\fR()
  660. function shall fail if:
  661. .TP
  662. .BR EBADF
  663. The
  664. .IR fd
  665. argument is not a valid file descriptor open for executing.
  666. .P
  667. The
  668. .IR exec
  669. functions may fail if:
  670. .TP
  671. .BR ENOMEM
  672. The new process image requires more memory than is allowed by
  673. the hardware or system-imposed memory management constraints.
  674. .P
  675. The
  676. .IR exec
  677. functions, except for
  678. \fIfexecve\fR(),
  679. may fail if:
  680. .TP
  681. .BR ELOOP
  682. More than
  683. {SYMLOOP_MAX}
  684. symbolic links were encountered during resolution of the
  685. .IR path
  686. or
  687. .IR file
  688. argument.
  689. .TP
  690. .BR ENAMETOOLONG
  691. .br
  692. The length of the
  693. .IR path
  694. argument or the length of the pathname constructed from the
  695. .IR file
  696. argument exceeds
  697. {PATH_MAX},
  698. or pathname resolution of a symbolic link produced an intermediate result
  699. with a length that exceeds
  700. {PATH_MAX}.
  701. .TP
  702. .BR ETXTBSY
  703. The new process image file is a pure procedure (shared text) file that
  704. is currently open for writing by some process.
  705. .LP
  706. .IR "The following sections are informative."
  707. .SH EXAMPLES
  708. .SS "Using execl(\|)"
  709. .P
  710. The following example executes the
  711. .IR ls
  712. command, specifying the pathname of the executable (\c
  713. .BR /bin/ls )
  714. and using arguments supplied directly to the command to produce
  715. single-column output.
  716. .sp
  717. .RS 4
  718. .nf
  719. #include <unistd.h>
  720. .P
  721. int ret;
  722. \&...
  723. ret = execl ("/bin/ls", "ls", "-1", (char *)0);
  724. .fi
  725. .P
  726. .RE
  727. .SS "Using execle(\|)"
  728. .P
  729. The following example is similar to
  730. .IR "Using execl(\|)".
  731. In addition, it specifies the environment for the new process image
  732. using the
  733. .IR env
  734. argument.
  735. .sp
  736. .RS 4
  737. .nf
  738. #include <unistd.h>
  739. .P
  740. int ret;
  741. char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
  742. \&...
  743. ret = execle ("/bin/ls", "ls", "-l", (char *)0, env);
  744. .fi
  745. .P
  746. .RE
  747. .SS "Using execlp(\|)"
  748. .P
  749. The following example searches for the location of the
  750. .IR ls
  751. command among the directories specified by the
  752. .IR PATH
  753. environment variable.
  754. .sp
  755. .RS 4
  756. .nf
  757. #include <unistd.h>
  758. .P
  759. int ret;
  760. \&...
  761. ret = execlp ("ls", "ls", "-l", (char *)0);
  762. .fi
  763. .P
  764. .RE
  765. .SS "Using execv(\|)"
  766. .P
  767. The following example passes arguments to the
  768. .IR ls
  769. command in the
  770. .IR cmd
  771. array.
  772. .sp
  773. .RS 4
  774. .nf
  775. #include <unistd.h>
  776. .P
  777. int ret;
  778. char *cmd[] = { "ls", "-l", (char *)0 };
  779. \&...
  780. ret = execv ("/bin/ls", cmd);
  781. .fi
  782. .P
  783. .RE
  784. .SS "Using execve(\|)"
  785. .P
  786. The following example passes arguments to the
  787. .IR ls
  788. command in the
  789. .IR cmd
  790. array, and specifies the environment for the new process image using the
  791. .IR env
  792. argument.
  793. .sp
  794. .RS 4
  795. .nf
  796. #include <unistd.h>
  797. .P
  798. int ret;
  799. char *cmd[] = { "ls", "-l", (char *)0 };
  800. char *env[] = { "HOME=/usr/home", "LOGNAME=home", (char *)0 };
  801. \&...
  802. ret = execve ("/bin/ls", cmd, env);
  803. .fi
  804. .P
  805. .RE
  806. .SS "Using execvp(\|)"
  807. .P
  808. The following example searches for the location of the
  809. .IR ls
  810. command among the directories specified by the
  811. .IR PATH
  812. environment variable, and passes arguments to the
  813. .IR ls
  814. command in the
  815. .IR cmd
  816. array.
  817. .sp
  818. .RS 4
  819. .nf
  820. #include <unistd.h>
  821. .P
  822. int ret;
  823. char *cmd[] = { "ls", "-l", (char *)0 };
  824. \&...
  825. ret = execvp ("ls", cmd);
  826. .fi
  827. .P
  828. .RE
  829. .SH "APPLICATION USAGE"
  830. As the state of conversion descriptors and message catalog
  831. descriptors in the new process image is undefined, conforming
  832. applications should not rely on their use and should close them prior
  833. to calling one of the
  834. .IR exec
  835. functions.
  836. .P
  837. Applications that require other than the default POSIX locale as the
  838. global locale in the new process image should call
  839. \fIsetlocale\fR()
  840. with the appropriate parameters.
  841. .P
  842. When assigning a new value to the
  843. .IR environ
  844. variable, applications should ensure that the environment to which it
  845. will point contains at least the following:
  846. .IP " 1." 4
  847. Any implementation-defined variables required by the implementation to
  848. provide a conforming environment. See the _CS_V7_ENV entry in
  849. .IR <unistd.h>
  850. and
  851. \fIconfstr\fR()
  852. for details.
  853. .IP " 2." 4
  854. A value for
  855. .IR PATH
  856. which finds conforming versions of all standard utilities before any
  857. other versions.
  858. .P
  859. The same constraint applies to the
  860. .IR envp
  861. array passed to
  862. \fIexecle\fR()
  863. or
  864. \fIexecve\fR(),
  865. in order to ensure that the new process image is invoked in a conforming
  866. environment.
  867. .P
  868. Applications should not execute programs with file descriptor 0 not open
  869. for reading or with file descriptor 1 or 2 not open for writing, as this
  870. might cause the executed program to misbehave. In order not to pass on
  871. these file descriptors to an executed program, applications should not
  872. just close them but should reopen them on, for example,
  873. .BR /dev/null .
  874. Some implementations may reopen them automatically, but applications
  875. should not rely on this being done.
  876. .P
  877. If an application wants to perform a checksum test of the file being
  878. executed before executing it, the file will need to be opened with read
  879. permission to perform the checksum test.
  880. .P
  881. Since execute permission is checked by
  882. \fIfexecve\fR(),
  883. the file description
  884. .IR fd
  885. need not have been opened with the O_EXEC flag. However, if the file
  886. to be executed denies read and write permission for the process
  887. preparing to do the
  888. .IR exec ,
  889. the only way to provide the
  890. .IR fd
  891. to
  892. \fIfexecve\fR()
  893. will be to use the O_EXEC flag when opening
  894. .IR fd .
  895. In this case, the application will not be able to perform a checksum
  896. test since it will not be able to read the contents of the file.
  897. .P
  898. Note that when a file descriptor is opened with O_RDONLY, O_RDWR, or
  899. O_WRONLY mode, the file descriptor can be used to read, read and write,
  900. or write the file, respectively, even if the mode of the file changes
  901. after the file was opened. Using the O_EXEC open mode is different;
  902. \fIfexecve\fR()
  903. will ignore the mode that was used when the file descriptor was opened
  904. and the
  905. .IR exec
  906. will fail if the mode of the file associated with
  907. .IR fd
  908. does not grant execute permission to the calling process at the time
  909. \fIfexecve\fR()
  910. is called.
  911. .SH RATIONALE
  912. Early proposals required that the value of
  913. .IR argc
  914. passed to
  915. \fImain\fR()
  916. be ``one or greater''. This was driven by the same requirement in
  917. drafts of the ISO\ C standard.
  918. In fact, historical implementations have passed a value of zero when no
  919. arguments are supplied to the caller of the
  920. .IR exec
  921. functions. This requirement was removed from the ISO\ C standard and subsequently
  922. removed from this volume of POSIX.1\(hy2017 as well. The wording, in particular the use of the
  923. word \fIshould\fP, requires a Strictly Conforming POSIX Application
  924. to pass at least one argument to the
  925. .IR exec
  926. function, thus guaranteeing that
  927. .IR argc
  928. be one or greater when invoked by such an application. In fact, this is
  929. good practice, since many existing applications reference
  930. .IR argv [0]
  931. without first checking the value of
  932. .IR argc .
  933. .P
  934. The requirement on a Strictly Conforming POSIX Application also states
  935. that the value passed as the first argument be a filename string
  936. associated with the process being started. Although some existing
  937. applications pass a pathname rather than a filename string in some
  938. circumstances, a filename string is more generally useful, since the
  939. common usage of
  940. .IR argv [0]
  941. is in printing diagnostics. In some cases the filename passed is not
  942. the actual filename of the file; for example, many implementations of the
  943. .IR login
  944. utility use a convention of prefixing a
  945. <hyphen-minus>
  946. (\c
  947. .BR '\(hy' )
  948. to the actual filename, which indicates to the command interpreter being
  949. invoked that it is a ``login shell''.
  950. .P
  951. Also, note that the
  952. .IR test
  953. and
  954. .IR [
  955. utilities require specific strings for the
  956. .IR argv [0]
  957. argument to have deterministic behavior across all implementations.
  958. .P
  959. Historically, there have been two ways that implementations can
  960. .IR exec
  961. shell scripts.
  962. .P
  963. One common historical implementation is that the
  964. \fIexecl\fR(),
  965. \fIexecv\fR(),
  966. \fIexecle\fR(),
  967. and
  968. \fIexecve\fR()
  969. functions return an
  970. .BR [ENOEXEC]
  971. error for any file not recognizable as executable, including a shell
  972. script. When the
  973. \fIexeclp\fR()
  974. and
  975. \fIexecvp\fR()
  976. functions encounter such a file, they assume the file to be a shell
  977. script and invoke a known command interpreter to interpret such files.
  978. This is now required by POSIX.1\(hy2008. These implementations of
  979. \fIexecvp\fR()
  980. and
  981. \fIexeclp\fR()
  982. only give the
  983. .BR [ENOEXEC]
  984. error in the rare case of a problem with the command interpreter's
  985. executable file. Because of these implementations, the
  986. .BR [ENOEXEC]
  987. error is not mentioned for
  988. \fIexeclp\fR()
  989. or
  990. \fIexecvp\fR(),
  991. although implementations can still give it.
  992. .P
  993. Another way that some historical implementations handle shell scripts
  994. is by recognizing the first two bytes of the file as the character
  995. string
  996. .BR \(dq#!\(dq
  997. and using the remainder of the first line of the file as the name of
  998. the command interpreter to execute.
  999. .P
  1000. One potential source of confusion noted by the standard developers
  1001. is over how the contents of a process image file affect the behavior
  1002. of the
  1003. .IR exec
  1004. family of functions. The following is a description of the actions
  1005. taken:
  1006. .IP " 1." 4
  1007. If the process image file is a valid executable (in a format that is
  1008. executable and valid and having appropriate privileges) for this
  1009. system, then the system executes the file.
  1010. .IP " 2." 4
  1011. If the process image file has appropriate privileges and is in a format
  1012. that is executable but not valid for this system (such as a recognized
  1013. binary for another architecture), then this is an error and
  1014. .IR errno
  1015. is set to
  1016. .BR [EINVAL]
  1017. (see later RATIONALE on
  1018. .BR [EINVAL] ).
  1019. .IP " 3." 4
  1020. If the process image file has appropriate privileges but is not
  1021. otherwise recognized:
  1022. .RS 4
  1023. .IP " a." 4
  1024. If this is a call to
  1025. \fIexeclp\fR()
  1026. or
  1027. \fIexecvp\fR(),
  1028. then they invoke a command interpreter assuming that the process image
  1029. file is a shell script.
  1030. .IP " b." 4
  1031. If this is not a call to
  1032. \fIexeclp\fR()
  1033. or
  1034. \fIexecvp\fR(),
  1035. then an error occurs and
  1036. .IR errno
  1037. is set to
  1038. .BR [ENOEXEC] .
  1039. .RE
  1040. .P
  1041. Applications that do not require to access their arguments may use
  1042. the form:
  1043. .sp
  1044. .RS 4
  1045. .nf
  1046. main(void)
  1047. .fi
  1048. .P
  1049. .RE
  1050. as specified in the ISO\ C standard. However, the implementation will always
  1051. provide the two arguments
  1052. .IR argc
  1053. and
  1054. .IR argv ,
  1055. even if they are not used.
  1056. .P
  1057. Some implementations provide a third argument to
  1058. \fImain\fR()
  1059. called
  1060. .IR envp .
  1061. This is defined as a pointer to the environment. The ISO\ C standard
  1062. specifies invoking
  1063. \fImain\fR()
  1064. with two arguments, so implementations must support applications
  1065. written this way. Since this volume of POSIX.1\(hy2017 defines the global variable
  1066. .IR environ ,
  1067. which is also provided by historical implementations and can be used
  1068. anywhere that
  1069. .IR envp
  1070. could be used, there is no functional need for the
  1071. .IR envp
  1072. argument. Applications should use the
  1073. \fIgetenv\fR()
  1074. function rather than accessing the environment directly via either
  1075. .IR envp
  1076. or
  1077. .IR environ .
  1078. Implementations are required to support the two-argument calling
  1079. sequence, but this does not prohibit an implementation from supporting
  1080. .IR envp
  1081. as an optional third argument.
  1082. .P
  1083. This volume of POSIX.1\(hy2017 specifies that signals set to SIG_IGN
  1084. remain set to SIG_IGN, and that the new process image inherits the
  1085. signal mask of the thread that called
  1086. .IR exec
  1087. in the old process image. This is consistent with historical
  1088. implementations, and it permits some useful functionality, such as the
  1089. .IR nohup
  1090. command. However, it should be noted that many existing applications
  1091. wrongly assume that they start with certain signals set to the default
  1092. action and/or unblocked. In particular, applications written with a
  1093. simpler signal model that does not include blocking of signals, such as
  1094. the one in the ISO\ C standard, may not behave properly if invoked with some
  1095. signals blocked. Therefore, it is best not to block or ignore signals
  1096. across
  1097. .IR exec s
  1098. without explicit reason to do so, and especially not to block signals
  1099. across
  1100. .IR exec s
  1101. of arbitrary (not closely cooperating) programs.
  1102. .P
  1103. The
  1104. .IR exec
  1105. functions always save the value of the effective user ID
  1106. and effective group ID
  1107. of the process at the completion of the
  1108. .IR exec ,
  1109. whether or not the set-user-ID
  1110. or the set-group-ID
  1111. bit of the process image file is set.
  1112. .P
  1113. The statement about
  1114. .IR argv [\|]
  1115. and
  1116. .IR envp [\|]
  1117. being constants is included to make explicit to future writers of
  1118. language bindings that these objects are completely constant. Due to a
  1119. limitation of the ISO\ C standard, it is not possible to state that idea in
  1120. standard C. Specifying two levels of
  1121. .IR const \-\c
  1122. .IR qualification
  1123. for the
  1124. .IR argv [\|]
  1125. and
  1126. .IR envp [\|]
  1127. parameters for the
  1128. .IR exec
  1129. functions may seem to be the natural choice, given that these functions
  1130. do not modify either the array of pointers or the characters to which
  1131. the function points, but this would disallow existing correct code.
  1132. Instead, only the array of pointers is noted as constant. The table of
  1133. assignment compatibility for
  1134. .IR dst =\c
  1135. .IR src
  1136. derived from the ISO\ C standard summarizes the compatibility:
  1137. .TS
  1138. box tab(!) center;
  1139. r | lB | lB | lB | lB
  1140. lB | c | c | c | c.
  1141. \fIdst\fP:!char *[\|]!const char *[\|]!char *const[\|]!const char *const[\|]
  1142. _
  1143. \fIsrc\fP:
  1144. char *[\|]!VALID!\(em!VALID!\(em
  1145. const char *[\|]!\(em!VALID!\(em!VALID
  1146. char * const [\|]!\(em!\(em!VALID!\(em
  1147. const char *const[\|]!\(em!\(em!\(em!VALID
  1148. .TE
  1149. .P
  1150. Since all existing code has a source type matching the first row, the
  1151. column that gives the most valid combinations is the third column. The
  1152. only other possibility is the fourth column, but using it would require
  1153. a cast on the
  1154. .IR argv
  1155. or
  1156. .IR envp
  1157. arguments. It is unfortunate that the fourth column cannot be used,
  1158. because the declaration a non-expert would naturally use would be that
  1159. in the second row.
  1160. .P
  1161. The ISO\ C standard and this volume of POSIX.1\(hy2017 do not conflict on the use of
  1162. .IR environ ,
  1163. but some historical implementations of
  1164. .IR environ
  1165. may cause a conflict. As long as
  1166. .IR environ
  1167. is treated in the same way as an entry point (for example,
  1168. \fIfork\fR()),
  1169. it conforms to both standards. A library can contain
  1170. \fIfork\fR(),
  1171. but if there is a user-provided
  1172. \fIfork\fR(),
  1173. that
  1174. \fIfork\fR()
  1175. is given precedence and no problem ensues. The situation is similar
  1176. for
  1177. .IR environ :
  1178. the definition in this volume of POSIX.1\(hy2017 is to be used if there is no user-provided
  1179. .IR environ
  1180. to take precedence. At least three implementations are known to exist
  1181. that solve this problem.
  1182. .TP
  1183. .BR E2BIG
  1184. The limit
  1185. {ARG_MAX}
  1186. applies not just to the size of the argument list, but to the sum of
  1187. that and the size of the environment list.
  1188. .TP
  1189. .BR EFAULT
  1190. Some historical systems return
  1191. .BR [EFAULT]
  1192. rather than
  1193. .BR [ENOEXEC]
  1194. when the new process image file is corrupted. They are non-conforming.
  1195. .TP
  1196. .BR EINVAL
  1197. This error condition was added to POSIX.1\(hy2008 to allow an implementation to
  1198. detect executable files generated for different architectures, and
  1199. indicate this situation to the application. Historical implementations
  1200. of shells,
  1201. \fIexecvp\fR(),
  1202. and
  1203. \fIexeclp\fR()
  1204. that encounter an
  1205. .BR [ENOEXEC]
  1206. error will execute a shell on the assumption that the file is a shell
  1207. script. This will not produce the desired effect when the file is a
  1208. valid executable for a different architecture. An implementation may
  1209. now choose to avoid this problem by returning
  1210. .BR [EINVAL]
  1211. when a valid executable for a different architecture is encountered.
  1212. Some historical implementations return
  1213. .BR [EINVAL]
  1214. to indicate that the
  1215. .IR path
  1216. argument contains a character with the high order bit set. The
  1217. standard developers chose to deviate from historical practice for the
  1218. following reasons:
  1219. .RS 12
  1220. .IP " 1." 4
  1221. The new utilization of
  1222. .BR [EINVAL]
  1223. will provide some measure of utility to the user community.
  1224. .IP " 2." 4
  1225. Historical use of
  1226. .BR [EINVAL]
  1227. is not acceptable in an internationalized operating environment.
  1228. .RE
  1229. .TP
  1230. .BR ENAMETOOLONG
  1231. .br
  1232. Since the file pathname may be constructed by taking elements in the
  1233. .IR PATH
  1234. variable and putting them together with the filename, the
  1235. .BR [ENAMETOOLONG]
  1236. error condition could also be reached this way.
  1237. .TP
  1238. .BR ETXTBSY
  1239. System V returns this error when the executable file is currently open
  1240. for writing by some process. This volume of POSIX.1\(hy2017 neither requires nor prohibits this
  1241. behavior.
  1242. .P
  1243. Other systems (such as System V) may return
  1244. .BR [EINTR]
  1245. from
  1246. .IR exec .
  1247. This is not addressed by this volume of POSIX.1\(hy2017, but implementations may have a
  1248. window between the call to
  1249. .IR exec
  1250. and the time that a signal could cause one of the
  1251. .IR exec
  1252. calls to return with
  1253. .BR [EINTR] .
  1254. .P
  1255. An explicit statement regarding the floating-point environment (as
  1256. defined in the
  1257. .IR <fenv.h>
  1258. header) was added to make it clear that the floating-point environment
  1259. is set to its default when a call to one of the
  1260. .IR exec
  1261. functions succeeds. The requirements for inheritance or setting to the
  1262. default for other process and thread start-up functions is covered by
  1263. more generic statements in their descriptions and can be summarized as
  1264. follows:
  1265. .IP "\fIposix_spawn\fR\^(\|)" 14
  1266. Set to default.
  1267. .IP "\fIfork\fR\^(\|)" 14
  1268. Inherit.
  1269. .IP "\fIpthread_create\fR\^(\|)" 14
  1270. Inherit.
  1271. .P
  1272. The purpose of the
  1273. \fIfexecve\fR()
  1274. function is to enable executing a file which has been verified to be
  1275. the intended file. It is possible to actively check the file by reading
  1276. from the file descriptor and be sure that the file is not exchanged for
  1277. another between the reading and the execution. Alternatively, a
  1278. function like
  1279. \fIopenat\fR()
  1280. can be used to open a file which has been found by reading the content
  1281. of a directory using
  1282. \fIreaddir\fR().
  1283. .SH "FUTURE DIRECTIONS"
  1284. None.
  1285. .SH "SEE ALSO"
  1286. .ad l
  1287. .IR "\fIalarm\fR\^(\|)",
  1288. .IR "\fIatexit\fR\^(\|)",
  1289. .IR "\fIchmod\fR\^(\|)",
  1290. .IR "\fIclose\fR\^(\|)",
  1291. .IR "\fIconfstr\fR\^(\|)",
  1292. .IR "\fIexit\fR\^(\|)",
  1293. .IR "\fIfcntl\fR\^(\|)",
  1294. .IR "\fIfork\fR\^(\|)",
  1295. .IR "\fIfstatvfs\fR\^(\|)",
  1296. .IR "\fIgetenv\fR\^(\|)",
  1297. .IR "\fIgetitimer\fR\^(\|)",
  1298. .IR "\fIgetrlimit\fR\^(\|)",
  1299. .IR "\fImknod\fR\^(\|)",
  1300. .IR "\fImmap\fR\^(\|)",
  1301. .IR "\fInice\fR\^(\|)",
  1302. .IR "\fIopen\fR\^(\|)",
  1303. .IR "\fIposix_spawn\fR\^(\|)",
  1304. .IR "\fIposix_trace_create\fR\^(\|)",
  1305. .IR "\fIposix_trace_event\fR\^(\|)",
  1306. .IR "\fIposix_trace_eventid_equal\fR\^(\|)",
  1307. .IR "\fIpthread_atfork\fR\^(\|)",
  1308. .IR "\fIpthread_sigmask\fR\^(\|)",
  1309. .IR "\fIputenv\fR\^(\|)",
  1310. .IR "\fIreaddir\fR\^(\|)",
  1311. .IR "\fIsemop\fR\^(\|)",
  1312. .IR "\fIsetlocale\fR\^(\|)",
  1313. .IR "\fIshmat\fR\^(\|)",
  1314. .IR "\fIsigaction\fR\^(\|)",
  1315. .IR "\fIsigaltstack\fR\^(\|)",
  1316. .IR "\fIsigpending\fR\^(\|)",
  1317. .IR "\fIsystem\fR\^(\|)",
  1318. .IR "\fItimes\fR\^(\|)",
  1319. .IR "\fIulimit\fR\^(\|)",
  1320. .IR "\fIumask\fR\^(\|)"
  1321. .ad b
  1322. .P
  1323. The Base Definitions volume of POSIX.1\(hy2017,
  1324. .IR "Chapter 8" ", " "Environment Variables",
  1325. .IR "\fB<unistd.h>\fP"
  1326. .P
  1327. The Shell and Utilities volume of POSIX.1\(hy2017,
  1328. .IR "\fItest\fR\^"
  1329. .\"
  1330. .SH COPYRIGHT
  1331. Portions of this text are reprinted and reproduced in electronic form
  1332. from IEEE Std 1003.1-2017, Standard for Information Technology
  1333. -- Portable Operating System Interface (POSIX), The Open Group Base
  1334. Specifications Issue 7, 2018 Edition,
  1335. Copyright (C) 2018 by the Institute of
  1336. Electrical and Electronics Engineers, Inc and The Open Group.
  1337. In the event of any discrepancy between this version and the original IEEE and
  1338. The Open Group Standard, the original IEEE and The Open Group Standard
  1339. is the referee document. The original Standard can be obtained online at
  1340. http://www.opengroup.org/unix/online.html .
  1341. .PP
  1342. Any typographical or formatting errors that appear
  1343. in this page are most likely
  1344. to have been introduced during the conversion of the source files to
  1345. man page format. To report such errors, see
  1346. https://www.kernel.org/doc/man-pages/reporting_bugs.html .