|
Packit |
032894 |
'\"! tbl | nroff \-man
|
|
Packit |
032894 |
'\" t macro stdmacro
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.de SAMPLE
|
|
Packit |
032894 |
.br
|
|
Packit |
032894 |
.RS 0
|
|
Packit |
032894 |
.nf
|
|
Packit |
032894 |
.nh
|
|
Packit |
032894 |
..
|
|
Packit |
032894 |
.de ESAMPLE
|
|
Packit |
032894 |
.hy
|
|
Packit |
032894 |
.fi
|
|
Packit |
032894 |
.RE
|
|
Packit |
032894 |
..
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.TH DEBUGINFOD-FIND 1
|
|
Packit |
032894 |
.SH NAME
|
|
Packit |
032894 |
debuginfod-find \- request debuginfo-related data
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SH SYNOPSIS
|
|
Packit |
032894 |
.B debuginfod-find [\fIOPTION\fP]... debuginfo \fIBUILDID\fP
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.B debuginfod-find [\fIOPTION\fP]... executable \fIBUILDID\fP
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.B debuginfod-find [\fIOPTION\fP]... source \fIBUILDID\fP \fI/FILENAME\fP
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SH DESCRIPTION
|
|
Packit |
032894 |
\fBdebuginfod-find\fP queries one or more \fBdebuginfod\fP servers for
|
|
Packit |
032894 |
debuginfo-related data. In case of a match, it saves the the
|
|
Packit |
032894 |
requested file into a local cache, prints the file name to standard
|
|
Packit |
032894 |
output, and exits with a success status of 0. In case of any error,
|
|
Packit |
032894 |
it exits with a failure status and an error message to standard error.
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.\" Much of the following text is duplicated with debuginfod.8
|
|
Packit |
032894 |
|
|
Packit |
032894 |
The debuginfod system uses buildids to identify debuginfo-related data.
|
|
Packit |
032894 |
These are stored as binary notes in ELF/DWARF files, and are
|
|
Packit |
032894 |
represented as lowercase hexadecimal. For example, for a program
|
|
Packit |
032894 |
/bin/ls, look at the ELF note GNU_BUILD_ID:
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SAMPLE
|
|
Packit |
032894 |
% readelf -n /bin/ls | grep -A4 build.id
|
|
Packit |
032894 |
Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
|
|
Packit |
032894 |
Owner Data size Type
|
|
Packit |
032894 |
GNU 20 GNU_BUILD_ID
|
|
Packit |
032894 |
Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
|
|
Packit |
032894 |
.ESAMPLE
|
|
Packit |
032894 |
|
|
Packit |
032894 |
Then the hexadecimal BUILDID is simply:
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SAMPLE
|
|
Packit |
032894 |
8713b9c3fb8a720137a4a08b325905c7aaf8429d
|
|
Packit |
032894 |
.ESAMPLE
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SS debuginfo \fIBUILDID\fP
|
|
Packit |
032894 |
|
|
Packit |
032894 |
If the given buildid is known to a server, this request will result
|
|
Packit |
032894 |
in a binary object that contains the customary \fB.*debug_*\fP
|
|
Packit |
032894 |
sections. This may be a split debuginfo file as created by
|
|
Packit |
032894 |
\fBstrip\fP, or it may be an original unstripped executable.
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SS executable \fIBUILDID\fP
|
|
Packit |
032894 |
|
|
Packit |
032894 |
If the given buildid is known to the server, this request will result
|
|
Packit |
032894 |
in a binary object that contains the normal executable segments. This
|
|
Packit |
032894 |
may be a executable stripped by \fBstrip\fP, or it may be an original
|
|
Packit |
032894 |
unstripped executable. \fBET_DYN\fP shared libraries are considered
|
|
Packit |
032894 |
to be a type of executable.
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SS source \fIBUILDID\fP \fI/SOURCE/FILE\fP
|
|
Packit |
032894 |
|
|
Packit |
032894 |
If the given buildid is known to the server, this request will result
|
|
Packit |
032894 |
in a binary object that contains the source file mentioned. The path
|
|
Packit |
032894 |
should be absolute. Relative path names commonly appear in the DWARF
|
|
Packit |
032894 |
file's source directory, but these paths are relative to
|
|
Packit |
032894 |
individual compilation unit AT_comp_dir paths, and yet an executable
|
|
Packit |
032894 |
is made up of multiple CUs. Therefore, to disambiguate, debuginfod
|
|
Packit |
032894 |
expects source queries to prefix relative path names with the CU
|
|
Packit |
032894 |
compilation-directory, followed by a mandatory "/".
|
|
Packit |
032894 |
|
|
Packit |
032894 |
Note: the user should not elide \fB../\fP or \fB/./\fP or extraneous
|
|
Packit |
032894 |
\fB///\fP sorts of path components in the directory names, because if
|
|
Packit |
032894 |
this is how those names appear in the DWARF files, that is what
|
|
Packit |
032894 |
debuginfod needs to see too.
|
|
Packit |
032894 |
|
|
Packit |
032894 |
For example:
|
|
Packit |
032894 |
.TS
|
|
Packit |
032894 |
l l.
|
|
Packit |
032894 |
#include <stdio.h> source BUILDID /usr/include/stdio.h
|
|
Packit |
032894 |
/path/to/foo.c source BUILDID /path/to/foo.c
|
|
Packit |
032894 |
\../bar/foo.c AT_comp_dir=/zoo/ source BUILDID /zoo//../bar/foo.c
|
|
Packit |
032894 |
.TE
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SH "OPTIONS"
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.TP
|
|
Packit |
032894 |
.B "\-v"
|
|
Packit |
032894 |
Increase verbosity, including printing frequent download-progress messages.
|
|
Packit |
032894 |
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SH "SECURITY"
|
|
Packit |
032894 |
|
|
Packit |
032894 |
debuginfod-find \fBdoes not\fP include any particular security
|
|
Packit |
032894 |
features. It trusts that the binaries returned by the debuginfod(s)
|
|
Packit |
032894 |
are accurate. Therefore, the list of servers should include only
|
|
Packit |
032894 |
trustworthy ones. If accessed across HTTP rather than HTTPS, the
|
|
Packit |
032894 |
network should be trustworthy. Authentication information through
|
|
Packit |
032894 |
the internal \fIlibcurl\fP library is not currently enabled, except
|
|
Packit |
032894 |
for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style.
|
|
Packit |
032894 |
(The debuginfod server does not perform authentication, but a front-end
|
|
Packit |
032894 |
proxy server could.)
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SH "ENVIRONMENT VARIABLES"
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.TP 21
|
|
Packit |
032894 |
.B DEBUGINFOD_URLS
|
|
Packit |
032894 |
This environment variable contains a list of URL prefixes for trusted
|
|
Packit |
032894 |
debuginfod instances. Alternate URL prefixes are separated by space.
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.TP 21
|
|
Packit |
032894 |
.B DEBUGINFOD_TIMEOUT
|
|
Packit |
032894 |
This environment variable governs the timeout for each debuginfod HTTP
|
|
Packit |
86a02d |
connection. A server that fails to provide at least 100K of data
|
|
Packit |
86a02d |
within this many seconds is skipped. The default is 90 seconds. (Zero
|
|
Packit |
86a02d |
or negative means "no timeout".)
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.TP 21
|
|
Packit |
032894 |
.B DEBUGINFOD_CACHE_PATH
|
|
Packit |
032894 |
This environment variable governs the location of the cache where
|
|
Packit |
032894 |
downloaded files are kept. It is cleaned periodically as this program
|
|
Packit |
032894 |
is reexecuted. Cache management parameters may be set by files under
|
|
Packit |
032894 |
this directory: see the \fBdebuginfod_find_debuginfo(3)\fP man page
|
|
Packit |
032894 |
for details. The default is $HOME/.debuginfod_client_cache.
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SH "FILES"
|
|
Packit |
032894 |
.LP
|
|
Packit |
032894 |
.PD .1v
|
|
Packit |
032894 |
.TP 20
|
|
Packit |
032894 |
.B $HOME/.debuginfod_client_cache
|
|
Packit |
032894 |
Default cache directory.
|
|
Packit |
032894 |
.PD
|
|
Packit |
032894 |
|
|
Packit |
032894 |
.SH "SEE ALSO"
|
|
Packit |
032894 |
.I "debuginfod(8)"
|
|
Packit |
032894 |
.I "debuginfod_find_debuginfod(3)"
|