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
37       OPTIONAL FUNCTIONS
38
39       typedef int (*debuginfod_progressfn_t)(debuginfod_client *client,
40                                              long a, long b);
41       void debuginfod_set_progressfn(debuginfod_client *client,
42                                      debuginfod_progressfn_t progressfn);
43       void debuginfod_set_verbose_fd(debuginfod_client *client,
44                                      int fd);
45       void debuginfod_set_user_data(debuginfod_client *client,
46                                     void *data);
47       void* debuginfod_get_user_data(debuginfod_client *client);
48       const char* debuginfod_get_url(debuginfod_client *client);
49       int debuginfod_add_http_header(debuginfod_client *client,
50                                      const char* header);
51
52

DESCRIPTION

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

RETURN VALUE

95       debuginfod_begin returns the debuginfod_client handle to use  with  all
96       other calls.  On error NULL will be returned and errno will be set.
97
98       If a find family function is successful, the resulting file is saved to
99       the client cache and a file descriptor to that file is  returned.   The
100       caller  needs  to close() this descriptor.  Otherwise, a negative error
101       code is returned.
102
103

OPTIONAL FUNCTIONS

105       A small number of optional functions are available to tune or query the
106       operation of the debuginfod client.
107
108
109   PROGRESS CALLBACK
110       As the debuginfod_find_*() functions may block for seconds or longer, a
111       progress callback function is called periodically, if  configured  with
112       debuginfod_set_progressfn().   This  function sets a new progress call‐
113       back function (or NULL) for the client handle.
114
115       The given callback function is called from the context of  each  thread
116       that  is  invoking  any of the other lookup functions.  It is given two
117       numeric parameters that, if thought of as a numerator a and denominator
118       b,  together  represent a completion fraction a/b.  The denominator may
119       be zero initially, until a quantity such as an exact download size  be‐
120       comes known.
121
122       The  progress  callback function is also the supported way to interrupt
123       the download operation.  (The library does not modify or  trigger  sig‐
124       nals.)   The  progress  callback must return 0 to continue the work, or
125       any other value to stop work as soon as  possible.   Consequently,  the
126       debuginfod_find_*()  function  will  likely  return  with an error, but
127       might still succeed.
128
129
130   VERBOSE OUTPUT
131       The debuginfod_find_*() functions may use  several  techniques  to  re‐
132       trieve  the requested files, through the cache or through one or multi‐
133       ple servers or file URLs. To show how a query is handled  the  debugin‐
134       fod_set_verbose_fd() can be used to set a particular file descriptor on
135       which verbose output is given about the query steps and eventual errors
136       encountered.
137
138
139   USER DATA POINTER
140       A  single  void  * pointer associated with the connection handle may be
141       set  any  time  via  debuginfod_set_user_data(),  and   retrieved   via
142       debuginfod_get_user_data().  The value is undefined if unset.
143
144
145   URL
146       The  URL of the current or most recent outgoing download, if known, may
147       be retrieved via debuginfod_get_url() from the progressfn callback,  or
148       afterwards.   It may be NULL.  The resulting string is owned by the li‐
149       brary, and must not be modified or freed.  The caller should copy it if
150       it is needed beyond the release of the client object.
151
152
153   HTTP HEADER
154       Before  each lookup function is initiated, a client application may add
155       HTTP request headers.  These are  reset  after  each  lookup  function.
156       debuginfod_add_http_header()  may  be  called  with strings of the form
157       "Header: value".  These strings are copied by the library.  A zero  re‐
158       turn  value  indicates success, but out-of-memory conditions may result
159       in a non-zero -ENOMEM. If the string is in the wrong form -EINVAL  will
160       be returned.
161
162       Note  that  the  current  debuginfod-client library implementation uses
163       libcurl, but you shouldn't rely on that fact. Don't use  this  function
164       for replacing any standard headers, except for the User-Agent mentioned
165       below. The only supported usage of this function is for adding  an  op‐
166       tional  header which might or might not be passed through to the server
167       for logging purposes only.
168
169       By default, the library adds a descriptive User-Agent: header to outgo‐
170       ing  requests.   If  the client application adds a header with the same
171       name, this default is suppressed.
172
173

CACHE

175       If the query is successful, the debuginfod_find_*() functions save  the
176       target  file  to a local cache. The location of the cache is controlled
177       by the $DEBUGINFOD_CACHE_PATH environment variable (see below).  Clean‐
178       ing  of  the  cache  is  controlled  by  the cache_clean_interval_s and
179       max_unused_age_s files, which are found in  the  $DEBUGINFOD_CACHE_PATH
180       directory.  cache_clean_interval_s controls how frequently the cache is
181       traversed for cleaning and max_unused_age_s controls how  long  a  file
182       can  go unused (fstat(2) atime) before it's removed from the cache dur‐
183       ing cleaning. These files should contain only an ASCII decimal  integer
184       representing the interval or max unused age in seconds.  The default is
185       one day and one week, respectively.  Values of zero mean "immediately".
186
187

