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 .nf
53 #include <unistd.h>
54
55 \fBchar *\fR\fBgetlogin\fR(\fBvoid\fR);
56 .fi
57
58 .LP
59 .nf
60 \fBchar *\fR\fBgetlogin_r\fR(\fBchar *\fR\fIname\fR, \fBint\fR \fInamelen\fR);
61 .fi
62
63 .SS "Standard conforming"
64 .nf
65 cc [ \fIflag \fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary \fR... ]
66
67 \fBint\fR \fBgetlogin_r\fR(\fBchar *\fR\fIname\fR, \fBsize_t\fR \fInamesize\fR);
68 .fi
69
70 .SH DESCRIPTION
71 The \fBgetlogin()\fR function returns a pointer to the login name as found in
72 \fB/var/adm/utmpx\fR. It can be used in conjunction with \fBgetpwnam\fR(3C) to
73 locate the correct password file entry when the same user \fBID\fR is shared by
74 several login names.
75 .sp
76 .LP
77 The login name plus the terminating null byte can be up to 33 characters
78 in length.
79 Newly-compiled programs should use the \fBLOGIN_NAME_MAX\fR symbol,
80 defined in <\fBlimits.h\fR>, to size the buffer.
81 Older programs that call \fBgetlogin()\fR expect only the legacy
82 9-character length.
83 These automatically link to a version of the \fBgetlogin()\fR functions that
84 truncates longer login names.
85 It's also possible to compile new programs that link to truncating versions
86 of these functions by defining \fB__USE_LEGACY_LOGNAME__\fR in the
87 compile environment.
88 .sp
89 .LP
90 Some older programs will correctly handle long login names returned
91 by the \fBgetlogin()\fR function.
92 For this case, the user compatibility library
93 \fB/usr/lib/getloginx.so.1\fR redirects to a version of the \fBgetlogin()\fR
94 function that returns the long name.
95 This library should be added to such an application
96 at runtime using \fBLD_PRELOAD\fR.
97 .sp
98 .LP
99 If \fBgetlogin()\fR is called within a process that is not attached to a
100 terminal, it returns a null pointer. The correct procedure for determining the
101 login name is to call \fBcuserid\fR(3C), or to call \fBgetlogin()\fR and if it
102 fails to call \fBgetpwuid\fR(3C).
103 .sp
104 .LP
105 The \fBgetlogin_r()\fR function has the same functionality as \fBgetlogin()\fR
106 except that the caller must supply a buffer \fIname\fR with length \fInamelen\fR
107 to store the result. The \fIname\fR buffer should be at least
108 \fBLOGIN_NAME_MAX\fR bytes in size (defined in <\fBlimits.h\fR>). The POSIX
109 version (see \fBstandards\fR(5)) of \fBgetlogin_r()\fR takes a \fInamesize\fR
110 parameter of type \fBsize_t\fR. If the size of the supplied buffer is less than
111 the size of \fBLOGIN_NAME_MAX\fR and the name, including the null
112 terminator, does not fit inside the buffer, than an error will be generated.
113 Otherwise, the buffer \fIname\fR will be updated with the login name.
114
115 .SH RETURN VALUES
116 Upon successful completion, \fBgetlogin()\fR returns a pointer to the login
117 name or a null pointer if the user's login name cannot be found. Otherwise it
118 returns a null pointer and sets \fBerrno\fR to indicate the error.
119 .sp
120 .LP
121 The standard-conforming \fBgetlogin_r()\fR returns \fB0\fR if successful, or
122 the error number upon failure.
123 .SH ERRORS
124 The \fBgetlogin_r()\fR function will fail if:
125 .sp
126 .ne 2
127 .na
128 \fB\fBERANGE\fR\fR
129 .ad
130 .RS 10n
131 The size of the buffer is smaller than the result to be returned.
132 .RE
133
134 .sp
135 .ne 2
136 .na
137 \fB\fBEINVAL\fR\fR
138 .ad
139 .RS 10n
140 And entry for the current user was not found in the \fB/var/adm/utmpx\fR file.
141 .RE
142
143 .sp
144 .LP
145 The \fBgetlogin()\fR and \fBgetlogin_r()\fR functions may fail if:
146 .sp
147 .ne 2
148 .na
149 \fB\fBEMFILE\fR\fR
150 .ad
151 .RS 10n
152 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
153 process.
154 .RE
155
156 .sp
157 .ne 2
158 .na
159 \fB\fBENFILE\fR\fR
160 .ad
161 .RS 10n
162 The maximum allowable number of files is currently open in the system.
163 .RE
164
165 .sp
166 .ne 2
167 .na
168 \fB\fBENXIO\fR\fR
169 .ad
170 .RS 10n
171 The calling process has no controlling terminal.
172 .RE
173
174 .sp
175 .LP
176 The \fBgetlogin_r()\fR function may fail if:
177 .sp
178 .ne 2
179 .na
180 \fB\fBERANGE\fR\fR
181 .ad
182 .RS 10n
183 The size of the buffer is smaller than the result to be returned.
184 .RE
185
186 .SH USAGE
187 The return value of \fBgetlogin()\fR points to thread-specific data whose
188 content is overwritten on each call by the same thread.
189 .sp
190 .LP
191 Three names associated with the current process can be determined:
192 \fBgetpwuid(\fR\fBgeteuid()\fR\fB)\fR returns the name associated with the
193 effective user ID of the process; \fBgetlogin()\fR returns the name associated
194 with the current login activity; and \fBgetpwuid(\fR\fBgetuid()\fR\fB)\fR
195 returns the name associated with the real user ID of the process.
196 .SH FILES
197 .ne 2
198 .na
199 \fB\fB/var/adm/utmpx\fR\fR
200 .ad
201 .RS 18n
202 user access and administration information
203 .RE
204
205 .sp
206 .ne 2
207 .na
208 \fB\fB/usr/lib/getloginx.so.1\fR\fR
209 .ad
210 .RS 18n
211 A compatibility library that returns long login names to older applications.
212 .RE
213
214 .sp
215 .ne 2
216 .na
217 \fB\fB/usr/lib/64/getloginx.so.1\fR\fR
218 .ad
219 .RS 18n
220 A 64-bit compatibility library to return long login names.
221 .RE
222
223 .SH ATTRIBUTES
224 See \fBattributes\fR(5) for descriptions of the following attributes:
225 .sp
226
227 .sp
228 .TS
229 box;
230 c | c
231 l | l .
232 ATTRIBUTE TYPE ATTRIBUTE VALUE
233 _
234 Interface Stability Standard
235 _
236 MT-Level See below.
237 .TE
238
239 .SH SEE ALSO
240 \fBgeteuid\fR(2), \fBgetuid\fR(2), \fBcuserid\fR(3C), \fBgetgrnam\fR(3C),
241 \fBgetpwnam\fR(3C), \fBgetpwuid\fR(3C), \fButmpx\fR(4), \fBattributes\fR(5),
242 \fBstandards\fR(5)
243 .SH NOTES
244 When compiling multithreaded programs, see \fBIntro\fR(3).
245 .sp
246 .LP
247 The \fBgetlogin()\fR function is safe to use in multithreaded applications, but
248 is discouraged. The \fBgetlogin_r()\fR function should be used instead.
249 .sp
250 .LP
251 Solaris 2.4 and earlier releases provided a \fBgetlogin_r()\fR as specified in
252 POSIX.1c Draft 6. The final POSIX.1c standard changed the interface as
253 described above. Support for the Draft 6 interface is provided for
254 compatibility only and may not be supported in future releases. New
255 applications and libraries should use the standard-conforming interface.