about summary refs log tree commit diff
path: root/REORG.TODO/manual/nss.texi
diff options
context:
space:
mode:
Diffstat (limited to 'REORG.TODO/manual/nss.texi')
-rw-r--r--REORG.TODO/manual/nss.texi734
1 files changed, 734 insertions, 0 deletions
diff --git a/REORG.TODO/manual/nss.texi b/REORG.TODO/manual/nss.texi
new file mode 100644
index 0000000000..ee70ad309d
--- /dev/null
+++ b/REORG.TODO/manual/nss.texi
@@ -0,0 +1,734 @@
+@node Name Service Switch, Users and Groups, Job Control, Top
+@chapter System Databases and Name Service Switch
+@c %MENU% Accessing system databases
+@cindex Name Service Switch
+@cindex NSS
+@cindex databases
+
+Various functions in the C Library need to be configured to work
+correctly in the local environment.  Traditionally, this was done by
+using files (e.g., @file{/etc/passwd}), but other nameservices (like the
+Network Information Service (NIS) and the Domain Name Service (DNS))
+became popular, and were hacked into the C library, usually with a fixed
+search order.
+
+@Theglibc{} contains a cleaner solution to this problem.  It is
+designed after a method used by Sun Microsystems in the C library of
+@w{Solaris 2}.  @Theglibc{} follows their name and calls this
+scheme @dfn{Name Service Switch} (NSS).
+
+Though the interface might be similar to Sun's version there is no
+common code.  We never saw any source code of Sun's implementation and
+so the internal interface is incompatible.  This also manifests in the
+file names we use as we will see later.
+
+
+@menu
+* NSS Basics::                  What is this NSS good for.
+* NSS Configuration File::      Configuring NSS.
+* NSS Module Internals::        How does it work internally.
+* Extending NSS::               What to do to add services or databases.
+@end menu
+
+@node NSS Basics, NSS Configuration File, Name Service Switch, Name Service Switch
+@section NSS Basics
+
+The basic idea is to put the implementation of the different services
+offered to access the databases in separate modules.  This has some
+advantages:
+
+@enumerate
+@item
+Contributors can add new services without adding them to @theglibc{}.
+@item
+The modules can be updated separately.
+@item
+The C library image is smaller.
+@end enumerate
+
+To fulfill the first goal above, the ABI of the modules will be described
+below.  For getting the implementation of a new service right it is
+important to understand how the functions in the modules get called.
+They are in no way designed to be used by the programmer directly.
+Instead the programmer should only use the documented and standardized
+functions to access the databases.
+
+@noindent
+The databases available in the NSS are
+
+@cindex ethers
+@cindex group
+@cindex hosts
+@cindex netgroup
+@cindex networks
+@cindex protocols
+@cindex passwd
+@cindex rpc
+@cindex services
+@cindex shadow
+@table @code
+@item aliases
+Mail aliases
+@comment @pxref{Mail Aliases}.
+@item ethers
+Ethernet numbers,
+@comment @pxref{Ethernet Numbers}.
+@item group
+Groups of users, @pxref{Group Database}.
+@item hosts
+Host names and numbers, @pxref{Host Names}.
+@item netgroup
+Network wide list of host and users, @pxref{Netgroup Database}.
+@item networks
+Network names and numbers, @pxref{Networks Database}.
+@item protocols
+Network protocols, @pxref{Protocols Database}.
+@item passwd
+User passwords, @pxref{User Database}.
+@item rpc
+Remote procedure call names and numbers,
+@comment @pxref{RPC Database}.
+@item services
+Network services, @pxref{Services Database}.
+@item shadow
+Shadow user passwords,
+@comment @pxref{Shadow Password Database}.
+@end table
+
+@noindent
+There will be some more added later (@code{automount}, @code{bootparams},
+@code{netmasks}, and @code{publickey}).
+
+@node NSS Configuration File, NSS Module Internals, NSS Basics, Name Service Switch
+@section The NSS Configuration File
+
+@cindex @file{/etc/nsswitch.conf}
+@cindex @file{nsswitch.conf}
+Somehow the NSS code must be told about the wishes of the user.  For
+this reason there is the file @file{/etc/nsswitch.conf}.  For each
+database, this file contains a specification of how the lookup process should
+work.  The file could look like this:
+
+@example
+@include nsswitch.texi
+@end example
+
+The first column is the database as you can guess from the table above.
+The rest of the line specifies how the lookup process works.  Please
+note that you specify the way it works for each database individually.
+This cannot be done with the old way of a monolithic implementation.
+
+The configuration specification for each database can contain two
+different items:
+
+@itemize @bullet
+@item
+the service specification like @code{files}, @code{db}, or @code{nis}.
+@item
+the reaction on lookup result like @code{[NOTFOUND=return]}.
+@end itemize
+
+@menu
+* Services in the NSS configuration::  Service names in the NSS configuration.
+* Actions in the NSS configuration::  React appropriately to the lookup result.
+* Notes on NSS Configuration File::  Things to take care about while
+                                     configuring NSS.
+@end menu
+
+@node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File
+@subsection Services in the NSS configuration File
+
+The above example file mentions five different services: @code{files},
+@code{db}, @code{dns}, @code{nis}, and @code{nisplus}.  This does not
+mean these
+services are available on all sites and neither does it mean these are
+all the services which will ever be available.
+
+In fact, these names are simply strings which the NSS code uses to find
+the implicitly addressed functions.  The internal interface will be
+described later.  Visible to the user are the modules which implement an
+individual service.
+
+Assume the service @var{name} shall be used for a lookup.  The code for
+this service is implemented in a module called @file{libnss_@var{name}}.
+On a system supporting shared libraries this is in fact a shared library
+with the name (for example) @file{libnss_@var{name}.so.2}.  The number
+at the end is the currently used version of the interface which will not
+change frequently.  Normally the user should not have to be cognizant of
+these files since they should be placed in a directory where they are
+found automatically.  Only the names of all available services are
+important.
+
+@node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File
+@subsection Actions in the NSS configuration
+
+The second item in the specification gives the user much finer control
+on the lookup process.  Action items are placed between two service
+names and are written within brackets.  The general form is
+
+@display
+@code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]}
+@end display
+
+@noindent
+where
+
+@smallexample
+@var{status} @result{} success | notfound | unavail | tryagain
+@var{action} @result{} return | continue
+@end smallexample
+
+The case of the keywords is insignificant.  The @var{status}
+values are the results of a call to a lookup function of a specific
+service.  They mean:
+
+@ftable @samp
+@item success
+No error occurred and the wanted entry is returned.  The default action
+for this is @code{return}.
+
+@item notfound
+The lookup process works ok but the needed value was not found.  The
+default action is @code{continue}.
+
+@item unavail
+@cindex DNS server unavailable
+The service is permanently unavailable.  This can either mean the needed
+file is not available, or, for DNS, the server is not available or does
+not allow queries.  The default action is @code{continue}.
+
+@item tryagain
+The service is temporarily unavailable.  This could mean a file is
+locked or a server currently cannot accept more connections.  The
+default action is @code{continue}.
+@end ftable
+
+@noindent
+The @var{action} values mean:
+
+@ftable @samp
+@item return
+
+If the status matches, stop the lookup process at this service
+specification.  If an entry is available, provide it to the application.
+If an error occurred, report it to the application.  In case of a prior
+@samp{merge} action, the data is combined with previous lookup results,
+as explained below.
+
+@item continue
+
+If the status matches, proceed with the lookup process at the next
+entry, discarding the result of the current lookup (and any merged
+data).  An exception is the @samp{initgroups} database and the
+@samp{success} status, where @samp{continue} acts like @code{merge}
+below.
+
+@item merge
+
+Proceed with the lookup process, retaining the current lookup result.
+This action is useful only with the @samp{success} status.  If a
+subsequent service lookup succeeds and has a matching @samp{return}
+specification, the results are merged, the lookup process ends, and the
+merged results are returned to the application.  If the following service
+has a matching @samp{merge} action, the lookup process continues,
+retaining the combined data from this and any previous lookups.
+
+After a @code{merge} action, errors from subsequent lookups are ignored,
+and the data gathered so far will be returned.
+
+The @samp{merge} only applies to the @samp{success} status.  It is
+currently implemented for the @samp{group} database and its group
+members field, @samp{gr_mem}.  If specified for other databases, it
+causes the lookup to fail (if the @var{status} matches).
+
+When processing @samp{merge} for @samp{group} membership, the group GID
+and name must be identical for both entries.  If only one or the other is
+a match, the behavior is undefined.
+
+@end ftable
+
+@noindent
+If we have a line like
+
+@smallexample
+ethers: nisplus [NOTFOUND=return] db files
+@end smallexample
+
+@noindent
+this is equivalent to
+
+@smallexample
+ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
+                 TRYAGAIN=continue]
+        db      [SUCCESS=return NOTFOUND=continue UNAVAIL=continue
+                 TRYAGAIN=continue]
+        files
+@end smallexample
+
+@noindent
+(except that it would have to be written on one line).  The default
+value for the actions are normally what you want, and only need to be
+changed in exceptional cases.
+
+If the optional @code{!} is placed before the @var{status} this means
+the following action is used for all statuses but @var{status} itself.
+I.e., @code{!} is negation as in the C language (and others).
+
+Before we explain the exception which makes this action item necessary
+one more remark: obviously it makes no sense to add another action
+item after the @code{files} service.  Since there is no other service
+following the action @emph{always} is @code{return}.
+
+@cindex nisplus, and completeness
+Now, why is this @code{[NOTFOUND=return]} action useful?  To understand
+this we should know that the @code{nisplus} service is often
+complete; i.e., if an entry is not available in the NIS+ tables it is
+not available anywhere else.  This is what is expressed by this action
+item: it is useless to examine further services since they will not give
+us a result.
+
+@cindex nisplus, and booting
+@cindex bootstrapping, and services
+The situation would be different if the NIS+ service is not available
+because the machine is booting.  In this case the return value of the
+lookup function is not @code{notfound} but instead @code{unavail}.  And
+as you can see in the complete form above: in this situation the
+@code{db} and @code{files} services are used.  Neat, isn't it?  The
+system administrator need not pay special care for the time the system
+is not completely ready to work (while booting or shutdown or
+network problems).
+
+
+@node Notes on NSS Configuration File,  , Actions in the NSS configuration, NSS Configuration File
+@subsection Notes on the NSS Configuration File
+
+Finally a few more hints.  The NSS implementation is not completely
+helpless if @file{/etc/nsswitch.conf} does not exist.  For
+all supported databases there is a default value so it should normally
+be possible to get the system running even if the file is corrupted or
+missing.
+
+@cindex default value, and NSS
+For the @code{hosts} and @code{networks} databases the default value is
+@code{dns [!UNAVAIL=return] files}.  I.e., the system is prepared for
+the DNS service not to be available but if it is available the answer it
+returns is definitive.
+
+The @code{passwd}, @code{group}, and @code{shadow} databases are
+traditionally handled in a special way.  The appropriate files in the
+@file{/etc} directory are read but if an entry with a name starting
+with a @code{+} character is found NIS is used.  This kind of lookup
+remains possible by using the special lookup service @code{compat}
+and the default value for the three databases above is
+@code{compat [NOTFOUND=return] files}.
+
+For all other databases the default value is
+@code{nis [NOTFOUND=return] files}.  This solution gives the best
+chance to be correct since NIS and file based lookups are used.
+
+@cindex optimizing NSS
+A second point is that the user should try to optimize the lookup
+process.  The different service have different response times.
+A simple file look up on a local file could be fast, but if the file
+is long and the needed entry is near the end of the file this may take
+quite some time.  In this case it might be better to use the @code{db}
+service which allows fast local access to large data sets.
+
+Often the situation is that some global information like NIS must be
+used.  So it is unavoidable to use service entries like @code{nis} etc.
+But one should avoid slow services like this if possible.
+
+
+@node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
+@section NSS Module Internals
+
+Now it is time to describe what the modules look like.  The functions
+contained in a module are identified by their names.  I.e., there is no
+jump table or the like.  How this is done is of no interest here; those
+interested in this topic should read about Dynamic Linking.
+@comment @ref{Dynamic Linking}.
+
+
+@menu
+* NSS Module Names::            Construction of the interface function of
+                                the NSS modules.
+* NSS Modules Interface::       Programming interface in the NSS module
+                                functions.
+@end menu
+
+@node NSS Module Names, NSS Modules Interface, NSS Module Internals, NSS Module Internals
+@subsection The Naming Scheme of the NSS Modules
+
+@noindent
+The name of each function consists of various parts:
+
+@quotation
+       _nss_@var{service}_@var{function}
+@end quotation
+
+@var{service} of course corresponds to the name of the module this
+function is found in.@footnote{Now you might ask why this information is
+duplicated.  The answer is that we want to make it possible to link
+directly with these shared objects.}  The @var{function} part is derived
+from the interface function in the C library itself.  If the user calls
+the function @code{gethostbyname} and the service used is @code{files}
+the function
+
+@smallexample
+       _nss_files_gethostbyname_r
+@end smallexample
+
+@noindent
+in the module
+
+@smallexample
+       libnss_files.so.2
+@end smallexample
+
+@noindent
+@cindex reentrant NSS functions
+is used.  You see, what is explained above in not the whole truth.  In
+fact the NSS modules only contain reentrant versions of the lookup
+functions.  I.e., if the user would call the @code{gethostbyname_r}
+function this also would end in the above function.  For all user
+interface functions the C library maps this call to a call to the
+reentrant function.  For reentrant functions this is trivial since the
+interface is (nearly) the same.  For the non-reentrant version the
+library keeps internal buffers which are used to replace the user
+supplied buffer.
+
+I.e., the reentrant functions @emph{can} have counterparts.  No service
+module is forced to have functions for all databases and all kinds to
+access them.  If a function is not available it is simply treated as if
+the function would return @code{unavail}
+(@pxref{Actions in the NSS configuration}).
+
+The file name @file{libnss_files.so.2} would be on a @w{Solaris 2}
+system @file{nss_files.so.2}.  This is the difference mentioned above.
+Sun's NSS modules are usable as modules which get indirectly loaded
+only.
+
+The NSS modules in @theglibc{} are prepared to be used as normal
+libraries themselves.  This is @emph{not} true at the moment, though.
+However,  the organization of the name space in the modules does not make it
+impossible like it is for Solaris.  Now you can see why the modules are
+still libraries.@footnote{There is a second explanation: we were too
+lazy to change the Makefiles to allow the generation of shared objects
+not starting with @file{lib} but don't tell this to anybody.}
+
+
+@node NSS Modules Interface,  , NSS Module Names, NSS Module Internals
+@subsection The Interface of the Function in NSS Modules
+
+Now we know about the functions contained in the modules.  It is now
+time to describe the types.  When we mentioned the reentrant versions of
+the functions above, this means there are some additional arguments
+(compared with the standard, non-reentrant versions).  The prototypes for
+the non-reentrant and reentrant versions of our function above are:
+
+@smallexample
+struct hostent *gethostbyname (const char *name)
+
+int gethostbyname_r (const char *name, struct hostent *result_buf,
+                     char *buf, size_t buflen, struct hostent **result,
+                     int *h_errnop)
+@end smallexample
+
+@noindent
+The actual prototype of the function in the NSS modules in this case is
+
+@smallexample
+enum nss_status _nss_files_gethostbyname_r (const char *name,
+                                            struct hostent *result_buf,
+                                            char *buf, size_t buflen,
+                                            int *errnop, int *h_errnop)
+@end smallexample
+
+I.e., the interface function is in fact the reentrant function with the
+change of the return value, the omission of the @var{result} parameter,
+and the addition of the @var{errnop} parameter.  While the user-level
+function returns a pointer to the result the reentrant function return
+an @code{enum nss_status} value:
+
+@vtable @code
+@item NSS_STATUS_TRYAGAIN
+numeric value @code{-2}
+
+@item NSS_STATUS_UNAVAIL
+numeric value @code{-1}
+
+@item NSS_STATUS_NOTFOUND
+numeric value @code{0}
+
+@item NSS_STATUS_SUCCESS
+numeric value @code{1}
+@end vtable
+
+@noindent
+Now you see where the action items of the @file{/etc/nsswitch.conf} file
+are used.
+
+If you study the source code you will find there is a fifth value:
+@code{NSS_STATUS_RETURN}.  This is an internal use only value, used by a
+few functions in places where none of the above value can be used.  If
+necessary the source code should be examined to learn about the details.
+
+In case the interface function has to return an error it is important
+that the correct error code is stored in @code{*@var{errnop}}.  Some
+return status values have only one associated error code, others have
+more.
+
+@multitable @columnfractions .3 .2 .50
+@item
+@code{NSS_STATUS_TRYAGAIN} @tab
+        @code{EAGAIN} @tab One of the functions used ran temporarily out of
+resources or a service is currently not available.
+@item
+@tab
+        @code{ERANGE} @tab The provided buffer is not large enough.
+The function should be called again with a larger buffer.
+@item
+@code{NSS_STATUS_UNAVAIL} @tab
+        @code{ENOENT} @tab A necessary input file cannot be found.
+@item
+@code{NSS_STATUS_NOTFOUND} @tab
+        @code{ENOENT} @tab The requested entry is not available.
+
+@item
+@code{NSS_STATUS_NOTFOUND} @tab
+	@code{SUCCESS} @tab There are no entries.
+Use this to avoid returning errors for inactive services which may
+be enabled at a later time. This is not the same as the service
+being temporarily unavailable.
+@end multitable
+
+These are proposed values.  There can be other error codes and the
+described error codes can have different meaning.  @strong{With one
+exception:} when returning @code{NSS_STATUS_TRYAGAIN} the error code
+@code{ERANGE} @emph{must} mean that the user provided buffer is too
+small.  Everything else is non-critical.
+
+In statically linked programs, the main application and NSS modules do
+not share the same thread-local variable @code{errno}, which is the
+reason why there is an explicit @var{errnop} function argument.
+
+The above function has something special which is missing for almost all
+the other module functions.  There is an argument @var{h_errnop}.  This
+points to a variable which will be filled with the error code in case
+the execution of the function fails for some reason.  (In statically
+linked programs, the thread-local variable @code{h_errno} is not shared
+with the main application.)
+
+The @code{get@var{XXX}by@var{YYY}} functions are the most important
+functions in the NSS modules.  But there are others which implement
+the other ways to access system databases (say for the
+password database, there are @code{setpwent}, @code{getpwent}, and
+@code{endpwent}).  These will be described in more detail later.
+Here we give a general way to determine the
+signature of the module function:
+
+@itemize @bullet
+@item
+the return value is @code{enum nss_status};
+@item
+the name (@pxref{NSS Module Names});
+@item
+the first arguments are identical to the arguments of the non-reentrant
+function;
+@item
+the next four arguments are:
+
+@table @code
+@item STRUCT_TYPE *result_buf
+pointer to buffer where the result is stored.  @code{STRUCT_TYPE} is
+normally a struct which corresponds to the database.
+@item char *buffer
+pointer to a buffer where the function can store additional data for
+the result etc.
+@item size_t buflen
+length of the buffer pointed to by @var{buffer}.
+@item int *errnop
+the low-level error code to return to the application.  If the return
+value is not @code{NSS_STATUS_SUCCESS}, @code{*@var{errnop}} needs to be
+set to a non-zero value.  An NSS module should never set
+@code{*@var{errnop}} to zero.  The value @code{ERANGE} is special, as
+described above.
+@end table
+
+@item
+possibly a last argument @var{h_errnop}, for the host name and network
+name lookup functions.  If the return value is not
+@code{NSS_STATUS_SUCCESS}, @code{*@var{h_errnop}} needs to be set to a
+non-zero value.  A generic error code is @code{NETDB_INTERNAL}, which
+instructs the caller to examine @code{*@var{errnop}} for further
+details.  (This includes the @code{ERANGE} special case.)
+@end itemize
+
+@noindent
+This table is correct for all functions but the @code{set@dots{}ent}
+and @code{end@dots{}ent} functions.
+
+
+@node Extending NSS,  , NSS Module Internals, Name Service Switch
+@section Extending NSS
+
+One of the advantages of NSS mentioned above is that it can be extended
+quite easily.  There are two ways in which the extension can happen:
+adding another database or adding another service.  The former is
+normally done only by the C library developers.  It is
+here only important to remember that adding another database is
+independent from adding another service because a service need not
+support all databases or lookup functions.
+
+A designer/implementer of a new service is therefore free to choose the
+databases s/he is interested in and leave the rest for later (or
+completely aside).
+
+@menu
+* Adding another Service to NSS::  What is to do to add a new service.
+* NSS Module Function Internals::  Guidelines for writing new NSS
+                                        service functions.
+@end menu
+
+@node Adding another Service to NSS, NSS Module Function Internals, Extending NSS, Extending NSS
+@subsection Adding another Service to NSS
+
+The sources for a new service need not (and should not) be part of @theglibc{}
+itself.  The developer retains complete control over the
+sources and its development.  The links between the C library and the
+new service module consists solely of the interface functions.
+
+Each module is designed following a specific interface specification.
+For now the version is 2 (the interface in version 1 was not adequate)
+and this manifests in the version number of the shared library object of
+the NSS modules: they have the extension @code{.2}.  If the interface
+changes again in an incompatible way, this number will be increased.
+Modules using the old interface will still be usable.
+
+Developers of a new service will have to make sure that their module is
+created using the correct interface number.  This means the file itself
+must have the correct name and on ELF systems the @dfn{soname} (Shared
+Object Name) must also have this number.  Building a module from a bunch
+of object files on an ELF system using GNU CC could be done like this:
+
+@smallexample
+gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS
+@end smallexample
+
+@noindent
+@ref{Link Options, Options for Linking, , gcc, GNU CC}, to learn
+more about this command line.
+
+To use the new module the library must be able to find it.  This can be
+achieved by using options for the dynamic linker so that it will search
+the directory where the binary is placed.  For an ELF system this could be
+done by adding the wanted directory to the value of
+@code{LD_LIBRARY_PATH}.
+
+But this is not always possible since some programs (those which run
+under IDs which do not belong to the user) ignore this variable.
+Therefore the stable version of the module should be placed into a
+directory which is searched by the dynamic linker.  Normally this should
+be the directory @file{$prefix/lib}, where @file{$prefix} corresponds to
+the value given to configure using the @code{--prefix} option.  But be
+careful: this should only be done if it is clear the module does not
+cause any harm.  System administrators should be careful.
+
+
+@node NSS Module Function Internals,  , Adding another Service to NSS, Extending NSS
+@subsection Internals of the NSS Module Functions
+
+Until now we only provided the syntactic interface for the functions in
+the NSS module.  In fact there is not much more we can say since the
+implementation obviously is different for each function.  But a few
+general rules must be followed by all functions.
+
+In fact there are four kinds of different functions which may appear in
+the interface.  All derive from the traditional ones for system databases.
+@var{db} in the following table is normally an abbreviation for the
+database (e.g., it is @code{pw} for the password database).
+
+@table @code
+@item enum nss_status _nss_@var{database}_set@var{db}ent (void)
+This function prepares the service for following operations.  For a
+simple file based lookup this means files could be opened, for other
+services this function simply is a noop.
+
+One special case for this function is that it takes an additional
+argument for some @var{database}s (i.e., the interface is
+@code{int set@var{db}ent (int)}).  @ref{Host Names}, which describes the
+@code{sethostent} function.
+
+The return value should be @var{NSS_STATUS_SUCCESS} or according to the
+table above in case of an error (@pxref{NSS Modules Interface}).
+
+@item enum nss_status _nss_@var{database}_end@var{db}ent (void)
+This function simply closes all files which are still open or removes
+buffer caches.  If there are no files or buffers to remove this is again
+a simple noop.
+
+There normally is no return value other than @var{NSS_STATUS_SUCCESS}.
+
+@item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen, int *errnop)
+Since this function will be called several times in a row to retrieve
+one entry after the other it must keep some kind of state.  But this
+also means the functions are not really reentrant.  They are reentrant
+only in that simultaneous calls to this function will not try to
+write the retrieved data in the same place (as it would be the case for
+the non-reentrant functions); instead, it writes to the structure
+pointed to by the @var{result} parameter.  But the calls share a common
+state and in the case of a file access this means they return neighboring
+entries in the file.
+
+The buffer of length @var{buflen} pointed to by @var{buffer} can be used
+for storing some additional data for the result.  It is @emph{not}
+guaranteed that the same buffer will be passed for the next call of this
+function.  Therefore one must not misuse this buffer to save some state
+information from one call to another.
+
+Before the function returns with a failure code, the implementation
+should store the value of the local @var{errno} variable in the variable
+pointed to be @var{errnop}.  This is important to guarantee the module
+working in statically linked programs.  The stored value must not be
+zero.
+
+As explained above this function could also have an additional last
+argument.  This depends on the database used; it happens only for
+@code{host} and @code{networks}.
+
+The function shall return @code{NSS_STATUS_SUCCESS} as long as there are
+more entries.  When the last entry was read it should return
+@code{NSS_STATUS_NOTFOUND}.  When the buffer given as an argument is too
+small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be
+returned.  When the service was not formerly initialized by a call to
+@code{_nss_@var{DATABASE}_set@var{db}ent} all return values allowed for
+this function can also be returned here.
+
+@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)
+This function shall return the entry from the database which is
+addressed by the @var{PARAMS}.  The type and number of these arguments
+vary.  It must be individually determined by looking to the user-level
+interface functions.  All arguments given to the non-reentrant version
+are here described by @var{PARAMS}.
+
+The result must be stored in the structure pointed to by @var{result}.
+If there are additional data to return (say strings, where the
+@var{result} structure only contains pointers) the function must use the
+@var{buffer} of length @var{buflen}.  There must not be any references
+to non-constant global data.
+
+The implementation of this function should honor the @var{stayopen}
+flag set by the @code{set@var{DB}ent} function whenever this makes sense.
+
+Before the function returns, the implementation should store the value of
+the local @var{errno} variable in the variable pointed to by
+@var{errnop}.  This is important to guarantee the module works in
+statically linked programs.
+
+Again, this function takes an additional last argument for the
+@code{host} and @code{networks} database.
+
+The return value should as always follow the rules given above
+(@pxref{NSS Modules Interface}).
+
+@end table