From patchwork Wed Jul 28 19:42:30 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alice Zhang X-Patchwork-Id: 45841 From: alizhang@redhat.com (Alice Zhang) Date: Wed, 28 Jul 2021 15:42:30 -0400 Subject: [PATCH] debuginfod-doc: PR27950 - Remove redanduncies in man page. Message-ID: <20210728194230.298903-1-alizhang@redhat.com> Create a new file, debuginfod-client-config.7, that holds all environment variables and cache control files related info. Get rid of repetitive definitions in three other files, instead, those files will include the content of new file. Any future modification related to environment variables and cache files will only require changes in one file. Signed-off-by: Alice Zhang --- doc/ChangeLog | 10 +++++ doc/debuginfod-client-config.7 | 68 +++++++++++++++++++++++++++++++++ doc/debuginfod-find.1 | 30 +-------------- doc/debuginfod.8 | 49 +----------------------- doc/debuginfod_find_debuginfo.3 | 51 +------------------------ 5 files changed, 81 insertions(+), 127 deletions(-) create mode 100644 doc/debuginfod-client-config.7 diff --git a/doc/ChangeLog b/doc/ChangeLog index 05fcd23d..4ace8771 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,13 @@ +2021-07-28 Alice Zhang + + PR27950 + * debuginfod-client-config.7: New file to store all cache config + infos. + * debuginfod-find.1: Removed redundant occurrences of environment + variables & cache control files. + * debuginfod.8: Likewise. + * debuginfod_find_debuginfo.3: Likewise. + 2021-04-23 Frank Ch. Eigler PR27701 diff --git a/doc/debuginfod-client-config.7 b/doc/debuginfod-client-config.7 new file mode 100644 index 00000000..81539dc2 --- /dev/null +++ b/doc/debuginfod-client-config.7 @@ -0,0 +1,68 @@ +.SH ENVIRONMENT VARIABLES +.TP 21 +.B TMPDIR +This environment variable points to a file system to be used for +temporary files. The default is /tmp. + +.TP 21 +.B DEBUGINFOD_URLS +This environment variable contains a list of URL prefixes for trusted +debuginfod instances. Alternate URL prefixes are separated by space. +Avoid referential loops that cause a server to contact itself, directly +or indirectly - the results would be hilarious. + +.TP 21 +.B DEBUGINFOD_TIMEOUT +This environment variable governs the timeout for each debuginfod HTTP +connection. A server that fails to provide at least 100K of data +within this many seconds is skipped. The default is 90 seconds. (Zero +or negative means "no timeout".) + + +.TP 21 +.B DEBUGINFOD_CACHE_PATH +This environment variable governs the location of the cache where +downloaded files are kept. It is cleaned periodically as this +program is reexecuted. If XDG_CACHE_HOME is set then +$XDG_CACHE_HOME/debuginfod_client is the default location, otherwise +$HOME/.cache/debuginfod_client is used. For more information regarding +the client cache see \fIdebuginfod_find_debuginfo(3)\fP. + +.TP 21 +.B DEBUGINFOD_PROGRESS +This environment variable governs the default progress function. If +set, and if a progressfn is not explicitly set, then the library will +configure a default progressfn. This function will append a simple +progress message periodically to stderr. The default is no progress +function output. + +.TP 21 +.B DEBUGINFOD_VERBOSE +This environment variable governs the default file descriptor for +verbose output. If set, and if a verbose fd is not explicitly set, +then the verbose output will be produced on STDERR_FILENO. + +.TP 21 +.B DEBUGINFOD_RETRY_LITMIT +This environment variable governs the default limit of retry attempts. If a +query failed with errno other than ENOENT, will initiate several attempts +within the limit. + +.SH FILES +.TP 20 +.B $HOME/.debuginfod.sqlite +Default database file. +.PD + +.TP 20 +.B $XDG_CACHE_HOME/debuginfod_client +Default cache directory for content from upstream debuginfods. +If XDG_CACHE_HOME is not set then \fB$HOME/.cache/debuginfod_client\fP +is used. +.PD + +.TP 20 +.B $HOME/.debuginfod_client_cache +Default cache directory. If XDG_CACHE_HOME is not set then +\fB$HOME/.cache/debuginfod_client\fP is used. +.PD diff --git a/doc/debuginfod-find.1 b/doc/debuginfod-find.1 index 12d4ec2d..ec357b38 100644 --- a/doc/debuginfod-find.1 +++ b/doc/debuginfod-find.1 @@ -125,35 +125,7 @@ for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style. (The debuginfod server does not perform authentication, but a front-end proxy server could.) -.SH "ENVIRONMENT VARIABLES" - -.TP 21 -.B DEBUGINFOD_URLS -This environment variable contains a list of URL prefixes for trusted -debuginfod instances. Alternate URL prefixes are separated by space. - -.TP 21 -.B DEBUGINFOD_TIMEOUT -This environment variable governs the timeout for each debuginfod HTTP -connection. A server that fails to provide at least 100K of data -within this many seconds is skipped. The default is 90 seconds. (Zero -or negative means "no timeout".) - -.TP 21 -.B DEBUGINFOD_CACHE_PATH -This environment variable governs the location of the cache where -downloaded files are kept. It is cleaned periodically as this program -is reexecuted. Cache management parameters may be set by files under -this directory: see the \fBdebuginfod_find_debuginfo(3)\fP man page -for details. The default is $HOME/.debuginfod_client_cache. - -.SH "FILES" -.LP -.PD .1v -.TP 20 -.B $HOME/.debuginfod_client_cache -Default cache directory. -.PD +.so ./debuginfod-client-config.7 .SH "SEE ALSO" .I "debuginfod(8)" diff --git a/doc/debuginfod.8 b/doc/debuginfod.8 index f70af625..35f4708b 100644 --- a/doc/debuginfod.8 +++ b/doc/debuginfod.8 @@ -12,7 +12,6 @@ .fi .RE .. - .TH DEBUGINFOD 8 .SH NAME debuginfod \- debuginfo-related http file-server daemon @@ -418,53 +417,7 @@ rather than HTTPS, the network should be trustworthy. Authentication information through the internal \fIlibcurl\fP library is not currently enabled. - -.SH "ENVIRONMENT VARIABLES" - -.TP -.B TMPDIR -This environment variable points to a file system to be used for -temporary files. The default is /tmp. - -.TP -.B DEBUGINFOD_URLS -This environment variable contains a list of URL prefixes for trusted -debuginfod instances. Alternate URL prefixes are separated by space. -Avoid referential loops that cause a server to contact itself, directly -or indirectly - the results would be hilarious. - -.TP -.B DEBUGINFOD_TIMEOUT -This environment variable governs the timeout for each debuginfod HTTP -connection. A server that fails to provide at least 100K of data -within this many seconds is skipped. The default is 90 seconds. (Zero -or negative means "no timeout".) - - -.TP -.B DEBUGINFOD_CACHE_PATH -This environment variable governs the location of the cache where -downloaded files are kept. It is cleaned periodically as this -program is reexecuted. If XDG_CACHE_HOME is set then -$XDG_CACHE_HOME/debuginfod_client is the default location, otherwise -$HOME/.cache/debuginfod_client is used. For more information regarding -the client cache see \fIdebuginfod_find_debuginfo(3)\fP. - -.SH FILES -.LP -.PD .1v -.TP 20 -.B $HOME/.debuginfod.sqlite -Default database file. -.PD - -.TP 20 -.B $XDG_CACHE_HOME/debuginfod_client -Default cache directory for content from upstream debuginfods. -If XDG_CACHE_HOME is not set then \fB$HOME/.cache/debuginfod_client\fP -is used. -.PD - +.so ./debuginfod-client-config.7 .SH "SEE ALSO" .I "debuginfod-find(1)" diff --git a/doc/debuginfod_find_debuginfo.3 b/doc/debuginfod_find_debuginfo.3 index 7730dd32..60a69fd0 100644 --- a/doc/debuginfod_find_debuginfo.3 +++ b/doc/debuginfod_find_debuginfo.3 @@ -241,48 +241,6 @@ for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style. (The debuginfod server does not perform authentication, but a front-end proxy server could.) -.SH "ENVIRONMENT VARIABLES" - -.TP 21 -.B DEBUGINFOD_URLS -This environment variable contains a list of URL prefixes for trusted -debuginfod instances. Alternate URL prefixes are separated by space. - -.TP 21 -.B DEBUGINFOD_TIMEOUT -This environment variable governs the timeout for each debuginfod HTTP -connection. A server that fails to provide at least 100K of data -within this many seconds is skipped. The default is 90 seconds. (Zero -or negative means "no timeout".) - -.TP 21 -.B DEBUGINFOD_PROGRESS -This environment variable governs the default progress function. If -set, and if a progressfn is not explicitly set, then the library will -configure a default progressfn. This function will append a simple -progress message periodically to stderr. The default is no progress -function output. - -.TP 21 -.B DEBUGINFOD_VERBOSE -This environment variable governs the default file descriptor for -verbose output. If set, and if a verbose fd is not explicitly set, -then the verbose output will be produced on STDERR_FILENO. - -.TP 21 -.B DEBUGINFOD_CACHE_PATH -This environment variable governs the location of the cache where -downloaded files are kept. It is cleaned periodically as this -program is reexecuted. If XDG_CACHE_HOME is set then -$XDG_CACHE_HOME/debuginfod_client is the default location, otherwise -$HOME/.cache/debuginfod_client is used. - -.TP 21 -.B DEBUGINFOD_RETRY_LITMIT -This environment variable governs the default limit of retry attempts. If a -query failed with errno other than ENOENT, will initiate several attempts -within the limit. - .SH "ERRORS" The following list is not comprehensive. Error codes may also originate from calls to various C Library functions. @@ -341,14 +299,7 @@ System is unable to allocate resources. Query failed due to timeout. \fB$DEBUGINFOD_TIMEOUT\fP controls the timeout duration. See debuginfod(8) for more information. -.SH "FILES" -.LP -.PD .1v -.TP 20 -.B $HOME/.debuginfod_client_cache -Default cache directory. If XDG_CACHE_HOME is not set then -\fB$HOME/.cache/debuginfod_client\fP is used. -.PD +.so ./debuginfod-client-config.7 .SH "SEE ALSO" .I "debuginfod(8)"