From patchwork Fri Sep 23 12:21:21 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 15949 Received: (qmail 2086 invoked by alias); 23 Sep 2016 12:21:26 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 2066 invoked by uid 89); 23 Sep 2016 12:21:25 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-5.0 required=5.0 tests=BAYES_00, RP_MATCHES_RCVD, SPF_HELO_PASS autolearn=ham version=3.3.2 spammy=vtable, yyy, examine, xxx X-HELO: mx1.redhat.com Subject: Re: [PATCH] manual: Clarify NSS error reporting To: libc-alpha@sourceware.org References: From: Florian Weimer Message-ID: Date: Fri, 23 Sep 2016 14:21:21 +0200 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.3.0 MIME-Version: 1.0 In-Reply-To: On 09/13/2016 02:13 PM, Florian Weimer wrote: > This is prompted by bug 20532. It turns out that the manual was already > pretty clear about error-reporting requirements. > > The new specification does not require that h_errnop must not be set to > zero; I believe the variable is different from errno in this regard. This is what I committed. There was a note mentioning three inserted arguments, but there are actually four. Thanks, Florian manual: Clarify NSS error reporting The manual already required that NSS implementation functions set error codes if they return a value that is not NSS_STATUS_SUCCESS, but this was not very explicit. The errnop parameter was omitted in a few places, and the function return value was incorrect. 2016-09-23 Florian Weimer * manual/nss.texi (NSS Modules Interface): Adjust function return type to enum nss_status. Document errnop argument. Clarify h_errnop semantics. Fix cross-reference formatting. (NSS Module Function Internals): Mention that *errnop needs to be set on failure, but not to zero. diff --git a/manual/nss.texi b/manual/nss.texi index 2770fed..e6bfd96 100644 --- a/manual/nss.texi +++ b/manual/nss.texi @@ -445,9 +445,10 @@ enum nss_status _nss_files_gethostbyname_r (const char *name, @end smallexample I.e., the interface function is in fact the reentrant function with the -change of the return value and the omission of the @var{result} -parameter. While the user-level function returns a pointer to the -result the reentrant function return an @code{enum nss_status} value: +change of the return value, the omission of the @var{result} parameter, +and the addition of the @var{errnop} parameter. While the user-level +function returns a pointer to the result the reentrant function return +an @code{enum nss_status} value: @vtable @code @item NSS_STATUS_TRYAGAIN @@ -507,13 +508,16 @@ 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. +In statically linked programs, the main application and NSS modules do +not share the same thread-local variable @code{errno}, which is the +reason why there is an explicit @var{errnop} function argument. + 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}. +the execution of the function fails for some reason. (In statically +linked programs, the thread-local variable @code{h_errno} is not shared +with the main application.) The @code{get@var{XXX}by@var{YYY}} functions are the most important functions in the NSS modules. But there are others which implement @@ -525,14 +529,14 @@ signature of the module function: @itemize @bullet @item -the return value is @code{int}; +the return value is @code{enum nss_status}; @item -the name is as explained in @pxref{NSS Module Names}; +the name (@pxref{NSS Module Names}); @item the first arguments are identical to the arguments of the non-reentrant function; @item -the next three arguments are: +the next four arguments are: @table @code @item STRUCT_TYPE *result_buf @@ -543,11 +547,21 @@ pointer to a buffer where the function can store additional data for the result etc. @item size_t buflen length of the buffer pointed to by @var{buffer}. +@item int *errnop +the low-level error code to return to the application. If the return +value is not @code{NSS_STATUS_SUCCESS}, @code{*@var{errnop}} needs to be +set to a non-zero value. An NSS module should never set +@code{*@var{errnop}} to zero. The value @code{ERANGE} is special, as +described above. @end table @item possibly a last argument @var{h_errnop}, for the host name and network -name lookup functions. +name lookup functions. If the return value is not +@code{NSS_STATUS_SUCCESS}, @code{*@var{h_errnop}} needs to be set to a +non-zero value. A generic error code is @code{NETDB_INTERNAL}, which +instructs the caller to examine @code{*@var{errnop}} for further +details. (This includes the @code{ERANGE} special case.) @end itemize @noindent @@ -672,10 +686,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. -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. +Before the function returns with a failure code, 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. The stored value must not be +zero. As explained above this function could also have an additional last argument. This depends on the database used; it happens only for