Debian Codegraph @

upstream/debian-trixie/man3/getpwent.3

raw
1 '\" t
2 .\" Copyright 1993 David Metcalfe ([email protected])
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .\" References consulted:
7 .\" Linux libc source code
8 .\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
9 .\" 386BSD man pages
10 .\"
11 .\" Modified Sat Jul 24 19:22:14 1993 by Rik Faith ([email protected])
12 .\" Modified Mon May 27 21:37:47 1996 by Martin Schulze <[email protected]>
13 .\" Modified Thu Dec 13 21:10:55 2001 by Martin Schulze <[email protected]>
14 .\"
15 .TH getpwent 3 2024-05-02 "Linux man-pages 6.9.1"
16 .SH NAME
17 getpwent, setpwent, endpwent \- get password file entry
18 .SH LIBRARY
19 Standard C library
20 .RI ( libc ", " \-lc )
21 .SH SYNOPSIS
22 .nf
23 .B #include <sys/types.h>
24 .B #include <pwd.h>
25 .P
26 .B struct passwd *getpwent(void);
27 .B void setpwent(void);
28 .B void endpwent(void);
29 .fi
30 .P
31 .RS -4
32 Feature Test Macro Requirements for glibc (see
33 .BR feature_test_macros (7)):
34 .RE
35 .P
36 .BR getpwent (),
37 .BR setpwent (),
38 .BR endpwent ():
39 .nf
40 _XOPEN_SOURCE >= 500
41 .\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
42 || /* glibc >= 2.19: */ _DEFAULT_SOURCE
43 || /* glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
44 .fi
45 .SH DESCRIPTION
46 The
47 .BR getpwent ()
48 function returns a pointer to a structure containing
49 the broken-out fields of a record from the password database
50 (e.g., the local password file
51 .IR /etc/passwd ,
52 NIS, and LDAP).
53 The first time
54 .BR getpwent ()
55 is called, it returns the first entry; thereafter, it returns successive
56 entries.
57 .P
58 The
59 .BR setpwent ()
60 function rewinds to the beginning
61 of the password database.
62 .P
63 The
64 .BR endpwent ()
65 function is used to close the password database
66 after all processing has been performed.
67 .P
68 The \fIpasswd\fP structure is defined in \fI<pwd.h>\fP as follows:
69 .P
70 .in +4n
71 .EX
72 struct passwd {
73 char *pw_name; /* username */
74 char *pw_passwd; /* user password */
75 uid_t pw_uid; /* user ID */
76 gid_t pw_gid; /* group ID */
77 char *pw_gecos; /* user information */
78 char *pw_dir; /* home directory */
79 char *pw_shell; /* shell program */
80 };
81 .EE
82 .in
83 .\" Next paragraph rejected upstream
84 .PP
85 When
86 .BR shadow (5)
87 passwords are enabled (which is default on many GNU/Linux
88 installations) the content of
89 .I pw_passwd
90 is usually not very useful. In such a case most passwords are stored
91 in a separate file.
92 .PP
93 The variable
94 .I pw_shell
95 may be empty, in which case the system will execute the default shell
96 .RB ( /bin/sh )
97 for the user.
98 .P
99 For more information about the fields of this structure, see
100 .BR passwd (5).
101 .SH RETURN VALUE
102 The
103 .BR getpwent ()
104 function returns a pointer to a
105 .I passwd
106 structure, or NULL if
107 there are no more entries or an error occurred.
108 If an error occurs,
109 .I errno
110 is set to indicate the error.
111 If one wants to check
112 .I errno
113 after the call, it should be set to zero before the call.
114 .P
115 The return value may point to a static area, and may be overwritten
116 by subsequent calls to
117 .BR getpwent (),
118 .BR getpwnam (3),
119 or
120 .BR getpwuid (3).
121 (Do not pass the returned pointer to
122 .BR free (3).)
123 .SH ERRORS
124 .TP
125 .B EINTR
126 A signal was caught; see
127 .BR signal (7).
128 .TP
129 .B EIO
130 I/O error.
131 .TP
132 .B EMFILE
133 The per-process limit on the number of open file descriptors has been reached.
134 .TP
135 .B ENFILE
136 The system-wide limit on the total number of open files has been reached.
137 .TP
138 .B ENOMEM
139 .\" not in POSIX
140 Insufficient memory to allocate
141 .I passwd
142 structure.
143 .\" to allocate the passwd structure, or to allocate buffers
144 .TP
145 .B ERANGE
146 Insufficient buffer space supplied.
147 .SH FILES
148 .TP
149 .I /etc/passwd
150 local password database file
151 .SH ATTRIBUTES
152 For an explanation of the terms used in this section, see
153 .BR attributes (7).
154 .TS
155 allbox;
156 lb lb lbx
157 l l l.
158 Interface Attribute Value
159 T{
160 .na
161 .nh
162 .BR getpwent ()
163 T} Thread safety T{
164 .na
165 .nh
166 MT-Unsafe race:pwent
167 race:pwentbuf locale
168 T}
169 T{
170 .na
171 .nh
172 .BR setpwent (),
173 .BR endpwent ()
174 T} Thread safety T{
175 .na
176 .nh
177 MT-Unsafe race:pwent locale
178 T}
179 .TE
180 .P
181 In the above table,
182 .I pwent
183 in
184 .I race:pwent
185 signifies that if any of the functions
186 .BR setpwent (),
187 .BR getpwent (),
188 or
189 .BR endpwent ()
190 are used in parallel in different threads of a program,
191 then data races could occur.
192 .SH VERSIONS
193 The
194 .I pw_gecos
195 field is not specified in POSIX, but is present on most implementations.
196 .SH STANDARDS
197 POSIX.1-2008.
198 .SH HISTORY
199 POSIX.1-2001, SVr4, 4.3BSD.
200 .SH SEE ALSO
201 .BR fgetpwent (3),
202 .BR getpw (3),
203 .BR getpwent_r (3),
204 .BR getpwnam (3),
205 .BR getpwuid (3),
206 .BR putpwent (3),
207 .\" Next line rejected upstream
208 .BR shadow (5),
209 .BR passwd (5)