Ubuntu Manpage: debuginfod_find_debuginfo - request debuginfo from debuginfod

Provided by: libdebuginfod-dev_0.187-4_amd64

NAME

       debuginfod_find_debuginfo - request debuginfo from debuginfod

SYNOPSIS

       #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_verbose_fd(debuginfod_client *client,
                                      int fd);
       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);

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 requires 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. A handle may be reused for
a series of lookups, which can improve performance due to retention of connections and
caches.

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.

OPTIONAL FUNCTIONS

       A  small  number of optional functions are available to tune or query the operation of the
       debuginfod client.

   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.

   VERBOSE OUTPUT
       The debuginfod_find_*() functions may use several techniques  to  retrieve  the  requested
       files,  through  the  cache or through one or multiple servers or file URLs. To show how a
       query is handled the debuginfod_set_verbose_fd() can be used  to  set  a  particular  file
       descriptor  on  which  verbose  output  is given about the query steps and eventual errors
       encountered.

   USER DATA POINTER
       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.

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

   HTTP HEADER
       Before  each  lookup  function  is  initiated,  a  client application may add HTTP request
       headers.  These are reset after each lookup function.  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.

MACROS

   DEBUGINFOD_SONAME
       Defined to the string that could be passed to  dlopen(3)  if  the  library  is  loaded  at
       runtime, for example

           void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);

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

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. Also returned when an HTTPS connection couldn't
be verified (bad certificate).

ECONNRESET
Unable to either send or receive 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 and $DEBUGINFOD_MAXTIME control
this.

EF2BIG Query aborted due to the file requested being too big. The $DEBUGINFOD_MAXSIZE
controls this.