]>
Commit | Line | Data |
---|---|---|
706074a5 UD |
1 | @c each section should have index entries corresponding to the section title |
2 | ||
3 | @node Name Service Switch | |
4 | @chapter System Databases and Name Service Switch | |
5 | ||
2c6fe0bd UD |
6 | @cindex Name Service Switch |
7 | @cindex NSS | |
8 | @cindex databses | |
706074a5 UD |
9 | Various functions in the C Library need to be configured to work |
10 | correctly in the local environment. Traditionally, this was done by | |
11 | using files (e.g., @file{/etc/passwd}), but other nameservices (line the | |
12 | Network Information Service (NIS) and the Domain Name Service (DNS)) | |
13 | became popular, and were hacked into the C library, usually with a fixed | |
84384f5b | 14 | search order (@pxref{frobnicate, , ,jargon, The Jargon File}). |
706074a5 UD |
15 | |
16 | The GNU C Library contains a cleaner solution of this problem. It is | |
17 | designed after a method used by Sun Microsystems in the C library of | |
18 | @w{Solaris 2}. GNU C Library follows their name and calls this | |
19 | scheme @dfn{Name Service Switch} (NSS). | |
20 | ||
21 | Though the interface might be similar to Sun's version there is no | |
22 | common code. We never saw any source code of Sun's implementation and | |
2de99474 | 23 | so the internal interface is incompatible. This is also manifests in the |
706074a5 UD |
24 | file names we use as we will see later. |
25 | ||
26 | ||
27 | @menu | |
28 | * NSS Basics:: What is this NSS good for. | |
29 | * NSS Configuration File:: Configuring NSS. | |
30 | * NSS Module Internals:: How does it work internally. | |
31 | * Extending NSS:: What to do to add services or databases. | |
32 | @end menu | |
33 | ||
34 | @node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch | |
35 | @section NSS Basics | |
36 | ||
37 | The basic idea is to put the implementation of the different services | |
38 | offered to access the databases in separate modules. This has some | |
39 | advantages: | |
40 | ||
41 | @enumerate | |
42 | @item | |
43 | Contributors can add new services without adding them to GNU C Library. | |
44 | @item | |
45 | The modules can be updated separately. | |
46 | @item | |
47 | The C library image is smaller. | |
48 | @end enumerate | |
49 | ||
50 | To fulfill the first goal above the ABI of the modules will be described | |
51 | below. For getting the implementation of a new service right it is | |
52 | important to understand how the functions in the modules get called. | |
53 | They are in no way designed to be used by the programmer directly. | |
54 | Instead the programmer should only use the documented and standardized | |
55 | functions to access the databases. | |
56 | ||
57 | @noindent | |
58 | The databases available in the NSS are | |
59 | ||
60 | @cindex ethers | |
61 | @cindex group | |
62 | @cindex hosts | |
ba1ffaa1 | 63 | @cindex netgroup |
706074a5 UD |
64 | @cindex network |
65 | @cindex protocols | |
66 | @cindex passwd | |
67 | @cindex rpc | |
68 | @cindex services | |
69 | @cindex shadow | |
70 | @vtable @code | |
71 | @item ethers | |
72 | Ethernet numbers, | |
73 | @comment @pxref{Ethernet Numbers}. | |
74 | @item group | |
75 | Groups of users, @pxref{Group Database}. | |
76 | @item hosts | |
77 | Host names and numbers, @pxref{Host Names}. | |
ba1ffaa1 UD |
78 | @item netgroup |
79 | Network wide list of host and users, @pxref{Netgroup Database}. | |
706074a5 UD |
80 | @item network |
81 | Network names and numbers, @pxref{Networks Database}. | |
82 | @item protocols | |
83 | Network protocols, @pxref{Protocols Database}. | |
84 | @item passwd | |
85 | User passwords, @pxref{User Database}. | |
86 | @item rpc | |
87 | Remote procedure call names and numbers, | |
88 | @comment @pxref{RPC Database}. | |
89 | @item services | |
90 | Network services, @pxref{Services Database}. | |
91 | @item shadow | |
92 | Shadow user passwords, | |
93 | @comment @pxref{Shadow Password Database}. | |
94 | @end vtable | |
95 | ||
96 | @noindent | |
97 | There will be some more added later (@code{aliases}, @code{automount}, | |
ba1ffaa1 | 98 | @code{bootparams}, @code{netmasks}, and @code{publickey}). |
706074a5 UD |
99 | |
100 | @node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch | |
101 | @section The NSS Configuration File | |
102 | ||
103 | @cindex @file{/etc/nsswitch.conf} | |
104 | @cindex @file{nsswitch.conf} | |
105 | Somehow the NSS code must be told about the wishes of the user. For | |
106 | this reason there is the file @file{/etc/nsswitch.conf}. For each | |
107 | database this file contain a specification how the lookup process should | |
108 | work. The file could look like this: | |
109 | ||
110 | @example | |
111 | @include nsswitch.texi | |
112 | @end example | |
113 | ||
114 | The first column is the database as you can guess from the table above. | |
115 | The rest of the line specifies how the lookup process works. Please | |
116 | note that you specify the way it works for each database individually. | |
117 | This cannot be done with the old way of a monolithic implementation. | |
118 | ||
119 | The configuration specification for each database can contain two | |
120 | different items: | |
121 | ||
122 | @itemize @bullet | |
123 | @item | |
124 | the service specification like @code{files}, @code{db}, or @code{nis}. | |
125 | @item | |
126 | the reaction on lookup result line @code{[NOTFOUND=return]}. | |
127 | @end itemize | |
128 | ||
129 | @menu | |
ba1ffaa1 | 130 | * Services in the NSS configuration:: Service names in the NSS configuration. |
706074a5 UD |
131 | * Actions in the NSS configuration:: React approprite on the lookup result. |
132 | * Notes on NSS Configuration File:: Things to take care about while | |
133 | configuring NSS. | |
134 | @end menu | |
135 | ||
136 | @node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File | |
137 | @subsection Services in the NSS configuration File | |
138 | ||
139 | The above example file mentions four different services: @code{files}, | |
140 | @code{db}, @code{nis}, and @code{nisplus}. This does not mean these | |
141 | services are available on all sites and it does also not mean these are | |
142 | all the services which will ever be available. | |
143 | ||
144 | In fact, these names are simply strings which the NSS code uses to find | |
145 | the implicitly addressed functions. The internal interface will be | |
146 | described later. Visible to the user are the modules which implement an | |
147 | individual service. | |
148 | ||
149 | Assume the service @var{name} shall be used for a lookup. The code for | |
150 | this service is implemented in a module called @file{libnss_@var{name}}. | |
151 | On a system supporting shared libraries this is in fact a shared library | |
152 | with the name (for example) @file{libnss_@var{name}.so.1}. The number | |
153 | at the end is the currently used version of the interface which will not | |
154 | change frequently. Normally the user should not have to be cognizant of | |
155 | these files since they should be placed in a directory where they are | |
156 | found automatically. Only the names of all available services are | |
157 | important. | |
158 | ||
159 | @node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File | |
160 | @subsection Actions in the NSS configuration | |
161 | ||
162 | The second item in the specification gives the user much finer control | |
163 | on the lookup process. Action items are placed between two service | |
164 | names and are written within brackets. The general form is | |
165 | ||
2de99474 | 166 | @display |
57ba7bb4 | 167 | @code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]} |
2de99474 | 168 | @end display |
706074a5 UD |
169 | |
170 | @noindent | |
171 | where | |
172 | ||
173 | @smallexample | |
174 | @var{status} @result{} success | notfound | unavail | tryagain | |
175 | @var{action} @result{} return | continue | |
176 | @end smallexample | |
177 | ||
178 | The case of the keywords is insignificant. The @var{status} | |
179 | values are the results of a call to a lookup function of a specific | |
180 | service. They mean | |
181 | ||
182 | @ftable @samp | |
183 | @item success | |
184 | No error occured an the wanted entry is returned. The default action | |
185 | for this is @code{return}. | |
186 | ||
187 | @item notfound | |
188 | The lookup process works ok but the needed value was not found. The | |
189 | default action is @code{continue}. | |
190 | ||
191 | @item unavail | |
192 | @cindex DNS server unavailable | |
193 | The service is permanently unavailable. This can either mean the needed | |
194 | file is not available, or, for DNS, the server is not available or does | |
195 | not allow queries. The default action is @code{continue}. | |
196 | ||
197 | @item tryagain | |
198 | The service is temporarily unavailable. This could mean a file is | |
199 | locked or a server currently cannot accept more connections. The | |
200 | default action is @code{continue}. | |
201 | @end ftable | |
202 | ||
203 | @noindent | |
204 | If we have a line like | |
205 | ||
206 | @smallexample | |
207 | ethers: nisplus [NOTFOUND=return] db files | |
208 | @end smallexample | |
209 | ||
210 | @noindent | |
211 | this is equivalent to | |
212 | ||
213 | @smallexample | |
214 | ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue | |
215 | TRYAGAIN=continue] | |
216 | db [SUCCESS=return NOTFOUND=continue UNAVAIL=continue | |
217 | TRYAGAIN=continue] | |
218 | files | |
219 | @end smallexample | |
220 | ||
221 | @noindent | |
222 | (except that it would have to be written on one line). The default | |
223 | value for the actions are normally what you want, and only need to be | |
224 | changed in exceptional cases. | |
225 | ||
226 | If the optional @code{!} is placed before the @var{status} this means | |
227 | the following action is used for all statii but @var{status} itself. | |
228 | I.e., @code{!} is negation as in the C language (and others). | |
229 | ||
230 | Before we explain the exception which makes this action item necessary | |
231 | one more remark: obviously it makes no sense to add another action | |
232 | item after the @code{files} service. Since there is no other service | |
233 | following the action @emph{always} is @code{return}. | |
234 | ||
235 | @cindex nisplus, and completeness | |
236 | Now, why is this @code{[NOTFOUND=return]} action useful? To understand | |
237 | this we should know that the @code{nisplus} service is often | |
238 | complete; i.e., if an entry is not available in the NIS+ tables it is | |
239 | not available anywhere else. This is what is expressed by this action | |
240 | item: it is useless to examine further services since they will not give | |
241 | us a result. | |
242 | ||
243 | @cindex nisplus, and booting | |
244 | @cindex bootstrapping, and services | |
245 | The situation would be different if the NIS+ service is not available | |
246 | because the machine is booting. In this case the return value of the | |
247 | lookup function is not @code{notfound} but instead @code{unavail}. And | |
248 | as you can see in the complete form above: in this situation the | |
249 | @code{db} and @code{files} services are used. Neat, isn't it? The | |
250 | system administrator need not pay special care for the time the system | |
251 | is not completely ready to work (while booting or shutdown or | |
252 | network problems). | |
253 | ||
254 | ||
255 | @node Notes on NSS Configuration File, , Actions in the NSS configuration, NSS Configuration File | |
256 | @subsection Notes on the NSS Configuration File | |
257 | ||
258 | Finally a few more hints. The NSS implementation is not completely | |
259 | helpless if @file{/etc/nsswitch.conf} does not exist. For | |
260 | all supported databases there is a default value so it should normally | |
261 | be possible to get the system running even if the file is corrupted or | |
262 | missing. | |
263 | ||
ba1ffaa1 UD |
264 | @cindex default value, and NSS |
265 | For the @code{hosts} and @code{network} databases the default value is | |
266 | @code{dns [!UNAVAIL=return] files}. I.e., the system is prepared for | |
267 | the DNS service not to be available but if it is available the answer it | |
268 | returns is ultimative. | |
269 | ||
270 | For all other databases the default value is | |
271 | @code{compat [NOTFOUND=return] files}. This solution give the best | |
272 | chance to be correct since NIS and file based lookup is used. The | |
273 | @code{compat} service is available in a separate add-on to GNU C | |
274 | library, available in the same place you got the GNU C library source | |
275 | from. | |
276 | ||
277 | @cindex optimizing NSS | |
706074a5 UD |
278 | A second point is that the user should try to optimize the lookup |
279 | process. The different service have different response times. A simple | |
280 | file look up on a local file could be fast, but if the file is long and the | |
281 | needed entry is near the end of the file this may take quite some time. | |
282 | In this case it might be better to use the @code{db} service which | |
283 | allows fast local access to large data sets. | |
284 | ||
285 | Often the situation is that some global information like NIS must be | |
286 | used. So it is unavoidable to use service entries like @code{nis} etc. | |
287 | But one should avoid slow services like this if possible. | |
288 | ||
289 | ||
290 | @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch | |
291 | @section NSS Module Internals | |
292 | ||
293 | Now it is time to described how the modules look like. The functions | |
294 | contained in a module are identified by their names. I.e., there is no | |
295 | jump table or the like. How this is done is of no interest here; those | |
296 | interested in this topic should read about Dynamic Linking. | |
297 | @comment @ref{Dynamic Linking}. | |
298 | ||
299 | ||
300 | @menu | |
301 | * NSS Module Names:: Construction of the interface function of | |
302 | the NSS modules. | |
303 | * NSS Modules Interface:: Programming interface in the NSS module | |
304 | functions. | |
305 | @end menu | |
306 | ||
307 | @node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals | |
308 | @subsection The Naming Scheme of the NSS Modules | |
309 | ||
310 | @noindent | |
311 | The name of each function consist of various parts: | |
312 | ||
313 | @quotation | |
314 | _nss_@var{service}_@var{function} | |
315 | @end quotation | |
316 | ||
317 | @var{service} of course corresponds to the name of the module this | |
318 | function is found in.@footnote{Now you might ask why to duplicate this | |
319 | information. The answer is that we want to keep the possibility to link | |
320 | directly with these shared objects.} The @var{function} part is derived | |
321 | from the interface function in the C library itself. If the user calls | |
322 | the function @code{gethostbyname} and the service used is @code{files} | |
323 | the function | |
324 | ||
325 | @smallexample | |
326 | _nss_files_gethostbyname_r | |
327 | @end smallexample | |
328 | ||
329 | @noindent | |
330 | in the module | |
331 | ||
332 | @smallexample | |
333 | libnss_files.so.1 | |
334 | @end smallexample | |
335 | ||
336 | @noindent | |
337 | @cindex reentrant NSS functions | |
338 | is used. You see, what is explained above in not the whole truth. In | |
339 | fact the NSS modules only contain reentrant versions of the lookup | |
340 | functions. I.e., if the user would call the @code{gethostbyname_r} | |
341 | function this also would end in the above function. For all user | |
342 | interface functions the C library maps this call to a call to the | |
343 | reentrant function. For reentrant functions this is trivial since the | |
344 | interface is (nearly) the same. For the non-reentrant version pointers | |
345 | to static buffers are used to replace the user supplied buffers. | |
346 | ||
347 | I.e., the reentrant functions @emph{can} have counterparts. No service | |
348 | module is forced to have functions for all databases and all kinds to | |
349 | access them. If a function is not available it is simply treated as if | |
350 | the function would return @code{unavail} | |
351 | (@pxref{Actions in the NSS configuration}). | |
352 | ||
2de99474 UD |
353 | The file name @file{libnss_files.so.1} would be on a @w{Solaris 2} |
354 | system @file{nss_files.so.1}. This is the difference mentioned above. | |
355 | Sun's NSS modules are usable as modules which get indirectly loaded | |
356 | only. | |
357 | ||
358 | The NSS modules in the GNU C Library are prepared to be used as normal | |
359 | libraries itself. | |
360 | @comment Fix me if necessary. | |
361 | This is @emph{not} true in the moment, though. But the different | |
362 | organization of the name space in the modules does not make it | |
363 | impossible like it is for Solaris. Now you can see why the modules are | |
364 | still libraries.@footnote{There is a second explanation: we were too | |
365 | lazy to change the Makefiles to allow the generation of shared objects | |
366 | not starting with @file{lib} but do not tell this anybody.} | |
367 | ||
706074a5 UD |
368 | |
369 | @node NSS Modules Interface, , NSS Module Names, NSS Module Internals | |
370 | @subsection The Interface of the Function in NSS Modules | |
371 | ||
372 | Now we know about the functions contained in the modules. It is now | |
373 | time to describe the types. When we mentioned the reentrant versions of | |
374 | the functions above, this means there are some additional arguments | |
375 | (compared with the standard, non-reentrant version). The prototypes for | |
376 | the non-reentrant and reentrant versions of our function above are: | |
377 | ||
378 | @smallexample | |
379 | struct hostent *gethostbyname (const char *name) | |
380 | ||
381 | struct hostent *gethostbyname_r (const char *name, | |
382 | struct hostent *result_buf, char *buf, | |
383 | int buflen, int *h_errnop) | |
384 | @end smallexample | |
385 | ||
386 | @noindent | |
ba1ffaa1 | 387 | The actual prototype of the function in the NSS modules in this case is |
706074a5 UD |
388 | |
389 | @smallexample | |
ba1ffaa1 UD |
390 | enum nss_status _nss_files_gethostbyname_r (const char *name, |
391 | struct hostent *result_buf, | |
392 | char *buf, int buflen, | |
393 | int *h_errnop) | |
706074a5 UD |
394 | @end smallexample |
395 | ||
ba1ffaa1 UD |
396 | I.e., the interface function is in fact the reentrant function with the |
397 | change of the return value. While the user-level function returns a | |
398 | pointer to the result the reentrant function return an @code{enum | |
399 | nss_status} value: | |
706074a5 | 400 | |
2c6fe0bd UD |
401 | @vindex NSS_STATUS_TRYAGAIN |
402 | @vindex NSS_STATUS_UNAVAIL | |
403 | @vindex NSS_STATUS_NOTFOUND | |
404 | @vindex NSS_STATUS_SUCCESS | |
706074a5 UD |
405 | @ftable @code |
406 | @item NSS_STATUS_TRYAGAIN | |
407 | numeric value @code{-2} | |
408 | ||
409 | @item NSS_STATUS_UNAVAIL | |
410 | numeric value @code{-1} | |
411 | ||
412 | @item NSS_STATUS_NOTFOUND | |
413 | numeric value @code{0} | |
414 | ||
415 | @item NSS_STATUS_SUCCESS | |
416 | numeric value @code{1} | |
417 | @end ftable | |
418 | ||
419 | @noindent | |
420 | Now you see where the action items of the @file{/etc/nsswitch.conf} file | |
421 | are used. | |
422 | ||
ba1ffaa1 UD |
423 | If you study the source code you will find there is a fifth value: |
424 | @code{NSS_STATUS_RETURN}. This is an internal use only value, used by a | |
425 | few functions in places where none of the above value can be used. If | |
426 | necessary the source code should be examined to learn about the details. | |
427 | ||
428 | The above function has something special which is missing for almost all | |
706074a5 UD |
429 | the other module functions. There is an argument @var{h_errnop}. This |
430 | points to a variable which will be filled with the error code in case | |
431 | the execution of the function fails for some reason. The reentrant | |
432 | function cannot use the global variable @var{h_errno}; | |
433 | @code{gethostbyname} calls @code{gethostbyname_r} with the | |
434 | last argument set to @code{&h_errno}. | |
435 | ||
436 | The @code{get@var{XXX}by@var{YYY}} functions are the most important | |
437 | functions in the NSS modules. But there are others which implement | |
438 | the other ways to access system databases (say for the | |
439 | password database, there are @code{setpwent}, @code{getpwent}, and | |
440 | @code{endpwent}). These will be described in more detail later. | |
441 | Here we give a general way to determine the | |
442 | signature of the module function: | |
443 | ||
444 | @itemize @bullet | |
445 | @item | |
446 | the return value is @code{int}; | |
447 | @item | |
448 | the name is as explain in @pxref{NSS Module Names}; | |
449 | @item | |
450 | the first arguments are identical to the arguments of the non-reentrant | |
451 | function; | |
452 | @item | |
453 | the next three arguments are: | |
454 | ||
455 | @table @code | |
456 | @item STRUCT_TYPE result_buf | |
457 | pointer to buffer where the result is stored. @code{STRUCT_TYPE} is | |
458 | normally a struct which corresponds to the database. | |
459 | @item char *buffer | |
460 | pointer to a buffer where the function can store additional adata for | |
461 | the result etc. | |
462 | @item int buflen | |
463 | length of the buffer pointed to by @var{buffer}. | |
464 | @end table | |
465 | ||
466 | @item | |
467 | possibly a last argument @var{h_errnop}, for the host name and network | |
468 | name lookup functions. | |
469 | @end itemize | |
470 | ||
471 | @noindent | |
472 | This table is correct for all functions but the @code{set@dots{}ent} | |
473 | and @code{end@dots{}ent} functions. | |
474 | ||
475 | ||
476 | @node Extending NSS, , NSS Module Internals, Name Service Switch | |
477 | @section Extending NSS | |
478 | ||
479 | One of the advantages of NSS mentioned above is that it can be extended | |
480 | quite easily. There are two ways in which the extension can happen: | |
481 | adding another database or adding another service. The former is | |
482 | normally done only by the C library developers. It is | |
483 | here only important to remember that adding another database is | |
484 | independent from adding another service because a service need not | |
485 | support all databases or lookup functions. | |
486 | ||
487 | A designer/implementor of a new service is therefore free to choose the | |
488 | databases s/he is interested in and leave the rest for later (or | |
489 | completely aside). | |
490 | ||
491 | @menu | |
492 | * Adding another Service to NSS:: What is to do to add a new service. | |
493 | * NSS Module Function Internals:: Guidelines for writing new NSS | |
494 | service functions. | |
495 | @end menu | |
496 | ||
497 | @node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS | |
498 | @subsection Adding another Service to NSS | |
499 | ||
500 | The sources for a new service need not (and should not) be part of the | |
501 | GNU C Library itself. The developer retains complete control over the | |
502 | sources and its development. The links between the C library and the | |
503 | new service module consists solely of the interface functions. | |
504 | ||
505 | Each module is designed following a specific interface specification. | |
506 | For now the version is 1 and this manifests in the version number of the | |
507 | shared library object of the NSS modules: they have the extension | |
508 | @code{.1}. If the interface ever changes in an incompatible way, | |
509 | this number will be increased---hopefully this will never be necessary. | |
510 | Modules using the old interface will still be usable. | |
511 | ||
512 | Developers of a new service will have to make sure that their module is | |
513 | created using the correct interface number. This means the file itself | |
514 | must have the correct name and on ElF systems the @dfn{soname} (Shared | |
515 | Object Name) must also have this number. Building a module from a bunch | |
516 | of object files on an ELF system using GNU CC could be done like this: | |
517 | ||
518 | @smallexample | |
519 | gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS | |
520 | @end smallexample | |
521 | ||
522 | @noindent | |
523 | @ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn | |
524 | more about this command line. | |
525 | ||
526 | To use the new module the library must be able to find it. This can be | |
527 | achieved by using options for the dynamic linker so that it will search | |
528 | directory where the binary is placed. For an ELF system this could be | |
529 | done by adding the wanted directory to the value of | |
530 | @code{LD_LIBRARY_PATH}. | |
531 | ||
532 | But this is not always possible since some program (those which run | |
533 | under IDs which do not belong to the user) ignore this variable. | |
534 | Therefore the stable version of the module should be placed into a | |
535 | directory which is searched by the dynamic linker. Normally this should | |
536 | be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to | |
537 | the value given to configure using the @code{--prefix} option. But be | |
538 | careful: this should only be done if it is clear the module does not | |
539 | cause any harm. System administrators should be careful. | |
540 | ||
541 | ||
542 | @node NSS Module Function Internals, , Adding another Service to NSS, Extending NSS | |
543 | @subsection Internals of the NSS Module Functions | |
544 | ||
545 | Until now we only provided the syntactic interface for the functions in | |
546 | the NSS module. In fact there is not more much we can tell since the | |
547 | implementation obviously is different for each function. But a few | |
548 | general rules must be followed by all functions. | |
549 | ||
550 | In fact there are four kinds of different functions which may appear in | |
551 | the interface. All derive from the traditional ones for system databases. | |
552 | @var{db} in the following table is normally an abbreviation for the | |
553 | database (e.g., it is @code{pw} for the password database). | |
554 | ||
555 | @table @code | |
556 | @item int _nss_@var{database}_set@var{db}ent (void) | |
557 | This function prepares the service for following operations. For a | |
558 | simple file based lookup this means files could be opened, for other | |
559 | services this function simply is a noop. | |
560 | ||
561 | One special case for this function is that it takes an additional | |
562 | argument for some @var{database}s (i.e., the interface is | |
563 | @code{int set@var{db}ent (int)}). @ref{Host Names}, which describes the | |
564 | @code{sethostent} function. | |
565 | ||
566 | The return value should be @var{NSS_STATUS_SUCCESS} or according to the | |
567 | table above in case of an error (@pxref{NSS Modules Interface}). | |
568 | ||
569 | @item int _nss_@var{database}_end@var{db}ent (void) | |
570 | This function simply closes all files which are still open or removes | |
571 | buffer caches. If there are no files or buffers to remove this is again | |
572 | a simple noop. | |
573 | ||
574 | There normally is no return value different to @var{NSS_STATUS_SUCCESS}. | |
575 | ||
576 | @item int _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, int buflen) | |
577 | Since this function will be called several times in a row to retrieve | |
578 | one entry after the other it must keep some kind of state. But this | |
579 | also means the functions are not really reentrant. They are reentrant | |
580 | only in that simultaneous calls to this function will not try to | |
581 | write the retrieved data in the same place (as it would be the case for | |
582 | the non-reentrant functions); instead, it writes to the structure | |
583 | pointed to by the @var{result} parameter. But the calls share a common | |
584 | state and in the case of a file access this means they return neighboring | |
585 | entries in the file. | |
586 | ||
587 | The buffer of length @var{buflen} pointed to by @var{buffer} can be used | |
588 | for storing some additional data for the result. It is @emph{not} | |
589 | guaranteed that the same buffer will be passed for the next call of this | |
590 | function. Therefore one must not misuse this buffer to save some state | |
591 | information from one call to another. | |
592 | ||
593 | As explained above this function could also have an additional last | |
594 | argument. This depends on the database used; it happens only for | |
595 | @code{host} and @code{network}. | |
596 | ||
597 | The function shall return @code{NSS_STATUS_SUCCESS} as long as their are | |
598 | more entries. When the last entry was read it should return | |
599 | @code{NSS_STATUS_NOTFOUND}. When the buffer given as an argument is too | |
600 | small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be | |
601 | returned. When the service was not formerly initialized by a call to | |
602 | @code{_nss_@var{DATABASE}_set@var{db}ent} all return value allowed for | |
603 | this function can also be returned here. | |
604 | ||
605 | @item int _nss_@var{DATABASE}_get@var{db}by@var{XX}_r (@var{PARAMS}, @var{STRUCTURE} *result, char *buffer, int buflen) | |
606 | This function shall return the entry from the database which is | |
607 | addressed by the @var{PARAMS}. The type and number of these arguments | |
608 | vary. It must be individually determined by looking to the user-level | |
609 | interface functions. All arguments given to the non-reentrant version | |
610 | are here described by @var{PARAMS}. | |
611 | ||
612 | The result must be stored in the structure pointed to by @var{result}. | |
613 | If there is additional data to return (say strings, where the | |
614 | @var{result} structure only contains pointers) the function must use the | |
615 | @var{buffer} or length @var{buflen}. There must not be any references | |
616 | to non-constant global data. | |
617 | ||
618 | The implementation of this function should honour the @var{stayopen} | |
619 | flag set by the @code{set@var{DB}ent} function whenever this makes sense. | |
620 | ||
621 | Again, this function takes an additional last argument for the | |
622 | @code{host} and @code{network} database. | |
623 | ||
624 | The return value should as always follow the rules given above | |
625 | (@pxref{NSS Modules Interface}). | |
626 | ||
627 | @end table |