1
2
3DEBUGINFOD_FIND_*(3)       Library Functions Manual       DEBUGINFOD_FIND_*(3)
4
5
6

NAME

8       debuginfod_find_debuginfo - request debuginfo from debuginfod
9
10

SYNOPSIS

12       #include <elfutils/debuginfod.h>
13
14       Link with -ldebuginfod.
15
16       CONNECTION HANDLE
17
18       debuginfod_client *debuginfod_begin(void);
19       void debuginfod_end(debuginfod_client *client);
20
21       LOOKUP FUNCTIONS
22
23       int debuginfod_find_debuginfo(debuginfod_client *client,
24                                     const unsigned char *build_id,
25                                     int build_id_len,
26                                     char ** path);
27       int debuginfod_find_executable(debuginfod_client *client,
28                                      const unsigned char *build_id,
29                                      int build_id_len,
30                                      char ** path);
31       int debuginfod_find_source(debuginfod_client *client,
32                                  const unsigned char *build_id,
33                                  int build_id_len,
34                                  const char *filename,
35                                  char ** path);
36       int debuginfod_find_section(debuginfod_client *client,
37                                  const unsigned char *build_id,
38                                  int build_id_len,
39                                  const char * section,
40                                  char ** path);
41
42
43       OPTIONAL FUNCTIONS
44
45       typedef int (*debuginfod_progressfn_t)(debuginfod_client *client,
46                                              long a, long b);
47       void debuginfod_set_progressfn(debuginfod_client *client,
48                                      debuginfod_progressfn_t progressfn);
49       void debuginfod_set_verbose_fd(debuginfod_client *client,
50                                      int fd);
51       void debuginfod_set_user_data(debuginfod_client *client,
52                                     void *data);
53       void* debuginfod_get_user_data(debuginfod_client *client);
54       const char* debuginfod_get_url(debuginfod_client *client);
55       int debuginfod_add_http_header(debuginfod_client *client,
56                                      const char* header);
57       const char* debuginfod_get_headers(debuginfod_client *client);
58
59

DESCRIPTION

61       debuginfod_begin()  creates  a debuginfod_client connection handle that
62       should be used with all other calls.  debuginfod_end() should be called
63       on the client handle to release all state and storage when done.
64
65       debuginfod_find_debuginfo(), debuginfod_find_executable(), and debugin‐
66       fod_find_source() query the debuginfod server URLs contained in $DEBUG‐
67       INFOD_URLS  (see  below)  for  the debuginfo, executable or source file
68       with the given build_id. build_id should be a pointer to either a null-
69       terminated, lowercase hex string or a binary blob. If build_id is given
70       as a hex string,  build_id_len  should  be  0.  Otherwise  build_id_len
71       should be the number of bytes in the binary blob.
72
73       debuginfod_find_source() also requires a filename in order to specify a
74       particular source file. filename should be an absolute  path  that  in‐
75       cludes  the  compilation directory of the CU associated with the source
76       file.  Relative path names commonly appear in the DWARF  file's  source
77       directory,  but these paths are relative to individual compilation unit
78       AT_comp_dir paths, and yet an executable is made up  of  multiple  CUs.
79       Therefore, to disambiguate, debuginfod expects source queries to prefix
80       relative path names with the CU compilation-directory,  followed  by  a
81       mandatory "/".
82
83       Note:  the  caller  may  or  may not elide ../ or /./ or extraneous ///
84       sorts of path components in the directory  names.   debuginfod  accepts
85       both  forms.  Specifically, debuginfod canonicalizes path names accord‐
86       ing to RFC3986 section 5.2.4 (Remove Dot Segments), plus  reducing  any
87       // to / in the path.
88
89       debuginfod_find_section()  queries the debuginfod server URLs contained
90       in $DEBUGINFOD_URLS for the binary contents  of  an  ELF/DWARF  section
91       contained  in  a  debuginfo or executable file with the given build_id.
92       section should be the name of the  desired  ELF/DWARF  section.   If  a
93       server  does  not  support section queries, debuginfod_find_section may
94       query the server for the debuginfo and/or executable with  build_id  in
95       order to retrieve and extract the section.
96
97       If  path  is  not  NULL and the query is successful, path is set to the
98       path of the file in the cache. The caller must free() this value.
99
100       The URLs in $DEBUGINFOD_URLS may be queried in parallel. As soon  as  a
101       debuginfod  server  begins transferring the target file all of the con‐
102       nections to the other servers are closed.
103
104       A client handle should be used from only one thread at a time.  A  han‐
105       dle  may  be  reused for a series of lookups, which can improve perfor‐
106       mance due to retention of connections and caches.
107
108

RETURN VALUE

110       debuginfod_begin returns the debuginfod_client handle to use  with  all
111       other calls.  On error NULL will be returned and errno will be set.
112
113       If a find family function is successful, the resulting file is saved to
114       the client cache and a file descriptor to that file is  returned.   The
115       caller  needs  to close() this descriptor.  Otherwise, a negative error
116       code is returned.
117
118

OPTIONAL FUNCTIONS

