nscd.conf.5: describe reloading, clarifications

  - Added a subsection of NOTES describing nscd's reloading behavior
  and providing advice on how to configure it.
- Clarifications for the threads, reload-count, positive-time-to-live,
  check-files, and shared attributes.

Derived by reading the nscd, libresolv and glibc source and some painful experience.
  

Hello Greg,

On 7/28/21 12:09 AM, Greg Banks wrote:
> - Added a subsection of NOTES describing nscd's reloading behavior
>    and providing advice on how to configure it.
> - Clarifications for the threads, reload-count, positive-time-to-live,
>    check-files, and shared attributes.
> 
> Derived by reading the nscd, libresolv and glibc source and some painful experience.

Thanks for the patch.

Please see some comments below.

Thanks,

Alex

> 
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..52f7051d5 100644
> --- a/man5/nscd.conf.5
> +++ b/man5/nscd.conf.5
> @@ -1,5 +1,6 @@
>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>   .\"
>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>   .\" This program is free software; you can redistribute it and/or
> @@ -53,9 +54,12 @@ The default is 0.
>   .B threads
>   .I number
>   .RS
> -This is the number of threads that are started to wait for
> +This is the initial number of threads that are started to wait for
>   requests.
> -At least five threads will always be created.
> +At least five threads will always be created.  The number of threads
> +may increase dynamically up to
> +.B max\-threads
> +in response to demand from clients, but never decreases.
>   .RE
>   .PP
>   .B max\-threads
> @@ -83,9 +87,15 @@ Specifies the user who is allowed to request statistics.
>   unlimited |
>   .I number
>   .RS
> -Limit on the number of times a cached entry gets reloaded without being used
> -before it gets removed.
> -The default is 5.
> +Sets a limit on the number of times a cached entry gets reloaded without being used


See the following extract from man-pages(7):

$ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
    Use semantic newlines
        In the source of a manual page,  new  sentences  should  be
        started  on new lines, and long sentences should split into
        lines at clause breaks (commas, semicolons, colons, and  so
        on).   This  convention,  sometimes known as "semantic new‐
        lines", makes it easier to see the effect of patches, which
        often  operate at the level of individual sentences or sen‐
        tence clauses.

> +before it gets removed.  The limit can take values ranging from 0
> +to 254; values 255 or higher behave the same as
> +.BR unlimited .
> +Limit values can be specified in either decimal or hexadecimal with a
> +"0x" prefix.  The special value
> +.B unlimited
> +is case-insensitive.  The default limit is 5.  A limit of 0 turns off the reloading
> +feature.  See NOTES below for further discussion of reloading.
>   .RE
>   .PP
>   .B paranoia
> @@ -128,6 +138,9 @@ in the specified cache for
>   is in seconds.
>   Larger values increase cache hit rates and reduce mean
>   response times, but increase problems with cache coherence.
> +Note that for some name services (including specifically DNS)
> +the TTL returned from the name service is used and this attribute
> +is ignored.
>   .RE
>   .PP
>   .B negative\-time\-to\-live
> @@ -166,6 +179,7 @@ The files are
>   .IR /etc/passwd ,
>   .IR /etc/group ,
>   .IR /etc/hosts ,
> +.IR /etc/resolv.conf ,
>   .IR /etc/services ,
>   and
>   .IR /etc/netgroup .
> @@ -194,6 +208,8 @@ is shared with the clients so
>   that they can directly search in them instead of having to ask the
>   daemon over the socket each time a lookup is performed.
>   The default is no.
> +Note that a cache miss will still result in asking the daemon over
> +the socket.
>   .RE
>   .PP
>   .B max\-db\-size
> @@ -230,12 +246,82 @@ and
>   .IR group .
>   .RE
>   .SH NOTES
> +.PP
>   The default values stated in this manual page originate
>   from the source code of
>   .BR nscd (8)
>   and are used if not overridden in the configuration file.
>   The default values used in the configuration file of
>   your distribution might differ.
> +.SS Reloading
> +.PP
> +.BR nscd (8)
> +has a feature called reloading whose behavior can be surprising.
> +.PP
> +Reloading is enabled when the
> +.B reload-count
> +attribute has a non-zero value.  The default value in the source
> +code enables reloading, although your distribution may differ.
> +.PP
> +When
> +reloading is enabled, positive cached entries (the results of
> +successful queries) do not simply expire when their TTL is up.  Instead,
> +at the expiry time
> +.B nscd
> +will "reload", i.e. re-issue the same name service query that created the cached
> +entry, to get a new value to cache.  Depending on
> +.B /etc/nsswitch.conf

Also from man-pages(7):

    Formatting conventions (general)
