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 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 void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY);
181
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
197 The following list is not comprehensive. Error codes may also originate
198 from calls to various C Library functions.
199 EACCESS
202 Denied access to resource located at the URL.
203 ECONNREFUSED
206 Unable to connect to remote host. Also returned when an HTTPS
207 connection couldn't be verified (bad certificate).
208 ECONNRESET
211 Unable to either send or receive network data.
212 EHOSTUNREACH
215 Unable to resolve remote host.
216 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 EIO Unable to write data received from server to local file.
224 EMLINK Too many HTTP redirects.
227 ENETUNREACH
230 Unable to initialize network connection.
231 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 ENOMEM System is unable to allocate resources.
239 ENOSYS $DEBUGINFOD_URLS is not defined.
242 ETIME Query failed due to timeout. $DEBUGINFOD_TIMEOUT and $DEBUGIN‐
245 FOD_MAXTIME control this.
246 EF2BIG Query aborted due to the file requested being too big. The $DE‐
249 BUGINFOD_MAXSIZE controls this.
250
254 debuginfod(8)
255 DEBUGINFOD_FIND_*(3)