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