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
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 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.
90
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 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
103 A small number of optional functions are available to tune or query the
104 operation of the debuginfod client.
105 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 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 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 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 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 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 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 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 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
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
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 void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);
192
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
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 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 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 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 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
247 The following list is not comprehensive. Error codes may also originate
248 from calls to various C Library functions.
249 EACCESS
252 Denied access to resource located at the URL.
253 ECONNREFUSED
256 Unable to connect to remote host. Also returned when an HTTPS
257 connection couldn't be verified (bad certificate).
258 ECONNRESET
261 Unable to either send or receive network data.
262 EHOSTUNREACH
265 Unable to resolve remote host.
266 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 EIO Unable to write data received from server to local file.
274 EMLINK Too many HTTP redirects.
277 ENETUNREACH
280 Unable to initialize network connection.
281 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 ENOMEM System is unable to allocate resources.
289 ENOSYS $DEBUGINFOD_URLS is not defined.
292 ETIME Query failed due to timeout. $DEBUGINFOD_TIMEOUT controls the
295 timeout duration. See debuginfod(8) for more information.
296
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
305 debuginfod(8)
306 DEBUGINFOD_FIND_*(3)