Provided by: libdebuginfod-dev_0.190-1.1build4_amd64 bug

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);
       int debuginfod_find_section(debuginfod_client *client,
                                  const unsigned char *build_id,
                                  int build_id_len,
                                  const char * section,
                                  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);
       const char* debuginfod_get_headers(debuginfod_client *client);

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.

       debuginfod_find_section() queries the debuginfod server URLs contained in $DEBUGINFOD_URLS
       for the binary contents of an ELF/DWARF section contained in  a  debuginfo  or  executable
       file with the given build_id. section should be the name of the desired ELF/DWARF section.
       If a server does not support section queries, debuginfod_find_section may query the server
       for  the  debuginfo  and/or  executable with build_id in order to retrieve and extract the
       section.

       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.

       $DEBUGINFOD_HEADERS_FILE specifies a file to supply headers  to  outgoing  requests.  Each
       non-whitespace line of this file is handled as if debuginfod_add_http_header() were called
       on the contents.

       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. You can use this function to add  authorization
       information  for  access control, or to provide optional headers to the server for logging
       purposes.

       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.

       During or after a lookup, a client application may call debuginfod_get_headers() to gather
       the subset of HTTP response headers received from the current or  most  recent  debuginfod
       server.   Only those headers prefixed with X-DEBUGINFOD (case-insensitive) are kept.  They
       are returned as a single string, with each "header: value" terminated with a \n (not  \r\n
       as  in HTTP).  It may be NULL.  The resulting string is owned by the library, and must not
       be modified or freed.  The caller should copy the returned string if it is  needed  beyond
       the release of the client object.

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_*() functions 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.

SEE ALSO

       debuginfod(8)

                                                                             DEBUGINFOD_FIND_*(3)