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 .PP
  19 .B "char *getlogin(void);"
  20 .BI "int getlogin_r(char " buf [. bufsize "], size_t " bufsize );
  21 .PP
  22 .B #include <stdio.h>
  23 .PP
  24 .BI "char *cuserid(char *" string );
  25 .fi
  26 .PP
  27 .RS -4
  28 Feature Test Macro Requirements for glibc (see
  29 .BR feature_test_macros (7)):
  30 .RE
  31 .PP
  32 .BR getlogin_r ():
  33 .nf
  34 .\" Deprecated: _REENTRANT ||
  35     _POSIX_C_SOURCE >= 199506L
  36 .fi
  37 .PP
  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 .PP
  56 .BR getlogin_r ()
  57 returns this same username in the array
  58 .I buf
  59 of size
  60 .IR bufsize .
  61 .PP
  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 .PP
  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 .PP
  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 .PP
  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 .PP
 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 .ad l
 138 .nh
 139 .TS
 140 allbox;
 141 lb lb lbx
 142 l l l.
 143 Interface       Attribute       Value
 144 T{
 145 .BR getlogin ()
 146 T}      Thread safety   T{
 147 MT-Unsafe race:getlogin race:utent
 148 sig:ALRM timer locale
 149 T}
 150 T{
 151 .BR getlogin_r ()
 152 T}      Thread safety   T{
 153 MT-Unsafe race:utent sig:ALRM timer
 154 locale
 155 T}
 156 T{
 157 .BR cuserid ()
 158 T}      Thread safety   T{
 159 MT-Unsafe race:cuserid/!string locale
 160 T}
 161 .TE
 162 .hy
 163 .ad
 164 .sp 1
 165 In the above table,
 166 .I utent
 167 in
 168 .I race:utent
 169 signifies that if any of the functions
 170 .BR setutent (3),
 171 .BR getutent (3),
 172 or
 173 .BR endutent (3)
 174 are used in parallel in different threads of a program,
 175 then data races could occur.
 176 .BR getlogin ()
 177 and
 178 .BR getlogin_r ()
 179 call those functions,
 180 so we use race:utent to remind users.
 181 .SH VERSIONS
 182 OpenBSD has
 183 .BR getlogin ()
 184 and
 185 .BR setlogin (),
 186 and a username
 187 associated with a session, even if it has no controlling terminal.
 188 .SH STANDARDS
 189 .TP
 190 .BR getlogin ()
 191 .TQ
 192 .BR getlogin_r ()
 193 POSIX.1-2008.
 194 .TP
 195 .BR cuserid ()
 196 None.
 197 .SH STANDARDS
 198 .TP
 199 .BR getlogin ()
 200 .TQ
 201 .BR getlogin_r ():
 202 POSIX.1-2001.
 203 OpenBSD.
 204 .TP
 205 .BR cuserid ()
 206 System V, POSIX.1-1988.
 207 Removed in POSIX.1-1990.
 208 SUSv2.
 209 Removed in POSIX.1-2001.
 210 .IP
 211 System V has a
 212 .BR cuserid ()
 213 function which uses the real
 214 user ID rather than the effective user ID.
 215 .SH BUGS
 216 Unfortunately, it is often rather easy to fool
 217 .BR getlogin ().
 218 Sometimes it does not work at all, because some program messed up
 219 the utmp file.
 220 Often, it gives only the first 8 characters of
 221 the login name.
 222 The user currently logged in on the controlling terminal
 223 of our program need not be the user who started it.
 224 Avoid
 225 .BR getlogin ()
 226 for security-related purposes.
 227 .PP
 228 Note that glibc does not follow the POSIX specification and uses
 229 .I stdin
 230 instead of
 231 .IR /dev/tty .
 232 A bug.
 233 (Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8
 234 all return the login name also when
 235 .I stdin
 236 is redirected.)
 237 .PP
 238 Nobody knows precisely what
 239 .BR cuserid ()
 240 does; avoid it in portable programs.
 241 Or avoid it altogether: use
 242 .I getpwuid(geteuid())
 243 instead, if that is
 244 what you meant.
 245 .B Do not use
 246 .BR cuserid ().
 247 .SH SEE ALSO
 248 .BR logname (1),
 249 .BR geteuid (2),
 250 .BR getuid (2),
 251 .BR utmp (5)