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