diff options
Diffstat (limited to 'man/man3/exec.3')
| -rw-r--r-- | man/man3/exec.3 | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/man/man3/exec.3 b/man/man3/exec.3 new file mode 100644 index 0000000..a94a2f1 --- /dev/null +++ b/man/man3/exec.3 @@ -0,0 +1,311 @@ +'\" t +.\" Copyright (c) 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)exec.3 6.4 (Berkeley) 4/19/91 +.\" +.\" Converted for Linux, Mon Nov 29 11:12:48 1993, faith@cs.unc.edu +.\" Updated more for Linux, Tue Jul 15 11:54:18 1997, pacman@cqc.com +.\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added note on casting NULL +.\" +.TH exec 3 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +execl, execlp, execle, execv, execvp, execvpe \- execute a file +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.B extern char **environ; +.P +.BI "int execl(const char *" pathname ", const char *" arg ", ..." +.B " /*, (char *) NULL */);" +.BI "int execlp(const char *" file ", const char *" arg ", ..." +.B " /*, (char *) NULL */);" +.BI "int execle(const char *" pathname ", const char *" arg ", ..." +.BI " /*, (char *) NULL, char *const " envp "[] */);" +.BI "int execv(const char *" pathname ", char *const " argv "[]);" +.BI "int execvp(const char *" file ", char *const " argv "[]);" +.BI "int execvpe(const char *" file ", char *const " argv \ +"[], char *const " envp "[]);" +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR execvpe (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.BR exec () +family of functions replaces the current process image with a new process +image. +The functions described in this manual page are layered on top of +.BR execve (2). +(See the manual page for +.BR execve (2) +for further details about the replacement of the current process image.) +.P +The initial argument for these functions is the name of a file that is +to be executed. +.P +The functions can be grouped based on the letters following the "exec" prefix. +.\" +.SS l - execl(), execlp(), execle() +The +.I "const char\ *arg" +and subsequent ellipses can be thought of as +.IR arg0 , +.IR arg1 , +\&..., +.IR argn . +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 filename associated +with the file being executed. +The list of arguments +.I must +be terminated by a null pointer, +and, since these are variadic functions, this pointer must be cast +.IR "(char\ *) NULL" . +.P +By contrast with the 'l' functions, the 'v' functions (below) specify the +command-line arguments of the executed program as a vector. +.\" +.SS v - execv(), execvp(), execvpe() +The +.I "char\ *const argv[]" +argument is 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 filename +associated with the file being executed. +The array of pointers +.I must +be terminated by a null pointer. +.SS e - execle(), execvpe() +The environment of the new process image is specified via the argument +.IR envp . +The +.I envp +argument is an array of pointers to null-terminated strings and +.I must +be terminated by a null pointer. +.P +All other +.BR exec () +functions (which do not include 'e' in the suffix) +take the environment for the new process +image from the external variable +.I environ +in the calling process. +.SS p - execlp(), execvp(), execvpe() +These functions duplicate the actions of the shell in +searching for an executable file +if the specified filename does not contain a slash (/) character. +The file is sought in the colon-separated list of directory pathnames +specified in the +.B PATH +environment variable. +If this variable isn't defined, the path list defaults to +a list that includes the directories returned by +.I confstr(_CS_PATH) +(which typically returns the value "/bin:/usr/bin") +and possibly also the current working directory; +see NOTES for further details. +.P +.BR execvpe () +searches for the program using the value of +.B PATH +from the caller's environment, not from the +.I envp +argument. +.P +If the specified filename includes a slash character, then +.B PATH +is ignored, and the file at the specified pathname is executed. +.P +In addition, certain errors are treated specially. +.P +If permission is denied for a file (the attempted +.BR execve (2) +failed with the error +.BR EACCES ), +these functions will continue searching the rest of the search path. +If no other file is found, however, +they will return with +.I errno +set to +.BR EACCES . +.P +If the header of a file isn't recognized (the attempted +.BR execve (2) +failed with the error +.BR ENOEXEC ), +these functions will execute the shell +.RI ( /bin/sh ) +with the path of the file as its first argument. +(If this attempt fails, no further searching is done.) +.P +All other +.BR exec () +functions (which do not include 'p' in the suffix) +take as their first argument a (relative or absolute) pathname +that identifies the program to be executed. +.SH RETURN VALUE +The +.BR exec () +functions return only if an error has occurred. +The return value is \-1, and +.I errno +is set to indicate the error. +.SH ERRORS +All of these functions may fail and set +.I errno +for any of the errors specified for +.BR execve (2). +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR execl (), +.BR execle (), +.BR execv () +T} Thread safety MT-Safe +T{ +.na +.nh +.BR execlp (), +.BR execvp (), +.BR execvpe () +T} Thread safety MT-Safe env +.TE +.SH VERSIONS +The default search path (used when the environment +does not contain the variable \fBPATH\fR) +shows some variation across systems. +It generally includes +.I /bin +and +.I /usr/bin +(in that order) and may also include the current working directory. +On some other systems, the current working is included after +.I /bin +and +.IR /usr/bin , +as an anti-Trojan-horse measure. +The glibc implementation long followed the traditional default where +the current working directory is included at the start of the search path. +However, some code refactoring during the development of glibc 2.24 +.\" glibc commit 1eb8930608705702d5746e5491bab4e4429fcb83 +caused the current working directory to be dropped altogether +from the default search path. +This accidental behavior change is considered mildly beneficial, +and won't be reverted. +.P +The behavior of +.BR execlp () +and +.BR execvp () +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. +BSD (and possibly other systems) do an automatic +sleep and retry if +.B ETXTBSY +is encountered. +Linux treats it as a hard +error and returns immediately. +.P +Traditionally, the functions +.BR execlp () +and +.BR execvp () +ignored all errors except for the ones described above and +.B ENOMEM +and +.BR E2BIG , +upon which they returned. +They now return if any error other than the ones +described above occurs. +.SH STANDARDS +.TP +.B environ +.TQ +.BR execl () +.TQ +.BR execlp () +.TQ +.BR execle () +.TQ +.BR execv () +.TQ +.BR execvp () +POSIX.1-2008. +.TP +.BR execvpe () +GNU. +.SH HISTORY +.TP +.B environ +.TQ +.BR execl () +.TQ +.BR execlp () +.TQ +.BR execle () +.TQ +.BR execv () +.TQ +.BR execvp () +POSIX.1-2001. +.TP +.BR execvpe () +glibc 2.11. +.SH BUGS +Before glibc 2.24, +.BR execl () +and +.BR execle () +employed +.BR realloc (3) +internally and were consequently not async-signal-safe, +in violation of the requirements of POSIX.1. +.\" https://sourceware.org/bugzilla/show_bug.cgi?id=19534 +This was fixed in glibc 2.24. +.\" +.SS Architecture-specific details +On sparc and sparc64, +.BR execv () +is provided as a system call by the kernel +(with the prototype shown above) +for compatibility with SunOS. +This function is +.I not +employed by the +.BR execv () +wrapper function on those architectures. +.SH SEE ALSO +.BR sh (1), +.BR execve (2), +.BR execveat (2), +.BR fork (2), +.BR ptrace (2), +.BR fexecve (3), +.BR system (3), +.BR environ (7) |