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 int debuginfod_find_section(debuginfod_client *client,
37 const unsigned char *build_id,
38 int build_id_len,
39 const char * section,
40 char ** path);
41 OPTIONAL FUNCTIONS
44 typedef int (*debuginfod_progressfn_t)(debuginfod_client *client,
46 long a, long b);
47 void debuginfod_set_progressfn(debuginfod_client *client,
48 debuginfod_progressfn_t progressfn);
49 void debuginfod_set_verbose_fd(debuginfod_client *client,
50 int fd);
51 void debuginfod_set_user_data(debuginfod_client *client,
52 void *data);
53 void* debuginfod_get_user_data(debuginfod_client *client);
54 const char* debuginfod_get_url(debuginfod_client *client);
55 int debuginfod_add_http_header(debuginfod_client *client,
56 const char* header);
57 const char* debuginfod_get_headers(debuginfod_client *client);
58
61 debuginfod_begin() creates a debuginfod_client connection handle that
62 should be used with all other calls. debuginfod_end() should be called
63 on the client handle to release all state and storage when done.
64 debuginfod_find_debuginfo(), debuginfod_find_executable(), and debugin‐
66 fod_find_source() query the debuginfod server URLs contained in $DEBUG‐
67 INFOD_URLS (see below) for the debuginfo, executable or source file
68 with the given build_id. build_id should be a pointer to either a null-
69 terminated, lowercase hex string or a binary blob. If build_id is given
70 as a hex string, build_id_len should be 0. Otherwise build_id_len
71 should be the number of bytes in the binary blob.
72 debuginfod_find_source() also requires a filename in order to specify a
74 particular source file. filename should be an absolute path that in‐
75 cludes the compilation directory of the CU associated with the source
76 file. Relative path names commonly appear in the DWARF file's source
77 directory, but these paths are relative to individual compilation unit
78 AT_comp_dir paths, and yet an executable is made up of multiple CUs.
79 Therefore, to disambiguate, debuginfod expects source queries to prefix
80 relative path names with the CU compilation-directory, followed by a
81 mandatory "/".
82 Note: the caller may or may not elide ../ or /./ or extraneous ///
84 sorts of path components in the directory names. debuginfod accepts
85 both forms. Specifically, debuginfod canonicalizes path names accord‐
86 ing to RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing any
87 // to / in the path.
88 debuginfod_find_section() queries the debuginfod server URLs contained
90 in $DEBUGINFOD_URLS for the binary contents of an ELF/DWARF section
91 contained in a debuginfo or executable file with the given build_id.
92 section should be the name of the desired ELF/DWARF section. If a
93 server does not support section queries, debuginfod_find_section may
94 query the server for the debuginfo and/or executable with build_id in
95 order to retrieve and extract the section.
96 If path is not NULL and the query is successful, path is set to the
98 path of the file in the cache. The caller must free() this value.
99 The URLs in $DEBUGINFOD_URLS may be queried in parallel. As soon as a
101 debuginfod server begins transferring the target file all of the con‐
102 nections to the other servers are closed.
103 A client handle should be used from only one thread at a time. A han‐
105 dle may be reused for a series of lookups, which can improve perfor‐
106 mance due to retention of connections and caches.
107
110 debuginfod_begin returns the debuginfod_client handle to use with all
111 other calls. On error NULL will be returned and errno will be set.
112 If a find family function is successful, the resulting file is saved to
114 the client cache and a file descriptor to that file is returned. The
115 caller needs to close() this descriptor. Otherwise, a negative error
116 code is returned.
117
120 A small number of optional functions are available to tune or query the
121 operation of the debuginfod client.
122 PROGRESS CALLBACK
125 As the debuginfod_find_*() functions may block for seconds or longer, a
126 progress callback function is called periodically, if configured with
127 debuginfod_set_progressfn(). This function sets a new progress call‐
128 back function (or NULL) for the client handle.
129 The given callback function is called from the context of each thread
131 that is invoking any of the other lookup functions. It is given two
132 numeric parameters that, if thought of as a numerator a and denominator
133 b, together represent a completion fraction a/b. The denominator may
134 be zero initially, until a quantity such as an exact download size be‐
135 comes known.
136 The progress callback function is also the supported way to interrupt
138 the download operation. (The library does not modify or trigger sig‐
139 nals.) The progress callback must return 0 to continue the work, or
140 any other value to stop work as soon as possible. Consequently, the
141 debuginfod_find_*() function will likely return with an error, but
142 might still succeed.
143 VERBOSE OUTPUT
146 The debuginfod_find_*() functions may use several techniques to re‐
147 trieve the requested files, through the cache or through one or multi‐
148 ple servers or file URLs. To show how a query is handled the debugin‐
149 fod_set_verbose_fd() can be used to set a particular file descriptor on
150 which verbose output is given about the query steps and eventual errors
151 encountered.
152 USER DATA POINTER
155 A single void * pointer associated with the connection handle may be
156 set any time via debuginfod_set_user_data(), and retrieved via
157 debuginfod_get_user_data(). The value is undefined if unset.
158 URL
161 The URL of the current or most recent outgoing download, if known, may
162 be retrieved via debuginfod_get_url() from the progressfn callback, or
163 afterwards. It may be NULL. The resulting string is owned by the li‐
164 brary, and must not be modified or freed. The caller should copy it if
165 it is needed beyond the release of the client object.
166 HTTP HEADER
169 Before each lookup function is initiated, a client application may add
170 HTTP request headers. These are reset after each lookup function.
171 debuginfod_add_http_header() may be called with strings of the form
172 "Header: value". These strings are copied by the library. A zero re‐
173 turn value indicates success, but out-of-memory conditions may result
174 in a non-zero -ENOMEM. If the string is in the wrong form -EINVAL will
175 be returned.
176 $DEBUGINFOD_HEADERS_FILE specifies a file to supply headers to outgoing
178 requests. Each non-whitespace line of this file is handled as if
179 debuginfod_add_http_header() were called on the contents.
180 Note that the current debuginfod-client library implementation uses
182 libcurl, but you shouldn't rely on that fact. Don't use this function
183 for replacing any standard headers, except for the User-Agent mentioned
184 below. You can use this function to add authorization information for
185 access control, or to provide optional headers to the server for log‐
186 ging purposes.
187 By default, the library adds a descriptive User-Agent: header to outgo‐
189 ing requests. If the client application adds a header with the same
190 name, this default is suppressed.
191 During or after a lookup, a client application may call
193 debuginfod_get_headers() to gather the subset of HTTP response headers
194 received from the current or most recent debuginfod server. Only those
195 headers prefixed with X-DEBUGINFOD (case-insensitive) are kept. They
196 are returned as a single string, with each "header: value" terminated
197 with a \n (not \r\n as in HTTP). It may be NULL. The resulting string
198 is owned by the library, and must not be modified or freed. The caller
199 should copy the returned string if it is needed beyond the release of
200 the client object.
201
204 DEBUGINFOD_SONAME
205 Defined to the string that could be passed to dlopen(3) if the library
206 is loaded at runtime, for example
207 void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);
210
213 debuginfod_find_*() functions do not include any particular security
214 features. They trust that the binaries returned by the debuginfod(s)
215 are accurate. Therefore, the list of servers should include only
216 trustworthy ones. If accessed across HTTP rather than HTTPS, the net‐
217 work should be trustworthy. Passing user authentication information
218 through the internal libcurl library is not currently enabled, except
219 for the basic plaintext http[s]://userid:password@hostname/ style.
220 (The debuginfod server does not perform authentication, but a front-end
221 proxy server could.)
222
225 The following list is not comprehensive. Error codes may also originate
226 from calls to various C Library functions.
227 EACCESS
230 Denied access to resource located at the URL.
231 ECONNREFUSED
234 Unable to connect to remote host. Also returned when an HTTPS
235 connection couldn't be verified (bad certificate).
236 ECONNRESET
239 Unable to either send or receive network data.
240 EHOSTUNREACH
243 Unable to resolve remote host.
244 EINVAL One or more arguments are incorrectly formatted. build_id may be
247 too long (greater than 256 characters), filename may not be an
248 absolute path or a debuginfod URL is malformed.
249 EIO Unable to write data received from server to local file.
252 EMLINK Too many HTTP redirects.
255 ENETUNREACH
258 Unable to initialize network connection.
259 ENOENT Could not find the resource located at URL. Often this error
262 code indicates that a debuginfod server was successfully con‐
263 tacted but the server could not find the target file.
264 ENOMEM System is unable to allocate resources.
267 ENOSYS $DEBUGINFOD_URLS is not defined.
270 ETIME Query failed due to timeout. $DEBUGINFOD_TIMEOUT and $DEBUGIN‐
273 FOD_MAXTIME control this.
274 EF2BIG Query aborted due to the file requested being too big. The $DE‐
277 BUGINFOD_MAXSIZE controls this.
278
282 debuginfod(8)
283 DEBUGINFOD_FIND_*(3)