Re: nss.texi patch for review

["Carlos O'Donell" <carlos at redhat dot com>]

On 09/04/2014 12:50 AM, ricaljasan wrote:
> I am preparing a patch for the glibc manual and would like to offer my
> first attempt at revision for review. I've edited the manual/nss.texi
> file. The diff was obtained from `git diff'. It appears to meet the
> criteria in section 13 of
> https://sourceware.org/glibc/wiki/Contribution%20checklist, but I wanted
> to make sure that was OK.

Your diff looks great. We always want more contributions to the manual!

Off the top, your patch has one high-level structural problem: You mix
typos and grammar fixes with new content.

Please split the patch into two patches. One for typos and grammar
fixes which we can check in quickly, and a second with new text.

I can check this in for you once it's ready.

> There are some places where reading only the diff doesn't do the edits
> justice, so I wanted to mention those. In "The NSS Configuration File"
> section, the language was a little ambiguous to me. The word "action"
> seemed to be used for a handful of things, so I tried to rearrange or
> word things so they were clearer in context. In general, I tried to make
> the language more consistent throughout the chapter.
> 
> There are some comments near the end of the diff which I expect to
> remove before any commit; they are there for my reference at this time,
> but I have left them in case somebody who reviews this knows the answer
> to the questions within them. I'll be inspecting the source further to
> see if I can answer them myself, but since this email is only intended
> as a preliminary review, I thought it wouldn't hurt to leave them.
> 
> There are quite a few purely grammatical edits. I always appreciate
> well-written documentation and I think (hope) most of them do contribute
> to the document's clarity. I've tried not to add anything like
> superfluous commas (but no guarantees, as those can be a matter of taste
> - another aspect I hope to address with this review).
> 
> I believe I've dialed in Thunderbird to send mail according to the
> specifications in the third point of section 13 of the the above URL. I
> have sent myself some test messages to verify Content-Type is
> text/x-patch and the Content-Disposition is inline rather than
> attachment. The charset is only specified for the message body, but it
> is utf-8. Let me know if anything was wrong.

Mail looks good.

> I also have some questions about the overall process. Do I create a
> Changelog entry or does the developer who approves and commits my patch?
> Since a developer commits the patch, I don't have anything to do with
> the git commit log, correct? Hopefully I'm understanding that much of
> the procedure.

(a) You write the ChangeLog entry yourself. And include it in your
    email. I can write the entry for you this firs time if you want:

e.g.

2014-09-04  Rical Jasan  <ricaljasan@pacific.net>

	* manual/nss.texi (Name Service Switch): Fix typos, grammar,
	and make style consistent.

Followed by:

2014-09-04  Rical Jasan  <ricaljasan@pacific.net>

	* manual/nss.texi (Name Service Switch): Expand documentation
	and clarify where appropriate.


(b) The developer who commits your patch will likely use your email
    body as the commit message, so structure it so it reads like a good
    commit message.

> Lastly, the subject of the email doesn't conform to section 2 of the
> above URL because I'm only posting this for review, but that will be
> adjusted accordingly.
> 
> Thank you for taking the time to help.
> 
> Rical Jasan
 
 
> diff --git a/manual/nss.texi b/manual/nss.texi
> index bf3e69d..00eb173 100644
> --- a/manual/nss.texi
> +++ b/manual/nss.texi
> @@ -12,12 +12,12 @@ Network Information Service (NIS) and the Domain Name Service (DNS))
>  became popular, and were hacked into the C library, usually with a fixed
>  search order.
>  
> -@Theglibc{} contains a cleaner solution of this problem.  It is
> +@Theglibc{} contains a cleaner solution to this problem.  It is

OK.

>  designed after a method used by Sun Microsystems in the C library of
>  @w{Solaris 2}.  @Theglibc{} follows their name and calls this
>  scheme @dfn{Name Service Switch} (NSS).
>  
> -Though the interface might be similar to Sun's version there is no
> +Though the interface might be similar to Sun's version, there is no

OK.

>  common code.  We never saw any source code of Sun's implementation and
>  so the internal interface is incompatible.  This also manifests in the
>  file names we use as we will see later.
> @@ -46,7 +46,7 @@ The modules can be updated separately.
>  The C library image is smaller.
>  @end enumerate
>  
> -To fulfill the first goal above the ABI of the modules will be described
> +To fulfill the first goal above, the ABI of the modules will be described

OK.

>  below.  For getting the implementation of a new service right it is
>  important to understand how the functions in the modules get called.
>  They are in no way designed to be used by the programmer directly.
> @@ -68,7 +68,7 @@ The databases available in the NSS are
>  @cindex shadow
>  @vtable @code
>  @item aliases
> -Mail aliases
> +Mail aliases,

OK. All list items use commas.

>  @comment @pxref{Mail Aliases}.
>  @item ethers
>  Ethernet numbers,
> @@ -78,7 +78,7 @@ Groups of users, @pxref{Group Database}.
>  @item hosts
>  Host names and numbers, @pxref{Host Names}.
>  @item netgroup
> -Network wide list of host and users, @pxref{Netgroup Database}.
> +Network-wide list of hosts and users, @pxref{Netgroup Database}.

OK.

>  @item networks
>  Network names and numbers, @pxref{Networks Database}.
>  @item protocols
> @@ -91,7 +91,7 @@ Remote procedure call names and numbers,
>  @item services
>  Network services, @pxref{Services Database}.
>  @item shadow
> -Shadow user passwords,
> +Shadow user passwords

OK. End of list no comma.

>  @comment @pxref{Shadow Password Database}.
>  @end vtable
>  
> @@ -106,26 +106,26 @@ There will be some more added later (@code{automount}, @code{bootparams},
>  @cindex @file{nsswitch.conf}
>  Somehow the NSS code must be told about the wishes of the user.  For
>  this reason there is the file @file{/etc/nsswitch.conf}.  For each
> -database this file contain a specification how the lookup process should
> +database, this file contains a specification of how the lookup process should

OK.

>  work.  The file could look like this:
>  
>  @example
>  @include nsswitch.texi
>  @end example
>  
> -The first column is the database as you can guess from the table above.
> +The first column is the database, as seen in the table above.

OK.

>  The rest of the line specifies how the lookup process works.  Please
>  note that you specify the way it works for each database individually.
>  This cannot be done with the old way of a monolithic implementation.
>  
>  The configuration specification for each database can contain two
> -different items:
> +different types of items:

OK.

>  
>  @itemize @bullet
>  @item
> -the service specification like @code{files}, @code{db}, or @code{nis}.
> +a service specification, like @code{files}, @code{db}, or @code{nis}.

OK.

>  @item
> -the reaction on lookup result like @code{[NOTFOUND=return]}.
> +an action taken on lookup result, like @code{[NOTFOUND=return]}.

OK.

>  @end itemize
>  
>  @menu
> @@ -138,10 +138,10 @@ the reaction on lookup result like @code{[NOTFOUND=return]}.
>  @node Services in the NSS configuration, Actions in the NSS configuration, NSS Configuration File, NSS Configuration File
>  @subsection Services in the NSS configuration File
>  
> +The first type of item in the configuration specification is a service.

OK.

>  The above example file mentions five different services: @code{files},
>  @code{db}, @code{dns}, @code{nis}, and @code{nisplus}.  This does not
> -mean these
> -services are available on all sites and it does also not mean these are
> +mean these services are available on all sites nor does it mean these are
>  all the services which will ever be available.

OK.

>  
>  In fact, these names are simply strings which the NSS code uses to find
> @@ -149,10 +149,10 @@ the implicitly addressed functions.  The internal interface will be
>  described later.  Visible to the user are the modules which implement an
>  individual service.
>  
> -Assume the service @var{name} shall be used for a lookup.  The code for
> -this service is implemented in a module called @file{libnss_@var{name}}.
> -On a system supporting shared libraries this is in fact a shared library
> -with the name (for example) @file{libnss_@var{name}.so.2}.  The number
> +Assume the service @var{service} shall be used for a lookup.  The code for
> +this service is implemented in a module called @file{libnss_@var{service}}.
> +On a system supporting shared libraries, the module is a shared library
> +with the name (for example) @file{libnss_@var{service}.so.2}.  The number

OK. I like the use of "service" better than "name."

>  at the end is the currently used version of the interface which will not
>  change frequently.  Normally the user should not have to be cognizant of
>  these files since they should be placed in a directory where they are
> @@ -162,9 +162,10 @@ important.
>  @node Actions in the NSS configuration, Notes on NSS Configuration File, Services in the NSS configuration, NSS Configuration File
>  @subsection Actions in the NSS configuration
>  
> -The second item in the specification gives the user much finer control
> -on the lookup process.  Action items are placed between two service
> -names and are written within brackets.  The general form is
> +The second type of item in the configuration specification is an action.
> +The action construct gives the user much finer control over the lookup
> +process.  Action items are placed between two service names and are
> +written within brackets.  The general form is

OK.

>  
>  @display
>  @code{[} ( @code{!}? @var{status} @code{=} @var{action} )+ @code{]}
> @@ -226,73 +227,90 @@ ethers: nisplus [SUCCESS=return NOTFOUND=return UNAVAIL=continue
>  value for the actions are normally what you want, and only need to be
>  changed in exceptional cases.
>  
> -If the optional @code{!} is placed before the @var{status} this means
> -the following action is used for all statuses but @var{status} itself.
> -I.e., @code{!} is negation as in the C language (and others).
> +If the optional @code{!} is placed before the @var{status}, this means
> +the following @var{action} is used for all statuses but @var{status}
> +itself.  I.e., @code{!} is negation as in the C language (and others).
> +For example, the default action set could also be written

OK.

>  
> -Before we explain the exception which makes this action item necessary
> -one more remark: obviously it makes no sense to add another action
> -item after the @code{files} service.  Since there is no other service
> -following the action @emph{always} is @code{return}.
> +@smallexample
> +[SUCCESS=return !SUCCESS=continue]
> +@end smallexample
> +
> +Note how there is no action construct following the @code{files} service.
> +Since there is no other service after it, the action is @emph{always}
> +@code{return}.

OK. Much better. I hope you plan to continue contributing :-)

>  
>  @cindex nisplus, and completeness
> -Now, why is this @code{[NOTFOUND=return]} action useful?  To understand
> -this we should know that the @code{nisplus} service is often
> -complete; i.e., if an entry is not available in the NIS+ tables it is
> -not available anywhere else.  This is what is expressed by this action
> -item: it is useless to examine further services since they will not give
> -us a result.
> +You may be wondering why the @code{[NOTFOUND=return]} action is useful.
> +The @code{nisplus} service is often complete; i.e., if an entry is not
> +available in the NIS+ tables, it is not available anywhere else.
> +This action item is equivalent to stating it is useless to examine
> +further services, since they will not give us a result.

OK.

>  
>  @cindex nisplus, and booting
>  @cindex bootstrapping, and services
>  The situation would be different if the NIS+ service is not available
> -because the machine is booting.  In this case the return value of the
> -lookup function is not @code{notfound} but instead @code{unavail}.  And
> -as you can see in the complete form above: in this situation the
> +because the machine is booting.  In this case, the return value of the
> +lookup function is not @code{notfound} but instead @code{unavail}.
> +As you can see in the example configuration above, in this situation the

OK. I dislike starting sentences with coordinating conjunctions only because
it looks sloppy, so I also prefer starting with "As." You could use a
conjunctive adverb if you wanted, like "furthermore," but that reads slightly
pretentious and overly verbose.

>  @code{db} and @code{files} services are used.  Neat, isn't it?  The
>  system administrator need not pay special care for the time the system
> -is not completely ready to work (while booting or shutdown or
> +is not completely ready to work (during boot, shutdown, or while having

OK.

>  network problems).
>  
>  
>  @node Notes on NSS Configuration File,  , Actions in the NSS configuration, NSS Configuration File
>  @subsection Notes on the NSS Configuration File
>  
> -Finally a few more hints.  The NSS implementation is not completely
> -helpless if @file{/etc/nsswitch.conf} does not exist.  For
> -all supported databases there is a default value so it should normally
> +Finally, a few more hints.  First, the NSS implementation is not
> +completely helpless if @file{/etc/nsswitch.conf} does not exist.  For
> +all supported databases there is a default value, so it should normally

OK.

>  be possible to get the system running even if the file is corrupted or
>  missing.
>  
>  @cindex default value, and NSS
> -For the @code{hosts} and @code{networks} databases the default value is
> -@code{dns [!UNAVAIL=return] files}.  I.e., the system is prepared for
> -the DNS service not to be available but if it is available the answer it
> -returns is definitive.
> +For the @code{hosts} and @code{networks} databases, the default value is
> +
> +@smallexample
> +dns [!UNAVAIL=return] files
> +@end smallexample
> +
> +@noindent
> +i.e., the system is prepared for the DNS service to not be available,
> +but if it is, the answer it returns is definitive.

OK. Much better.

>  
>  The @code{passwd}, @code{group}, and @code{shadow} databases are
>  traditionally handled in a special way.  The appropriate files in the
> -@file{/etc} directory are read but if an entry with a name starting
> -with a @code{+} character is found NIS is used.  This kind of lookup
> -remains possible by using the special lookup service @code{compat}
> -and the default value for the three databases above is
> -@code{compat [NOTFOUND=return] files}.
> +@file{/etc} directory are read, but if an entry with a name starting
> +with a @code{+} character is found, NIS is used.  This kind of lookup
> +remains possible by using the special lookup service @code{compat}.
> +The default value for the three databases above is
> +
> +@smallexample
> +compat [NOTFOUND=return] files
> +@end smallexample

OK.

>  
>  For all other databases the default value is
> -@code{nis [NOTFOUND=return] files}.  This solution give the best
> -chance to be correct since NIS and file based lookup is used.
> +
> +@smallexample
> +nis [NOTFOUND=return] files
> +@end smallexample
> +
> +@noindent
> +This solution gives the best chance to be correct since NIS and
> +file-based lookups are used.

OK.

>  
>  @cindex optimizing NSS
> -A second point is that the user should try to optimize the lookup
> -process.  The different service have different response times.
> -A simple file look up on a local file could be fast, but if the file
> +A second hint is that the user should try to optimize the lookup
> +process.  The different services have different response times.
> +A simple file lookup on a local file could be fast, but if the file

OK.

>  is long and the needed entry is near the end of the file this may take
>  quite some time.  In this case it might be better to use the @code{db}
>  service which allows fast local access to large data sets.
>  
> -Often the situation is that some global information like NIS must be
> -used.  So it is unavoidable to use service entries like @code{nis} etc.
> -But one should avoid slow services like this if possible.
> +Often, the situation is that some global information like NIS must be
> +used, so using service entries like @code{nis} is unavoidable.
> +However, one should avoid slow services like this if possible.

OK.

>  
>  
>  @node NSS Module Internals, Extending NSS, NSS Configuration File, Name Service Switch
> @@ -316,14 +334,14 @@ interested in this topic should read about Dynamic Linking.
>  @subsection The Naming Scheme of the NSS Modules
>  
>  @noindent
> -The name of each function consist of various parts:
> +The name of each function consists of various parts:

OK.

>  
>  @quotation
>         _nss_@var{service}_@var{function}
>  @end quotation
>  
> -@var{service} of course corresponds to the name of the module this
> -function is found in.@footnote{Now you might ask why this information is
> +@var{service} corresponds to the name of the module this
> +function is found in.@footnote{Now, you might ask why this information is

OK.

>  duplicated.  The answer is that we want to make it possible to link
>  directly with these shared objects.}  The @var{function} part is derived
>  from the interface function in the C library itself.  If the user calls
> @@ -342,32 +360,32 @@ in the module
>  @end smallexample
>  
>  @noindent
> +is used.
> +

OK.

>  @cindex reentrant NSS functions
> -is used.  You see, what is explained above in not the whole truth.  In
> -fact the NSS modules only contain reentrant versions of the lookup
> -functions.  I.e., if the user would call the @code{gethostbyname_r}
> -function this also would end in the above function.  For all user
> -interface functions the C library maps this call to a call to the
> +The NSS modules only contain reentrant versions of the lookup
> +functions.  I.e., if the user calls the @code{gethostbyname_r}
> +function, the function above is also called.  For all user
> +interface functions, the C library maps the call to a call to the
>  reentrant function.  For reentrant functions this is trivial since the
> -interface is (nearly) the same.  For the non-reentrant version The
> +interface is (nearly) the same.  For the non-reentrant version, the
>  library keeps internal buffers which are used to replace the user
>  supplied buffer.
>  
> -I.e., the reentrant functions @emph{can} have counterparts.  No service
> -module is forced to have functions for all databases and all kinds to
> -access them.  If a function is not available it is simply treated as if
> +The reentrant functions @emph{can} have counterparts.  No service
> +module is forced to have all functions for all databases.
> +If a function is not available it is simply treated as if
>  the function would return @code{unavail}
>  (@pxref{Actions in the NSS configuration}).

OK.

>  
> -The file name @file{libnss_files.so.2} would be on a @w{Solaris 2}
> -system @file{nss_files.so.2}.  This is the difference mentioned above.
> -Sun's NSS modules are usable as modules which get indirectly loaded
> -only.
> +On a @w{Solaris 2} system , the file name @file{libnss_files.so.2}
> +would be @file{nss_files.so.2}.  Sun's NSS modules are usable as
> +modules which get indirectly loaded only.

OK.

>  
>  The NSS modules in @theglibc{} are prepared to be used as normal
> -libraries themselves.  This is @emph{not} true at the moment, though.
> +libraries themselves, although this is @emph{not} true at the moment.
>  However,  the organization of the name space in the modules does not make it
> -impossible like it is for Solaris.  Now you can see why the modules are
> +impossible like it is for Solaris.  That is why the modules are

OK. I kike the more formal and less verbose tone.

>  still libraries.@footnote{There is a second explanation: we were too
>  lazy to change the Makefiles to allow the generation of shared objects
>  not starting with @file{lib} but don't tell this to anybody.}
> @@ -376,11 +394,11 @@ not starting with @file{lib} but don't tell this to anybody.}
>  @node NSS Modules Interface,  , NSS Module Names, NSS Module Internals
>  @subsection 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:
> +Now that we know how the functions contained in the modules are named,
> +it is time to describe their interface.  There are some additional
> +arguments to the reentrant versions of the functions above, compared
> +with the standard, non-reentrant versions.  The prototypes for
> +the non-reentrant and reentrant versions of the example function are:

OK.

>  
>  @smallexample
>  struct hostent *gethostbyname (const char *name)
> @@ -400,10 +418,11 @@ enum nss_status _nss_files_gethostbyname_r (const char *name,
>                                              int *errnop, int *h_errnop)
>  @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:
> +The module interface function is the reentrant function with a
> +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 module's reentrant
> +function returns an @code{enum nss_status} value:

OK.

>  
>  @vtable @code
>  @item NSS_STATUS_TRYAGAIN
> @@ -423,14 +442,14 @@ numeric value @code{1}
>  Now you see where the action items of the @file{/etc/nsswitch.conf} file
>  are used.
>  
> -If you study the source code you will find there is a fifth value:
> +If you study the source code, you will find there is a fifth value:
>  @code{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.
> +few functions in places where none of the above values 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
> +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
> +return status values have only one associated error code; others have
>  more.
>  
>  @multitable @columnfractions .3 .2 .50
> @@ -444,17 +463,17 @@ resources or a service is currently not available.
>  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.
> +        @code{ENOENT} @tab The requested entry is not available.

Haven't verified this yet.

>  @item
>  @code{NSS_STATUS_NOTFOUND} @tab
> -        @code{ENOENT} @tab The requested entry is not available.
> +        @code{ENOENT} @tab A necessary input file cannot be found.
>  @end multitable

Haven't verified this yet.

>  
>  These are proposed values.  There can be other error codes and the
> -described error codes can have different meaning.  @strong{With one
> +error codes described above can have different meanings.  @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.
> +@code{ERANGE} @emph{must} mean that the user-provided buffer is too
> +small.  Everything else is non-critical.

OK. Good use of `-'.

