This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Documenting secure_getenv() in Linux man-pages
- From: Michael Kerrisk <mtk dot manpages at gmail dot com>
- To: Florian Weimer <fweimer at redhat dot com>
- Cc: "Carlos O'Donell" <carlos_odonell at mentor dot com>, Roland McGrath <roland at hack dot frob dot com>, libc-alpha at sourceware dot org
- Date: Tue, 14 Aug 2012 08:22:16 +0200
- Subject: Documenting secure_getenv() in Linux man-pages
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.