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