twalk_r.3: New link to twalk(3) page

[thirdparty/man-pages.git] / man3 / getlogin.3

diff --git a/man3/getlogin.3 b/man3/getlogin.3
index cd43163b9218d3b3b03702d5a6e426e1193b2a96..36fa8b7d23479a826d56473230b04ded9d772437 100644 (file)
--- a/man3/getlogin.3
+++ b/man3/getlogin.3
@@ -25,35 +25,42 @@
 .\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3
 .\"  added ref to /etc/utmp, added BUGS section, etc.
 .\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use
-.TH GETLOGIN 3 2013-04-19 "GNU" "Linux Programmer's Manual"
+.TH GETLOGIN 3 2019-03-06 "GNU" "Linux Programmer's Manual"
 .SH NAME
 getlogin, getlogin_r, cuserid \- get username
 .SH SYNOPSIS
 .B #include <unistd.h>
-.sp
+.PP
 .B "char *getlogin(void);"
 .br
 .BI "int getlogin_r(char *" buf ", size_t " bufsize );
-.sp
+.PP
 .B #include <stdio.h>
-.sp
+.PP
 .BI "char *cuserid(char *" string );
-.sp
+.PP
 .in -4n
 Feature Test Macro Requirements for glibc (see
 .BR feature_test_macros (7)):
 .in
-.sp
+.PP
 .BR getlogin_r ():
-_REENTRANT || _POSIX_C_SOURCE\ >=\ 199506L
-.br
+.\" Deprecated: _REENTRANT ||
+_POSIX_C_SOURCE\ >=\ 199506L
+.PP
 .BR cuserid ():
-_XOPEN_SOURCE
+.nf
+    Since glibc 2.24:
+        (_XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
+        || _GNU_SOURCE
+    Up to and including glibc 2.23:
+        _XOPEN_SOURCE
+.fi
 .SH DESCRIPTION
 .BR getlogin ()
 returns a pointer to a string containing the name of
 the user logged in on the controlling terminal of the process, or a
-NULL pointer if this information cannot be determined.
+null pointer if this information cannot be determined.
 The string is
 statically allocated and might be overwritten on subsequent calls to
 this function or to
@@ -69,7 +76,7 @@ of size
 returns a pointer to a string containing a username
 associated with the effective user ID of the process.
 If \fIstring\fP
-is not a NULL pointer, it should be an array that can hold at least
+is not a null pointer, it should be an array that can hold at least
 \fBL_cuserid\fP characters; the string is returned in this array.
 Otherwise, a pointer to a string in a static area is returned.
 This
@@ -104,20 +111,20 @@ returns 0 when successful, and nonzero on failure.
 POSIX specifies
 .TP
 .B EMFILE
-The calling process already has the maximum allowed number of open files.
+The per-process limit on the number of open file descriptors has been reached.
 .TP
 .B ENFILE
-The system already has the maximum allowed number of open files.
+The system-wide limit on the total number of open files has been reached.
 .TP
 .B ENXIO
 The calling process has no controlling terminal.
 .TP
 .B ERANGE
 (getlogin_r)
-The length of the username, including the terminating null byte (\(aq\\0\(aq),
+The length of the username, including the terminating null byte (\(aq\e0\(aq),
 is larger than
 .IR bufsize .
-.LP
+.PP
 Linux/glibc also has
 .TP
 .B ENOENT
@@ -138,25 +145,54 @@ password database file
 (traditionally \fI/etc/utmp\fP;
 some libc versions used \fI/var/adm/utmp\fP)
 .SH ATTRIBUTES
-.SS Multithreading (see pthreads(7))
-The
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface      Attribute       Value
+T{
 .BR getlogin ()
-function is not thread-safe.
-.LP
-The
+T}     Thread safety   T{
+MT-Unsafe race:getlogin race:utent
+.br
+sig:ALRM timer locale
+T}
+T{
 .BR getlogin_r ()
-function is thread-safe.
-.LP
-The
+T}     Thread safety   T{
+MT-Unsafe race:utent sig:ALRM timer
+.br
+locale
+T}
+T{
 .BR cuserid ()
-function is thread-safe with exceptions.
-It is not thread-safe if called with a NULL parameter.
-.SH CONFORMING TO
+T}     Thread safety   MT-Unsafe race:cuserid/!string locale
+.TE
+.sp 1
+In the above table,
+.I utent
+in
+.I race:utent
+signifies that if any of the functions
+.BR setutent (3),
+.BR getutent (3),
+or
+.BR endutent (3)
+are used in parallel in different threads of a program,
+then data races could occur.
 .BR getlogin ()
 and
 .BR getlogin_r ()
-specified in POSIX.1-2001.
-
+call those functions,
+so we use race:utent to remind users.
+.SH CONFORMING TO
+.BR getlogin ()
+and
+.BR getlogin_r ():
+POSIX.1-2001, POSIX.1-2008.
+.PP
 System V has a
 .BR cuserid ()
 function which uses the real
@@ -167,7 +203,7 @@ function
 was included in the 1988 version of POSIX,
 but removed from the 1990 version.
 It was present in SUSv2, but removed in POSIX.1-2001.
-.LP
+.PP
 OpenBSD has
 .BR getlogin ()
 and
@@ -186,7 +222,7 @@ of our program need not be the user who started it.
 Avoid
 .BR getlogin ()
 for security-related purposes.
-.LP
+.PP
 Note that glibc does not follow the POSIX specification and uses
 .I stdin
 instead of
@@ -196,7 +232,7 @@ A bug.
 all return the login name also when
 .I stdin
 is redirected.)
-.LP
+.PP
 Nobody knows precisely what
 .BR cuserid ()
 does; avoid it in portable programs.
@@ -207,6 +243,7 @@ what you meant.
 .B Do not use
 .BR cuserid ().
 .SH SEE ALSO
+.BR logname (1),
 .BR geteuid (2),
 .BR getuid (2),
 .BR utmp (5)