1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
  45 .\" Copyright (c) 2004 Sun Microsystems, Inc.  All Rights Reserved.
  46 .\" Copyright (c) 2013 Gary Mills
  47 .\"
  48 .TH GETLOGIN 3C "Mar 15, 2014"
  49 .SH NAME
  50 getlogin, getlogin_r \- get login name
  51 .SH SYNOPSIS
  52 .LP
  53 .nf
  54 #include <unistd.h>
  55 
  56 \fBchar *\fR\fBgetlogin\fR(\fBvoid\fR);
  57 .fi
  58 
  59 .LP
  60 .nf
  61 \fBchar *\fR\fBgetlogin_r\fR(\fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
  62 .fi
  63 
  64 .SS "Standard conforming"
  65 .LP
  66 .nf
  67 cc [ \fIflag \fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary \fR... ]
  68 
  69 \fBint\fR \fBgetlogin_r\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fInamesize\fR);
  70 .fi
  71 
  72 .SH DESCRIPTION
  73 .sp
  74 .LP
  75 The \fBgetlogin()\fR function returns a pointer to the login name as found in
  76 \fB/var/adm/utmpx\fR. It can be used in conjunction with \fBgetpwnam\fR(3C) to
  77 locate the correct password file entry when the same user \fBID\fR is shared by
  78 several login names.
  79 .sp
  80 .LP
  81 The login name plus the terminating null byte can be up to 33 characters
  82 in length.
  83 Newly-compiled programs should use the \fBLOGIN_NAME_MAX\fR symbol,
  84 defined in <\fBlimits.h\fR>, to size the buffer.
  85 Older programs that call \fBgetlogin()\fR  expect only the legacy
  86 9-character length.
  87 These automatically link to a version of the \fBgetlogin()\fR functions that
  88 truncates longer login names.
  89 It's also possible to compile new programs that link to truncating versions
  90 of these functions by defining \fB__USE_LEGACY_LOGNAME__\fR in the
  91 compile environment.
  92 .sp
  93 .LP
  94 Some older programs will correctly handle long login names returned
  95 by the \fBgetlogin()\fR function.
  96 For this case, the user compatibility library
  97 \fB/usr/lib/getloginx.so.1\fR redirects to a version of the \fBgetlogin()\fR
  98 function that returns the long name.
  99 This library should be added to such an application
 100 at runtime using \fBLD_PRELOAD\fR.
 101 .sp
 102 .LP
 103 If \fBgetlogin()\fR is called within a process that is not attached to a
 104 terminal, it returns a null pointer. The correct procedure for determining the
 105 login name is to call \fBcuserid\fR(3C), or to call \fBgetlogin()\fR and if it
 106 fails to call \fBgetpwuid\fR(3C).
 107 .sp
 108 .LP
 109 
 110 The \fBgetlogin_r()\fR function has the same functionality as \fBgetlogin()\fR
 111 except that the caller must supply a buffer \fIname\fR with length \fInamelen\fR
 112 to store the result.  The \fIname\fR buffer should be at least
 113 \fBLOGIN_NAME_MAX\fR bytes in size (defined in <\fBlimits.h\fR>). The POSIX
 114 version (see \fBstandards\fR(5)) of \fBgetlogin_r()\fR takes a \fInamesize\fR
 115 parameter of type \fBsize_t\fR. If the size of the supplied buffer is less than
 116 the size of \fBLOGIN_NAME_MAX\fR and the name, including the null
 117 terminator, does not fit inside the buffer, than an error will be generated.
 118 Otherwise, the buffer \fIname\fR will be updated with the login name.
 119 
 120 .SH RETURN VALUES
 121 .sp
 122 .LP
 123 Upon successful completion, \fBgetlogin()\fR returns a pointer to the login
 124 name or a null pointer if the user's login name cannot be found.  Otherwise it
 125 returns a null pointer and sets \fBerrno\fR to indicate the error.
 126 .sp
 127 .LP
 128 The standard-conforming \fBgetlogin_r()\fR returns \fB0\fR if successful, or
 129 the error number upon failure.
 130 .SH ERRORS
 131 .sp
 132 .LP
 133 The \fBgetlogin_r()\fR function will fail if:
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fBERANGE\fR\fR
 138 .ad
 139 .RS 10n
 140 The size of the buffer is smaller than the result to be returned.
 141 .RE
 142 
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fBEINVAL\fR\fR
 147 .ad
 148 .RS 10n
 149 And entry for the current user was not found in the \fB/var/adm/utmpx\fR file.
 150 .RE
 151 
 152 .sp
 153 .LP
 154 The \fBgetlogin()\fR and \fBgetlogin_r()\fR functions may fail if:
 155 .sp
 156 .ne 2
 157 .na
 158 \fB\fBEMFILE\fR\fR
 159 .ad
 160 .RS 10n
 161 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
 162 process.
 163 .RE
 164 
 165 .sp
 166 .ne 2
 167 .na
 168 \fB\fBENFILE\fR\fR
 169 .ad
 170 .RS 10n
 171 The maximum allowable number of files is currently open in the system.
 172 .RE
 173 
 174 .sp
 175 .ne 2
 176 .na
 177 \fB\fBENXIO\fR\fR
 178 .ad
 179 .RS 10n
 180 The calling process has no controlling terminal.
 181 .RE
 182 
 183 .sp
 184 .LP
 185 The \fBgetlogin_r()\fR function may fail if:
 186 .sp
 187 .ne 2
 188 .na
 189 \fB\fBERANGE\fR\fR
 190 .ad
 191 .RS 10n
 192 The size of the buffer is smaller than the result to be returned.
 193 .RE
 194 
 195 .SH USAGE
 196 .sp
 197 .LP
 198 The return value of \fBgetlogin()\fR points to thread-specific data whose
 199 content is overwritten on each call by the same thread.
 200 .sp
 201 .LP
 202 Three names associated with the current process can be determined:
 203 \fBgetpwuid(\fR\fBgeteuid()\fR\fB)\fR returns the name associated with the
 204 effective user ID of the process; \fBgetlogin()\fR returns the name associated
 205 with the current login activity; and \fBgetpwuid(\fR\fBgetuid()\fR\fB)\fR
 206 returns the name associated with the real user ID of the process.
 207 .SH FILES
 208 .sp
 209 .ne 2
 210 .na
 211 \fB\fB/var/adm/utmpx\fR\fR
 212 .ad
 213 .RS 18n
 214 user access and administration information
 215 .RE
 216 
 217 .sp
 218 .ne 2
 219 .na
 220 \fB\fB/usr/lib/getloginx.so.1\fR\fR
 221 .ad
 222 .RS 18n
 223 A compatibility library that returns long login names to older applications.
 224 .RE
 225 
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fB/usr/lib/64/getloginx.so.1\fR\fR
 230 .ad
 231 .RS 18n
 232 A 64-bit compatibility library to return long login names.
 233 .RE
 234 
 235 .SH ATTRIBUTES
 236 .sp
 237 .LP
 238 See \fBattributes\fR(5) for descriptions of the following attributes:
 239 .sp
 240 
 241 .sp
 242 .TS
 243 box;
 244 c | c
 245 l | l .
 246 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 247 _
 248 Interface Stability     Standard
 249 _
 250 MT-Level        See below.
 251 .TE
 252 
 253 .SH SEE ALSO
 254 .sp
 255 .LP
 256 \fBgeteuid\fR(2), \fBgetuid\fR(2), \fBcuserid\fR(3C), \fBgetgrnam\fR(3C),
 257 \fBgetpwnam\fR(3C), \fBgetpwuid\fR(3C), \fButmpx\fR(4), \fBattributes\fR(5),
 258 \fBstandards\fR(5)
 259 .SH NOTES
 260 .sp
 261 .LP
 262 When compiling multithreaded programs, see \fBIntro\fR(3).
 263 .sp
 264 .LP
 265 The \fBgetlogin()\fR function is safe to use in multithreaded applications, but
 266 is discouraged. The \fBgetlogin_r()\fR function should be used instead.
 267 .sp
 268 .LP
 269 Solaris 2.4 and earlier releases provided a \fBgetlogin_r()\fR as specified in
 270 POSIX.1c Draft 6. The final POSIX.1c standard changed the interface as
 271 described above. Support for the Draft 6 interface is provided for
 272 compatibility only and may not be supported in future releases. New
 273 applications and libraries should use the standard-conforming interface.