plucky (3) debuginfod_find_section.3.gz

Provided by: libdebuginfod-dev_0.192-4_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);
       int debuginfod_find_metadata(debuginfod_client *client,
                                   const char *key,
                                   const char *value,
                                   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.

       debuginfod_find_metadata() queries all debuginfod server URLs contained in $DEBUGINFOD_URLS for  metadata
       for  all matches of a given key/value query against files in their indexes.  The resulting file is a JSON
       document.  See the debuginfod-find(1) man page for examples of the supported types of  key/value  queries
       and their JSON results.

       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 file descriptor points to  the  beginning  of  the  file.   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

       If IMA signature(s) are available from the RPMs  that  contain  requested  files,  then  debuginfod  will
       extract  those  signatures  into response headers, and debuginfod_find_*() will perform verification upon
       the files.  Validation policy is  controlled  via  tags  inserted  into  $DEBUGINFOD_URLS.   By  default,
       debuginfod_find_*() acts in ignore mode.

       If accessed across HTTP rather than HTTPS, the network should be trustworthy.  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.

       EBADMSG
              File content failed IMA verification against a known signer certificate.

       ENOKEY File content failed IMA verification due to missing signer certificate.

       ENODATA
              File content failed IMA verification because of a missing signature.

SEE ALSO

       debuginfod(8)

                                                                                            DEBUGINFOD_FIND_*(3)