Debian Codegraph @

upstream/debian-trixie/man3/getlogin.3

raw
1 '\" t
2 .\" Copyright 1995 James R. Van Zandt <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3
7 .\" added ref to /etc/utmp, added BUGS section, etc.
8 .\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use
9 .TH getlogin 3 2024-06-15 "Linux man-pages 6.9.1"
10 .SH NAME
11 getlogin, getlogin_r, cuserid \- get username
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ", " \-lc )
15 .SH SYNOPSIS
16 .nf
17 .B #include <unistd.h>
18 .P
19 .B "char *getlogin(void);"
20 .BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize );
21 .P
22 .B #include <stdio.h>
23 .P
24 .BI "char *cuserid(char *" string );
25 .fi
26 .P
27 .RS -4
28 Feature Test Macro Requirements for glibc (see
29 .BR feature_test_macros (7)):
30 .RE
31 .P
32 .BR getlogin_r ():
33 .nf
34 .\" Deprecated: _REENTRANT ||
35 _POSIX_C_SOURCE >= 199506L
36 .fi
37 .P
38 .BR cuserid ():
39 .nf
40 Since glibc 2.24:
41 (_XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
42 || _GNU_SOURCE
43 Up to and including glibc 2.23:
44 _XOPEN_SOURCE
45 .fi
46 .SH DESCRIPTION
47 .BR getlogin ()
48 returns a pointer to a string containing the name of
49 the user logged in on the controlling terminal of the process, or a
50 null pointer if this information cannot be determined.
51 The string is
52 statically allocated and might be overwritten on subsequent calls to
53 this function or to
54 .BR cuserid ().
55 .P
56 .BR getlogin_r ()
57 returns this same username in the array
58 .I buf
59 of size
60 .IR bufsize .
61 .P
62 .BR cuserid ()
63 returns a pointer to a string containing a username
64 associated with the effective user ID of the process.
65 If \fIstring\fP
66 is not a null pointer, it should be an array that can hold at least
67 \fBL_cuserid\fP characters; the string is returned in this array.
68 Otherwise, a pointer to a string in a static area is returned.
69 This
70 string is statically allocated and might be overwritten on subsequent
71 calls to this function or to
72 .BR getlogin ().
73 .P
74 The macro \fBL_cuserid\fP is an integer constant that indicates how
75 long an array you might need to store a username.
76 \fBL_cuserid\fP is declared in \fI<stdio.h>\fP.
77 .P
78 These functions let your program identify positively the user who is
79 running
80 .RB ( cuserid ())
81 or the user who logged in this session
82 .RB ( getlogin ()).
83 (These can differ when set-user-ID programs are involved.)
84 .P
85 For most purposes, it is more useful to use the environment variable
86 \fBLOGNAME\fP to find out who the user is.
87 This is more flexible
88 precisely because the user can set \fBLOGNAME\fP arbitrarily.
89 .SH RETURN VALUE
90 .BR getlogin ()
91 returns a pointer to the username when successful,
92 and NULL on failure, with
93 .I errno
94 set to indicate the error.
95 .BR getlogin_r ()
96 returns 0 when successful, and nonzero on failure.
97 .SH ERRORS
98 POSIX specifies:
99 .TP
100 .B EMFILE
101 The per-process limit on the number of open file descriptors has been reached.
102 .TP
103 .B ENFILE
104 The system-wide limit on the total number of open files has been reached.
105 .TP
106 .B ENXIO
107 The calling process has no controlling terminal.
108 .TP
109 .B ERANGE
110 (getlogin_r)
111 The length of the username,
112 including the terminating null byte
113 .RB ( \[aq]\[rs]0\[aq] ),
114 is larger than
115 .IR bufsize .
116 .P
117 Linux/glibc also has:
118 .TP
119 .B ENOENT
120 There was no corresponding entry in the utmp-file.
121 .TP
122 .B ENOMEM
123 Insufficient memory to allocate passwd structure.
124 .TP
125 .B ENOTTY
126 Standard input didn't refer to a terminal.
127 (See BUGS.)
128 .SH FILES
129 .TP
130 \fI/etc/passwd\fP
131 password database file
132 .TP
133 \fI/var/run/utmp\fP
134 (traditionally \fI/etc/utmp\fP;
135 some libc versions used \fI/var/adm/utmp\fP)
136 .SH ATTRIBUTES
137 For an explanation of the terms used in this section, see
138 .BR attributes (7).
139 .TS
140 allbox;
141 lb lb lbx
142 l l l.
143 Interface Attribute Value
144 T{
145 .na
146 .nh
147 .BR getlogin ()
148 T} Thread safety T{
149 .na
150 .nh
151 MT-Unsafe race:getlogin race:utent
152 sig:ALRM timer locale
153 T}
154 T{
155 .na
156 .nh
157 .BR getlogin_r ()
158 T} Thread safety T{
159 .na
160 .nh
161 MT-Unsafe race:utent sig:ALRM timer
162 locale
163 T}
164 T{
165 .na
166 .nh
167 .BR cuserid ()
168 T} Thread safety T{
169 .na
170 .nh
171 MT-Unsafe race:cuserid/!string locale
172 T}
173 .TE
174 .P
175 In the above table,
176 .I utent
177 in
178 .I race:utent
179 signifies that if any of the functions
180 .BR setutent (3),
181 .BR getutent (3),
182 or
183 .BR endutent (3)
184 are used in parallel in different threads of a program,
185 then data races could occur.
186 .BR getlogin ()
187 and
188 .BR getlogin_r ()
189 call those functions,
190 so we use race:utent to remind users.
191 .SH VERSIONS
192 OpenBSD has
193 .BR getlogin ()
194 and
195 .BR setlogin (),
196 and a username
197 associated with a session, even if it has no controlling terminal.
198 .SH STANDARDS
199 .TP
200 .BR getlogin ()
201 .TQ
202 .BR getlogin_r ()
203 POSIX.1-2008.
204 .TP
205 .BR cuserid ()
206 None.
207 .SH STANDARDS
208 .TP
209 .BR getlogin ()
210 .TQ
211 .BR getlogin_r ():
212 POSIX.1-2001.
213 OpenBSD.
214 .TP
215 .BR cuserid ()
216 System V, POSIX.1-1988.
217 Removed in POSIX.1-1990.
218 SUSv2.
219 Removed in POSIX.1-2001.
220 .IP
221 System V has a
222 .BR cuserid ()
223 function which uses the real
224 user ID rather than the effective user ID.
225 .SH BUGS
226 Unfortunately, it is often rather easy to fool
227 .BR getlogin ().
228 Sometimes it does not work at all, because some program messed up
229 the utmp file.
230 Often, it gives only the first 8 characters of
231 the login name.
232 The user currently logged in on the controlling terminal
233 of our program need not be the user who started it.
234 Avoid
235 .BR getlogin ()
236 for security-related purposes.
237 .P
238 Note that glibc does not follow the POSIX specification and uses
239 .I stdin
240 instead of
241 .IR /dev/tty .
242 A bug.
243 (Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8
244 all return the login name also when
245 .I stdin
246 is redirected.)
247 .P
248 Nobody knows precisely what
249 .BR cuserid ()
250 does; avoid it in portable programs.
251 Or avoid it altogether: use
252 .I getpwuid(geteuid())
253 instead, if that is
254 what you meant.
255 .B Do not use
256 .BR cuserid ().
257 .SH SEE ALSO
258 .BR logname (1),
259 .BR geteuid (2),
260 .BR getuid (2),
261 .BR utmp (5)