1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>nsss: the nsss-unix library interface</title>
<meta name="Description" content="nsss: the nsss-unix library interface" />
<meta name="Keywords" content="NSS pwd group shadow library libnsss unix nsss-unix files /etc/passwd /etc/group /etc/shadow skarnet" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">libnsss</a><br />
<a href="../">nsss</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>nsss-unix</tt> library interface </h1>
<h2> General information </h2>
<p>
The <a href="//git.skarnet.org/cgi-bin/cgit.cgi/nsss/tree/src/include/nsss/nsss-unix.h">nsss/nsss-unix.h</a>
functions in libnsss provide a clean interface to get user/group data from the regular
<tt>/etc/passwd</tt>, <tt>/etc/group</tt> and <tt>/etc/shadow</tt> text files.
</p>
<p>
All the following functions take as their first argument a pointer to a handle
that has the <tt>nsss_unix_t</tt> type. This handle must be declared and
initialized to NSSS_UNIX_ZERO prior to any call. It can be declared in the stack.
</p>
<h2> Programming </h2>
<h4><code>int nsss_unix_pwd_start (nsss_unix_t *a)</code></h4>
<p>
Opens a session with <tt>/etc/passwd</tt>. <em>*a</em> must be
NSSS_UNIX_ZERO prior to the call. On error, returns 0, and sets errno.
On success, returns 1, and <em>*a</em> is a handle to an <tt>/etc/passwd</tt>
session. This function must be called <em>even for a non-enumeration lookup</em>.
</p>
<h4><code>int nsss_unix_pwd_maybe_start (nsss_unix_t *a)</code></h4>
<p>
Opens a session with <tt>/etc/passwd</tt> if it hasn't been opened yet.
On error, returns 0, and sets errno.
On success, returns 1, and <em>*a</em> is a handle to an <tt>/etc/passwd</tt>
session. Calling this function when <em>*a</em> is already opened to an
<tt>/etc/passwd</tt> session simply returns 1.
</p>
<h4><code>int nsss_unix_pwd_rewind (nsss_unix_t *a)</code></h4>
<p>
Performs a <tt>setpwent()</tt> operation on the current session.
Returns 1 on success, and 0 (and sets errno) on error.
</p>
<h4><code>void nsss_unix_pwd_end (nsss_unix_t *a)</code></h4>
<p>
Closes the current <tt>/etc/passwd</tt> session. After this
function returns, <em>*a</em> can be reused with another
<tt>nsss_unix_*_start()</tt> function.
</p>
<h4><code>int nsss_unix_pwd_getbyname (nsss_unix_t *a, struct passwd *pw, stralloc *sa, char const *name)</code></h4>
<p>
Performs a <tt>getpwnam(<em>name</em>)</tt> on the current, open,
<tt>/etc/passwd</tt> session. On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*pw</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings. If <em>name</em> is not found, the function returns 0
without changing errno.
</p>
<h4><code>int nsss_unix_pwd_getbyuid (nsss_unix_t *a, struct passwd *pw, stralloc *sa, uid_t uid)</code></h4>
<p>
Performs a <tt>getpwuid(<em>uid</em>)</tt> on the current, open,
<tt>/etc/passwd</tt> session. On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*pw</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings. If <em>uid</em> is not found, the function returns 0
without changing errno.
</p>
<h4><code>int nsss_unix_pwd_get (nsss_unix_t *a, struct passwd *pw, stralloc *sa)</code></h4>
<p>
Performs a <tt>getpwent()</tt> on the current, open,
<tt>/etc/passwd</tt> session (i.e. get the next entry in the file, as
part of an enumeration). On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*pw</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings. On EOF, the function returns 0 without changing errno.
</p>
<h4><code>int nsss_unix_grp_start (nsss_unix_t *a)</code></h4>
<p>
Opens a session with <tt>/etc/group</tt>. <em>*a</em> must be
NSSS_UNIX_ZERO prior to the call. On error, returns 0, and sets errno.
On success, returns 1, and <em>*a</em> is a handle to an <tt>/etc/group</tt>
session. This function must be called <em>even for a non-enumeration lookup</em>.
</p>
<h4><code>int nsss_unix_grp_maybe_start (nsss_unix_t *a)</code></h4>
<p>
Opens a session with <tt>/etc/group</tt> if it hasn't been opened yet.
On error, returns 0, and sets errno.
On success, returns 1, and <em>*a</em> is a handle to an <tt>/etc/group</tt>
session. Calling this function when <em>*a</em> is already opened to an
<tt>/etc/group</tt> session simply returns 1.
</p>
<h4><code>int nsss_unix_grp_rewind (nsss_unix_t *a)</code></h4>
<p>
Performs a <tt>setgrent()</tt> operation on the current session.
Returns 1 on success, and 0 (and sets errno) on error.
</p>
<h4><code>void nsss_unix_grp_end (nsss_unix_t *a)</code></h4>
<p>
Closes the current <tt>/etc/group</tt> session. After this
function returns, <em>*a</em> can be reused with another
<tt>nsss_unix_*_start()</tt> function.
</p>
<h4><code>int nsss_unix_grp_getbyname (nsss_unix_t *a, struct group *gr, stralloc *sa, genalloc *ga, char const *name)</code></h4>
<p>
Performs a <tt>getgrnam(<em>name</em>)</tt> on the current, open,
<tt>/etc/group</tt> session. On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*gr</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings, and the <em>*ga</em>
<a href="//skarnet.org/skalibs/libstddjb/genalloc.html">genalloc</a>,
which must be able to hold objects of type <tt>char *</tt>,
to store pointers for the <tt>gr->gr_mem</tt> field.
If <em>name</em> is not found, the function returns 0
without changing errno.
</p>
<h4><code>int nsss_unix_grp_getbygid (nsss_unix_t *a, struct group *gr, stralloc *sa, genalloc *ga, gid_t gid)</code></h4>
<p>
Performs a <tt>getgrgid(<em>gid</em>)</tt> on the current, open,
<tt>/etc/group</tt> session. On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*gr</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings, and the <em>*ga</em>
<a href="//skarnet.org/skalibs/libstddjb/genalloc.html">genalloc</a>,
which must be able to hold objects of type <tt>char *</tt>,
to store pointers for the <tt>gr->gr_mem</tt> field.
If <em>gid</em> is not found, the function returns 0
without changing errno.
</p>
<h4><code>int nsss_unix_grp_get (nsss_unix_t *a, struct group *gr, stralloc *sa, genalloc *ga)</code></h4>
<p>
Performs a <tt>getgrent()</tt> on the current, open,
<tt>/etc/group</tt> session (i.e. get the next entry in the file, as
part of an enumeration). On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*gr</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings, and the <em>*ga</em>
<a href="//skarnet.org/skalibs/libstddjb/genalloc.html">genalloc</a>,
which must be able to hold objects of type <tt>char *</tt>,
to store pointers for the <tt>gr->gr_mem</tt> field.
On EOF, the function returns 0 without changing errno.
</p>
<h4><code>int nsss_unix_shadow_start (nsss_unix_t *a)</code></h4>
<p>
Opens a session with <tt>/etc/shadow</tt>. <em>*a</em> must be
NSSS_UNIX_ZERO prior to the call. On error, returns 0, and sets errno.
On success, returns 1, and <em>*a</em> is a handle to an <tt>/etc/shadow</tt>
session. This function must be called <em>even for a non-enumeration lookup</em>.
</p>
<h4><code>int nsss_unix_shadow_maybe_start (nsss_unix_t *a)</code></h4>
<p>
Opens a session with <tt>/etc/shadow</tt> if it hasn't been opened yet.
On error, returns 0, and sets errno.
On success, returns 1, and <em>*a</em> is a handle to an <tt>/etc/shadow</tt>
session. Calling this function when <em>*a</em> is already opened to an
<tt>/etc/shadow</tt> session simply returns 1.
</p>
<h4><code>int nsss_unix_shadow_rewind (nsss_unix_t *a)</code></h4>
<p>
Performs a <tt>setspent()</tt> operation on the current session.
Returns 1 on success, and 0 (and sets errno) on error.
</p>
<h4><code>void nsss_unix_shadow_end (nsss_unix_t *a)</code></h4>
<p>
Closes the current <tt>/etc/shadow</tt> session. After this
function returns, <em>*a</em> can be reused with another
<tt>nsss_unix_*_start()</tt> function.
</p>
<h4><code>int nsss_unix_shadow_getbyname (nsss_unix_t *a, struct spwd *sp, stralloc *sa, char const *name)</code></h4>
<p>
Performs a <tt>getspnam(<em>name</em>)</tt> on the current, open,
<tt>/etc/shadow</tt> session. On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*sp</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings. If <em>name</em> is not found, the function returns 0
without changing errno.
</p>
<h4><code>int nsss_unix_shadow_get (nsss_unix_t *a, struct spwd *sp, stralloc *sa)</code></h4>
<p>
Performs a <tt>getspent()</tt> on the current, open,
<tt>/etc/shadow</tt> session (i.e. get the next entry in the file, as
part of an enumeration). On error, returns 0 and sets errno.
On success, returns 1, and stores the result into <em>*sp</em>,
using the <em>*sa</em>
<a href="//skarnet.org/skalibs/libstddjb/stralloc.html">stralloc</a> to
store strings. On EOF, the function returns 0 without changing errno.
</p>
</body>
</html>
|
