1getspnam(3C)             Standard C Library Functions             getspnam(3C)
2
3
4

NAME

6       getspnam,  getspnam_r,  getspent, getspent_r, setspent, endspent, fget‐
7       spent, fgetspent_r - get password entry
8

SYNOPSIS

10       #include <shadow.h>
11
12       struct spwd *getspnam(const char *name);
13
14
15       struct spwd *getspnam_r(const char *name, struct spwd *result,
16            char *buffer, int buflen);
17
18
19       struct spwd *getspent(void);
20
21
22       struct spwd *getspent_r(struct spwd *result, char *buffer,
23            int buflen);
24
25
26       void setspent(void);
27
28
29       void endspent(void);
30
31
32       struct spwd *fgetspent(FILE *fp);
33
34
35       struct spwd *fgetspent_r(FILE *fp, struct spwd *result,
36            char *buffer, int buflen);
37
38

DESCRIPTION

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
44
45       The getspnam() function searches for a shadow password entry  with  the
46       login name specified by the character string argument name.
47
48
49       The   setspent(), getspent(), and endspent() functions are used to enu‐
50       merate shadow password entries from the database.
51
52
53       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
58
59       Successive  calls  to  getspent()  return  either successive entries or
60       NULL, indicating the end of the enumeration.
61
62
63       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
70
71       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
76   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
82
83       The   getspnam_r(),  getspent_r(),  and fgetspent_r() functions provide
84       reentrant interfaces for these operations.
85
86
87       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
93
94       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
106
107       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
114
115       Like its non-reentrant counterpart, getspnam_r() leaves the enumeration
116       position in an indeterminate state.
117

RETURN VALUES

119       Password entries are represented by the struct spwd  structure  defined
120       in <shadow.h>:
121
122         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
134
135
136       See shadow(4) for more information on the interpretation of this data.
137
138
139       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
143
144       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
149
150       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
154
155       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

ERRORS

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

ATTRIBUTES

167       See attributes(5) for descriptions of the following attributes:
168
169
170
171
172       ┌─────────────────────────────┬─────────────────────────────┐
173       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
174       ├─────────────────────────────┼─────────────────────────────┤
175       │MT-Level                     │See "Reentrant  Interfaces"  │
176       │                             │in DESCRIPTION.              │
177       └─────────────────────────────┴─────────────────────────────┘
178

SEE ALSO

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

WARNINGS

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

NOTES

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
193
194       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
200
201       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
207
208       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
211
212       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
218
219       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.
226
227
228
229SunOS 5.11                        23 Jan 2008                     getspnam(3C)
Impressum