]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright 1995 James R. Van Zandt <jrv@vanzandt.mv.com> | |
4 | .\" | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
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 | |
28 | .TH GETLOGIN 3 2003-08-24 "Linux 2.4" "Linux Programmer's Manual" | |
29 | .SH NAME | |
30 | getlogin, getlogin_r, cuserid \- get user name | |
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 ); | |
41 | .SH DESCRIPTION | |
60a90ecd MK |
42 | .BR getlogin () |
43 | returns a pointer to a string containing the name of | |
fea681da | 44 | the user logged in on the controlling terminal of the process, or a |
c13182ef MK |
45 | null pointer if this information cannot be determined. |
46 | The string is | |
fea681da | 47 | statically allocated and might be overwritten on subsequent calls to |
60a90ecd MK |
48 | this function or to |
49 | .BR cuserid (). | |
fea681da | 50 | .PP |
60a90ecd MK |
51 | .BR getlogin_r () |
52 | returns this same user name in the array | |
fea681da MK |
53 | .I buf |
54 | of size | |
55 | .IR bufsize . | |
56 | .PP | |
60a90ecd MK |
57 | .BR cuserid () |
58 | returns a pointer to a string containing a user name | |
c13182ef MK |
59 | associated with the effective user ID of the process. |
60 | If \fIstring\fP | |
fea681da MK |
61 | is not a null pointer, it should be an array that can hold at least |
62 | \fBL_cuserid\fP characters; the string is returned in this array. | |
c13182ef MK |
63 | Otherwise, a pointer to a string in a static area is returned. |
64 | This | |
fea681da | 65 | string is statically allocated and might be overwritten on subsequent |
60a90ecd MK |
66 | calls to this function or to |
67 | .BR getlogin (). | |
fea681da MK |
68 | .PP |
69 | The macro \fBL_cuserid\fP is an integer constant that indicates how | |
70 | long an array you might need to store a user name. \fBL_cuserid\fP is | |
71 | declared in \fBstdio.h\fP. | |
72 | .PP | |
73 | These functions let your program identify positively the user who is | |
60a90ecd MK |
74 | running |
75 | .RB ( cuserid ()) | |
76 | or the user who logged in this session | |
77 | .RB ( getlogin ()). | |
78 | (These can differ when set-user-ID programs are involved.) | |
fea681da MK |
79 | .PP |
80 | For most purposes, it is more useful to use the environment variable | |
c13182ef MK |
81 | \fBLOGNAME\fP to find out who the user is. |
82 | This is more flexible | |
fea681da MK |
83 | precisely because the user can set \fBLOGNAME\fP arbitrarily. |
84 | .SH "RETURN VALUE" | |
60a90ecd MK |
85 | .BR getlogin () |
86 | returns a pointer to the user name when successful, | |
fea681da | 87 | and NULL on failure. |
60a90ecd MK |
88 | .BR getlogin_r () |
89 | returns 0 when successful, and non-zero on failure. | |
fea681da MK |
90 | .SH ERRORS |
91 | POSIX specifies | |
92 | .TP | |
93 | .B EMFILE | |
94 | The calling process already has the maximum allowed number of open files. | |
95 | .TP | |
96 | .B ENFILE | |
97 | The system already has the maximum allowed number of open files. | |
98 | .TP | |
99 | .B ENXIO | |
100 | The calling process has no controlling tty. | |
101 | .TP | |
102 | .B ERANGE | |
103 | (getlogin_r) | |
c13182ef | 104 | The length of the user name, including the terminating null byte, |
28d88c17 | 105 | is larger than |
fea681da MK |
106 | .IR bufsize . |
107 | .LP | |
108 | Linux/glibc also has | |
109 | .TP | |
110 | .B ENOENT | |
111 | There was no corresponding entry in the utmp-file. | |
112 | .TP | |
113 | .B ENOMEM | |
114 | Insufficient memory to allocate passwd structure. | |
115 | .SH FILES | |
116 | .nf | |
117 | \fI/etc/passwd\fP password database file | |
118 | .br | |
119 | \fI/var/run/utmp\fP (traditionally \fI/etc/utmp\fP; | |
120 | some libc versions used \fI/var/adm/utmp\fP) | |
121 | .fi | |
122 | .SH "CONFORMING TO" | |
68e1685c MK |
123 | .BR getlogin () |
124 | and | |
125 | .BR getlogin_r () | |
126 | specified in POSIX.1-2001. | |
127 | ||
60a90ecd MK |
128 | System V has a |
129 | .BR cuserid () | |
130 | function which uses the real | |
c13182ef | 131 | user ID rather than the effective user ID. |
60a90ecd MK |
132 | The |
133 | .BR cuserid () | |
134 | function | |
c13182ef | 135 | was included in the 1988 version of POSIX, |
68e1685c MK |
136 | but removed from the 1990 version. |
137 | It was present in SUSv2, but removed in POSIX.1-2001. | |
fea681da | 138 | .LP |
60a90ecd MK |
139 | OpenBSD has |
140 | .BR getlogin () | |
141 | and | |
142 | .BR setlogin (), | |
143 | and a username | |
fea681da MK |
144 | associated with a session, even if it has no controlling tty. |
145 | .SH BUGS | |
c13182ef | 146 | Unfortunately, it is often rather easy to fool |
b5cc2ffb | 147 | .BR getlogin (). |
fea681da | 148 | Sometimes it does not work at all, because some program messed up |
c13182ef MK |
149 | the utmp file. |
150 | Often, it gives only the first 8 characters of | |
151 | the login name. | |
152 | The user currently logged in on the controlling tty | |
fea681da | 153 | of our program need not be the user who started it. |
c13182ef | 154 | Avoid |
b5cc2ffb MK |
155 | .BR getlogin () |
156 | for security-related purposes. | |
fea681da | 157 | .LP |
c13182ef | 158 | Note that glibc does not follow the POSIX spec and uses |
68e1685c | 159 | .I stdin |
fea681da MK |
160 | instead of |
161 | .IR /dev/tty . | |
c13182ef MK |
162 | A bug. |
163 | (Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8 | |
164 | all return the login name also when | |
165 | .I stdin | |
68e1685c | 166 | is redirected.) |
fea681da | 167 | .LP |
c13182ef MK |
168 | Nobody knows precisely what |
169 | .BR cuserid () | |
b5cc2ffb | 170 | does; avoid it in portable programs. |
c13182ef | 171 | Or avoid it altogether: use |
b5cc2ffb MK |
172 | .I getpwuid(geteuid()) |
173 | instead, if that is | |
fea681da | 174 | what you meant. |
c13182ef | 175 | DO NOT USE |
b5cc2ffb | 176 | .BR cuserid (). |
fea681da MK |
177 | .SH "SEE ALSO" |
178 | .BR geteuid (2), | |
179 | .BR getuid (2) |