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_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
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 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 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 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 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 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 A client handle should be used from only one thread at a time.
88
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 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
101 A small number of optional functions are available to tune or query the
102 operation of the debuginfod client.
103 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 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 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 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 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 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 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 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
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
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
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 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 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 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
221 The following list is not comprehensive. Error codes may also originate
222 from calls to various C Library functions.
223 EACCESS
226 Denied access to resource located at the URL.
227 ECONNREFUSED
230 Unable to connect to remote host.
231 ECONNRESET
234 Unable to either send or recieve network data.
235 EHOSTUNREACH
238 Unable to resolve remote host.
239 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 EIO Unable to write data received from server to local file.
247 EMLINK Too many HTTP redirects.
250 ENETUNREACH
253 Unable to initialize network connection.
254 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 ENOMEM System is unable to allocate resources.
262 ENOSYS $DEBUGINFOD_URLS is not defined.
265 ETIME Query failed due to timeout. $DEBUGINFOD_TIMEOUT controls the
268 timeout duration. See debuginfod(8) for more information.
269
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
278 debuginfod(8)
279 DEBUGINFOD_FIND_*(3)