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
|
<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-switch library interface</title>
<meta name="Description" content="nsss: the nsss-switch library interface" />
<meta name="Keywords" content="NSS pwd group shadow library libnsss switch nsss-switch client server nsssd backend connection socket 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-switch</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-switch.h">nsss/nsss-switch.h</a>
functions in libnsss provide a clean interface to get user/group data from a
<em>nsss daemon</em>, for instance one implemented via
<a href="../nsssd-unix.html">nsssd-unix</a> or
<a href="../nsssd-nslcd.html">nsssd-nslcd</a>. They are the C client library
to such a daemon.
</p>
<p>
Most of the following functions take, in addition to their obvious arguments,
a <em>tain_t const *</em> argument conventionally named <em>deadline</em> and
a <em>tain_t *</em> argument conventionally named <em>stamp</em>. These two
arguments are there to ensure that the function, which connects to another
process in an otherwise synchronous manner, does not block forever. How to
use these arguments is explained, for instance,
<a href="//skarnet.org/s6/libs6/ftrigr.html#synctimed">here</a>.
A function <em>foobar</em> also has a version named <em>foobar_g</em> that
only takes the <em>deadline</em> argument, assuming the current timestamp
is held in the STAMP global variable.
</p>
<p>
All the functions take as their first argument a pointer to a handle
that has the <tt>nsss_switch_t</tt> type. This handle must be declared and
initialized to NSSS_SWITCH_ZERO prior to any call. It can be declared in the stack.
</p>
<h2> Programming </h2>
<h4><code>int nsss_switch_start (nsss_switch_t *a, unsigned int what, char const *path, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Opens a session with a nsss daemon listening to a Unix domain socket
located at <em>path</em>. <em>*a</em> must be
NSSS_SWITCH_ZERO prior to the call. The nature of the session depends on
the <em>what</em> argument, which should be one of NSSS_SWITCH_PWD,
NSSS_SWITCH_GRP or NSSS_SWITCH_SHADOW depending on whether subsequent
requests will query the user, group or shadow database.
On error, the function returns 0, and sets errno.
On success, it returns 1, and <em>*a</em> is a handle to a session with
the nsssd daemon. This function must be called for every batch of
communication with a nsssd service, not only for enumerations.
</p>
<h4><code>void nsss_switch_end (nsss_switch_t *a, unsigned int what)</code></h4>
<p>
Closes the current session. The <em>what</em> argument must be the same one
that has been given to <tt>nsss_switch_start</tt>. After this function returns,
<em>*a</em> can be reused.
</p>
<h4><code>int nsss_switch_pwd_rewind (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>setpwent()</tt> operation on the current session.
Returns 1 on success, and 0 (and sets errno) on error.
</p>
<h4><code>int nsss_switch_pwd_end (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>endpwent()</tt> operation on the current session,
i.e. ends an enumeration. Returns 1 on success, and 0 (and sets errno)
on error.
</p>
<h4><code>int nsss_switch_pwd_getbyname (nsss_switch_t *a, struct passwd *pw, stralloc *sa, char const *name, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>getpwnam(<em>name</em>)</tt> on the current 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_switch_pwd_getbyuid (nsss_switch_t *a, struct passwd *pw, stralloc *sa, uid_t uid, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>getpwuid(<em>uid</em>)</tt> on the current 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_switch_pwd_get (nsss_switch_t *a, struct passwd *pw, stralloc *sa, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a a <tt>getpwent()</tt> on the current session,
i.e. get the next entry 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_switch_grp_rewind (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of 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_switch_grp_end (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>endgrent()</tt> operation on the current session,
i.e. ends an enumeration. Returns 1 on success, and 0 (and sets errno)
on error.
</p>
<h4><code>int nsss_switch_grp_getbyname (nsss_switch_t *a, struct group *gr, stralloc *sa, genalloc *ga, char const *name, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a a <tt>getgrnam(<em>name</em>)</tt> on the current 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_switch_grp_getbygid (nsss_switch_t *a, struct group *gr, stralloc *sa, genalloc *ga, gid_t gid, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>getgrgid(<em>gid</em>)</tt> on the current 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_switch_grp_get (nsss_switch_t *a, struct group *gr, stralloc *sa, genalloc *ga, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>getgrent()</tt> on the current session,
i.e. get the next entry 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_switch_shadow_rewind (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>setspent()</tt> operation on the current session.
Returns 1 on success, and 0 (and sets errno) on error.
</p>
<h4><code>int nsss_switch_shadow_end (nsss_switch_t *a, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>endspent()</tt> operation on the current session,
i.e. ends an enumeration. Returns 1 on success, and 0 (and sets errno)
on error.
</p>
<h4><code>int nsss_switch_shadow_getbyname (nsss_switch_t *a, struct spwd *sp, stralloc *sa, char const *name, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>getspnam(<em>name</em>)</tt> on the current 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_switch_shadow_get (nsss_switch_t *a, struct spwd *sp, stralloc *sa, tain_t const *deadline, tain_t *stamp)</code></h4>
<p>
Performs the equivalent of a <tt>getspent()</tt> on the current session,
i.e. get the next entry 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>
|
