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
68       includes 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.
90
91

RETURN VALUE

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

OPTIONAL FUNCTIONS

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

CACHE

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

MACROS

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

SECURITY

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

ENVIRONMENT VARIABLES

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

ERRORS

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

FILES

299       $HOME/.debuginfod_client_cache
300                           Default  cache  directory. If XDG_CACHE_HOME is not
301                           set then $HOME/.cache/debuginfod_client is used.
302
303

SEE ALSO

305       debuginfod(8)
306
307
308
309                                                          DEBUGINFOD_FIND_*(3)
Impressum