1DEBUGINFOD_FIND_*(3) Library Functions Manual DEBUGINFOD_FIND_*(3)
4
8 debuginfod_find_debuginfo - request debuginfo from debuginfod
9
12 #include <elfutils/debuginfod.h>
13 Link with -ldebuginfod.
15 CONNECTION HANDLE
17 debuginfod_client *debuginfod_begin(void);
19 void debuginfod_end(debuginfod_client *client);
20 LOOKUP FUNCTIONS
22 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 OPTIONAL FUNCTIONS
38 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
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 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 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 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 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 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 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
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 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
105 A small number of optional functions are available to tune or query the
106 operation of the debuginfod client.
107 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 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 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 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 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 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 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 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 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
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
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 void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);
195
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
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 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 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 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 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
250 The following list is not comprehensive. Error codes may also originate
251 from calls to various C Library functions.
252 EACCESS
255 Denied access to resource located at the URL.
256 ECONNREFUSED
259 Unable to connect to remote host. Also returned when an HTTPS
260 connection couldn't be verified (bad certificate).
261 ECONNRESET
264 Unable to either send or receive network data.
265 EHOSTUNREACH
268 Unable to resolve remote host.
269 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 EIO Unable to write data received from server to local file.
277 EMLINK Too many HTTP redirects.
280 ENETUNREACH
283 Unable to initialize network connection.
284 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 ENOMEM System is unable to allocate resources.
292 ENOSYS $DEBUGINFOD_URLS is not defined.
295 ETIME Query failed due to timeout. $DEBUGINFOD_TIMEOUT controls the
298 timeout duration. See debuginfod(8) for more information.
299
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
308 debuginfod(8)
309 DEBUGINFOD_FIND_*(3)