Debian Codegraph @

upstream/debian-unstable/man3/getlogin.3

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