MACROS

189   DEBUGINFOD_SONAME
190       Defined to the string that could be passed to dlopen(3) if the  library
191       is loaded at runtime, for example
192
193
194           void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);
195
196

SECURITY

198       debuginfod_find_debuginfo(), debuginfod_find_executable(), and debugin‐
199       fod_find_source() do not  include  any  particular  security  features.
200       They  trust  that  the binaries returned by the debuginfod(s) are accu‐
201       rate.  Therefore, the list of servers should include  only  trustworthy
202       ones.  If accessed across HTTP rather than HTTPS, the network should be
203       trustworthy.  Passing user authentication information through  the  in‐
204       ternal  libcurl  library is not currently enabled, except for the basic
205       plaintext http[s]://userid:password@hostname/ style.   (The  debuginfod
206       server  does  not  perform authentication, but a front-end proxy server
207       could.)
208
209

ENVIRONMENT VARIABLES

211       DEBUGINFOD_URLS      This environment variable contains a list  of  URL
212                            prefixes for trusted debuginfod instances.  Alter‐
213                            nate URL prefixes are separated by space.
214
215
216       DEBUGINFOD_TIMEOUT   This environment variable governs the timeout  for
217                            each  debuginfod  HTTP  connection.  A server that
218                            fails to provide at least 100K of data within this
219                            many  seconds  is  skipped. The default is 90 sec‐
220                            onds.  (Zero or negative means "no timeout".)
221
222
223       DEBUGINFOD_PROGRESS  This  environment  variable  governs  the  default
224                            progress function.  If set, and if a progressfn is
225                            not explicitly set, then the library will  config‐
226                            ure  a default progressfn.  This function will ap‐
227                            pend a simple  progress  message  periodically  to
228                            stderr.   The default is no progress function out‐
229                            put.
230
231
232       DEBUGINFOD_VERBOSE   This environment variable governs the default file
233                            descriptor  for  verbose output.  If set, and if a
234                            verbose fd is not explicitly set, then the verbose
235                            output will be produced on STDERR_FILENO.
236
237
238       DEBUGINFOD_CACHE_PATH
239                            This  environment variable governs the location of
240                            the cache where downloaded files are kept.  It  is
241                            cleaned  periodically  as  this  program is reexe‐
242                            cuted.   If    XDG_CACHE_HOME    is    set    then
243                            $XDG_CACHE_HOME/debuginfod_client  is  the default
244                            location, otherwise $HOME/.cache/debuginfod_client
245                            is used.
246
247
248

ERRORS

250       The following list is not comprehensive. Error codes may also originate
251       from calls to various C Library functions.
252
253
254       EACCESS
255              Denied access to resource located at the URL.
256
257
258       ECONNREFUSED
259              Unable to connect to remote host. Also returned  when  an  HTTPS
260              connection couldn't be verified (bad certificate).
261
262
263       ECONNRESET
264              Unable to either send or receive network data.
265
266
267       EHOSTUNREACH
268              Unable to resolve remote host.
269
270
271       EINVAL One or more arguments are incorrectly formatted. build_id may be
272              too long (greater than 256 characters), filename may not  be  an
273              absolute path or a debuginfod URL is malformed.
274
275
276       EIO    Unable to write data received from server to local file.
277
278
279       EMLINK Too many HTTP redirects.
280
281
282       ENETUNREACH
283              Unable to initialize network connection.
284
285
286       ENOENT Could  not  find  the  resource located at URL. Often this error
287              code indicates that a debuginfod server  was  successfully  con‐
288              tacted but the server could not find the target file.
289
290
291       ENOMEM System is unable to allocate resources.
292
293
294       ENOSYS $DEBUGINFOD_URLS is not defined.
295
296
297       ETIME  Query  failed  due  to timeout. $DEBUGINFOD_TIMEOUT controls the
298              timeout duration. See debuginfod(8) for more information.
299
300

FILES

302       $HOME/.debuginfod_client_cache
303                           Default cache directory. If XDG_CACHE_HOME  is  not
304                           set then $HOME/.cache/debuginfod_client is used.
305
306

SEE ALSO

308       debuginfod(8)
309
310
311
312                                                          DEBUGINFOD_FIND_*(3)
Impressum