| blob | 4a983d77c89e25bdfce6bb77e83072393478303c |
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 .\" Copyright (c) 2001, The IEEE and The Open Group. All Rights Reserved.
45 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH GETPWNAM 3C "Feb 25, 2017"
48 .SH NAME
49 getpwnam, getpwnam_r, getpwent, getpwuid, getpwuid_r, setpwent,
50 endpwent \- get password entry
51 .SH SYNOPSIS
52 .LP
53 .nf
54 #include <pwd.h>
56 \fBstruct passwd *\fR\fBgetpwnam\fR(\fBconst char *\fR\fIname\fR);
57 .fi
59 .LP
60 .nf
61 \fBint\fR \fBgetpwnam_r\fR(\fBconst char *\fR\fIname\fR, \fBstruct passwd *\fR\fIpwd\fR, \fBchar *\fR\fIbuffer\fR,
62 \fBsize_t\fR \fIbufsize\fR, \fBstruct passwd **\fR\fIresult\fR);
63 .fi
65 .LP
66 .nf
67 \fBstruct passwd *\fR\fBgetpwent\fR(\fBvoid\fR);
68 .fi
70 .LP
71 .nf
72 \fBstruct passwd *\fR\fBgetpwuid\fR(\fBuid_t\fR \fIuid\fR);
73 .fi
75 .LP
76 .nf
77 \fBint\fR \fBgetpwuid_r\fR(\fBuid_t\fR \fIuid\fR, \fBstruct passwd *\fR\fIpwd\fR, \fBchar *\fR\fIbuffer\fR,
78 \fBsize_t\fR \fIbufsize\fR, \fBstruct passwd **\fR\fIresult\fR);
79 .fi
81 .LP
82 .nf
83 \fBvoid\fR \fBsetpwent\fR(\fBvoid\fR);
84 .fi
86 .LP
87 .nf
88 \fBvoid\fR \fBendpwent\fR(\fBvoid\fR);
89 .fi
91 .SH DESCRIPTION
92 .LP
93 These functions are used to obtain password entries. Entries can come from any
94 of the sources for \fBpasswd\fR specified in the \fB/etc/nsswitch.conf\fR file
95 (see \fBnsswitch.conf\fR(4)).
96 .sp
97 .LP
98 The \fBgetpwnam()\fR function searches for a password entry with the login name
99 specified by the character string parameter \fIname\fR.
100 .sp
101 .LP
102 The \fBgetpwuid()\fR function searches for a password entry with the (numeric)
103 user \fBID\fR specified by the \fIuid\fR parameter.
104 .sp
105 .LP
106 The \fBsetpwent()\fR, \fBgetpwent()\fR, and \fBendpwent()\fR functions are used
107 to enumerate password entries from the database. The \fBsetpwent()\fR function
108 sets (or resets) the enumeration to the beginning of the set of password
109 entries. This function should be called before the first call to
110 \fBgetpwent()\fR. Calls to \fBgetpwnam()\fR and \fBgetpwuid()\fR leave the
111 enumeration position in an indeterminate state. Successive calls to
112 \fBgetpwent()\fR return either successive entries or a null pointer, indicating
113 the end of the enumeration.
114 .sp
115 .LP
116 The \fBendpwent()\fR function may be called to indicate that the caller expects
117 to do no further password retrieval operations; the system may then close the
118 password file, deallocate resources it was using, and so forth. It is still
119 allowed, but possibly less efficient, for the process to call more password
120 functions after calling \fBendpwent()\fR.
121 .SS "Reentrant Interfaces"
122 .LP
123 The \fBgetpwnam()\fR, \fBgetpwuid()\fR, and \fBgetpwent()\fR functions are not
124 safe to use in multithreaded applications.
125 .sp
126 .LP
127 The parallel functions \fBgetpwnam_r()\fR and \fBgetpwuid_r()\fR,
128 provide reentrant interfaces for these operations.
129 .sp
130 .LP
131 Each reentrant interface performs the same operation as its non-reentrant
132 counterpart, named by removing the "\|_r\|" suffix. The reentrant interfaces,
133 however, use buffers supplied by the caller to store returned results instead
134 of using thread-specific data that can be overwritten by each call. They are
135 safe for use in both single-threaded and multithreaded applications.
136 .sp
137 .LP
138 Each reentrant interface takes the same parameters as its non-reentrant
139 counterpart, as well as the following additional parameters. The \fIpwd\fR
140 parameter must be a pointer to a \fBstruct passwd\fR structure allocated by the
141 caller. On successful completion, the function returns the password entry in
142 this structure. The parameter \fIbuffer\fR is a pointer to a buffer supplied by
143 the caller, used as storage space for the password data. All pointers within
144 the returned \fBstruct passwd\fR \fIpwd\fR point to data stored within this
145 buffer; see \fBpasswd Structure\fR below. The buffer must be large enough to
146 hold all the data associated with the password entry. The parameter
147 \fIbuflen\fR (or \fIbufsize\fR for the standard-conforming versions; see
148 \fBstandards\fR(5)) should give the size in bytes of \fIbuffer\fR. The maximum
149 size needed for this buffer can be determined with the
150 {\fB_SC_GETPW_R_SIZE_MAX\fR} \fBsysconf\fR(3C) parameter. The
151 standard-conforming versions place a pointer to the modified \fIpwd\fR
152 structure in the \fIresult\fR parameter, instead of returning a pointer to this
153 structure. A null pointer is returned at the location pointed to by
154 \fIresult\fR on error or if the requested entry is not found.
155 .sp
156 .LP
157 Like their non-reentrant counterparts, \fBgetpwnam_r()\fR and
158 \fBgetpwuid_r()\fR leave the enumeration position in an indeterminate state.
159 .SS "passwd Structure"
160 .LP
161 Password entries are represented by the \fBstruct passwd\fR structure defined
162 in <\fBpwd.h\fR>:
163 .sp
164 .in +2
165 .nf
166 struct passwd {
167 char *pw_name; /* user's login name */
168 char *pw_passwd; /* no longer used */
169 uid_t pw_uid; /* user's uid */
170 gid_t pw_gid; /* user's gid */
171 char *pw_age; /* not used */
172 char *pw_comment; /* not used */
173 char *pw_gecos; /* typically user's full name */
174 char *pw_dir; /* user's home dir */
175 char *pw_shell; /* user's login shell */
176 };
177 .fi
178 .in -2
180 .sp
181 .LP
182 The \fBpw_passwd\fR member should not be used as the encrypted password for the
183 user; use \fBgetspnam()\fR or \fBgetspnam_r()\fR instead. See
184 \fBgetspnam\fR(3C).
185 .SH RETURN VALUES
186 .LP
187 The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, and
188 \fBgetpwuid_r()\fR functions each return a pointer to a \fBstruct passwd\fR if
189 they successfully locate the requested entry. A null pointer is returned if the
190 requested entry is not found, or an error occurs. On error, \fBerrno\fR is set
191 to indicate the error.
192 .sp
193 .LP
194 Applications wishing to check for error situations should set \fBerrno\fR to 0
195 before calling \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR,
196 \fBgetpwuid_r()\fR and \fBgetpwent()\fR. If these non-reentrant functions
197 return a null pointer and \fBerrno\fR is non-zero, an error occurred.
198 .sp
199 .LP
200 The standard-conforming functions \fBgetpwnam_r()\fR and \fBgetpwuid_r()\fR can
201 return \fB0\fR even on an error, particularly in the case where the requested
202 entry is not found. The application needs to check the return value and that
203 the \fIpwd\fR pointer is non-null. Otherwise, an error value is returned to
204 indicate the error.
205 .sp
206 .LP
207 The \fBgetpwent()\fR function returns a pointer to a \fBstruct passwd\fR if it
208 successfully enumerates an entry; otherwise it returns a null pointer on
209 end-of-file or error. On error, \fBerrno\fR is set to indicate the error.
210 .sp
211 .LP
212 See \fBIntro\fR(2) for the proper usage and interpretation of \fBerrno\fR in
213 multithreaded applications.
214 .sp
215 .LP
216 The \fBgetpwnam()\fR, \fBgetpwuid()\fR, and \fBgetpwent()\fR functions use a
217 shared buffer, so returned data must be copied before a subsequent call to any
218 of these functions if the data is to be saved.
219 .sp
220 .LP
221 When the pointer returned by the reentrant functions \fBgetpwnam_r()\fR or
222 \fBgetpwuid_r()\fR is non-null, it is always equal to the \fIpwd\fR pointer
223 that was supplied by the caller.
224 .SH ERRORS
225 .LP
226 The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, \fBgetpwuid_r()\fR,
227 \fBgetpwent()\fR, \fBsetpwent()\fR, and \fBendpwent()\fR functions may fail if:
228 .sp
229 .ne 2
230 .na
231 \fB\fBEIO\fR\fR
232 .ad
233 .RS 7n
234 An I/O error has occurred.
235 .RE
237 .sp
238 .LP
239 The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, \fBgetpwuid_r()\fR,
240 \fBgetpwent()\fR, and \fBsetpwent()\fR functions may fail if:
241 .sp
242 .ne 2
243 .na
244 \fB\fBEMFILE\fR\fR
245 .ad
246 .RS 10n
247 There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
248 process.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fBENFILE\fR\fR
255 .ad
256 .RS 10n
257 The maximum allowable number of files is currently open in the system.
258 .RE
260 .sp
261 .LP
262 The \fBgetpwnam()\fR, \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, and
263 \fBgetpwuid_r()\fR functions may fail if:
264 .sp
265 .ne 2
266 .na
267 \fB\fBEINTR\fR\fR
268 .ad
269 .RS 9n
270 A signal was caught during the execution of the function call.
271 .RE
273 .sp
274 .LP
275 The \fBgetpwnam_r()\fR and \fBgetpwuid_r()\fR functions may fail if:
276 .sp
277 .ne 2
278 .na
279 \fB\fBERANGE\fR\fR
280 .ad
281 .RS 10n
282 Insufficient storage was supplied by \fIbuffer\fR and \fIbufsize\fR to contain
283 the data to be referenced by the resulting \fBpasswd\fR structure.
284 .RE
286 .SH USAGE
287 .LP
288 Three names associated with the current process can be determined:
289 \fBgetpwuid\fR(\fBgeteuid()\fR) returns the name associated with the effective
290 user ID of the process; \fBgetlogin()\fR returns the name associated with the
291 current login activity; and \fBgetpwuid\fR(\fBgetuid()\fR) returns the name
292 associated with the real user ID of the process.
293 .SH ATTRIBUTES
294 .LP
295 See \fBattributes\fR(5) for descriptions of the following attributes:
296 .sp
298 .sp
299 .TS
300 box;
301 c | c
302 l | l .
303 ATTRIBUTE TYPE ATTRIBUTE VALUE
304 _
305 Interface Stability Committed
306 _
307 MT-Level See \fBReentrant Interfaces\fR in \fBDESCRIPTION\fR.
308 _
309 Standard See below.
310 .TE
312 .sp
313 .LP
314 For \fBendpwent()\fR, \fBgetpwent()\fR, \fBgetpwnam()\fR,
315 \fBgetpwnam_r()\fR, \fBgetpwuid()\fR, \fBgetpwuid_r()\fR, and \fBsetpwent()\fR,
316 see \fBstandards\fR(5).
317 .SH SEE ALSO
318 .LP
319 \fBpasswd\fR(1), \fByppasswd\fR(1), \fBIntro\fR(2),
320 \fBIntro\fR(3), \fBcuserid\fR(3C), \fBgetgrnam\fR(3C), \fBgetlogin\fR(3C),
321 \fBgetspnam\fR(3C), \fBnsswitch.conf\fR(4), \fBpasswd\fR(4), \fBshadow\fR(4),
322 \fBattributes\fR(5), \fBstandards\fR(5)
323 .SH NOTES
324 .LP
325 When compiling multithreaded programs, see \fBIntro\fR(3).
326 .sp
327 .LP
328 Use of the enumeration interface \fBgetpwent()\fR is discouraged; enumeration
329 is supported for the \fBpasswd\fR file and \fBNIS,\fR but in general is not
330 efficient and might not be supported for all database sources. The
331 semantics of enumeration are discussed further in \fBnsswitch.conf\fR(4).
332 .sp
333 .LP
334 If a password entry from any of the sources contains an empty \fIuid\fR or
335 \fIgid\fR field, that entry will be ignored by the files and \fBNIS\fR
336 name service switch backends, causing the user to appear unknown to
337 the system.
338 .sp
339 .LP
340 If a password entry contains an empty \fIgecos\fR, \fIhome directory\fR, or
341 \fIshell\fR field, \fBgetpwnam()\fR and \fBgetpwnam_r()\fR return a pointer to
342 a null string in the respective field of the \fBpasswd\fR structure.
343 .sp
344 .LP
345 If the shell field is empty, \fBlogin\fR(1) automatically assigns the default
346 shell. See \fBlogin\fR(1).
347 .sp
348 .LP
349 Solaris 2.4 and earlier releases provided definitions of the \fBgetpwnam_r()\fR
350 and \fBgetpwuid_r()\fR functions as specified in POSIX.1c Draft 6. The final
351 POSIX.1c standard changed the interface for these functions. Support for the
352 Draft 6 interface is provided for compatibility only and might not be supported
353 in future releases. New applications and libraries should use the
354 standard-conforming interface.
355 .sp
356 .LP
357 For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR
358 flag is automatically turned on by defining the \fB_POSIX_C_SOURCE\fR flag
359 with a value \(>=199506L.