diff options
Diffstat (limited to 'debuginfod/debuginfod_find_debuginfo.3')
-rw-r--r-- | debuginfod/debuginfod_find_debuginfo.3 | 41 |
1 files changed, 37 insertions, 4 deletions
diff --git a/debuginfod/debuginfod_find_debuginfo.3 b/debuginfod/debuginfod_find_debuginfo.3 index 5007c1c2..3533dc2f 100644 --- a/debuginfod/debuginfod_find_debuginfo.3 +++ b/debuginfod/debuginfod_find_debuginfo.3 @@ -21,12 +21,43 @@ debuginfod_find_debuginfo \- request debuginfo from debuginfo server .nf .B #include <elfutils/debuginfod.h> .PP -.BI "debuginfod_find_debuginfo(const unsigned char *" build_id_bytes ", int " build_id_len ", char ** " path ");" -.BI "debuginfod_find_executable(const unsigned char *" build_id_bytes ", int " build_id_len ", char ** " path ");" -.BI "debuginfod_find_source(const unsigned char *" build_id_bytes ", int " build_id_len ", const char *" filename ", char ** " path ");" +.BI "debuginfod_find_debuginfo(const unsigned char *" build_id ", int " build_id_len ", char ** " path ");" +.BI "debuginfod_find_executable(const unsigned char *" build_id ", int " build_id_len ", char ** " path ");" +.BI "debuginfod_find_source(const unsigned char *" build_id ", int " build_id_len ", const char *" filename ", char ** " path ");" .SH DESCRIPTION -TODO +.BR debuginfod_find_debuginfo (), +.BR debuginfod_find_executable (), +and +.BR debuginfod_find_source () +query the debuginfod server URLs contained in +.BR $DEBUGINFOD_URLS +(see below) for the debuginfo, executable or source file with the given \fIbuild_id\fP. +\fIbuild_id\fP should be a pointer to either a null-terminated, lowercase hex string or +a binary blob. If \fIbuild_id\fP is given as a hex string, \fIbuild_id_len\fP +should be 0. Otherwise \fIbuild_id_len\fP should be the number of bytes in the binary blob. + +.BR debuginfod_find_source () +also requries a \fIfilename\fP in order to specify a particular source file. +\fIfilename\fP 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. + +If \fIpath\fP is not NULL and the query is successful, \fIpath\fP is set to the +path of the file in the cache. The caller must \fBfree\fP() this value. + +.SH "CACHE" +If the query is successful, the \fBdebuginfod_find_*\fP() functions save the target file +to a local cache. The location of the cache is controlled by the \fB$DEBUGINFOD_CACHE_PATH\fP +environment variable (see below). Cleaning of the cache is controlled by the \fIcache_clean_interval_s\fP +and \fImax_unused_age_s\fP files, which are found in the \fB$DEBUGINFOD_CACHE_PATH\fP directory. +\fIcache_clean_interval_s\fP controls how frequently the cache is traversed for cleaning and +\fImax_unused_age_s\fP controls how long a file can go unused before its removed from the cache +during cleaning. These files should contain only an ASCII integer representing the +interval or max unused age in seconds. The files contain a default value of 600. .SH "SECURITY" .BR debuginfod_find_debuginfo (), @@ -60,6 +91,8 @@ program is reexecuted. The default is $HOME/.debuginfod_client_cache. .\" XXX describe cache eviction policy +.SH "RETURN VALUE" + .SH "FILES" .LP .PD .1v |