120       A small number of optional functions are available to tune or query the
121       operation of the debuginfod client.
122
123
124   PROGRESS CALLBACK
125       As the debuginfod_find_*() functions may block for seconds or longer, a
126       progress callback function is called periodically, if  configured  with
127       debuginfod_set_progressfn().   This  function sets a new progress call‐
128       back function (or NULL) for the client handle.
129
130       The given callback function is called from the context of  each  thread
131       that  is  invoking  any of the other lookup functions.  It is given two
132       numeric parameters that, if thought of as a numerator a and denominator
133       b,  together  represent a completion fraction a/b.  The denominator may
134       be zero initially, until a quantity such as an exact download size  be‐
135       comes known.
136
137       The  progress  callback function is also the supported way to interrupt
138       the download operation.  (The library does not modify or  trigger  sig‐
139       nals.)   The  progress  callback must return 0 to continue the work, or
140       any other value to stop work as soon as  possible.   Consequently,  the
141       debuginfod_find_*()  function  will  likely  return  with an error, but
142       might still succeed.
143
144
145   VERBOSE OUTPUT
146       The debuginfod_find_*() functions may use  several  techniques  to  re‐
147       trieve  the requested files, through the cache or through one or multi‐
148       ple servers or file URLs. To show how a query is handled  the  debugin‐
149       fod_set_verbose_fd() can be used to set a particular file descriptor on
150       which verbose output is given about the query steps and eventual errors
151       encountered.
152
153
154   USER DATA POINTER
155       A  single  void  * pointer associated with the connection handle may be
156       set  any  time  via  debuginfod_set_user_data(),  and   retrieved   via
157       debuginfod_get_user_data().  The value is undefined if unset.
158
159
160   URL
161       The  URL of the current or most recent outgoing download, if known, may
162       be retrieved via debuginfod_get_url() from the progressfn callback,  or
163       afterwards.   It may be NULL.  The resulting string is owned by the li‐
164       brary, and must not be modified or freed.  The caller should copy it if
165       it is needed beyond the release of the client object.
166
167
168   HTTP HEADER
169       Before  each lookup function is initiated, a client application may add
170       HTTP request headers.  These are  reset  after  each  lookup  function.
171       debuginfod_add_http_header()  may  be  called  with strings of the form
172       "Header: value".  These strings are copied by the library.  A zero  re‐
173       turn  value  indicates success, but out-of-memory conditions may result
174       in a non-zero -ENOMEM. If the string is in the wrong form -EINVAL  will
175       be returned.
176
177       $DEBUGINFOD_HEADERS_FILE specifies a file to supply headers to outgoing
178       requests. Each non-whitespace line  of  this  file  is  handled  as  if
179       debuginfod_add_http_header() were called on the contents.
180
181       Note  that  the  current  debuginfod-client library implementation uses
182       libcurl, but you shouldn't rely on that fact. Don't use  this  function
183       for replacing any standard headers, except for the User-Agent mentioned
184       below. You can use this function to add authorization  information  for
185       access  control,  or to provide optional headers to the server for log‐
186       ging purposes.
187
188       By default, the library adds a descriptive User-Agent: header to outgo‐
189       ing  requests.   If  the client application adds a header with the same
190       name, this default is suppressed.
191
192       During  or  after   a   lookup,   a   client   application   may   call
193       debuginfod_get_headers()  to gather the subset of HTTP response headers
194       received from the current or most recent debuginfod server.  Only those
195       headers  prefixed  with X-DEBUGINFOD (case-insensitive) are kept.  They
196       are returned as a single string, with each "header:  value"  terminated
197       with a \n (not \r\n as in HTTP).  It may be NULL.  The resulting string
198       is owned by the library, and must not be modified or freed.  The caller
199       should  copy  the returned string if it is needed beyond the release of
200       the client object.
201
202

MACROS

204   DEBUGINFOD_SONAME
205       Defined to the string that could be passed to dlopen(3) if the  library
206       is loaded at runtime, for example
207
208
209           void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);
210
211

SECURITY

213       debuginfod_find_*()  functions  do  not include any particular security
214       features.  They trust that the binaries returned by  the  debuginfod(s)
215       are  accurate.   Therefore,  the  list  of  servers should include only
216       trustworthy ones.  If accessed across HTTP rather than HTTPS, the  net‐
217       work  should  be  trustworthy.  Passing user authentication information
218       through the internal libcurl library is not currently  enabled,  except
219       for  the  basic  plaintext  http[s]://userid:password@hostname/  style.
220       (The debuginfod server does not perform authentication, but a front-end
221       proxy server could.)
222
223

ERRORS

225       The following list is not comprehensive. Error codes may also originate
226       from calls to various C Library functions.
227
228
229       EACCESS
230              Denied access to resource located at the URL.
231
232
233       ECONNREFUSED
234              Unable to connect to remote host. Also returned  when  an  HTTPS
235              connection couldn't be verified (bad certificate).
236
237
238       ECONNRESET
239              Unable to either send or receive network data.
240
241
242       EHOSTUNREACH
243              Unable to resolve remote host.
244
245
246       EINVAL One or more arguments are incorrectly formatted. build_id may be
247              too long (greater than 256 characters), filename may not  be  an
248              absolute path or a debuginfod URL is malformed.
249
250
251       EIO    Unable to write data received from server to local file.
252
253
254       EMLINK Too many HTTP redirects.
255
256
257       ENETUNREACH
258              Unable to initialize network connection.
259
260
261       ENOENT Could  not  find  the  resource located at URL. Often this error
262              code indicates that a debuginfod server  was  successfully  con‐
263              tacted but the server could not find the target file.
264
265
266       ENOMEM System is unable to allocate resources.
267
268
269       ENOSYS $DEBUGINFOD_URLS is not defined.
270
271
272       ETIME  Query  failed  due to timeout. $DEBUGINFOD_TIMEOUT and $DEBUGIN‐
273              FOD_MAXTIME control this.
274
275
276       EF2BIG Query aborted due to the file requested being too big.  The $DE‐
277              BUGINFOD_MAXSIZE controls this.
278
279
280

SEE ALSO

282       debuginfod(8)
283
284
285
286                                                          DEBUGINFOD_FIND_*(3)
Impressum