GNU Info

(libc.info)NSS Modules Interface

---

Prev: NSS Module Names Up: NSS Module Internals

---

Enter node , (file) or (file)node

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 version).  The prototypes for
the non-reentrant and reentrant versions of our function above are:

     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)

The actual prototype of the function in the NSS modules in this case is

     enum nss_status _nss_files_gethostbyname_r (const char *name,
                                                 struct hostent *result_buf,
                                                 char *buf, size_t buflen,
                                                 int *errnop, int *h_errnop)

   I.e., the interface function is in fact the reentrant function with
the change of the return value and the omission of the RESULT
parameter.  While the user-level function returns a pointer to the
result the reentrant function return an `enum nss_status' value:

`NSS_STATUS_TRYAGAIN'
     numeric value `-2'

`NSS_STATUS_UNAVAIL'
     numeric value `-1'

`NSS_STATUS_NOTFOUND'
     numeric value `0'

`NSS_STATUS_SUCCESS'
     numeric value `1'

Now you see where the action items of the `/etc/nsswitch.conf' file are
used.

   If you study the source code you will find there is a fifth value:
`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 `*ERRNOP'.  Some return status
value have only one associated error code, others have more.

`NSS_STATUS_TRYAGAIN'   `EAGAIN'      One of the functions used ran
                                      temporarily out of resources or a
                                      service is currently not available.
                       `ERANGE'       The provided buffer is not large
                                      enough.  The function should be
                                      called again with a larger buffer.
`NSS_STATUS_UNAVAIL'    `ENOENT'      A necessary input file cannot be
                                      found.
`NSS_STATUS_NOTFOUND'   `ENOENT'      The requested entry is not
                                      available.

   These are proposed values.  There can be other error codes and the
described error codes can have different meaning.  *With one
exception:* when returning `NSS_STATUS_TRYAGAIN' the error code
`ERANGE' _must_ mean that the user provided buffer is too small.
Everything is non-critical.

   The above function has something special which is missing for almost
all the other module functions.  There is an argument 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.  The reentrant
function cannot use the global variable H_ERRNO; `gethostbyname' calls
`gethostbyname_r' with the last argument set to `&h_errno'.

   The `getXXXbyYYY' 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
`setpwent', `getpwent', and `endpwent').  These will be described in
more detail later.  Here we give a general way to determine the
signature of the module function:

   * the return value is `int';

   * the name is as explained in Note: NSS Module Names;

   * the first arguments are identical to the arguments of the
     non-reentrant function;

   * the next three arguments are:

    `STRUCT_TYPE *result_buf'
          pointer to buffer where the result is stored.  `STRUCT_TYPE'
          is normally a struct which corresponds to the database.

    `char *buffer'
          pointer to a buffer where the function can store additional
          data for the result etc.

    `size_t buflen'
          length of the buffer pointed to by BUFFER.

   * possibly a last argument H_ERRNOP, for the host name and network
     name lookup functions.

This table is correct for all functions but the `set...ent' and
`end...ent' functions.