[...]

        Filenames  (whether  pathnames,  or  references  to  header
        files) are always in italics (e.g., <stdio.h>),  except  in
        the  SYNOPSIS  section,  where  included  files are in bold
        (e.g., #include <stdio.h>).  When referring to  a  standard
        header  file include, specify the header file surrounded by
        angle brackets, in the usual C way (e.g., <stdio.h>).


> +this may mean that a DNS, LDAP or NIS request is made.  If the new query
> +is successful reloading will repeat
> +when the new value would expire, until
> +.B reload-count
> +reloads have happened for the entry, and only then will it actually be removed
> +from the cache.  A request from a client which hits the entry will reset
> +the reload counter on the entry.  Purging the cache using the
> +.B \-i

Also from man-pages(7):

        Complete commands should, if long, be  written  as  an  in‐
        dented  line on their own, with a blank line before and af‐
        ter the command, for example

            man 7 man-pages

        If the command is short, then it can be included inline  in
        the  text,  in italic format, for example, man 7 man‐pages.
        In this case, it may  be  worth  using  nonbreaking  spaces
        ("\ ")  at suitable places in the command.  Command options
        should be written in italics (e.g., -l).


> +command line option overrides the reload logic and removes the entry.
> +.PP
> +Reloading has the effect of extending cache entry TTLs without compromising
> +on cache coherency, at the cost of additional load on the backing name service.
> +Whether this is a good idea on your system depends on details of
> +your applications' behavior, your name service, and the effective TTL values of
> +your cache entries.  (Note that for some name services (for example, DNS), the
> +effective TTL is the value returned from the name service and
> +.I not
> +the value of the
> +.B positive\-time\-to\-live
> +attribute.)  Please consider the following advice carefully:
> +.IP \(bu
> +If your application will make a second request for the same name, after
> +more then 1 TTL but before
> +.B reload\-count
> +TTLs, and is sensitive to the latency of a cache miss, then reloading may be
> +a good idea for you.
> +.IP \(bu
> +If your name service is configured to return very short TTLs, and your
> +applications only make requests rarely under normal circumstances, then
> +reloading may result in additional load on your backing name service
> +without any benefit to applications, which is probably a bad idea for you.
> +.IP \(bu
> +If your name service capacity is limited, reloading may have the
> +surprising effect of increasing load on your name service instead of
> +reducing it, and may be a bad idea for you.
> +.IP \(bu
> +Setting
> +.B reload\-count
> +to
> +.B unlimited
> +is almost never a good idea, as it will result in a cache that never expires
> +entries and puts never-ending additional load on the backing name service.
> +.PP
> +Note also that some distributions have an init script for nscd with a "reload"
> +command which has the effect of purging
> +.BR nscd 's
> +caches using the
> +.B \-i
> +commandline option.  That use of the word "reload" is
> +.I entirely different
> +from the "reloading" described here.
>   .SH SEE ALSO
>   .BR nscd (8)
>   .\" .SH AUTHOR
>
  

​Thanks Alejandro,

Here's v2 of the patch with your feedback applied.



- Added a subsection of NOTES describing nscd's reloading behavior
  and providing advice on how to configure it.
- Clarifications for the threads, reload-count, positive-time-to-live,
  check-files, and shared attributes.

Derived by reading the nscd, libresolv and glibc source and some painful experience.

v2: review feedback

diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
index 7356bf7c2..a5c5e7bc3 100644
--- a/man5/nscd.conf.5
+++ b/man5/nscd.conf.5
@@ -1,5 +1,6 @@
 .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
 .\" Author: Thorsten Kukuk <kukuk@suse.de>
+.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
 .\"
 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
 .\" This program is free software; you can redistribute it and/or
@@ -53,9 +54,12 @@ The default is 0.
 .B threads
 .I number
 .RS
-This is the number of threads that are started to wait for
+This is the initial number of threads that are started to wait for
 requests.
 At least five threads will always be created.
+The number of threads may increase dynamically up to
+.B max\-threads
+in response to demand from clients, but never decreases.
 .RE
 .PP
 .B max\-threads
@@ -83,9 +87,18 @@ Specifies the user who is allowed to request statistics.
 unlimited |
 .I number
 .RS
-Limit on the number of times a cached entry gets reloaded without being used
+Sets a limit on the number of times a cached entry gets reloaded without being used
 before it gets removed.
-The default is 5.
+The limit can take values ranging from 0 to 254;
+values 255 or higher behave the same as
+.BR unlimited .
+Limit values can be specified in either decimal or hexadecimal with a "0x" prefix.
+The special value
+.B unlimited
+is case-insensitive.
+The default limit is 5.
+A limit of 0 turns off the reloading feature.
+See NOTES below for further discussion of reloading.
 .RE
 .PP
 .B paranoia
@@ -128,6 +141,9 @@ in the specified cache for
 is in seconds.
 Larger values increase cache hit rates and reduce mean
 response times, but increase problems with cache coherence.
+Note that for some name services (including specifically DNS)
+the TTL returned from the name service is used and this attribute
+is ignored.
 .RE
 .PP
 .B negative\-time\-to\-live
@@ -166,6 +182,7 @@ The files are
 .IR /etc/passwd ,
 .IR /etc/group ,
 .IR /etc/hosts ,
+.IR /etc/resolv.conf ,
 .IR /etc/services ,
 and
 .IR /etc/netgroup .
@@ -194,6 +211,8 @@ is shared with the clients so
 that they can directly search in them instead of having to ask the
 daemon over the socket each time a lookup is performed.
 The default is no.
+Note that a cache miss will still result in asking the daemon over
+the socket.
 .RE
 .PP
 .B max\-db\-size
@@ -230,12 +249,88 @@ and
 .IR group .
 .RE
 .SH NOTES
+.PP
 The default values stated in this manual page originate
 from the source code of
 .BR nscd (8)
 and are used if not overridden in the configuration file.
 The default values used in the configuration file of
 your distribution might differ.
+.SS Reloading
+.PP
+.BR nscd (8)
+has a feature called reloading whose behavior can be surprising.
+.PP
+Reloading is enabled when the
+.B reload-count
+attribute has a non-zero value.
+The default value in the source code enables reloading, although your distribution may differ.
+.PP
+When reloading is enabled, positive cached entries (the results of
+successful queries) do not simply expire when their TTL is up.
+Instead, at the expiry time
+.B nscd
+will "reload", i.e. re-issue the same name service query that created the cached
+entry, to get a new value to cache.
+Depending on
+.I /etc/nsswitch.conf
+this may mean that a DNS, LDAP or NIS request is made.
+If the new query is successful reloading will repeat when the new value would expire, until
+.B reload-count
+reloads have happened for the entry, and only then will it actually be removed
+from the cache.
+A request from a client which hits the entry will reset the reload counter on the entry.
+Purging the cache using
+.I nscd\ -i
+overrides the reload logic and removes the entry.
+.PP
+Reloading has the effect of extending cache entry TTLs without compromising
+on cache coherency, at the cost of additional load on the backing name service.
+Whether this is a good idea on your system depends on details of
+your applications' behavior, your name service, and the effective TTL values of
+your cache entries.
+(Note that for some name services (for example, DNS), the
+effective TTL is the value returned from the name service and
+.I not
+the value of the
+.B positive\-time\-to\-live
+attribute.)
+Please consider the following advice carefully:
+.IP \(bu
+If your application will make a second request for the same name,
+after more then 1 TTL but before
+.B reload\-count
+TTLs,
+and is sensitive to the latency of a cache miss,
+then reloading may be a good idea for you.
+.IP \(bu
+If your name service is configured to return very short TTLs,
+and your applications only make requests rarely under normal circumstances,
+then reloading may result in additional load on your backing name service
+without any benefit to applications,
+which is probably a bad idea for you.
+.IP \(bu
+If your name service capacity is limited,
+reloading may have the surprising effect of increasing load on your name
+service instead of reducing it,
+and may be a bad idea for you.
+.IP \(bu
+Setting
+.B reload\-count
+to
+.B unlimited
+is almost never a good idea,
+as it will result in a cache that never expires entries and puts never-ending
+additional load on the backing name service.
+.PP
+Some distributions have an init script for
+.BR nscd (8)
+with a
+.I reload
+command which uses
+.I nscd\ -i
+to purge the cache.
+That use of the word "reload" is entirely different from the "reloading" described here.
 .SH SEE ALSO
 .BR nscd (8)
 .\" .SH AUTHOR
  

On 8/3/21 2:19 AM, Greg Banks wrote:
> ​Thanks Alejandro,
> 
> Here's v2 of the patch with your feedback applied.


Hi Greg,

Sorry, but the patch does not apply (see below).
Could you please fix it?

Thanks,

Alex

$ git am patches/recv/Re\:\ \[patch\]\ nscd.conf.5\:\ describe\ 
reloading\,\ clarifications.eml
warning: quoted CRLF detected
warning: quoted CRLF detected
Applying: nscd.conf.5: describe reloading, clarifications
error: patch failed: man5/nscd.conf.5:1
error: man5/nscd.conf.5: patch does not apply
Patch failed at 0001 nscd.conf.5: describe reloading, clarifications
hint: Use 'git am --show-current-patch=diff' to see the failed patch
When you have resolved this problem, run "git am --continue".
If you prefer to skip this patch, run "git am --skip" instead.
To restore the original branch and stop patching, run "git am --abort".


> 
> 
> 
> - Added a subsection of NOTES describing nscd's reloading behavior
>    and providing advice on how to configure it.
> - Clarifications for the threads, reload-count, positive-time-to-live,
>    check-files, and shared attributes.
> 
> Derived by reading the nscd, libresolv and glibc source and some painful 
> experience.
> 
> v2: review feedback
> 
> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
> index 7356bf7c2..a5c5e7bc3 100644
> --- a/man5/nscd.conf.5
> +++ b/man5/nscd.conf.5
> @@ -1,5 +1,6 @@
>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 
> Microsoft Corp.
>   .\"
>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>   .\" This program is free software; you can redistribute it and/or
> @@ -53,9 +54,12 @@ The default is 0.
>   .B threads
>   .I number
>   .RS
> -This is the number of threads that are started to wait for
> +This is the initial number of threads that are started to wait for
>   requests.
>   At least five threads will always be created.
> +The number of threads may increase dynamically up to
> +.B max\-threads
> +in response to demand from clients, but never decreases.
>   .RE
>   .PP
>   .B max\-threads
> @@ -83,9 +87,18 @@ Specifies the user who is allowed to request statistics.
>   unlimited |
>   .I number
>   .RS
> -Limit on the number of times a cached entry gets reloaded without being 
> used
> +Sets a limit on the number of times a cached entry gets reloaded 
> without being used
>   before it gets removed.
> -The default is 5.
> +The limit can take values ranging from 0 to 254;
> +values 255 or higher behave the same as
> +.BR unlimited .
> +Limit values can be specified in either decimal or hexadecimal with a 
> "0x" prefix.
> +The special value
> +.B unlimited
> +is case-insensitive.
> +The default limit is 5.
> +A limit of 0 turns off the reloading feature.
> +See NOTES below for further discussion of reloading.
>   .RE
>   .PP
>   .B paranoia
> @@ -128,6 +141,9 @@ in the specified cache for
>   is in seconds.
>   Larger values increase cache hit rates and reduce mean
>   response times, but increase problems with cache coherence.
> +Note that for some name services (including specifically DNS)
> +the TTL returned from the name service is used and this attribute
> +is ignored.
>   .RE
>   .PP
>   .B negative\-time\-to\-live
> @@ -166,6 +182,7 @@ The files are
>   .IR /etc/passwd ,
>   .IR /etc/group ,
>   .IR /etc/hosts ,
> +.IR /etc/resolv.conf ,
>   .IR /etc/services ,
>   and
>   .IR /etc/netgroup .
> @@ -194,6 +211,8 @@ is shared with the clients so
>   that they can directly search in them instead of having to ask the
>   daemon over the socket each time a lookup is performed.
>   The default is no.
> +Note that a cache miss will still result in asking the daemon over
> +the socket.
>   .RE
>   .PP
>   .B max\-db\-size
> @@ -230,12 +249,88 @@ and
>   .IR group .
>   .RE
>   .SH NOTES
> +.PP
>   The default values stated in this manual page originate
>   from the source code of
>   .BR nscd (8)
>   and are used if not overridden in the configuration file.
>   The default values used in the configuration file of
>   your distribution might differ.
> +.SS Reloading
> +.PP
> +.BR nscd (8)
> +has a feature called reloading whose behavior can be surprising.
> +.PP
> +Reloading is enabled when the
> +.B reload-count
> +attribute has a non-zero value.
> +The default value in the source code enables reloading, although your 
> distribution may differ.
> +.PP
> +When reloading is enabled, positive cached entries (the results of
> +successful queries) do not simply expire when their TTL is up.
> +Instead, at the expiry time
> +.B nscd
> +will "reload", i.e. re-issue the same name service query that created 
> the cached
> +entry, to get a new value to cache.
> +Depending on
> +.I /etc/nsswitch.conf
> +this may mean that a DNS, LDAP or NIS request is made.
> +If the new query is successful reloading will repeat when the new value 
> would expire, until
> +.B reload-count
> +reloads have happened for the entry, and only then will it actually be 
> removed
> +from the cache.
> +A request from a client which hits the entry will reset the reload 
> counter on the entry.
> +Purging the cache using
> +.I nscd\ -i
> +overrides the reload logic and removes the entry.
> +.PP
> +Reloading has the effect of extending cache entry TTLs without compromising
> +on cache coherency, at the cost of additional load on the backing name 
> service.
> +Whether this is a good idea on your system depends on details of
> +your applications' behavior, your name service, and the effective TTL 
> values of
> +your cache entries.
> +(Note that for some name services (for example, DNS), the
> +effective TTL is the value returned from the name service and
> +.I not
> +the value of the
> +.B positive\-time\-to\-live
> +attribute.)
> +Please consider the following advice carefully:
> +.IP \(bu
> +If your application will make a second request for the same name,
> +after more then 1 TTL but before
> +.B reload\-count
> +TTLs,
> +and is sensitive to the latency of a cache miss,
> +then reloading may be a good idea for you.
> +.IP \(bu
> +If your name service is configured to return very short TTLs,
> +and your applications only make requests rarely under normal circumstances,
> +then reloading may result in additional load on your backing name service
> +without any benefit to applications,
> +which is probably a bad idea for you.
> +.IP \(bu
> +If your name service capacity is limited,
> +reloading may have the surprising effect of increasing load on your name
> +service instead of reducing it,
> +and may be a bad idea for you.
> +.IP \(bu
> +Setting
> +.B reload\-count
> +to
> +.B unlimited
> +is almost never a good idea,
> +as it will result in a cache that never expires entries and puts 
> never-ending
> +additional load on the backing name service.
> +.PP
> +Some distributions have an init script for
> +.BR nscd (8)
> +with a
> +.I reload
> +command which uses
> +.I nscd\ -i
> +to purge the cache.
> +That use of the word "reload" is entirely different from the 
> "reloading" described here.
>   .SH SEE ALSO
>   .BR nscd (8)
>   .\" .SH AUTHOR
> 
> ------------------------------------------------------------------------
> *From:* Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
> *Sent:* Wednesday, July 28, 2021 16:31
> *To:* Greg Banks <gbanks@linkedin.com>
> *Cc:* Michael Kerrisk <mtk.manpages@gmail.com>; 
> libc-alpha@sourceware.org <libc-alpha@sourceware.org>; Petr Baudis 
> <pasky@suse.cz>; DJ Delorie <dj@redhat.com>; linux-man@vger.kernel.org 
> <linux-man@vger.kernel.org>
> *Subject:* Re: [patch] nscd.conf.5: describe reloading, clarifications
> Hello Greg,
> 
> On 7/28/21 12:09 AM, Greg Banks wrote:
>> - Added a subsection of NOTES describing nscd's reloading behavior
>>    and providing advice on how to configure it.
>> - Clarifications for the threads, reload-count, positive-time-to-live,
>>    check-files, and shared attributes.
>> 
>> Derived by reading the nscd, libresolv and glibc source and some painful experience.
> 
> Thanks for the patch.
> 
> Please see some comments below.
> 
> Thanks,
> 
> Alex
> 
>> 
>> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
>> index 7356bf7c2..52f7051d5 100644
>> --- a/man5/nscd.conf.5
>> +++ b/man5/nscd.conf.5
>> @@ -1,5 +1,6 @@
>>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
>> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>>   .\"
>>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>>   .\" This program is free software; you can redistribute it and/or
>> @@ -53,9 +54,12 @@ The default is 0.
>>   .B threads
>>   .I number
>>   .RS
>> -This is the number of threads that are started to wait for
>> +This is the initial number of threads that are started to wait for
>>   requests.
>> -At least five threads will always be created.
>> +At least five threads will always be created.  The number of threads
>> +may increase dynamically up to
>> +.B max\-threads
>> +in response to demand from clients, but never decreases.
>>   .RE
>>   .PP
>>   .B max\-threads
>> @@ -83,9 +87,15 @@ Specifies the user who is allowed to request statistics.
>>   unlimited |
>>   .I number
>>   .RS
>> -Limit on the number of times a cached entry gets reloaded without being used
>> -before it gets removed.
>> -The default is 5.
>> +Sets a limit on the number of times a cached entry gets reloaded without being used
> 
> 
> See the following extract from man-pages(7):
> 
> $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
>      Use semantic newlines
>          In the source of a manual page,  new  sentences  should  be
>          started  on new lines, and long sentences should split into
>          lines at clause breaks (commas, semicolons, colons, and  so
>          on).   This  convention,  sometimes known as "semantic new‐
>          lines", makes it easier to see the effect of patches, which
>          often  operate at the level of individual sentences or sen‐
>          tence clauses.
> 
>> +before it gets removed.  The limit can take values ranging from 0
>> +to 254; values 255 or higher behave the same as
>> +.BR unlimited .
>> +Limit values can be specified in either decimal or hexadecimal with a
>> +"0x" prefix.  The special value
>> +.B unlimited
>> +is case-insensitive.  The default limit is 5.  A limit of 0 turns off the reloading
>> +feature.  See NOTES below for further discussion of reloading.
>>   .RE
>>   .PP
>>   .B paranoia
>> @@ -128,6 +138,9 @@ in the specified cache for
>>   is in seconds.
>>   Larger values increase cache hit rates and reduce mean
>>   response times, but increase problems with cache coherence.
>> +Note that for some name services (including specifically DNS)
>> +the TTL returned from the name service is used and this attribute
>> +is ignored.
>>   .RE
>>   .PP
>>   .B negative\-time\-to\-live
>> @@ -166,6 +179,7 @@ The files are
>>   .IR /etc/passwd ,
>>   .IR /etc/group ,
>>   .IR /etc/hosts ,
>> +.IR /etc/resolv.conf ,
>>   .IR /etc/services ,
>>   and
>>   .IR /etc/netgroup .
>> @@ -194,6 +208,8 @@ is shared with the clients so
>>   that they can directly search in them instead of having to ask the
>>   daemon over the socket each time a lookup is performed.
>>   The default is no.
>> +Note that a cache miss will still result in asking the daemon over
>> +the socket.
>>   .RE
>>   .PP
>>   .B max\-db\-size
>> @@ -230,12 +246,82 @@ and
>>   .IR group .
>>   .RE
>>   .SH NOTES
>> +.PP
>>   The default values stated in this manual page originate
>>   from the source code of
>>   .BR nscd (8)
>>   and are used if not overridden in the configuration file.
>>   The default values used in the configuration file of
>>   your distribution might differ.
>> +.SS Reloading
>> +.PP
>> +.BR nscd (8)
>> +has a feature called reloading whose behavior can be surprising.
>> +.PP
>> +Reloading is enabled when the
>> +.B reload-count
>> +attribute has a non-zero value.  The default value in the source
>> +code enables reloading, although your distribution may differ.
>> +.PP
>> +When
>> +reloading is enabled, positive cached entries (the results of
>> +successful queries) do not simply expire when their TTL is up.  Instead,
>> +at the expiry time
>> +.B nscd
>> +will "reload", i.e. re-issue the same name service query that created the cached
>> +entry, to get a new value to cache.  Depending on
>> +.B /etc/nsswitch.conf
> 
> Also from man-pages(7):
> 
>      Formatting conventions (general)
> [...]
> 
>          Filenames  (whether  pathnames,  or  references  to  header
>          files) are always in italics (e.g., <stdio.h>),  except  in
>          the  SYNOPSIS  section,  where  included  files are in bold
>          (e.g., #include <stdio.h>).  When referring to  a  standard
>          header  file include, specify the header file surrounded by
>          angle brackets, in the usual C way (e.g., <stdio.h>).
> 
> 
>> +this may mean that a DNS, LDAP or NIS request is made.  If the new query
>> +is successful reloading will repeat
>> +when the new value would expire, until
>> +.B reload-count
>> +reloads have happened for the entry, and only then will it actually be removed
>> +from the cache.  A request from a client which hits the entry will reset
>> +the reload counter on the entry.  Purging the cache using the
>> +.B \-i
> 
> Also from man-pages(7):
> 
>          Complete commands should, if long, be  written  as  an  in‐
>          dented  line on their own, with a blank line before and af‐
>          ter the command, for example
> 
>              man 7 man-pages
> 
>          If the command is short, then it can be included inline  in
>          the  text,  in italic format, for example, man 7 man‐pages.
>          In this case, it may  be  worth  using  nonbreaking  spaces
>          ("\ ")  at suitable places in the command.  Command options
>          should be written in italics (e.g., -l).
> 
> 
>> +command line option overrides the reload logic and removes the entry.
>> +.PP
>> +Reloading has the effect of extending cache entry TTLs without compromising
>> +on cache coherency, at the cost of additional load on the backing name service.
>> +Whether this is a good idea on your system depends on details of
>> +your applications' behavior, your name service, and the effective TTL values of
>> +your cache entries.  (Note that for some name services (for example, DNS), the
>> +effective TTL is the value returned from the name service and
>> +.I not
>> +the value of the
>> +.B positive\-time\-to\-live
>> +attribute.)  Please consider the following advice carefully:
>> +.IP \(bu
>> +If your application will make a second request for the same name, after
>> +more then 1 TTL but before
>> +.B reload\-count
>> +TTLs, and is sensitive to the latency of a cache miss, then reloading may be
>> +a good idea for you.
>> +.IP \(bu
>> +If your name service is configured to return very short TTLs, and your
>> +applications only make requests rarely under normal circumstances, then
>> +reloading may result in additional load on your backing name service
>> +without any benefit to applications, which is probably a bad idea for you.
>> +.IP \(bu
>> +If your name service capacity is limited, reloading may have the
>> +surprising effect of increasing load on your name service instead of
>> +reducing it, and may be a bad idea for you.
>> +.IP \(bu
>> +Setting
>> +.B reload\-count
>> +to
>> +.B unlimited
>> +is almost never a good idea, as it will result in a cache that never expires
>> +entries and puts never-ending additional load on the backing name service.
>> +.PP
>> +Note also that some distributions have an init script for nscd with a "reload"
>> +command which has the effect of purging
>> +.BR nscd 's
>> +caches using the
>> +.B \-i
>> +commandline option.  That use of the word "reload" is
>> +.I entirely different
>> +from the "reloading" described here.
>>   .SH SEE ALSO
>>   .BR nscd (8)
>>   .\" .SH AUTHOR
>> 
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; 
> https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=fxB1Fv38SNeZOf42yE1ZCLVfJVBi8RtvSC7loYLLKC4%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=fxB1Fv38SNeZOf42yE1ZCLVfJVBi8RtvSC7loYLLKC4%3D&amp;reserved=0>
> https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=gPrruohuthTCDA%2FW%2BR%2FgI2IWl2PEsZbXNk99Ax3pp38%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C8af3ff31ed6546255b1c08d95206af85%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637631010951616695%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=gPrruohuthTCDA%2FW%2BR%2FgI2IWl2PEsZbXNk99Ax3pp38%3D&amp;reserved=0>
  

Hi Alejandro,

I think you're a victim of the git bug described in https://bugzilla.redhat.com/show_bug.cgi?id=1469098  where git gets confused about whitespace when decoding base64 encoded message bodies.  The workarounds are to use "git am --ignore-whitespace", or to manually decode the base64 and adjust the MIME headers. I don't know of any way to control the transfer encoding from this mail client, sorry.  FYI my mail client has also "helpfully" stuck an annoying but harmless Unicode U+200B ZERO WIDTH SPACE character at the start of the message.

Greg.
  

Hi Greg,

On 8/3/21 4:17 PM, Greg Banks wrote:
> Hi Alejandro,
> 
> I think you're a victim of the git bug described in 
> https://bugzilla.redhat.com/show_bug.cgi?id=1469098 
> <https://bugzilla.redhat.com/show_bug.cgi?id=1469098>  where git gets 
> confused about whitespace when decoding base64 encoded message bodies.  
> The workarounds are to use "git am --ignore-whitespace", or to manually 
> decode the base64 and adjust the MIME headers. I don't know of any way 
> to control the transfer encoding from this mail client, sorry.  FYI my 
> mail client has also "helpfully" stuck an annoying but harmless Unicode 
> U+200B ZERO WIDTH SPACE character at the start of the message.

Thanks for that info, it worked.

But, it has CRLF (Windows) endings, and v2 didn't reach the mailing list 
(but v1 did).  And v1 didn't have CRLF endings.  Could you please use 
the same method you used for sending v1 to send an v3?
Also, please see some comments below.

Thanks,

Alex

> 
> Greg.
> ------------------------------------------------------------------------
> *From:* Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
> *Sent:* Tuesday, August 3, 2021 04:08
> *To:* Greg Banks <gbanks@linkedin.com>
> *Cc:* Michael Kerrisk <mtk.manpages@gmail.com>; 
> libc-alpha@sourceware.org <libc-alpha@sourceware.org>; Petr Baudis 
> <pasky@suse.cz>; DJ Delorie <dj@redhat.com>; linux-man@vger.kernel.org 
> <linux-man@vger.kernel.org>
> *Subject:* Re: [patch] nscd.conf.5: describe reloading, clarifications
> On 8/3/21 2:19 AM, Greg Banks wrote:
>> ​Thanks Alejandro,
>> 
>> Here's v2 of the patch with your feedback applied.
> 
> 
> Hi Greg,
> 
> Sorry, but the patch does not apply (see below).
> Could you please fix it?
> 
> Thanks,
> 
> Alex
> 
> $ git am patches/recv/Re\:\ \[patch\]\ nscd.conf.5\:\ describe\
> reloading\,\ clarifications.eml
> warning: quoted CRLF detected
> warning: quoted CRLF detected
> Applying: nscd.conf.5: describe reloading, clarifications
> error: patch failed: man5/nscd.conf.5:1
> error: man5/nscd.conf.5: patch does not apply
> Patch failed at 0001 nscd.conf.5: describe reloading, clarifications
> hint: Use 'git am --show-current-patch=diff' to see the failed patch
> When you have resolved this problem, run "git am --continue".
> If you prefer to skip this patch, run "git am --skip" instead.
> To restore the original branch and stop patching, run "git am --abort".
> 
> 
>> 
>> 
>> 
>> - Added a subsection of NOTES describing nscd's reloading behavior
>>    and providing advice on how to configure it.
>> - Clarifications for the threads, reload-count, positive-time-to-live,
>>    check-files, and shared attributes.
>> 
>> Derived by reading the nscd, libresolv and glibc source and some painful 
>> experience.
>> 
>> v2: review feedback
>> 
>> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
>> index 7356bf7c2..a5c5e7bc3 100644
>> --- a/man5/nscd.conf.5
>> +++ b/man5/nscd.conf.5
>> @@ -1,5 +1,6 @@
>>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
>> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 
>> Microsoft Corp.
>>   .\"
>>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>>   .\" This program is free software; you can redistribute it and/or
>> @@ -53,9 +54,12 @@ The default is 0.
>>   .B threads
>>   .I number
>>   .RS
>> -This is the number of threads that are started to wait for
>> +This is the initial number of threads that are started to wait for
>>   requests.
>>   At least five threads will always be created.
>> +The number of threads may increase dynamically up to
>> +.B max\-threads
>> +in response to demand from clients, but never decreases.
>>   .RE
>>   .PP
>>   .B max\-threads
>> @@ -83,9 +87,18 @@ Specifies the user who is allowed to request statistics.
>>   unlimited |
>>   .I number
>>   .RS
>> -Limit on the number of times a cached entry gets reloaded without being 
>> used
>> +Sets a limit on the number of times a cached entry gets reloaded 
>> without being used
>>   before it gets removed.
>> -The default is 5.
>> +The limit can take values ranging from 0 to 254;
>> +values 255 or higher behave the same as
>> +.BR unlimited .
>> +Limit values can be specified in either decimal or hexadecimal with a 
>> "0x" prefix.
>> +The special value
>> +.B unlimited
>> +is case-insensitive.
>> +The default limit is 5.
>> +A limit of 0 turns off the reloading feature.
>> +See NOTES below for further discussion of reloading.
>>   .RE
>>   .PP
>>   .B paranoia
>> @@ -128,6 +141,9 @@ in the specified cache for
>>   is in seconds.
>>   Larger values increase cache hit rates and reduce mean
>>   response times, but increase problems with cache coherence.
>> +Note that for some name services (including specifically DNS)
>> +the TTL returned from the name service is used and this attribute

Break just before (or after) "and" instead.

>> +is ignored.
>>   .RE
>>   .PP
>>   .B negative\-time\-to\-live
>> @@ -166,6 +182,7 @@ The files are
>>   .IR /etc/passwd ,
>>   .IR /etc/group ,
>>   .IR /etc/hosts ,
>> +.IR /etc/resolv.conf ,
>>   .IR /etc/services ,
>>   and
>>   .IR /etc/netgroup .
>> @@ -194,6 +211,8 @@ is shared with the clients so
>>   that they can directly search in them instead of having to ask the
>>   daemon over the socket each time a lookup is performed.
>>   The default is no.
>> +Note that a cache miss will still result in asking the daemon over

Break just after "in"

>> +the socket.
>>   .RE
>>   .PP
>>   .B max\-db\-size
>> @@ -230,12 +249,88 @@ and
>>   .IR group .
>>   .RE
>>   .SH NOTES
>> +.PP

That's not correct.  Did you copy that from another place?  If so, 
please tell me because I should fix it.

We use that between paragraphs, but not before the first one nor after 
the last one.

>>   The default values stated in this manual page originate
>>   from the source code of
>>   .BR nscd (8)
>>   and are used if not overridden in the configuration file.
>>   The default values used in the configuration file of
>>   your distribution might differ.
>> +.SS Reloading
>> +.PP

Nope.  Same reasons.

>> +.BR nscd (8)
>> +has a feature called reloading whose behavior can be surprising.
>> +.PP
>> +Reloading is enabled when the
>> +.B reload-count
>> +attribute has a non-zero value.
>> +The default value in the source code enables reloading, although your 

Break at the ',' instead.

>> distribution may differ.
>> +.PP
>> +When reloading is enabled, positive cached entries (the results of

idem.

>> +successful queries) do not simply expire when their TTL is up.

Break after ')'.

>> +Instead, at the expiry time
>> +.B nscd
>> +will "reload", i.e. re-issue the same name service query that created 
>> the cached
>> +entry, to get a new value to cache.

Break at the commas above.

>> +Depending on
>> +.I /etc/nsswitch.conf
>> +this may mean that a DNS, LDAP or NIS request is made.

Use a comma before "or" (Oxford comma).

>> +If the new query is successful reloading will repeat when the new value 

s/successful/successful,/

>> would expire, until

Break at the ',' instead.

>> +.B reload-count
>> +reloads have happened for the entry, and only then will it actually be 

idem.

>> removed
>> +from the cache.
>> +A request from a client which hits the entry will reset the reload 
>> counter on the entry.
>> +Purging the cache using
>> +.I nscd\ -i

Please, use \~ instead of "\ ".  (I know man-pages(7) recommends "\ ", 
but we're about to change that).

>> +overrides the reload logic and removes the entry.
>> +.PP
>> +Reloading has the effect of extending cache entry TTLs without compromising
>> +on cache coherency, at the cost of additional load on the backing name 
>> service.

In general, break at commas instead of random places.
The following regex should rarely match:

[,;:.] \+\w

>> +Whether this is a good idea on your system depends on details of
>> +your applications' behavior, your name service, and the effective TTL 
>> values of
>> +your cache entries.
>> +(Note that for some name services (for example, DNS), the
>> +effective TTL is the value returned from the name service and
>> +.I not
>> +the value of the
>> +.B positive\-time\-to\-live



>> +attribute.)
>> +Please consider the following advice carefully:
>> +.IP \(bu
>> +If your application will make a second request for the same name,
>> +after more then 1 TTL but before
>> +.B reload\-count
>> +TTLs,
>> +and is sensitive to the latency of a cache miss,
>> +then reloading may be a good idea for you.
>> +.IP \(bu
>> +If your name service is configured to return very short TTLs,
>> +and your applications only make requests rarely under normal circumstances,
>> +then reloading may result in additional load on your backing name service
>> +without any benefit to applications,
>> +which is probably a bad idea for you.
>> +.IP \(bu
>> +If your name service capacity is limited,
>> +reloading may have the surprising effect of increasing load on your name
>> +service instead of reducing it,
>> +and may be a bad idea for you.
>> +.IP \(bu
>> +Setting
>> +.B reload\-count
>> +to
>> +.B unlimited
>> +is almost never a good idea,
>> +as it will result in a cache that never expires entries and puts 
>> never-ending
>> +additional load on the backing name service.
>> +.PP
>> +Some distributions have an init script for
>> +.BR nscd (8)
>> +with a
>> +.I reload
>> +command which uses
>> +.I nscd\ -i

\~

>> +to purge the cache.
>> +That use of the word "reload" is entirely different from the 
>> "reloading" described here.
>>   .SH SEE ALSO
>>   .BR nscd (8)
>>   .\" .SH AUTHOR
>> 
>> ------------------------------------------------------------------------
>> *From:* Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
>> *Sent:* Wednesday, July 28, 2021 16:31
>> *To:* Greg Banks <gbanks@linkedin.com>
>> *Cc:* Michael Kerrisk <mtk.manpages@gmail.com>; 
>> libc-alpha@sourceware.org <libc-alpha@sourceware.org>; Petr Baudis 
>> <pasky@suse.cz>; DJ Delorie <dj@redhat.com>; linux-man@vger.kernel.org 
>> <linux-man@vger.kernel.org>
>> *Subject:* Re: [patch] nscd.conf.5: describe reloading, clarifications
>> Hello Greg,
>> 
>> On 7/28/21 12:09 AM, Greg Banks wrote:
>>> - Added a subsection of NOTES describing nscd's reloading behavior
>>>    and providing advice on how to configure it.
>>> - Clarifications for the threads, reload-count, positive-time-to-live,
>>>    check-files, and shared attributes.
>>> 
>>> Derived by reading the nscd, libresolv and glibc source and some painful experience.
>> 
>> Thanks for the patch.
>> 
>> Please see some comments below.
>> 
>> Thanks,
>> 
>> Alex
>> 
>>> 
>>> diff --git a/man5/nscd.conf.5 b/man5/nscd.conf.5
>>> index 7356bf7c2..52f7051d5 100644
>>> --- a/man5/nscd.conf.5
>>> +++ b/man5/nscd.conf.5
>>> @@ -1,5 +1,6 @@
>>>   .\" Copyright (c) 1999, 2000 SuSE GmbH Nuernberg, Germany
>>>   .\" Author: Thorsten Kukuk <kukuk@suse.de>
>>> +.\" Updates by Greg Banks <gbanks@linkedin.com> Copyright (c) 2021 Microsoft Corp.
>>>   .\"
>>>   .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
>>>   .\" This program is free software; you can redistribute it and/or
>>> @@ -53,9 +54,12 @@ The default is 0.
>>>   .B threads
>>>   .I number
>>>   .RS
>>> -This is the number of threads that are started to wait for
>>> +This is the initial number of threads that are started to wait for
>>>   requests.
>>> -At least five threads will always be created.
>>> +At least five threads will always be created.  The number of threads
>>> +may increase dynamically up to
>>> +.B max\-threads
>>> +in response to demand from clients, but never decreases.
>>>   .RE
>>>   .PP
>>>   .B max\-threads
>>> @@ -83,9 +87,15 @@ Specifies the user who is allowed to request statistics.
>>>   unlimited |
>>>   .I number
>>>   .RS
>>> -Limit on the number of times a cached entry gets reloaded without being used
>>> -before it gets removed.
>>> -The default is 5.
>>> +Sets a limit on the number of times a cached entry gets reloaded without being used
>> 
>> 
>> See the following extract from man-pages(7):
>> 
>> $ man 7 man-pages | sed -n '/Use semantic newlines/,/^$/p';
>>      Use semantic newlines
>>          In the source of a manual page,  new  sentences  should  be
>>          started  on new lines, and long sentences should split into
>>          lines at clause breaks (commas, semicolons, colons, and  so
>>          on).   This  convention,  sometimes known as "semantic new‐
>>          lines", makes it easier to see the effect of patches, which
>>          often  operate at the level of individual sentences or sen‐
>>          tence clauses.
>> 
>>> +before it gets removed.  The limit can take values ranging from 0
>>> +to 254; values 255 or higher behave the same as
>>> +.BR unlimited .
>>> +Limit values can be specified in either decimal or hexadecimal with a
>>> +"0x" prefix.  The special value
>>> +.B unlimited
>>> +is case-insensitive.  The default limit is 5.  A limit of 0 turns off the reloading
>>> +feature.  See NOTES below for further discussion of reloading.
>>>   .RE
>>>   .PP
>>>   .B paranoia
>>> @@ -128,6 +138,9 @@ in the specified cache for
>>>   is in seconds.
>>>   Larger values increase cache hit rates and reduce mean
>>>   response times, but increase problems with cache coherence.
>>> +Note that for some name services (including specifically DNS)
>>> +the TTL returned from the name service is used and this attribute
>>> +is ignored.
>>>   .RE
>>>   .PP
>>>   .B negative\-time\-to\-live
>>> @@ -166,6 +179,7 @@ The files are
>>>   .IR /etc/passwd ,
>>>   .IR /etc/group ,
>>>   .IR /etc/hosts ,
>>> +.IR /etc/resolv.conf ,
>>>   .IR /etc/services ,
>>>   and
>>>   .IR /etc/netgroup .
>>> @@ -194,6 +208,8 @@ is shared with the clients so
>>>   that they can directly search in them instead of having to ask the
>>>   daemon over the socket each time a lookup is performed.
>>>   The default is no.
>>> +Note that a cache miss will still result in asking the daemon over
>>> +the socket.
>>>   .RE
>>>   .PP
>>>   .B max\-db\-size
>>> @@ -230,12 +246,82 @@ and
>>>   .IR group .
>>>   .RE
>>>   .SH NOTES
>>> +.PP
>>>   The default values stated in this manual page originate
>>>   from the source code of
>>>   .BR nscd (8)
>>>   and are used if not overridden in the configuration file.
>>>   The default values used in the configuration file of
>>>   your distribution might differ.
>>> +.SS Reloading
>>> +.PP
>>> +.BR nscd (8)
>>> +has a feature called reloading whose behavior can be surprising.
>>> +.PP
>>> +Reloading is enabled when the
>>> +.B reload-count
>>> +attribute has a non-zero value.  The default value in the source
>>> +code enables reloading, although your distribution may differ.
>>> +.PP
>>> +When
>>> +reloading is enabled, positive cached entries (the results of
>>> +successful queries) do not simply expire when their TTL is up.  Instead,
>>> +at the expiry time
>>> +.B nscd
>>> +will "reload", i.e. re-issue the same name service query that created the cached
>>> +entry, to get a new value to cache.  Depending on
>>> +.B /etc/nsswitch.conf
>> 
>> Also from man-pages(7):
>> 
>>      Formatting conventions (general)
>> [...]
>> 
>>          Filenames  (whether  pathnames,  or  references  to  header
>>          files) are always in italics (e.g., <stdio.h>),  except  in
>>          the  SYNOPSIS  section,  where  included  files are in bold
>>          (e.g., #include <stdio.h>).  When referring to  a  standard
>>          header  file include, specify the header file surrounded by
>>          angle brackets, in the usual C way (e.g., <stdio.h>).
>> 
>> 
>>> +this may mean that a DNS, LDAP or NIS request is made.  If the new query
>>> +is successful reloading will repeat
>>> +when the new value would expire, until
>>> +.B reload-count
>>> +reloads have happened for the entry, and only then will it actually be removed
>>> +from the cache.  A request from a client which hits the entry will reset
>>> +the reload counter on the entry.  Purging the cache using the
>>> +.B \-i
>> 
>> Also from man-pages(7):
>> 
>>          Complete commands should, if long, be  written  as  an  in‐
>>          dented  line on their own, with a blank line before and af‐
>>          ter the command, for example
>> 
>>              man 7 man-pages
>> 
>>          If the command is short, then it can be included inline  in
>>          the  text,  in italic format, for example, man 7 man‐pages.
>>          In this case, it may  be  worth  using  nonbreaking  spaces
>>          ("\ ")  at suitable places in the command.  Command options
>>          should be written in italics (e.g., -l).
>> 
>> 
>>> +command line option overrides the reload logic and removes the entry.
>>> +.PP
>>> +Reloading has the effect of extending cache entry TTLs without compromising
>>> +on cache coherency, at the cost of additional load on the backing name service.
>>> +Whether this is a good idea on your system depends on details of
>>> +your applications' behavior, your name service, and the effective TTL values of
>>> +your cache entries.  (Note that for some name services (for example, DNS), the
>>> +effective TTL is the value returned from the name service and
>>> +.I not
>>> +the value of the
>>> +.B positive\-time\-to\-live
>>> +attribute.)  Please consider the following advice carefully:
>>> +.IP \(bu
>>> +If your application will make a second request for the same name, after
>>> +more then 1 TTL but before
>>> +.B reload\-count
>>> +TTLs, and is sensitive to the latency of a cache miss, then reloading may be
>>> +a good idea for you.
>>> +.IP \(bu
>>> +If your name service is configured to return very short TTLs, and your
>>> +applications only make requests rarely under normal circumstances, then
>>> +reloading may result in additional load on your backing name service
>>> +without any benefit to applications, which is probably a bad idea for you.
>>> +.IP \(bu
>>> +If your name service capacity is limited, reloading may have the
>>> +surprising effect of increasing load on your name service instead of
>>> +reducing it, and may be a bad idea for you.
>>> +.IP \(bu
>>> +Setting
>>> +.B reload\-count
>>> +to
>>> +.B unlimited
>>> +is almost never a good idea, as it will result in a cache that never expires
>>> +entries and puts never-ending additional load on the backing name service.
>>> +.PP
>>> +Note also that some distributions have an init script for nscd with a "reload"
>>> +command which has the effect of purging
>>> +.BR nscd 's
>>> +caches using the
>>> +.B \-i
>>> +commandline option.  That use of the word "reload" is
>>> +.I entirely different
>>> +from the "reloading" described here.
>>>   .SH SEE ALSO
>>>   .BR nscd (8)
>>>   .\" .SH AUTHOR
>>> 
>> 
>> 
>> -- 
>> Alejandro Colomar
>> Linux man-pages comaintainer; 
>> https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0> 
> 
>> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0>>
>> https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0> 
> 
>> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0>>
> 
> 
> -- 
> Alejandro Colomar
> Linux man-pages comaintainer; 
> https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=https%3A%2F%2Fwww.kernel.org%2Fdoc%2Fman-pages%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=E1e7YGUZhDDpr8av9wG1WPa%2B33YOe64%2F7%2BZdfMmRUoM%3D&amp;reserved=0>
> https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0 
> <https://nam06.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.alejandro-colomar.es%2F&amp;data=04%7C01%7Cgbanks%40linkedin.com%7C2e234f99d76a404167c408d95655f1d7%7C72f988bf86f141af91ab2d7cd011db47%7C1%7C0%7C637635750019288026%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000&amp;sdata=jznPum1MSudWgDiUuW9DJnI%2BiOi6dKwGpAG9PR8phKc%3D&amp;reserved=0>
  

Hi Alejandro,

> Could you please use the same method you used for sending v1 to send an v3? \

I did but apparently the email stack at my end insists on adding some randomness to its behavior.  I'm going to try and step outside this email text damage drama and send a pull request separately.

> Also, please see some comments below.

Applied, thanks.

> >> +.PP
>
> That's not correct.  Did you copy that from another place?  If so,
> please tell me because I should fix it.

No, it's a habit left over from the last time I contributed to this project (in 2008).  It seems the rules have changed.

> We use that between paragraphs, but not before the first one nor after
> the last one.

Ok, sure, but in that case the description of .PP in man(7) is wrong

       .PP      Begin a new paragraph and reset prevailing indent.

Greg.
  

CC += Branden


Hi Greg,

On 8/4/21 3:40 PM, Greg Banks wrote:
> Hi Alejandro,
> 
>  > Could you please use the same method you used for sending v1 to send 
> an v3? \
> 
> I did but apparently the email stack at my end insists on adding some 
> randomness to its behavior.  I'm going to try and step outside this 
> email text damage drama and send a pull request separately.

Hmm, not good.

The worst part is that as your emails are not plain text, they don't 
reach the mailing list (only the first one did).  If you can't solve it 
(I suggest using git-send-email(1), to avoid that randomness), I suggest 
that you send the email anyway as good as you can (better send it both 
inline and as an attachment, so that it is more likely that one of them 
will apply), and if it applies to my tree, I'll apply it and also 
forward it to the list as plain text.

> 
>> Also, please see some comments below.
> 
> Applied, thanks.
> 
>> >> +.PP
>> 
>> That's not correct.  Did you copy that from another place?  If so, 
>> please tell me because I should fix it.
> 
> No, it's a habit left over from the last time I contributed to this 
> project (in 2008).  It seems the rules have changed.
> 
>> We use that between paragraphs, but not before the first one nor after
>> the last one.
> 
> Ok, sure, but in that case the description of .PP in man(7) is wrong
> 
>         .PP      Begin a new paragraph and reset prevailing indent.

That's something that I had pending to address from Branden.  That page 
is a mix of things that should go into man-pages(7), groff_man_style(7), 
and groff_man(7), and then man(7) should be removed and replaced by a 
link page to groff_man(7).

For now,
You can read groff_man(7) (provided by the groff package), which tells 
us that .SH already does what .PP does (start a clean paragraph) (and it 
does more things, of course).  The thing is that if you add .PP after 
.SH you will have a blank line (and this an exercise of my mental groff, 
which I hope doesn't fail me this time), and it would be a bit weird to 
have a blank line after the section title.


Thanks,

Alex
  

Hi Alex,

At 2021-08-05T08:58:33+0200, Alejandro Colomar (man-pages) wrote:
[...]
> > > >> +.PP
> > > 
> > > That's not correct.  Did you copy that from another place?  If so,
> > > please tell me because I should fix it.
> > 
> > No, it's a habit left over from the last time I contributed to this
> > project (in 2008).  It seems the rules have changed.
> > 
> > > We use that between paragraphs, but not before the first one nor
> > > after the last one.
> > 
> > Ok, sure, but in that case the description of .PP in man(7) is wrong
> > 
> >         .PP      Begin a new paragraph and reset prevailing indent.
> 
> That's something that I had pending to address from Branden.  That
> page is a mix of things that should go into man-pages(7),
> groff_man_style(7), and groff_man(7), and then man(7) should be
> removed and replaced by a link page to groff_man(7).

I should emphasize that the foregoing is something I _proposed_ for
discussion.  I don't have any reason to suspect that it is something
that has wide buy-in yet.  I'm particularly interested in Michael's
opinion.

> For now, You can read groff_man(7) (provided by the groff package),
> which tells us that .SH already does what .PP does (start a clean
> paragraph) (and it does more things, of course).  The thing is that if
> you add .PP after .SH you will have a blank line (and this an exercise
> of my mental groff, which I hope doesn't fail me this time),

Sorry to disappoint you.  :-O

A PP (or LP, or P) call immediately after a SH call[1] will not add
vertical space because the SH macro definition puts *roff into what is
called "no-space mode"; vertical spacing is suppressed until turned back
on manually, or glyphs[2] are sent to the output.

> and it would be a bit weird to have a blank line after the section
> title.

Yes--as style advice I think this is quite sound and solidly
precedented.

To develop your *roff intuition, I suggest using groff as a REPL.  Yes,
it can be done!  For instance, while composing this mail, even though I
am familiar with the man(7) package sources, I attempted to protect
myself from the embarrassment of making an incorrect claim by testing
my knowledge with this short shell session[3].

$ nroff -man
.TH foo 1
.SH Name
.PP
Foobar.
foo(1)                      General Commands Manual                     foo(1)

Name
       Foobar.

                                                                        foo(1)

This quickly verified to me that I was right about no-space mode.

I so strongly advocate this method of familiarizing oneself with *roff
that I recently added a section about it to groff(1).

   Using groff as a REPL
       Those with a programmer’s bent may be pleased to know  that  they
       can use groff in a read-evaluate-print loop (REPL).  Doing so can
       be handy to verify one’s understanding of the formatter’s  behav‐
       ior  and/or  the syntax it accepts.  Turning on all warnings with
       -ww can aid this goal.

       $ groff -ww -Tutf8
       \# This is a comment. Let's define a register.
       .nr a 1
       \# Do integer arithmetic with operators evaluated left-to-right.
       .nr b \n[a]+5/2
       \# Let's get the result on the standard error stream.
       .tm \n[b]
       3
       \# Now we'll define a string.
       .ds name Leslie\" This is another form of comment.
       .nr b (\n[a] + (7/2))
       \# Center the next two text input lines.
       .ce 2
       Hi, \*[name].
       Your secret number is \n[b].
       \# We will see that the division rounded toward zero.
       It is
       \# Here's an if-else control structure.
       .ie (\n[b] % 2) odd.
       .el even.
       \# This trick sets the page length to the current vertical
       \# position, so that blank lines don't spew when we're done.
       .pl \n[nl]u
       <Control-D>
                                  Hi, Leslie.
                           Your secret number is 4.
       It is even.

The above example gets into many *roff concepts that man page authors
typically need not worry about.  Nevertheless the technique works with
macro packages, too, as shown earlier.  Macro packages often need to be
initialized.  man(7) is no exception.  If you do not call man's "TH" as
the first macro in the input, it will be unhappy.  That is why I had the
".TH foo 1" line.[4]

Regards,
Branden

[1] with arguments, technically--most people do not use the other legal
    form of calling SH input trap, which accepts input in the next line
[2] or drawing commands, but that's mostly irrelevant to man pages
[3] Full disclosure: my command input fibs above.  I actually used, not
    "nroff", but a shell alias of mine called "tgu", which runs a
    bleeding edge groff from a working tree, since I'm a groff
    developer.  After alias expansion, what I ran was
        ./build/test-groff -b -ww -Tutf8
    but that's not very useful to people who don't have a shell window
    that lives in a built groff working tree.
[4] A real man page would supply additional information to the macro.