>  The above function has something special which is missing for almost all
>  the other module functions.  There is an argument @var{h_errnop}.  This
> @@ -469,8 +488,8 @@ 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 @code{setpwent}, @code{getpwent}, and
>  @code{endpwent}).  These will be described in more detail later.
> -Here we give a general way to determine the
> -signature of the module function:
> +Here, we give a general way to determine the signature of a module
> +function:

OK.

>  @itemize @bullet
>  @item
> @@ -520,7 +539,7 @@ databases s/he is interested in and leave the rest for later (or
>  completely aside).
>  
>  @menu
> -* Adding another Service to NSS::  What is to do to add a new service.
> +* Adding Another Service to NSS::  How to add a new service.

OK. Thank you for that new menu title :}

>  * NSS Module Function Internals::  Guidelines for writing new NSS
>                                          service functions.
>  @end menu
> @@ -530,8 +549,8 @@ completely aside).
>  
>  The sources for a new service need not (and should not) be part of @theglibc{}
>  itself.  The developer retains complete control over the
> -sources and its development.  The links between the C library and the
> -new service module consists solely of the interface functions.
> +sources and their development.  The links between the C library and the
> +new service module consist solely of the interface functions.

OK.

>  
>  Each module is designed following a specific interface specification.
>  For now the version is 2 (the interface in version 1 was not adequate)
> @@ -586,7 +605,7 @@ database (e.g., it is @code{pw} for the password database).
>  @table @code
>  @item enum nss_status _nss_@var{database}_set@var{db}ent (void)
>  This function prepares the service for following operations.  For a
> -simple file based lookup this means files could be opened, for other
> +simple file-based lookup this means files could be opened; for other

