path: root/doc/debuginfod_find_debuginfo.3

'\"! tbl | nroff \-man
'\" t macro stdmacro

.de SAMPLE
.br
.RS 0
.nf
.nh
..
.de ESAMPLE
.hy
.fi
.RE
..

.TH DEBUGINFOD_FIND_DEBUGINFO 3
.SH NAME
debuginfod_find_debuginfo \- request debuginfo from debuginfod

.SH SYNOPSIS
.nf
.B #include <elfutils/debuginfod.h>
.PP
.BI "debuginfod_find_debuginfo(const unsigned char *" build_id ", int " build_id_len ", char ** " path ");"
.BI "debuginfod_find_executable(const unsigned char *" build_id ", int " build_id_len ", char ** " path ");"
.BI "debuginfod_find_source(const unsigned char *" build_id ", int " build_id_len ", const char *" filename ", char ** " path ");"

.SH DESCRIPTION
.BR debuginfod_find_debuginfo (),
.BR debuginfod_find_executable (),
and
.BR debuginfod_find_source ()
query the debuginfod server URLs contained in
.BR $DEBUGINFOD_URLS
(see below) for the debuginfo, executable or source file with the
given \fIbuild_id\fP. \fIbuild_id\fP should be a pointer to either
a null-terminated, lowercase hex string or a binary blob. If
\fIbuild_id\fP is given as a hex string, \fIbuild_id_len\fP should
be 0. Otherwise \fIbuild_id_len\fP should be the number of bytes in
the binary blob.

.BR debuginfod_find_source ()
also requries a \fIfilename\fP in order to specify a particular
source file. \fIfilename\fP should be an absolute path that includes
the compilation directory of the CU associated with the source file.
Relative path names commonly appear in the DWARF file's source directory,
but these paths are relative to individual compilation unit AT_comp_dir
paths, and yet an executable is made up of multiple CUs. Therefore, to
disambiguate, debuginfod expects source queries to prefix relative path
names with the CU compilation-directory, followed by a mandatory "/".

Note: the caller should not elide \fB../\fP or \fB/./\fP or extraneous
\fB///\fP sorts of path components in the directory names, because if
this is how those names appear in the DWARF files, that is what
debuginfod needs to see too.

If \fIpath\fP is not NULL and the query is successful, \fIpath\fP is set
to the path of the file in the cache. The caller must \fBfree\fP() this value.

The URLs in \fB$DEBUGINFOD_URLS\fP are queried in parallel. As soon as a
debuginfod server begins transfering the target file all of the connections
to the other servers are closed.

.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 "SECURITY"
.BR debuginfod_find_debuginfo (),
.BR debuginfod_find_executable (),
and
.BR debuginfod_find_source ()
\fBdo not\fP include any particular security
features.  They trust that the binaries returned by the debuginfod(s)
are accurate.  Therefore, the list of servers should include only
trustworthy ones.  If accessed across HTTP rather than HTTPS, the
network should be trustworthy.  Passing user authentication information
through the internal \fIlibcurl\fP library is not currently enabled, except
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 respond within this many seconds
is skipped.  The default is 5.

.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.  The default is $HOME/.debuginfod_client_cache.

.SH "RETURN VALUE"
If the query is successful, these functions save the target file
to the client cache and return a file descriptor to that file.
Otherwise an error code is returned.

.SH "ERRORS"
The following list is not comprehensive. Error codes may also
originate from calls to various C Library functions.

.TP
.BR EACCESS
Denied access to resource located at the URL.

.TP
.BR ECONNREFUSED
Unable to connect to remote host.

.TP
.BR ECONNRESET
Unable to either send or recieve network data.

.TP
.BR EHOSTUNREACH
Unable to resolve remote host.

.TP
.BR EINVAL
One or more arguments are incorrectly formatted. \fIbuild_id\fP may
be too long (greater than 256 characters), \fIfilename\fP may not
be an absolute path or a debuginfod URL is malformed.

.TP
.BR EIO
Unable to write data received from server to local file.

.TP
.BR EMLINK
Too many HTTP redirects.

.TP
.BR ENETUNREACH
Unable to initialize network connection.

.TP
.BR ENOENT
Could not find the resource located at URL. Often this error code
indicates that a debuginfod server was successfully contacted but
the server could not find the target file.

.TP
.BR ENOMEM
System is unable to allocate resources.

.TP
.BR ENOSYS
\fB$DEBUGINFOD_URLS\fP is not defined.

.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.
.PD

.SH "SEE ALSO"
.I "debuginfod(8)"