Documenting secure_getenv() in Linux man-pages

[Michael Kerrisk <mtk dot manpages at gmail dot com>]

Hi Florian, and others,

I've written the following patch to the Linux man pages to document
secure_getenv(). Could you take a moment to review it?

Much of it was written before I noticed that some documentation had
been added to the glibc manual, but once I discovered that, I added
the sentence on usage within libraries.

Cheers,

Michael


--- a/man3/getenv.3
+++ b/man3/getenv.3
@@ -28,15 +28,23 @@
 .\" Modified Sat Jul 24 19:30:29 1993 by Rik Faith (faith@cs.unc.edu)
 .\" Modified Fri Feb 14 21:47:50 1997 by Andries Brouwer (aeb@cwi.nl)
 .\"
-.TH GETENV 3  2008-03-17 "GNU" "Linux Programmer's Manual"
+.TH GETENV 3  2012-08-14 "GNU" "Linux Programmer's Manual"
 .SH NAME
-getenv \- get an environment variable
+getenv, secure_getenv \- get an environment variable
 .SH SYNOPSIS
 .nf
 .B #include <stdlib.h>
 .sp
 .BI "char *getenv(const char *" name );
 .fi
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR setjmp ():
+_GNU_SOURCE
 .SH DESCRIPTION
 The
 .BR getenv ()
@@ -46,13 +54,44 @@ environment variable
 and returns a pointer to the corresponding
 .I value
 string.
+
+The GNU-specific
+.BR secure_getenv ()
+function is just like
+.BR getenv ()
+except that it returns NULL in cases where "secure execution" is required.
+Secure execution is required if one of the following conditions
+was true when the program run by the calling process was loaded:
+.IP * 3
+the process's effective user ID did not match its real user ID or
+the process's effective group ID did not match its real group ID
+(typically this is the result of executing a set-user-ID or
+set-group-ID program);
+.IP *
+the effective capability bit was set on the executable file; or
+.IP *
+the process has a nonempty permitted capability set.
+.PP
+The
+.BR secure_getenv ()
+function is intended for use in general-purpose libraries
+to avoid vulnerabilities that could occur if
+set-user-ID or set-group-ID programs accidentally
+trusted the environment.
 .SH "RETURN VALUE"
 The
 .BR getenv ()
 function returns a pointer to the value in the
 environment, or NULL if there is no match.
 .SH "CONFORMING TO"
+.BR getenv ():
 SVr4, POSIX.1-2001, 4.3BSD, C89, C99.
+
+.BR secure_getenv ()
+is a GNU extension.
+.SH VERSIONS
+.BR secure_getenv ()
+first appeared in glibc 2.17.
 .SH NOTES
 The strings in the environment list are of the form \fIname=value\fP.