debuginfod: add description of libdebuginfod funcs and cache to debuginfod_find_*() man pagesdbgserver

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