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_user_data(debuginfod_client *client,
44                                     void *data);
45       void* debuginfod_get_user_data(debuginfod_client *client);
46       const char* debuginfod_get_url(debuginfod_client *client);
47       int debuginfod_add_http_header(debuginfod_client *client,
48                                      const char* header);
49
50

DESCRIPTION

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

RETURN VALUE

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

OPTIONAL FUNCTIONS

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

CACHE

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

SECURITY

175       debuginfod_find_debuginfo(), debuginfod_find_executable(), and debugin‐
176       fod_find_source()  do  not  include  any  particular security features.
177       They trust that the binaries returned by the  debuginfod(s)  are  accu‐
178       rate.   Therefore,  the list of servers should include only trustworthy
179       ones.  If accessed across HTTP rather than HTTPS, the network should be
180       trustworthy.   Passing  user  authentication  information  through  the
181       internal libcurl library is not currently enabled, except for the basic
182       plaintext  http[s]://userid:password@hostname/  style.  (The debuginfod
183       server does not perform authentication, but a  front-end  proxy  server
184       could.)
185
186

ENVIRONMENT VARIABLES

188       DEBUGINFOD_URLS      This  environment  variable contains a list of URL
189                            prefixes for trusted debuginfod instances.  Alter‐
190                            nate URL prefixes are separated by space.
191
192
193       DEBUGINFOD_TIMEOUT   This  environment variable governs the timeout for
194                            each debuginfod HTTP connection.   A  server  that
195                            fails to provide at least 100K of data within this
196                            many seconds is skipped. The default  is  90  sec‐
197                            onds.  (Zero or negative means "no timeout".)
198
199
200       DEBUGINFOD_PROGRESS  This  environment  variable  governs  the  default
201                            progress function.  If set, and if a progressfn is
202                            not  explicitly set, then the library will config‐
203                            ure a  default  progressfn.   This  function  will
204                            append  a  simple progress message periodically to
205                            stderr.  The default is no progress function  out‐
206                            put.
207
208
209       DEBUGINFOD_CACHE_PATH
210                            This  environment variable governs the location of
211                            the cache where downloaded files are kept.  It  is
212                            cleaned  periodically  as  this  program is reexe‐
213                            cuted.   If    XDG_CACHE_HOME    is    set    then
214                            $XDG_CACHE_HOME/debuginfod_client  is  the default
215                            location, otherwise $HOME/.cache/debuginfod_client
216                            is used.
217
218
219

ERRORS

221       The following list is not comprehensive. Error codes may also originate
222       from calls to various C Library functions.
223
224
225       EACCESS
226              Denied access to resource located at the URL.
227
228
229       ECONNREFUSED
230              Unable to connect to remote host.
231
232
233       ECONNRESET
234              Unable to either send or recieve network data.
235
236
237       EHOSTUNREACH
238              Unable to resolve remote host.
239
240
241       EINVAL One or more arguments are incorrectly formatted. build_id may be
242              too  long  (greater than 256 characters), filename may not be an
243              absolute path or a debuginfod URL is malformed.
244
245
246       EIO    Unable to write data received from server to local file.
247
248
249       EMLINK Too many HTTP redirects.
250
251
252       ENETUNREACH
253              Unable to initialize network connection.
254
255
256       ENOENT Could not find the resource located at  URL.  Often  this  error
257              code  indicates  that  a debuginfod server was successfully con‐
258              tacted but the server could not find the target file.
259
260
261       ENOMEM System is unable to allocate resources.
262
263
264       ENOSYS $DEBUGINFOD_URLS is not defined.
265
266
267       ETIME  Query failed due to timeout.  $DEBUGINFOD_TIMEOUT  controls  the
268              timeout duration. See debuginfod(8) for more information.
269
270

FILES

272       $HOME/.debuginfod_client_cache
273                           Default  cache  directory. If XDG_CACHE_HOME is not
274                           set then $HOME/.cache/debuginfod_client is used.
275
276

SEE ALSO

278       debuginfod(8)
279
280
281
282                                                          DEBUGINFOD_FIND_*(3)
Impressum