1getspnam(3C) Standard C Library Functions getspnam(3C)
2
6 getspnam, getspnam_r, getspent, getspent_r, setspent, endspent, fget‐
7 spent, fgetspent_r - get password entry
8
10 #include <shadow.h>
11 struct spwd *getspnam(const char *name);
13 struct spwd *getspnam_r(const char *name, struct spwd *result,
16 char *buffer, int buflen);
17 struct spwd *getspent(void);
20 struct spwd *getspent_r(struct spwd *result, char *buffer,
23 int buflen);
24 void setspent(void);
27 void endspent(void);
30 struct spwd *fgetspent(FILE *fp);
33 struct spwd *fgetspent_r(FILE *fp, struct spwd *result,
36 char *buffer, int buflen);
37
40 These functions are used to obtain shadow password entries. An entry
41 may come from any of the sources for shadow specified in the /etc/nss‐
42 witch.conf file (see nsswitch.conf(4)).
43 The getspnam() function searches for a shadow password entry with the
46 login name specified by the character string argument name.
47 The setspent(), getspent(), and endspent() functions are used to enu‐
50 merate shadow password entries from the database.
51 The setspent() function sets (or resets) the enumeration to the begin‐
54 ning of the set of shadow password entries. This function should be
55 called before the first call to getspent(). Calls to getspnam() leave
56 the enumeration position in an indeterminate state.
57 Successive calls to getspent() return either successive entries or
60 NULL, indicating the end of the enumeration.
61 The endspent() function may be called to indicate that the caller
64 expects to do no further shadow password retrieval operations; the sys‐
65 tem may then close the shadow password file, deallocate resources it
66 was using, and so forth. It is still allowed, but possibly less effi‐
67 cient, for the process to call more shadow password functions after
68 calling endspent().
69 The fgetspent() function, unlike the other functions above, does not
72 use nsswitch.conf; it reads and parses the next line from the stream
73 fp, which is assumed to have the format of the shadow file (see
74 shadow(4)).
75 Reentrant Interfaces
77 The getspnam(), getspent(), and fgetspent() functions use thread-spe‐
78 cific data storage that is reused in each call to one of these func‐
79 tions by the same thread, making them safe to use but not recommended
80 for multithreaded applications.
81 The getspnam_r(), getspent_r(), and fgetspent_r() functions provide
84 reentrant interfaces for these operations.
85 Each reentrant interface performs the same operation as its non-reen‐
88 trant counterpart, named by removing the _r suffix. The reentrant
89 interfaces, however, use buffers supplied by the caller to store
90 returned results, and are safe for use in both single-threaded and
91 multithreaded applications.
92 Each reentrant interface takes the same argument as its non-reentrant
95 counterpart, as well as the following additional arguments. The result
96 argument must be a pointer to a struct spwd structure allocated by the
97 caller. On successful completion, the function returns the shadow
98 password entry in this structure. The buffer argument must be a
99 pointer to a buffer supplied by the caller. This buffer is used as
100 storage space for the shadow password data. All of the pointers within
101 the returned struct spwd result point to data stored within this buffer
102 (see RETURN VALUES). The buffer must be large enough to hold all of the
103 data associated with the shadow password entry. The buflen argument
104 should give the size in bytes of the buffer indicated by buffer.
105 For enumeration in multithreaded applications, the position within the
108 enumeration is a process-wide property shared by all threads. The set‐
109 spent() function may be used in a multithreaded application but resets
110 the enumeration position for all threads. If multiple threads inter‐
111 leave calls to getspent_r(), the threads will enumerate disjoint sub‐
112 sets of the shadow password database.
113 Like its non-reentrant counterpart, getspnam_r() leaves the enumeration
116 position in an indeterminate state.
117
119 Password entries are represented by the struct spwd structure defined
120 in <shadow.h>:
121 struct spwd{
123 char *sp_namp; /* login name */
124 char *sp_pwdp; /* encrypted passwd */
125 int sp_lstchg; /* date of last change */
126 int sp_min; /* min days to passwd change */
127 int sp_max; /* max days to passwd change*/
128 int sp_warn; /* warning period */
129 int sp_inact; /* max days inactive */
130 int sp_expire; /* account expiry date */
131 unsigned int sp_flag; /* not used */
132 };
133 See shadow(4) for more information on the interpretation of this data.
137 The getspnam()and getspnam_r() functions each return a pointer to a
140 struct spwd if they successfully locate the requested entry; otherwise
141 they return NULL.
142 The getspent(), getspent_r(), fgetspent(), and fgetspent() functions
145 each return a pointer to a struct spwd if they successfully enumerate
146 an entry; otherwise they return NULL, indicating the end of the enumer‐
147 ation.
148 The getspnam(), getspent(), and fgetspent() functions use thread-spe‐
151 cific data storage, so returned data must be copied before a subsequent
152 call to any of these functions if the data is to be saved.
153 When the pointer returned by the reentrant functions getspnam_r(), get‐
156 spent_r(), and fgetspent_r() is non-null, it is always equal to the
157 result pointer that was supplied by the caller.
158
160 The reentrant functions getspnam_r(), getspent_r(), and fgetspent_r()
161 will return NULL and set errno to ERANGE if the length of the buffer
162 supplied by caller is not large enough to store the result. See
163 Intro(2) for the proper usage and interpretation of errno in multi‐
164 threaded applications.
165
167 See attributes(5) for descriptions of the following attributes:
168 ┌─────────────────────────────┬─────────────────────────────┐
173 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
174 ├─────────────────────────────┼─────────────────────────────┤
175 │MT-Level │See "Reentrant Interfaces" │
176 │ │in DESCRIPTION. │
177 └─────────────────────────────┴─────────────────────────────┘
178
180 nispasswd(1), passwd(1), yppasswd(1), Intro(3), getlogin(3C), getpw‐
181 nam(3C), nsswitch.conf(4), passwd(4), shadow(4), attributes(5)
182
184 The reentrant interfaces getspnam_r(), getspent_r(), and fgetspent_r()
185 are included in this release on an uncommitted basis only, and are sub‐
186 ject to change or removal in future minor releases.
187
189 When compiling multithreaded applications, see Intro(3), Notes On Mul‐
190 tithreaded Applications, for information about the use of the _REEN‐
191 TRANT flag.
192 Use of the enumeration interfaces getspent() and getspent_r() is not
195 recommended; enumeration is supported for the shadow file, NIS, and
196 NIS+, but in general is not efficient and may not be supported for all
197 database sources. The semantics of enumeration are discussed further
198 in nsswitch.conf(4).
199 Access to shadow password information may be restricted in a manner
202 depending on the database source being used. Access to the /etc/shadow
203 file is generally restricted to processes running with the effective
204 uid of the file owner or the {PRIV_FILE_DAC_READ} privilege. Other
205 database sources may impose stronger or less stringent restrictions.
206 Empty fields in the database source return -1 values for all fields
209 except sp_pwdp and sp_flag, where the value returned is 0.
210 When NIS is used as the database source, the information for the
213 shadow password entries is obtained from the ``passwd.byname'' map.
214 This map stores only the information for the sp_namp and sp_pwdp fields
215 of the struct spwd structure. Shadow password entries obtained from NIS
216 will contain the value -1 in the remainder of the fields.
217 When NIS+ is used as the database source, and the caller lacks the per‐
220 mission needed to retrieve the encrypted password from the NIS+
221 ``passwd.org_dir'' table, the NIS+ service returns the string ``*NP*''
222 instead of the actual encrypted password string. The functions
223 described on this page will then return the string ``*NP*'' to the
224 caller as the value of the member sp_pwdp in the returned shadow pass‐
225 word structure.
226SunOS 5.11 23 Jan 2008 getspnam(3C)