#include <elfutils/debuginfod.h> Link with -ldebuginfod. CONNECTION HANDLE debuginfod_client *debuginfod_begin(void); void debuginfod_end(debuginfod_client *client); LOOKUP FUNCTIONS 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); OPTIONAL FUNCTIONS typedef int (*debuginfod_progressfn_t)(debuginfod_client *client, long a, long b); void debuginfod_set_progressfn(debuginfod_client *client, debuginfod_progressfn_t progressfn); void debuginfod_set_user_data(debuginfod_client *client, void *data); void* debuginfod_get_user_data(debuginfod_client *client); const char* debuginfod_get_url(debuginfod_client *client); int debuginfod_add_http_header(debuginfod_client *client, const char* header);
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 may or may not elide ../ or /./ or extraneous /// sorts of path components in the directory names. debuginfod accepts both forms. Specifically, debuginfod canonicalizes path names according to RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing any // to / in the path.
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.
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.
A small number of optional functions are available to tune or query the operation of the debuginfod client.
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.
A single void * pointer associated with the connection handle may be set any time via debuginfod_set_user_data(), and retrieved via debuginfod_get_user_data(). The value is undefined if unset.
The URL of the current or most recent outgoing download, if known, may be retrieved via debuginfod_get_url() from the progressfn callback, or afterwards. It may be NULL. The resulting string is owned by the library, and must not be modified or freed. The caller should copy it if it is needed beyond the release of the client object.
Before a lookup function is initiated, a client application may add HTTP request headers to future downloads. debuginfod_add_http_header() may be called with strings of the form Header:~value. These strings are copied by the library. A zero return value indicates success, but out-of-memory conditions may result in a non-zero -ENOMEM. If the string is in the wrong form -EINVAL will be returned.
Note that the current debuginfod-client library implementation uses libcurl, but you shouldn't rely on that fact. Don't use this function for replacing any standard headers, except for the User-Agent mentioned below. The only supported usage of this function is for adding an optional header which might or might not be passed through to the server for logging purposes only.
By default, the library adds a descriptive User-Agent: header to outgoing requests. If the client application adds a header with the same name, this default is suppressed.