Add runtime check if mutex will be elided in tst-mutex8 testcases.
[glibc.git] / manual / nss.texi
blobd534c260d322b829136d2452dd671a5a82f90131
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
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.
15 @Theglibc{} contains a cleaner solution to this problem.  It is
16 designed after a method used by Sun Microsystems in the C library of
17 @w{Solaris 2}.  @Theglibc{} follows their name and calls this
18 scheme @dfn{Name Service Switch} (NSS).
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.
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
33 @node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch
34 @section NSS Basics
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:
40 @enumerate
41 @item
42 Contributors can add new services without adding them to @theglibc{}.
43 @item
44 The modules can be updated separately.
45 @item
46 The C library image is smaller.
47 @end enumerate
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.
56 @noindent
57 The databases available in the NSS are
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 @table @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 table
98 @noindent
99 There will be some more added later (@code{automount}, @code{bootparams},
100 @code{netmasks}, and @code{publickey}).
102 @node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch
103 @section The NSS Configuration File
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 contains a specification of how the lookup process should
110 work.  The file could look like this:
112 @example
113 @include nsswitch.texi
114 @end example
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.
121 The configuration specification for each database can contain two
122 different items:
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
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
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
141 The above example file mentions five different services: @code{files},
142 @code{db}, @code{dns}, @code{nis}, and @code{nisplus}.  This does not
143 mean these
144 services are available on all sites and neither does it mean these are
145 all the services which will ever be available.
147 In fact, these names are simply strings which the NSS code uses to find
148 the implicitly addressed functions.  The internal interface will be
149 described later.  Visible to the user are the modules which implement an
150 individual service.
152 Assume the service @var{name} shall be used for a lookup.  The code for
153 this service is implemented in a module called @file{libnss_@var{name}}.
154 On a system supporting shared libraries this is in fact a shared library
155 with the name (for example) @file{libnss_@var{name}.so.2}.  The number
156 at the end is the currently used version of the interface which will not
157 change frequently.  Normally the user should not have to be cognizant of
158 these files since they should be placed in a directory where they are
159 found automatically.  Only the names of all available services are
160 important.
162 @node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File
163 @subsection Actions in the NSS configuration
165 The second item in the specification gives the user much finer control
166 on the lookup process.  Action items are placed between two service
167 names and are written within brackets.  The general form is
169 @display
170 @code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]}
171 @end display
173 @noindent
174 where
176 @smallexample
177 @var{status} @result{} success | notfound | unavail | tryagain
178 @var{action} @result{} return | continue
179 @end smallexample
181 The case of the keywords is insignificant.  The @var{status}
182 values are the results of a call to a lookup function of a specific
183 service.  They mean:
185 @ftable @samp
186 @item success
187 No error occurred and the wanted entry is returned.  The default action
188 for this is @code{return}.
190 @item notfound
191 The lookup process works ok but the needed value was not found.  The
192 default action is @code{continue}.
194 @item unavail
195 @cindex DNS server unavailable
196 The service is permanently unavailable.  This can either mean the needed
197 file is not available, or, for DNS, the server is not available or does
198 not allow queries.  The default action is @code{continue}.
200 @item tryagain
201 The service is temporarily unavailable.  This could mean a file is
202 locked or a server currently cannot accept more connections.  The
203 default action is @code{continue}.
204 @end ftable
206 @noindent
207 The @var{action} values mean:
209 @ftable @samp
210 @item return
212 If the status matches, stop the lookup process at this service
213 specification.  If an entry is available, provide it to the application.
214 If an error occurred, report it to the application.  In case of a prior
215 @samp{merge} action, the data is combined with previous lookup results,
216 as explained below.
218 @item continue
220 If the status matches, proceed with the lookup process at the next
221 entry, discarding the result of the current lookup (and any merged
222 data).  An exception is the @samp{initgroups} database and the
223 @samp{success} status, where @samp{continue} acts like @code{merge}
224 below.
226 @item merge
228 Proceed with the lookup process, retaining the current lookup result.
229 This action is useful only with the @samp{success} status.  If a
230 subsequent service lookup succeeds and has a matching @samp{return}
231 specification, the results are merged, the lookup process ends, and the
232 merged results are returned to the application.  If the following service
233 has a matching @samp{merge} action, the lookup process continues,
234 retaining the combined data from this and any previous lookups.
236 After a @code{merge} action, errors from subsequent lookups are ignored,
237 and the data gathered so far will be returned.
239 The @samp{merge} only applies to the @samp{success} status.  It is
240 currently implemented for the @samp{group} database and its group
241 members field, @samp{gr_mem}.  If specified for other databases, it
242 causes the lookup to fail (if the @var{status} matches).
244 When processing @samp{merge} for @samp{group} membership, the group GID
245 and name must be identical for both entries.  If only one or the other is
246 a match, the behavior is undefined.
248 @end ftable
250 @noindent
251 If we have a line like
253 @smallexample
254 ethers: nisplus [NOTFOUND=return] db files
255 @end smallexample
257 @noindent
258 this is equivalent to
260 @smallexample
261 ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
262                  TRYAGAIN=continue]
263         db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
264                  TRYAGAIN=continue]
265         files
266 @end smallexample
268 @noindent
269 (except that it would have to be written on one line).  The default
270 value for the actions are normally what you want, and only need to be
271 changed in exceptional cases.
273 If the optional @code{!} is placed before the @var{status} this means
274 the following action is used for all statuses but @var{status} itself.
275 I.e., @code{!} is negation as in the C language (and others).
277 Before we explain the exception which makes this action item necessary
278 one more remark: obviously it makes no sense to add another action
279 item after the @code{files} service.  Since there is no other service
280 following the action @emph{always} is @code{return}.
282 @cindex nisplus, and completeness
283 Now, why is this @code{[NOTFOUND=return]} action useful?  To understand
284 this we should know that the @code{nisplus} service is often
285 complete; i.e., if an entry is not available in the NIS+ tables it is
286 not available anywhere else.  This is what is expressed by this action
287 item: it is useless to examine further services since they will not give
288 us a result.
290 @cindex nisplus, and booting
291 @cindex bootstrapping, and services
292 The situation would be different if the NIS+ service is not available
293 because the machine is booting.  In this case the return value of the
294 lookup function is not @code{notfound} but instead @code{unavail}.  And
295 as you can see in the complete form above: in this situation the
296 @code{db} and @code{files} services are used.  Neat, isn't it?  The
297 system administrator need not pay special care for the time the system
298 is not completely ready to work (while booting or shutdown or
299 network problems).
302 @node Notes on NSS Configuration File,  , Actions in the NSS configuration, NSS Configuration File
303 @subsection Notes on the NSS Configuration File
305 Finally a few more hints.  The NSS implementation is not completely
306 helpless if @file{/etc/nsswitch.conf} does not exist.  For
307 all supported databases there is a default value so it should normally
308 be possible to get the system running even if the file is corrupted or
309 missing.
311 @cindex default value, and NSS
312 For the @code{hosts} and @code{networks} databases the default value is
313 @code{dns [!UNAVAIL=return] files}.  I.e., the system is prepared for
314 the DNS service not to be available but if it is available the answer it
315 returns is definitive.
317 The @code{passwd}, @code{group}, and @code{shadow} databases are
318 traditionally handled in a special way.  The appropriate files in the
319 @file{/etc} directory are read but if an entry with a name starting
320 with a @code{+} character is found NIS is used.  This kind of lookup
321 remains possible if @theglibc{} was configured with the
322 @code{--enable-obsolete-nsl} option and the special lookup service
323 @code{compat} is used.  If @theglibc{} was configured with the
324 @code{--enable-obsolete-nsl} option the default value for the three
325 databases above is @code{compat [NOTFOUND=return] files}.  If the
326 @code{--enable-obsolete-nsl} option was not used the default value
327 for the services is @code{files}.
329 For all other databases the default value is @code{files} unless
330 @theglibc{} was configured with @code{--enable-obsolete-rpc} option, in
331 which case it the default value is @code{nis [NOTFOUND=return] files}.
333 @cindex optimizing NSS
334 A second point is that the user should try to optimize the lookup
335 process.  The different service have different response times.
336 A simple file look up on a local file could be fast, but if the file
337 is long and the needed entry is near the end of the file this may take
338 quite some time.  In this case it might be better to use the @code{db}
339 service which allows fast local access to large data sets.
341 Often the situation is that some global information like NIS must be
342 used.  So it is unavoidable to use service entries like @code{nis} etc.
343 But one should avoid slow services like this if possible.
346 @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
347 @section NSS Module Internals
349 Now it is time to describe what the modules look like.  The functions
350 contained in a module are identified by their names.  I.e., there is no
351 jump table or the like.  How this is done is of no interest here; those
352 interested in this topic should read about Dynamic Linking.
353 @comment @ref{Dynamic Linking}.
356 @menu
357 * NSS Module Names::            Construction of the interface function of
358                                 the NSS modules.
359 * NSS Modules Interface::       Programming interface in the NSS module
360                                 functions.
361 @end menu
363 @node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals
364 @subsection The Naming Scheme of the NSS Modules
366 @noindent
367 The name of each function consists of various parts:
369 @quotation
370        _nss_@var{service}_@var{function}
371 @end quotation
373 @var{service} of course corresponds to the name of the module this
374 function is found in.@footnote{Now you might ask why this information is
375 duplicated.  The answer is that we want to make it possible to link
376 directly with these shared objects.}  The @var{function} part is derived
377 from the interface function in the C library itself.  If the user calls
378 the function @code{gethostbyname} and the service used is @code{files}
379 the function
381 @smallexample
382        _nss_files_gethostbyname_r
383 @end smallexample
385 @noindent
386 in the module
388 @smallexample
389        libnss_files.so.2
390 @end smallexample
392 @noindent
393 @cindex reentrant NSS functions
394 is used.  You see, what is explained above in not the whole truth.  In
395 fact the NSS modules only contain reentrant versions of the lookup
396 functions.  I.e., if the user would call the @code{gethostbyname_r}
397 function this also would end in the above function.  For all user
398 interface functions the C library maps this call to a call to the
399 reentrant function.  For reentrant functions this is trivial since the
400 interface is (nearly) the same.  For the non-reentrant version the
401 library keeps internal buffers which are used to replace the user
402 supplied buffer.
404 I.e., the reentrant functions @emph{can} have counterparts.  No service
405 module is forced to have functions for all databases and all kinds to
406 access them.  If a function is not available it is simply treated as if
407 the function would return @code{unavail}
408 (@pxref{Actions in the NSS configuration}).
410 The file name @file{libnss_files.so.2} would be on a @w{Solaris 2}
411 system @file{nss_files.so.2}.  This is the difference mentioned above.
412 Sun's NSS modules are usable as modules which get indirectly loaded
413 only.
415 The NSS modules in @theglibc{} are prepared to be used as normal
416 libraries themselves.  This is @emph{not} true at the moment, though.
417 However,  the organization of the name space in the modules does not make it
418 impossible like it is for Solaris.  Now you can see why the modules are
419 still libraries.@footnote{There is a second explanation: we were too
420 lazy to change the Makefiles to allow the generation of shared objects
421 not starting with @file{lib} but don't tell this to anybody.}
424 @node NSS Modules Interface,  , NSS Module Names, NSS Module Internals
425 @subsection The Interface of the Function in NSS Modules
427 Now we know about the functions contained in the modules.  It is now
428 time to describe the types.  When we mentioned the reentrant versions of
429 the functions above, this means there are some additional arguments
430 (compared with the standard, non-reentrant versions).  The prototypes for
431 the non-reentrant and reentrant versions of our function above are:
433 @smallexample
434 struct hostent *gethostbyname (const char *name)
436 int gethostbyname_r (const char *name, struct hostent *result_buf,
437                      char *buf, size_t buflen, struct hostent **result,
438                      int *h_errnop)
439 @end smallexample
441 @noindent
442 The actual prototype of the function in the NSS modules in this case is
444 @smallexample
445 enum nss_status _nss_files_gethostbyname_r (const char *name,
446                                             struct hostent *result_buf,
447                                             char *buf, size_t buflen,
448                                             int *errnop, int *h_errnop)
449 @end smallexample
451 I.e., the interface function is in fact the reentrant function with the
452 change of the return value, the omission of the @var{result} parameter,
453 and the addition of the @var{errnop} parameter.  While the user-level
454 function returns a pointer to the result the reentrant function return
455 an @code{enum nss_status} value:
457 @vtable @code
458 @item NSS_STATUS_TRYAGAIN
459 numeric value @code{-2}
461 @item NSS_STATUS_UNAVAIL
462 numeric value @code{-1}
464 @item NSS_STATUS_NOTFOUND
465 numeric value @code{0}
467 @item NSS_STATUS_SUCCESS
468 numeric value @code{1}
469 @end vtable
471 @noindent
472 Now you see where the action items of the @file{/etc/nsswitch.conf} file
473 are used.
475 If you study the source code you will find there is a fifth value:
476 @code{NSS_STATUS_RETURN}.  This is an internal use only value, used by a
477 few functions in places where none of the above value can be used.  If
478 necessary the source code should be examined to learn about the details.
480 In case the interface function has to return an error it is important
481 that the correct error code is stored in @code{*@var{errnop}}.  Some
482 return status values have only one associated error code, others have
483 more.
485 @multitable @columnfractions .3 .2 .50
486 @item
487 @code{NSS_STATUS_TRYAGAIN} @tab
488         @code{EAGAIN} @tab One of the functions used ran temporarily out of
489 resources or a service is currently not available.
490 @item
491 @tab
492         @code{ERANGE} @tab The provided buffer is not large enough.
493 The function should be called again with a larger buffer.
494 @item
495 @code{NSS_STATUS_UNAVAIL} @tab
496         @code{ENOENT} @tab A necessary input file cannot be found.
497 @item
498 @code{NSS_STATUS_NOTFOUND} @tab
499         @code{ENOENT} @tab The requested entry is not available.
501 @item
502 @code{NSS_STATUS_NOTFOUND} @tab
503         @code{SUCCESS} @tab There are no entries.
504 Use this to avoid returning errors for inactive services which may
505 be enabled at a later time. This is not the same as the service
506 being temporarily unavailable.
507 @end multitable
509 These are proposed values.  There can be other error codes and the
510 described error codes can have different meaning.  @strong{With one
511 exception:} when returning @code{NSS_STATUS_TRYAGAIN} the error code
512 @code{ERANGE} @emph{must} mean that the user provided buffer is too
513 small.  Everything else is non-critical.
515 In statically linked programs, the main application and NSS modules do
516 not share the same thread-local variable @code{errno}, which is the
517 reason why there is an explicit @var{errnop} function argument.
519 The above function has something special which is missing for almost all
520 the other module functions.  There is an argument @var{h_errnop}.  This
521 points to a variable which will be filled with the error code in case
522 the execution of the function fails for some reason.  (In statically
523 linked programs, the thread-local variable @code{h_errno} is not shared
524 with the main application.)
526 The @code{get@var{XXX}by@var{YYY}} functions are the most important
527 functions in the NSS modules.  But there are others which implement
528 the other ways to access system databases (say for the
529 password database, there are @code{setpwent}, @code{getpwent}, and
530 @code{endpwent}).  These will be described in more detail later.
531 Here we give a general way to determine the
532 signature of the module function:
534 @itemize @bullet
535 @item
536 the return value is @code{enum nss_status};
537 @item
538 the name (@pxref{NSS Module Names});
539 @item
540 the first arguments are identical to the arguments of the non-reentrant
541 function;
542 @item
543 the next four arguments are:
545 @table @code
546 @item STRUCT_TYPE *result_buf
547 pointer to buffer where the result is stored.  @code{STRUCT_TYPE} is
548 normally a struct which corresponds to the database.
549 @item char *buffer
550 pointer to a buffer where the function can store additional data for
551 the result etc.
552 @item size_t buflen
553 length of the buffer pointed to by @var{buffer}.
554 @item int *errnop
555 the low-level error code to return to the application.  If the return
556 value is not @code{NSS_STATUS_SUCCESS}, @code{*@var{errnop}} needs to be
557 set to a non-zero value.  An NSS module should never set
558 @code{*@var{errnop}} to zero.  The value @code{ERANGE} is special, as
559 described above.
560 @end table
562 @item
563 possibly a last argument @var{h_errnop}, for the host name and network
564 name lookup functions.  If the return value is not
565 @code{NSS_STATUS_SUCCESS}, @code{*@var{h_errnop}} needs to be set to a
566 non-zero value.  A generic error code is @code{NETDB_INTERNAL}, which
567 instructs the caller to examine @code{*@var{errnop}} for further
568 details.  (This includes the @code{ERANGE} special case.)
569 @end itemize
571 @noindent
572 This table is correct for all functions but the @code{set@dots{}ent}
573 and @code{end@dots{}ent} functions.
576 @node Extending NSS,  , NSS Module Internals, Name Service Switch
577 @section Extending NSS
579 One of the advantages of NSS mentioned above is that it can be extended
580 quite easily.  There are two ways in which the extension can happen:
581 adding another database or adding another service.  The former is
582 normally done only by the C library developers.  It is
583 here only important to remember that adding another database is
584 independent from adding another service because a service need not
585 support all databases or lookup functions.
587 A designer/implementer of a new service is therefore free to choose the
588 databases s/he is interested in and leave the rest for later (or
589 completely aside).
591 @menu
592 * Adding another Service to NSS::  What is to do to add a new service.
593 * NSS Module Function Internals::  Guidelines for writing new NSS
594                                         service functions.
595 @end menu
597 @node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS
598 @subsection Adding another Service to NSS
600 The sources for a new service need not (and should not) be part of @theglibc{}
601 itself.  The developer retains complete control over the
602 sources and its development.  The links between the C library and the
603 new service module consists solely of the interface functions.
605 Each module is designed following a specific interface specification.
606 For now the version is 2 (the interface in version 1 was not adequate)
607 and this manifests in the version number of the shared library object of
608 the NSS modules: they have the extension @code{.2}.  If the interface
609 changes again in an incompatible way, this number will be increased.
610 Modules using the old interface will still be usable.
612 Developers of a new service will have to make sure that their module is
613 created using the correct interface number.  This means the file itself
614 must have the correct name and on ELF systems the @dfn{soname} (Shared
615 Object Name) must also have this number.  Building a module from a bunch
616 of object files on an ELF system using GNU CC could be done like this:
618 @smallexample
619 gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS
620 @end smallexample
622 @noindent
623 @ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn
624 more about this command line.
626 To use the new module the library must be able to find it.  This can be
627 achieved by using options for the dynamic linker so that it will search
628 the directory where the binary is placed.  For an ELF system this could be
629 done by adding the wanted directory to the value of
630 @code{LD_LIBRARY_PATH}.
632 But this is not always possible since some programs (those which run
633 under IDs which do not belong to the user) ignore this variable.
634 Therefore the stable version of the module should be placed into a
635 directory which is searched by the dynamic linker.  Normally this should
636 be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to
637 the value given to configure using the @code{--prefix} option.  But be
638 careful: this should only be done if it is clear the module does not
639 cause any harm.  System administrators should be careful.
642 @node NSS Module Function Internals,  , Adding another Service to NSS, Extending NSS
643 @subsection Internals of the NSS Module Functions
645 Until now we only provided the syntactic interface for the functions in
646 the NSS module.  In fact there is not much more we can say since the
647 implementation obviously is different for each function.  But a few
648 general rules must be followed by all functions.
650 In fact there are four kinds of different functions which may appear in
651 the interface.  All derive from the traditional ones for system databases.
652 @var{db} in the following table is normally an abbreviation for the
653 database (e.g., it is @code{pw} for the password database).
655 @table @code
656 @item enum nss_status _nss_@var{database}_set@var{db}ent (void)
657 This function prepares the service for following operations.  For a
658 simple file based lookup this means files could be opened, for other
659 services this function simply is a noop.
661 One special case for this function is that it takes an additional
662 argument for some @var{database}s (i.e., the interface is
663 @code{int set@var{db}ent (int)}).  @ref{Host Names}, which describes the
664 @code{sethostent} function.
666 The return value should be @var{NSS_STATUS_SUCCESS} or according to the
667 table above in case of an error (@pxref{NSS Modules Interface}).
669 @item enum nss_status _nss_@var{database}_end@var{db}ent (void)
670 This function simply closes all files which are still open or removes
671 buffer caches.  If there are no files or buffers to remove this is again
672 a simple noop.
674 There normally is no return value other than @var{NSS_STATUS_SUCCESS}.
676 @item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop)
677 Since this function will be called several times in a row to retrieve
678 one entry after the other it must keep some kind of state.  But this
679 also means the functions are not really reentrant.  They are reentrant
680 only in that simultaneous calls to this function will not try to
681 write the retrieved data in the same place (as it would be the case for
682 the non-reentrant functions); instead, it writes to the structure
683 pointed to by the @var{result} parameter.  But the calls share a common
684 state and in the case of a file access this means they return neighboring
685 entries in the file.
687 The buffer of length @var{buflen} pointed to by @var{buffer} can be used
688 for storing some additional data for the result.  It is @emph{not}
689 guaranteed that the same buffer will be passed for the next call of this
690 function.  Therefore one must not misuse this buffer to save some state
691 information from one call to another.
693 Before the function returns with a failure code, the implementation
694 should store the value of the local @var{errno} variable in the variable
695 pointed to be @var{errnop}.  This is important to guarantee the module
696 working in statically linked programs.  The stored value must not be
697 zero.
699 As explained above this function could also have an additional last
700 argument.  This depends on the database used; it happens only for
701 @code{host} and @code{networks}.
703 The function shall return @code{NSS_STATUS_SUCCESS} as long as there are
704 more entries.  When the last entry was read it should return
705 @code{NSS_STATUS_NOTFOUND}.  When the buffer given as an argument is too
706 small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be
707 returned.  When the service was not formerly initialized by a call to
708 @code{_nss_@var{DATABASE}_set@var{db}ent} all return values allowed for
709 this function can also be returned here.
711 @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)
712 This function shall return the entry from the database which is
713 addressed by the @var{PARAMS}.  The type and number of these arguments
714 vary.  It must be individually determined by looking to the user-level
715 interface functions.  All arguments given to the non-reentrant version
716 are here described by @var{PARAMS}.
718 The result must be stored in the structure pointed to by @var{result}.
719 If there are additional data to return (say strings, where the
720 @var{result} structure only contains pointers) the function must use the
721 @var{buffer} of length @var{buflen}.  There must not be any references
722 to non-constant global data.
724 The implementation of this function should honor the @var{stayopen}
725 flag set by the @code{set@var{DB}ent} function whenever this makes sense.
727 Before the function returns, the implementation should store the value of
728 the local @var{errno} variable in the variable pointed to by
729 @var{errnop}.  This is important to guarantee the module works in
730 statically linked programs.
732 Again, this function takes an additional last argument for the
733 @code{host} and @code{networks} database.
735 The return value should as always follow the rules given above
736 (@pxref{NSS Modules Interface}).
738 @end table