debuginfod_find_debuginfo man page

debuginfod_find_debuginfo — request debuginfo from debuginfod

Synopsis

#include <elfutils/debuginfod.h>

debuginfod_client *debuginfod_begin(void);
void debuginfod_end(debuginfod_client *client);

int debuginfod_find_debuginfo(debuginfod_client *client,
                              const unsigned char *build_id,
                              int build_id_len,
                              char ** path);
int debuginfod_find_executable(debuginfod_client *client,
                               const unsigned char *build_id,
                               int build_id_len,
                               char ** path);
int debuginfod_find_source(debuginfod_client *client,
                           const unsigned char *build_id,
                           int build_id_len,
                           const char *filename,
                           char ** path);

typedef int (*debuginfo_progressfn_t)(debuginfod_client *client,
                                      long a, long b);
void debuginfod_set_progressfn(debuginfod_client *client,
                               debuginfo_progressfn_t progressfn);

Link with -ldebuginfod.

Description

debuginfod_begin() creates a debuginfod_client connection handle that should be used with all other calls. debuginfod_end() should be called on the client handle to release all state and storage when done.

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

debuginfod_find_source() also requries a filename in order to specify a particular source file. filename 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 ../ or /./ or extraneous /// 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 path is not NULL and the query is successful, path is set to the path of the file in the cache. The caller must free() this value.

The URLs in $DEBUGINFOD_URLS may be queried in parallel. As soon as a debuginfod server begins transferring the target file all of the connections to the other servers are closed.

A client handle should be used from only one thread at a time.

Return Value

debuginfod_begin returns the debuginfod_client handle to use with all other calls.  On error NULL will be returned and errno will be set.

If a find family function is successful, the resulting file is saved to the client cache and a file descriptor to that file is returned. The caller needs to close() this descriptor.  Otherwise, a negative error code is returned.

Progress Callback

As the debuginfod_find_*() functions may block for seconds or longer, a progress callback function is called periodically, if configured with debuginfod_set_progressfn(). This function sets a new progress callback function (or NULL) for the client handle.

The given callback function is called from the context of each thread that is invoking any of the other lookup functions.  It is given two numeric parameters that, if thought of as a numerator a and denominator b, together represent a completion fraction a/b.  The denominator may be zero initially, until a quantity such as an exact download size becomes known.

The progress callback function is also the supported way to interrupt the download operation.  (The library does not modify or trigger signals.)  The progress callback must return 0 to continue the work, or any other value to stop work as soon as possible.  Consequently, the debuginfod_find_*() function will likely return with an error, but might still succeed.

Cache

If the query is successful, the debuginfod_find_*() functions save the target file to a local cache. The location of the cache is controlled by the $DEBUGINFOD_CACHE_PATH environment variable (see below). Cleaning of the cache is controlled by the cache_clean_interval_s and max_unused_age_s files, which are found in the $DEBUGINFOD_CACHE_PATH directory. cache_clean_interval_s controls how frequently the cache is traversed for cleaning and max_unused_age_s 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".

Security

debuginfod_find_debuginfo(), debuginfod_find_executable(), and debuginfod_find_source() do not 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 libcurl library is not currently enabled, except for the basic plaintext http[s]://userid:password@hostname/ style. (The debuginfod server does not perform authentication, but a front-end proxy server could.)

Environment Variables

DEBUGINFOD_URLS

This environment variable contains a list of URL prefixes for trusted debuginfod instances.  Alternate URL prefixes are separated by space.

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".)

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.

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.

Errors

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

EACCESS

Denied access to resource located at the URL.

ECONNREFUSED

Unable to connect to remote host.

ECONNRESET

Unable to either send or recieve network data.

EHOSTUNREACH

Unable to resolve remote host.

EINVAL

One or more arguments are incorrectly formatted. build_id may be too long (greater than 256 characters), filename may not be an absolute path or a debuginfod URL is malformed.

EIO

Unable to write data received from server to local file.

EMLINK

Too many HTTP redirects.

ENETUNREACH

Unable to initialize network connection.

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.

ENOMEM

System is unable to allocate resources.

ENOSYS

$DEBUGINFOD_URLS is not defined.

ETIME

Query failed due to timeout. $DEBUGINFOD_TIMEOUT controls the timeout duration. See debuginfod(8) for more information.

Files

$HOME/.debuginfod_client_cache

Default cache directory.

See Also

debuginfod(8)

Referenced By

debuginfod-find(1).

The man pages debuginfod_find_executable(3), debuginfod_find_source(3) and debuginfod_set_progressfn(3) are aliases of debuginfod_find_debuginfo(3).