man3/getlogin.3

   1 '\" t
   2 .\" Copyright 1995  James R. Van Zandt <jrv@vanzandt.mv.com>
   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 (date) "Linux man-pages (unreleased)"
  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, including the terminating null byte (\[aq]\e0\[aq]),
 112 is larger than
 113 .IR bufsize .
 114 .P
 115 Linux/glibc also has:
 116 .TP
 117 .B ENOENT
 118 There was no corresponding entry in the utmp-file.
 119 .TP
 120 .B ENOMEM
 121 Insufficient memory to allocate passwd structure.
 122 .TP
 123 .B ENOTTY
 124 Standard input didn't refer to a terminal.
 125 (See BUGS.)
 126 .SH FILES
 127 .TP
 128 \fI/etc/passwd\fP
 129 password database file
 130 .TP
 131 \fI/var/run/utmp\fP
 132 (traditionally \fI/etc/utmp\fP;
 133 some libc versions used \fI/var/adm/utmp\fP)
 134 .SH ATTRIBUTES
 135 For an explanation of the terms used in this section, see
 136 .BR attributes (7).
 137 .TS
 138 allbox;
 139 lb lb lbx
 140 l l l.
 141 Interface       Attribute       Value
 142 T{
 143 .na
 144 .nh
 145 .BR getlogin ()
 146 T}      Thread safety   T{
 147 .na
 148 .nh
 149 MT-Unsafe race:getlogin race:utent
 150 sig:ALRM timer locale
 151 T}
 152 T{
 153 .na
 154 .nh
 155 .BR getlogin_r ()
 156 T}      Thread safety   T{
 157 .na
 158 .nh
 159 MT-Unsafe race:utent sig:ALRM timer
 160 locale
 161 T}
 162 T{
 163 .na
 164 .nh
 165 .BR cuserid ()
 166 T}      Thread safety   T{
 167 .na
 168 .nh
 169 MT-Unsafe race:cuserid/!string locale
 170 T}
 171 .TE
 172 .P
 173 In the above table,
 174 .I utent
 175 in
 176 .I race:utent
 177 signifies that if any of the functions
 178 .BR setutent (3),
 179 .BR getutent (3),
 180 or
 181 .BR endutent (3)
 182 are used in parallel in different threads of a program,
 183 then data races could occur.
 184 .BR getlogin ()
 185 and
 186 .BR getlogin_r ()
 187 call those functions,
 188 so we use race:utent to remind users.
 189 .SH VERSIONS
 190 OpenBSD has
 191 .BR getlogin ()
 192 and
 193 .BR setlogin (),
 194 and a username
 195 associated with a session, even if it has no controlling terminal.
 196 .SH STANDARDS
 197 .TP
 198 .BR getlogin ()
 199 .TQ
 200 .BR getlogin_r ()
 201 POSIX.1-2008.
 202 .TP
 203 .BR cuserid ()
 204 None.
 205 .SH STANDARDS
 206 .TP
 207 .BR getlogin ()
 208 .TQ
 209 .BR getlogin_r ():
 210 POSIX.1-2001.
 211 OpenBSD.
 212 .TP
 213 .BR cuserid ()
 214 System V, POSIX.1-1988.
 215 Removed in POSIX.1-1990.
 216 SUSv2.
 217 Removed in POSIX.1-2001.
 218 .IP
 219 System V has a
 220 .BR cuserid ()
 221 function which uses the real
 222 user ID rather than the effective user ID.
 223 .SH BUGS
 224 Unfortunately, it is often rather easy to fool
 225 .BR getlogin ().
 226 Sometimes it does not work at all, because some program messed up
 227 the utmp file.
 228 Often, it gives only the first 8 characters of
 229 the login name.
 230 The user currently logged in on the controlling terminal
 231 of our program need not be the user who started it.
 232 Avoid
 233 .BR getlogin ()
 234 for security-related purposes.
 235 .P
 236 Note that glibc does not follow the POSIX specification and uses
 237 .I stdin
 238 instead of
 239 .IR /dev/tty .
 240 A bug.
 241 (Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8
 242 all return the login name also when
 243 .I stdin
 244 is redirected.)
 245 .P
 246 Nobody knows precisely what
 247 .BR cuserid ()
 248 does; avoid it in portable programs.
 249 Or avoid it altogether: use
 250 .I getpwuid(geteuid())
 251 instead, if that is
 252 what you meant.
 253 .B Do not use
 254 .BR cuserid ().
 255 .SH SEE ALSO
 256 .BR logname (1),
 257 .BR geteuid (2),
 258 .BR getuid (2),
 259 .BR utmp (5)