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