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

MACROS

175   DEBUGINFOD_SONAME
176       Defined to the string that could be passed to dlopen(3) if the  library
177       is loaded at runtime, for example
178
179
180           void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);
181
182

SECURITY

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

ERRORS

197       The following list is not comprehensive. Error codes may also originate
198       from calls to various C Library functions.
199
200
201       EACCESS
202              Denied access to resource located at the URL.
203
204
205       ECONNREFUSED
206              Unable  to  connect  to remote host. Also returned when an HTTPS
207              connection couldn't be verified (bad certificate).
208
209
210       ECONNRESET
211              Unable to either send or receive network data.
212
213
214       EHOSTUNREACH
215              Unable to resolve remote host.
216
217
218       EINVAL One or more arguments are incorrectly formatted. build_id may be
219              too  long  (greater than 256 characters), filename may not be an
220              absolute path or a debuginfod URL is malformed.
221
222
223       EIO    Unable to write data received from server to local file.
224
225
226       EMLINK Too many HTTP redirects.
227
228
229       ENETUNREACH
230              Unable to initialize network connection.
231
232
233       ENOENT Could not find the resource located at  URL.  Often  this  error
234              code  indicates  that  a debuginfod server was successfully con‐
235              tacted but the server could not find the target file.
236
237
238       ENOMEM System is unable to allocate resources.
239
240
241       ENOSYS $DEBUGINFOD_URLS is not defined.
242
243
244       ETIME  Query failed due to timeout. $DEBUGINFOD_TIMEOUT  and  $DEBUGIN‐
245              FOD_MAXTIME control this.
246
247
248       EF2BIG Query aborted due to the file requested being too big.  The $DE‐
249              BUGINFOD_MAXSIZE controls this.
250
251
252

SEE ALSO

254       debuginfod(8)
255
256
257
258                                                          DEBUGINFOD_FIND_*(3)
Impressum