Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)