Debian Codegraph @

upstream/debian-unstable/man3/getpwent.3

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