--- name: "debuginfod_find_executable" section: "3" platform: "linux" package: "debuginfod" version: "0.197-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/debuginfod_find_debuginfo" --- # debuginfod\_find\_executable(3) request debuginfo from debuginfod Part of [debuginfod\_find\_debuginfo(3)](/debuginfod_find_debuginfo/3.md). ## NAME debuginfod\_find\_debuginfo - request debuginfo from debuginfod ## SYNOPSIS ``` #include ``` Link with **-ldebuginfod**. CONNECTION HANDLE **debuginfod\_client \*debuginfod\_begin(void);** **void debuginfod\_end(debuginfod\_client \****client***);** LOOKUP FUNCTIONS **int debuginfod\_find\_debuginfo(debuginfod\_client \****client***,** **const unsigned char \****build\_id***,** **int** *build\_id\_len***,** **char \*\*** *path***);** **int debuginfod\_find\_executable(debuginfod\_client \****client***,** **const unsigned char \****build\_id***,** **int** *build\_id\_len***,** **char \*\*** *path***);** **int debuginfod\_find\_source(debuginfod\_client \****client***,** **const unsigned char \****build\_id***,** **int** *build\_id\_len***,** **const char \****filename***,** **char \*\*** *path***);** **int debuginfod\_find\_section(debuginfod\_client \****client***,** **const unsigned char \****build\_id***,** **int** *build\_id\_len***,** **const char \*** *section***,** **char \*\*** *path***);** **int debuginfod\_find\_metadata(debuginfod\_client \****client***,** **const char \****key***,** **const char \****value***,** **char \*\*** *path***);** OPTIONAL FUNCTIONS **typedef int (\*debuginfod\_progressfn\_t)(debuginfod\_client \****client***,** **long** *a***, long** *b***);** **void debuginfod\_set\_progressfn(debuginfod\_client \****client***,** **debuginfod\_progressfn\_t** *progressfn***);** **int debuginfod\_default\_progressfn(debuginfod\_client \****client***,** **long** *a***, long** *b***);** **void debuginfod\_set\_verbose\_fd(debuginfod\_client \****client***,** **int** *fd***);** **void debuginfod\_set\_user\_data(debuginfod\_client \****client***,** **void \****data***);** **void\* debuginfod\_get\_user\_data(debuginfod\_client \****client***);** **const char\* debuginfod\_get\_url(debuginfod\_client \****client***);** **int debuginfod\_add\_http\_header(debuginfod\_client \****client***,** **const char\*** *header***);** **const char\* debuginfod\_get\_headers(debuginfod\_client \****client***);** ## DESCRIPTION **debuginfod\_begin**() creates a **debuginfod\_client** connection handle that should be used with all other calls. **debuginfod\_end**() should be called on the **client** handle to release all state and storage when done. **debuginfod\_find\_debuginfo**(), **debuginfod\_find\_executable**(), and **debuginfod\_find\_source**() query the debuginfod server URLs contained in **$DEBUGINFOD\_URLS** (see below) for the debuginfo, executable or source file with the given *build\_id*. *build\_id* should be a pointer to either a null-terminated, lowercase hex string or a binary blob. If *build\_id* is given as a hex string, *build\_id\_len* should be 0. Otherwise *build\_id\_len* should be the number of bytes in the binary blob. **debuginfod\_find\_source**() also requires a *filename* in order to specify a particular source file. *filename* should be an absolute path that includes the compilation directory of the CU associated with the source file. Relative path names commonly appear in the DWARF file's source directory, but these paths are relative to individual compilation unit AT\_comp\_dir paths, and yet an executable is made up of multiple CUs. Therefore, to disambiguate, debuginfod expects source queries to prefix relative path names with the CU compilation-directory, followed by a mandatory "/". Note: the caller may or may not elide **../** or **/./** or extraneous **///** sorts of path components in the directory names. debuginfod accepts both forms. Specifically, debuginfod canonicalizes path names according to RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing any **//** to **/** in the path. **debuginfod\_find\_section**() queries the debuginfod server URLs contained in **$DEBUGINFOD\_URLS** for the binary contents of an ELF/DWARF section contained in a debuginfo or executable file with the given *build\_id*. *section* should be the name of the desired ELF/DWARF section. If a server does not support section queries, debuginfod\_find\_section may query the server for the debuginfo and/or executable with *build\_id* in order to retrieve and extract the section. **debuginfod\_find\_metadata**() queries all debuginfod server URLs contained in **$DEBUGINFOD\_URLS** for metadata for all matches of a given key/value query against files in their indexes. The resulting file is a JSON document. See the *[debuginfod-find(1)](/debuginfod-find/1.md)* man page for examples of the supported types of key/value queries and their JSON results. If *path* is not NULL and the query is successful, *path* is set to the path of the file in the cache. The caller must **free**() this value. The URLs in **$DEBUGINFOD\_URLS** may be queried in parallel. As soon as a debuginfod server begins transferring the target file all of the connections to the other servers are closed. A **client** handle should be used from only one thread at a time. A handle may be reused for a series of lookups, which can improve performance due to retention of connections and caches. ## RETURN VALUE **debuginfod\_begin** returns the **debuginfod\_client** handle to use with all other calls. On error **NULL** will be returned and **errno** will be set. If a find family function is successful, the resulting file is saved to the client cache and a file descriptor to that file is returned. The file descriptor points to the beginning of the file. The caller needs to **close**() this descriptor. Otherwise, a negative error code is returned. ## OPTIONAL FUNCTIONS A small number of optional functions are available to tune or query the operation of the debuginfod client. ### PROGRESS CALLBACK As the **debuginfod\_find\_\***() functions may block for seconds or longer, a progress callback function is called periodically, if configured with **debuginfod\_set\_progressfn**(). This function sets a new progress callback function (or NULL) for the client handle. The given callback function is called from the context of each thread that is invoking any of the other lookup functions. It is given two numeric parameters that, if thought of as a numerator *a* and denominator *b*, together represent a completion fraction *a/b*. The denominator may be zero initially, until a quantity such as an exact download size becomes known. The progress callback function is also the supported way to *interrupt* the download operation. (The library does *not* modify or trigger signals.) The progress callback must return 0 to continue the work, or any other value to stop work as soon as possible. Consequently, the **debuginfod\_find\_\***() function will likely return with an error, but might still succeed. **debuginfod\_default\_progressfn**() is the progress callback function set by the debuginfod client library when the **DEBUGINFOD\_PROGRESS** environment variable is set and no progressfn is explicitly set. For more information see **DEBUGINFOD\_PROGRESS** below. Custom progress callback functions may call **debuginfod\_default\_progressfn**() directly to report download status. ### VERBOSE OUTPUT The **debuginfod\_find\_\***() functions may use several techniques to retrieve the requested files, through the cache or through one or multiple servers or file URLs. To show how a query is handled the **debuginfod\_set\_verbose\_fd**() can be used to set a particular file descriptor on which verbose output is given about the query steps and eventual errors encountered. ### USER DATA POINTER A single *void \** pointer associated with the connection handle may be set any time via **debuginfod\_set\_user\_data**()**,** and retrieved via **debuginfod\_get\_user\_data**()**.** The value is undefined if unset. ### URL The URL of the current or most recent outgoing download, if known, may be retrieved via **debuginfod\_get\_url**() from the progressfn callback, or afterwards. It may be NULL. The resulting string is owned by the library, and must not be modified or freed. The caller should copy it if it is needed beyond the release of the client object. ### HTTP HEADER Before each lookup function is initiated, a client application may add HTTP request headers. These are reset after each lookup function. **debuginfod\_add\_http\_header**() may be called with strings of the form **"Header: value"**. These strings are copied by the library. A zero return value indicates success, but out-of-memory conditions may result in a non-zero *-ENOMEM*. If the string is in the wrong form *-EINVAL* will be returned. *$DEBUGINFOD\_HEADERS\_FILE* specifies a file to supply headers to outgoing requests. Each non-whitespace line of this file is handled as if **debuginfod\_add\_http\_header**() were called on the contents. Note that the current debuginfod-client library implementation uses libcurl, but you shouldn't rely on that fact. Don't use this function for replacing any standard headers, except for the User-Agent mentioned below. You can use this function to add authorization information for access control, or to provide optional headers to the server for logging purposes. By default, the library adds a descriptive *User-Agent:* header to outgoing requests. If the client application adds a header with the same name, this default is suppressed. During or after a lookup, a client application may call **debuginfod\_get\_headers**() to gather the subset of HTTP response headers received from the current or most recent debuginfod server. Only those headers prefixed with **X-DEBUGINFOD** (case-insensitive) are kept. They are returned as a single string, with each "header: value" terminated with a \\n (not \\r\\n as in HTTP). It may be NULL. The resulting string is owned by the library, and must not be modified or freed. The caller should copy the returned string if it is needed beyond the release of the client object. ## MACROS ### DEBUGINFOD\_SONAME Defined to the string that could be passed to [**dlopen**(3)](/dlopen/3.md) if the library is loaded at runtime, for example ``` void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY); ``` ## SECURITY If IMA signature(s) are available from the RPMs that contain requested files, then **debuginfod** will extract those signatures into response headers, and **debuginfod\_find\_\***() will perform verification upon the files. Validation policy is controlled via tags inserted into $DEBUGINFOD\_URLS. By default, **debuginfod\_find\_\***() acts in ignore mode. If accessed across HTTP rather than HTTPS, the network should be trustworthy. Authentication information through the internal *libcurl* library is not currently enabled, except for the basic plaintext *http\[s\]://userid:password@hostname/* style. (The debuginfod server does not perform authentication, but a front-end proxy server could.) ## ERRORS The following list is not comprehensive. Error codes may also originate from calls to various C Library functions. - **EACCESS** Denied access to resource located at the URL. - **ECONNREFUSED** Unable to connect to remote host. Also returned when an HTTPS connection couldn't be verified (bad certificate). - **ECONNRESET** Unable to either send or receive network data. - **EHOSTUNREACH** Unable to resolve remote host. - **EINVAL** One or more arguments are incorrectly formatted. *build\_id* may be too long (greater than 256 characters), *filename* may be empty, or a debuginfod URL is malformed. - **EIO** Unable to write data received from server to local file. - **EMLINK** Too many HTTP redirects. - **ENETUNREACH** Unable to initialize network connection. - **ENOENT** Could not find the resource located at URL. Often this error code indicates that a debuginfod server was successfully contacted but the server could not find the target file. - **ENOMEM** System is unable to allocate resources. - **ENOSYS** **$DEBUGINFOD\_URLS** is not defined. - **ETIME** Query failed due to timeout. **$DEBUGINFOD\_TIMEOUT** and **$DEBUGINFOD\_MAXTIME** control this. - **EF2BIG** Query aborted due to the file requested being too big. The **$DEBUGINFOD\_MAXSIZE** controls this. - **EBADMSG** File content failed IMA verification against a known signer certificate. - **ENOKEY** File content failed IMA verification due to missing signer certificate. - **ENODATA** File content failed IMA verification because of a missing signature. ## SEE ALSO *[debuginfod(8)](/debuginfod/8.md)*