(NSS Module Function Internals): Document new NSS module function interface.
authordrepper <drepper>
Fri, 16 Oct 1998 11:12:02 +0000 (11:12 +0000)
committerdrepper <drepper>
Fri, 16 Oct 1998 11:12:02 +0000 (11:12 +0000)
manual/nss.texi

index f6293c0..e1981e8 100644 (file)
@@ -511,10 +511,10 @@ 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.
 new service module consists solely of the interface functions.
 
 Each module is designed following a specific interface specification.
-For now the version is 1 and this manifests in the version number of the
-shared library object of the NSS modules: they have the extension
-@code{.1}.  If the interface ever changes in an incompatible way,
-this number will be increased---hopefully this will never be necessary.
+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
 Modules using the old interface will still be usable.
 
 Developers of a new service will have to make sure that their module is
@@ -524,7 +524,7 @@ 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
 of object files on an ELF system using GNU CC could be done like this:
 
 @smallexample
-gcc -shared -o libnss_NAME.so.1 -Wl,-soname,libnss_NAME.so.1 OBJECTS
+gcc -shared -o libnss_NAME.so.2 -Wl,-soname,libnss_NAME.so.2 OBJECTS
 @end smallexample
 
 @noindent
 @end smallexample
 
 @noindent
@@ -581,7 +581,7 @@ a simple noop.
 
 There normally is no return value different to @var{NSS_STATUS_SUCCESS}.
 
 
 There normally is no return value different to @var{NSS_STATUS_SUCCESS}.
 
-@item enum nss_status _nss_@var{database}_get@var{db}ent_r (@var{STRUCTURE} *result, char *buffer, size_t buflen)
+@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
 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
@@ -598,6 +598,11 @@ 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.
 
 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 @var{errno} variable in the variable pointed to be
+@var{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
 @code{host} and @code{networks}.
 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}.
@@ -610,7 +615,7 @@ returned.  When the service was not formerly initialized by a call to
 @code{_nss_@var{DATABASE}_set@var{db}ent} all return value allowed for
 this function can also be returned here.
 
 @code{_nss_@var{DATABASE}_set@var{db}ent} all return value 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)
+@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
 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
@@ -626,6 +631,11 @@ to non-constant global data.
 The implementation of this function should honour the @var{stayopen}
 flag set by the @code{set@var{DB}ent} function whenever this makes sense.
 
 The implementation of this function should honour 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 be
+@var{errnop}.  This is important to guarantee the module working in
+statically linked programs.
+
 Again, this function takes an additional last argument for the
 @code{host} and @code{networks} database.
 
 Again, this function takes an additional last argument for the
 @code{host} and @code{networks} database.