From 3d08cd331c1adcf0d917392f7e527b3f00511748 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Merging upstream version 6.8. Signed-off-by: Daniel Baumann --- man/man3/getlogin.3 | 259 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) create mode 100644 man/man3/getlogin.3 (limited to 'man/man3/getlogin.3') 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 +.\" +.\" 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 +.P +.B "char *getlogin(void);" +.BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize ); +.P +.B #include +.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\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) -- cgit v1.2.3