aboutsummaryrefslogtreecommitdiff
path: root/manual/nss.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/nss.texi')
-rw-r--r--manual/nss.texi32
1 files changed, 30 insertions, 2 deletions
diff --git a/manual/nss.texi b/manual/nss.texi
index 282127cc36..dd8aa9e210 100644
--- a/manual/nss.texi
+++ b/manual/nss.texi
@@ -433,13 +433,41 @@ If you study the source code you will find there is a fifth value:
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 @code{*@var{errnop}}. Some
+return status value have only one associated error code, others have
+more.
+
+@multitable @columnfractions .3 .2 .50
+@item
+@code{NSS_STATUS_TRYAGAIN} @tab
+ @code{EAGAIN} @tab One functions used ran temporarily out of
+resources or a service is currently not available.
+@item
+@tab
+ @code{ERANGE} @tab The provided buffer is not large enough.
+The function should be called again with a larger buffer.
+@item
+@code{NSS_STATUS_UNAVAIL} @tab
+ @code{ENOENT} @tab A necessary input file cannot be found.
+@item
+@code{NSS_STATUS_NOTFOUND} @tab
+ @code{ENOENT} @tab The requested entry is not available.
+@end multitable
+
+These are proposed values. There can be other error codes and the
+described error codes can have different meaning. @strong{With one
+exception:} when returning @code{NSS_STATUS_TRYAGAIN} the error code
+@code{ERANGE} @emph{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 @var{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 @var{h_errno};
-@code{gethostbyname} calls @code{gethostbyname_r} with the
-last argument set to @code{&h_errno}.
+@code{gethostbyname} calls @code{gethostbyname_r} with the last argument
+set to @code{&h_errno}.
The @code{get@var{XXX}by@var{YYY}} functions are the most important
functions in the NSS modules. But there are others which implement