Go to the first, previous, next, last section, table of contents.
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)
). section 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 (see section The Interface of the Function in NSS Modules).
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 honour 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
(see section The Interface of the Function in NSS Modules).
Go to the first, previous, next, last section, table of contents.