OK.

>  services this function simply is a noop.
>  
>  One special case for this function is that it takes an additional
> @@ -621,22 +640,27 @@ 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
> +Before the function returns, the implementation should store the value
> +of the local @var{errno} variable in the variable pointed to by
> +@var{errnop}.  This is important to guarantee the module works in

OK.

>  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, @var{h_errnop}.  This depends on the database used; it happens
> +only for @code{host} and @code{networks}.

OK.

>  
> +@comment Shouldn't it return SUCCESS on a match, even if it
> +@comment were the last entry, and NOTFOUND if the last entry
> +@comment was read _and_ there were no matches?

Haven't verified yet.

>  The function shall return @code{NSS_STATUS_SUCCESS} as long as there are
> -more entries.  When the last entry was read it should return
> +more entries.  If the last entry was read, it should return
>  @code{NSS_STATUS_NOTFOUND}.  When the buffer given as an argument is too
> -small for the data to be returned @code{NSS_STATUS_TRYAGAIN} should be
> -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
> +small for the data to be returned, @code{NSS_STATUS_TRYAGAIN} should be
> +returned.  When the service was not previously initialized by a call to
> +@code{_nss_@var{DATABASE}_set@var{db}ent}, all return values allowed for

OK.

>  this function can also be returned here.
> +@comment Does that mean it's possible to return SUCCESS
> +@comment even if the service has not been initialized?

Haven't verified yet.

>  
>  @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
> @@ -648,21 +672,21 @@ are here described by @var{PARAMS}.
>  The result must be stored in the structure pointed to by @var{result}.
>  If there is additional data to return (say strings, where the
>  @var{result} structure only contains pointers) the function must use the
> -@var{buffer} or length @var{buflen}.  There must not be any references
> +@var{buffer} of length @var{buflen}.  There must not be any references
>  to non-constant global data.
>  
>  The implementation of this function should honor 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
> +Before the function returns, the implementation should store the value of
> +the local @var{errno} variable in the variable pointed to by
> +@var{errnop}.  This is important to guarantee the module works in
>  statically linked programs.
>  
>  Again, this function takes an additional last argument for the
> -@code{host} and @code{networks} database.
> +@code{host} and @code{networks} databases, @var{h_errnop}.
>  
> -The return value should as always follow the rules given above
> +The return value should always follow the rules given above

OK.

>  (@pxref{NSS Modules Interface}).
>  
>  @end table

In summary:
- Split this into two or more patches.
- At least one for easy typo and grammar fixes.
- Another patch for substantive changes.
- Post to libc-alpha and I'll review again and try to get
  answers for your questions.

Cheers,
Carlos.