+2021-07-28 Alice Zhang <alizhang@redhat.com>
+
+ 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.
+ * Makefile.am: Updated to include debuginfod-client-config.7
+ * man3, man7: Symlinks for source tree man page testing.
+
2021-07-26 Noah Sanci <nsanci@redhat.com>
PR27982
EXTRA_DIST = COPYING-GFDL README
dist_man1_MANS=readelf.1 elfclassify.1
notrans_dist_man3_MANS=elf_update.3 elf_getdata.3 elf_clone.3 elf_begin.3
+notrans_dist_man7_MANS=
notrans_dist_man8_MANS=
notrans_dist_man1_MANS=
if DEBUGINFOD
+notrans_dist_man7_MANS += debuginfod-client-config.7
notrans_dist_man8_MANS += debuginfod.8
endif
if LIBDEBUGINFOD
+notrans_dist_man7_MANS += debuginfod-client-config.7
notrans_dist_man3_MANS += debuginfod_add_http_header.3
notrans_dist_man3_MANS += debuginfod_begin.3
notrans_dist_man3_MANS += debuginfod_end.3
--- /dev/null
+'\"! tbl | nroff \-man
+'\" t macro stdmacro
+.if \n(zZ=1 .ig zZ
+
+.TH DEBUGINFOD-CLIENT-CONFIG 7
+.SH NAME
+debuginfod-client-config \- debuginfod client environment variables, cache control files and etc.
+
+.SH SYNOPSIS
+Several environment variables and control files control the behaviour of debuginfod client applications.
+
+.\" The preceding section permits this man page to be viewed as if self-contained.
+.zZ
+.\" The following section (only) gets included into other man pages via .so
+
+
+.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_CACHE_PATH
+This environment variable governs the location of the cache where
+downloaded files and cache-control files are kept. The default
+directory is chosen based on other environment variables, see below.
+
+.TP
+.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
+.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
+.B $DEBUGINFOD_RETRY_LIMIT
+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.
+
+.TP
+.B $DEBUGINFOD_TIMEOUT
+This environment variable governs the download \fIcommencing\fP
+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_MAXTIME
+This environment variable dictates how long the client will wait to
+\fIcomplete\fP the download a file found on a server in seconds. It is best
+used to ensure that a file is downloaded quickly or be rejected. The
+default is 0 (infinite time).
+
+.TP
+.B $DEBUGINFOD_MAXSIZE
+This environment variable dictates the maximum size of a file to
+download in bytes. This is best used if the user would like to ensure
+only small files are downloaded. A value of 0 causes no consideration
+for size, and the client may attempt to download a file of any size.
+The default is 0 (infinite size).
+
+.SH CACHE
+
+Before each query, the debuginfod client library checks for a need to
+clean the cache. If it's time to clean, the library traverses the
+cache directory and removes downloaded debuginfo-related artifacts and
+newly empty directories, if they have not been accessed recently.
+
+Control files are located directly under the cache directory. They
+contain simple decimal numbers to set cache-related configuration
+parameters. If the files do not exist, the client library creates the
+files with the default parameter values as content.
+
+After each query, the debuginfod client library deposits newly
+received files into a directory & file that is named based on the
+build-id. A failed query is also cached by a special file. The
+naming convention used for these artifacts is deliberately
+\fBundocumented\fP.
+
+.TP
+.B $XDG_CACHE_HOME/debuginfod_client/
+Default cache directory, if $XDG_CACHE_HOME is set.
+.PD
+
+.TP
+.B $HOME/.cache/debuginfod_client/
+Default cache directory, if $XDG_CACHE_HOME is not set.
+.PD
+
+.TP
+.B $HOME/.debuginfod_client_cache/
+Deprecated cache directory, used only if preexisting.
+.PD
+
+.TP
+.B cache_clean_interval_s
+This control file gives the interval between cache cleaning rounds, in
+seconds. The default is 86400, one day. 0 means "immediately".
+
+.TP
+.B max_unused_age_s
+This control file sets how long unaccessed debuginfo-related files
+are retained, in seconds. The default is 604800, one week. 0 means
+"immediately".
+
+.TP
+.B cache_miss_s
+This control file sets how long to remember a query failure, in
+seconds. New queries for the same artifacts within this time window
+are short-circuited (returning an immediate failure instead of sending
+a new query to servers). This accelerates queries that probably would
+still fail. The default is 600, 10 minutes. 0 means "forget
+immediately".
(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.
-
-.TP 21
-.B DEBUGINFOD_MAXTIME
-This environment variable dictates how long the client will wait to
-download a file found on a server in seconds. It is best used to ensure
-that a file is downloaded quickly or be rejected. The default is
-0 (infinite time).
-
-.TP 21
-.B DEBUGINFOD_MAXSIZE
-This environment variable dictates the maximum size of a file to
-download in bytes. This is best used if the user would like to ensure
-only small files are downloaded. A value of 0 causes no consideration
-for size, and the client may attempt to download a file of any size.
-The default is 0 (infinite size).
-
-.SH "FILES"
-.LP
-.PD .1v
-.TP 20
-.B $HOME/.debuginfod_client_cache
-Default cache directory.
-.PD
+.nr zZ 1
+.so man7/debuginfod-client-config.7
.SH "SEE ALSO"
.I "debuginfod(8)"
.fi
.RE
..
-
.TH DEBUGINFOD 8
.SH NAME
debuginfod \- debuginfo-related http file-server daemon
information through the internal \fIlibcurl\fP library is not currently
enabled.
+.nr zZ 1
+.so man7/debuginfod-client-config.7
-.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.
-
+.SH ADDITIONAL FILES
.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
-
.SH "SEE ALSO"
.I "debuginfod-find(1)"
header to outgoing requests. If the client application adds
a header with the same name, this default is suppressed.
-.SH "CACHE"
-If the query is successful, the \fBdebuginfod_find_*\fP() functions save
-the target file to a local cache. The location of the cache is controlled
-by the \fB$DEBUGINFOD_CACHE_PATH\fP environment variable (see below).
-Cleaning of the cache is controlled by the \fIcache_clean_interval_s\fP
-and \fImax_unused_age_s\fP files, which are found in the
-\fB$DEBUGINFOD_CACHE_PATH\fP directory. \fIcache_clean_interval_s\fP controls
-how frequently the cache is traversed for cleaning and \fImax_unused_age_s\fP
-controls how long a file can go unused (fstat(2) atime) before it's
-removed from the cache during cleaning. These files should contain only an
-ASCII decimal integer representing the interval or max unused age in seconds.
-The default is one day and one week, respectively. Values of zero mean "immediately".
-
.SH "MACROS"
.SS "DEBUGINFOD_SONAME"
(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.
.TP
.BR ETIME
-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
+Query failed due to timeout. \fB$DEBUGINFOD_TIMEOUT\fP and
+\fB$DEBUGINFOD_MAXTIME\fP control this.
+
+.TP
+.BR EF2BIG
+Query aborted due to the file requested being too big. The
+\fB$DEBUGINFOD_MAXSIZE\fP controls this.
+
+.nr zZ 1
+.so man7/debuginfod-client-config.7
.SH "SEE ALSO"
.I "debuginfod(8)"
--- /dev/null
+.
\ No newline at end of file
--- /dev/null
+.
\ No newline at end of file
projects / thirdparty / elfutils.git / commitdiff
