Merging upstream version 6.8.

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

1 files changed, 259 insertions, 0 deletions

diff --git a/man/man3/getlogin.3 b/man/man3/getlogin.3
new file mode 100644
index 0000000..6ac36f8
--- /dev/null
+++ b/man/man3/getlogin.3
@@ -0,0 +1,259 @@
+'\" t
+.\" Copyright 1995  James R. Van Zandt <jrv@vanzandt.mv.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getlogin, getlogin_r, cuserid \- get username
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.P
+.B "char *getlogin(void);"
+.BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize );
+.P
+.B #include <stdio.h>
+.P
+.BI "char *cuserid(char *" string );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR getlogin_r ():
+.nf
+.\" Deprecated: _REENTRANT ||
+    _POSIX_C_SOURCE >= 199506L
+.fi
+.P
+.BR cuserid ():
+.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.
+The string is
+statically allocated and might be overwritten on subsequent calls to
+this function or to
+.BR cuserid ().
+.P
+.BR getlogin_r ()
+returns this same username in the array
+.I buf
+of size
+.IR bufsize .
+.P
+.BR cuserid ()
+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
+\fBL_cuserid\fP characters; the string is returned in this array.
+Otherwise, a pointer to a string in a static area is returned.
+This
+string is statically allocated and might be overwritten on subsequent
+calls to this function or to
+.BR getlogin ().
+.P
+The macro \fBL_cuserid\fP is an integer constant that indicates how
+long an array you might need to store a username.
+\fBL_cuserid\fP is declared in \fI<stdio.h>\fP.
+.P
+These functions let your program identify positively the user who is
+running
+.RB ( cuserid ())
+or the user who logged in this session
+.RB ( getlogin ()).
+(These can differ when set-user-ID programs are involved.)
+.P
+For most purposes, it is more useful to use the environment variable
+\fBLOGNAME\fP to find out who the user is.
+This is more flexible
+precisely because the user can set \fBLOGNAME\fP arbitrarily.
+.SH RETURN VALUE
+.BR getlogin ()
+returns a pointer to the username when successful,
+and NULL on failure, with
+.I errno
+set to indicate the error.
+.BR getlogin_r ()
+returns 0 when successful, and nonzero on failure.
+.SH ERRORS
+POSIX specifies:
+.TP
+.B EMFILE
+The per-process limit on the number of open file descriptors has been reached.
+.TP
+.B ENFILE
+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]\e0\[aq]),
+is larger than
+.IR bufsize .
+.P
+Linux/glibc also has:
+.TP
+.B ENOENT
+There was no corresponding entry in the utmp-file.
+.TP
+.B ENOMEM
+Insufficient memory to allocate passwd structure.
+.TP
+.B ENOTTY
+Standard input didn't refer to a terminal.
+(See BUGS.)
+.SH FILES
+.TP
+\fI/etc/passwd\fP
+password database file
+.TP
+\fI/var/run/utmp\fP
+(traditionally \fI/etc/utmp\fP;
+some libc versions used \fI/var/adm/utmp\fP)
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lbx
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR getlogin ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:getlogin race:utent
+sig:ALRM timer locale
+T}
+T{
+.na
+.nh
+.BR getlogin_r ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:utent sig:ALRM timer
+locale
+T}
+T{
+.na
+.nh
+.BR cuserid ()
+T}	Thread safety	T{
+.na
+.nh
+MT-Unsafe race:cuserid/!string locale
+T}
+.TE
+.P
+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 ()
+call those functions,
+so we use race:utent to remind users.
+.SH VERSIONS
+OpenBSD has
+.BR getlogin ()
+and
+.BR setlogin (),
+and a username
+associated with a session, even if it has no controlling terminal.
+.SH STANDARDS
+.TP
+.BR getlogin ()
+.TQ
+.BR getlogin_r ()
+POSIX.1-2008.
+.TP
+.BR cuserid ()
+None.
+.SH STANDARDS
+.TP
+.BR getlogin ()
+.TQ
+.BR getlogin_r ():
+POSIX.1-2001.
+OpenBSD.
+.TP
+.BR cuserid ()
+System V, POSIX.1-1988.
+Removed in POSIX.1-1990.
+SUSv2.
+Removed in POSIX.1-2001.
+.IP
+System V has a
+.BR cuserid ()
+function which uses the real
+user ID rather than the effective user ID.
+.SH BUGS
+Unfortunately, it is often rather easy to fool
+.BR getlogin ().
+Sometimes it does not work at all, because some program messed up
+the utmp file.
+Often, it gives only the first 8 characters of
+the login name.
+The user currently logged in on the controlling terminal
+of our program need not be the user who started it.
+Avoid
+.BR getlogin ()
+for security-related purposes.
+.P
+Note that glibc does not follow the POSIX specification and uses
+.I stdin
+instead of
+.IR /dev/tty .
+A bug.
+(Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8
+all return the login name also when
+.I stdin
+is redirected.)
+.P
+Nobody knows precisely what
+.BR cuserid ()
+does; avoid it in portable programs.
+Or avoid it altogether: use
+.I getpwuid(geteuid())
+instead, if that is
+what you meant.
+.B Do not use
+.BR cuserid ().
+.SH SEE ALSO
+.BR logname (1),
+.BR geteuid (2),
+.BR getuid (2),
+.BR utmp (5)