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
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.
|
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
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.
|