GNU Info

(libc.info)NSS Module Function Internals

---

Prev: Adding another Service to NSS Up: Extending NSS

---

Enter node , (file) or (file)node

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.  DB in the following table is normally an abbreviation for
the database (e.g., it is `pw' for the password database).

`enum nss_status _nss_DATABASE_setDBent (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 DATABASEs (i.e., the interface is `int setDBent
     (int)').  Note: Host Names, which describes the `sethostent'
     function.

     The return value should be NSS_STATUS_SUCCESS or according to the
     table above in case of an error (Note: NSS Modules Interface).

`enum nss_status _nss_DATABASE_endDBent (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 different to NSS_STATUS_SUCCESS.

`enum nss_status _nss_DATABASE_getDBent_r (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 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 BUFLEN pointed to by BUFFER can be used for
     storing some additional data for the result.  It is _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 the implementation should store the
     value of the local ERRNO variable in the variable pointed to be
     ERRNOP.  This is important to guarantee the module working in
     statically linked programs.

     As explained above this function could also have an additional last
     argument.  This depends on the database used; it happens only for
     `host' and `networks'.

     The function shall return `NSS_STATUS_SUCCESS' as long as there are
     more entries.  When the last entry was read it should return
     `NSS_STATUS_NOTFOUND'.  When the buffer given as an argument is too
     small for the data to be returned `NSS_STATUS_TRYAGAIN' should be
     returned.  When the service was not formerly initialized by a call
     to `_nss_DATABASE_setDBent' all return value allowed for this
     function can also be returned here.

`enum nss_status _nss_DATABASE_getDBbyXX_r (PARAMS, STRUCTURE *result, char *buffer, size_t buflen, int *errnop)'
     This function shall return the entry from the database which is
     addressed by the 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 PARAMS.

     The result must be stored in the structure pointed to by RESULT.
     If there is additional data to return (say strings, where the
     RESULT structure only contains pointers) the function must use the
     BUFFER or length BUFLEN.  There must not be any references to
     non-constant global data.

     The implementation of this function should honor the STAYOPEN flag
     set by the `setDBent' function whenever this makes sense.

     Before the function returns the implementation should store the
     value of the local ERRNO variable in the variable pointed to be
     ERRNOP.  This is important to guarantee the module working in
     statically linked programs.

     Again, this function takes an additional last argument for the
     `host' and `networks' database.

     The return value should as always follow the rules given above
     (Note: NSS Modules Interface).