From c63619503feca6e3ede7e0d6a839e537d97e8e6a Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Sat, 25 Sep 2010 08:22:31 +0200
Subject: [PATCH] exec.3: Document execpe()

This function was added to glibc in version 2.11.
Also various other small rewrites in the page.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 man3/exec.3 | 61 ++++++++++++++++++++++++++++++++---------------------
 1 file changed, 37 insertions(+), 24 deletions(-)

diff --git a/man3/exec.3 b/man3/exec.3
index bd8d6d6df..4b8e62d30 100644
--- a/man3/exec.3
+++ b/man3/exec.3
@@ -36,9 +36,9 @@
 .\" Modified, 24 Jun 2004, Michael Kerrisk <mtk.manpages@gmail.com>
 .\"     Added note on casting NULL
 .\"
-.TH EXEC 3  2010-09-23 "GNU" "Linux Programmer's Manual"
+.TH EXEC 3  2010-09-25 "GNU" "Linux Programmer's Manual"
 .SH NAME
-execl, execlp, execle, execv, execvp \- execute a file
+execl, execlp, execle, execv, execvp, execvpe \- execute a file
 .SH SYNOPSIS
 .B #include <unistd.h>
 .sp
@@ -55,6 +55,10 @@ execl, execlp, execle, execv, execvp \- execute a file
 .BI "int execv(const char *" path ", char *const " argv "[]);"
 .br
 .BI "int execvp(const char *" file ", char *const " argv "[]);"
+.br
+.BI "int execvpe(const char *" file ", char *const " argv "[],"
+.br
+.BI "           char *const " envp "[]);"
 .SH DESCRIPTION
 The
 .BR exec ()
@@ -66,7 +70,7 @@ The functions described in this manual page are front-ends for
 .BR execve (2)
 for further details about the replacement of the current process image.)
 .PP
-The initial argument for these functions is the pathname of a file which is
+The initial argument for these functions is the name of a file that is
 to be executed.
 .PP
 The
@@ -92,9 +96,10 @@ pointer, and, since these are variadic functions, this pointer must be cast
 .IR "(char *) NULL" .
 .PP
 The
-.BR execv ()
+.BR execv (),
+.BR execvp (),
 and
-.BR execvp ()
+.BR execvpe ()
 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 filename
@@ -105,26 +110,27 @@ be terminated by a NULL pointer.
 .PP
 The
 .BR execle ()
-function also specifies the environment of the executed process by following
-the NULL
-pointer that terminates the list of arguments in the argument list or the
-pointer to the
-.I argv
-array with an additional argument.
-This additional
+and
+.BR execvpe ()
+functions allow the caller to specify the environment of the
+executed program 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.
 The other functions take the environment for the new process
 image from the external variable
 .I environ
-in the current process.
+in the calling process.
 .SS Special semantics for execlp() and execvp()
 .PP
 The
-.BR execlp ()
+.BR execlp (),
+.BR execvp (),
 and
-.BR execvp ()
+.BR execvpe ()
 functions duplicate the actions of the shell in
 searching for an executable file
 if the specified filename does not contain a slash (/) character.
@@ -139,10 +145,9 @@ the current directory followed by the list of directories returned by
 .BR confstr (3)
 call typically returns the value "/bin:/usr/bin".)
 
-If the specified filename includes a slash character,
-then
+If the specified filename includes a slash character, then
 .B PATH
-is ignored, and file at the specified pathname is executed.
+is ignored, and the file at the specified pathname is executed.
 
 In addition, certain errors are treated specially.
 
@@ -166,21 +171,29 @@ 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.)
 .SH "RETURN VALUE"
-If any of the
+The
 .BR exec ()
-functions returns, an error will have occurred.
+functions only return if an error has have occurred.
 The return value is \-1, and
 .I errno
-will be set to indicate the error.
+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 the library function
+for any of the errors specified for
 .BR execve (2).
+.SH
+The
+.BR execvpe ()
+function first appeared in glibc 2.11.
 .SH "CONFORMING TO"
-POSIX.1-2001.
+POSIX.1-2001, POSIX.1-2008.
+
+The
+.BR execvpe ()
+function is a GNU extension.
 .SH NOTES
-On some other systems the default path (used when the environment
+On some other systems, the default path (used when the environment
 does not contain the variable \fBPATH\fR) has the current working
 directory listed after
 .I /bin