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