diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ChangeLog | 7 | ||||
| -rw-r--r-- | doc/Makefile.am | 1 | ||||
| -rw-r--r-- | doc/debuginfod-client-config.7 | 8 | ||||
| -rw-r--r-- | doc/debuginfod-find.1 | 4 | ||||
| -rw-r--r-- | doc/debuginfod.8 | 11 | ||||
| -rw-r--r-- | doc/debuginfod_find_debuginfo.3 | 33 | ||||
| -rw-r--r-- | doc/debuginfod_find_section.3 | 1 |
7 files changed, 49 insertions, 16 deletions
diff --git a/doc/ChangeLog b/doc/ChangeLog index 7f852824..dfefae9b 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -5,6 +5,13 @@ * debuginfod_find_metadata.3: New file. * Makefile.am (notrans_dist_*_man3): Add it. +2022-10-31 Aaron Merey <amerey@redhat.com> + + * Makefile.am (notrans_dist_man3_MANS): Add debuginfod_find_section.3. + * debuginfod_find_section.3: New file. + * debuginfod_find_debuginfo.3: Document debuginfod_find_section. + * debuginfod.8: Document section webapi. + 2022-10-28 Arsen Arsenović <arsen@aarsen.me> * readelf.1: Document the --syms alias. diff --git a/doc/Makefile.am b/doc/Makefile.am index 64ffdaa2..b547a8db 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -38,6 +38,7 @@ notrans_dist_man3_MANS += debuginfod_end.3 notrans_dist_man3_MANS += debuginfod_find_debuginfo.3 notrans_dist_man3_MANS += debuginfod_find_executable.3 notrans_dist_man3_MANS += debuginfod_find_source.3 +notrans_dist_man3_MANS += debuginfod_find_section.3 notrans_dist_man3_MANS += debuginfod_find_metadata.3 notrans_dist_man3_MANS += debuginfod_get_user_data.3 notrans_dist_man3_MANS += debuginfod_get_url.3 diff --git a/doc/debuginfod-client-config.7 b/doc/debuginfod-client-config.7 index 53d82806..bc98d1e6 100644 --- a/doc/debuginfod-client-config.7 +++ b/doc/debuginfod-client-config.7 @@ -134,3 +134,11 @@ are short-circuited (returning an immediate failure instead of sending a new query to servers). This accelerates queries that probably would still fail. The default is 600, 10 minutes. 0 means "forget immediately". + +.TP +.B metadata_retention_s +This control file sets how long to remember the results of a metadata +query. New queries for the same artifacts within this time window are +short-circuited (repeating the same results). This accelerates +queries that probably would probably have the same results. The +default is 86400, 1 day. 0 means "do not retain". diff --git a/doc/debuginfod-find.1 b/doc/debuginfod-find.1 index c44fbc76..c3670374 100644 --- a/doc/debuginfod-find.1 +++ b/doc/debuginfod-find.1 @@ -118,8 +118,8 @@ servers. l l l . KEY VALUE DESCRIPTION -\fBfile\fP path match exact \fIpath\fP, including in archives -\fBglob\fP pattern sqlite glob match \fIpattern\fP, including in archives +\fBfile\fP path exact match \fIpath\fP, including in archives +\fBglob\fP pattern glob match \fIpattern\fP, including in archives .TE The results of the search are output to \fBstdout\fP as a JSON array diff --git a/doc/debuginfod.8 b/doc/debuginfod.8 index 9f529d0a..0703e3b4 100644 --- a/doc/debuginfod.8 +++ b/doc/debuginfod.8 @@ -371,6 +371,17 @@ Note: the client should %-escape characters in /SOURCE/FILE that are not shown as "unreserved" in section 2.3 of RFC3986. Some characters that will be escaped include "+", "\\", "$", "!", the 'space' character, and ";". RFC3986 includes a more comprehensive list of these characters. + +.SS /buildid/\fIBUILDID\fP/section\fI/SECTION\fP +If the given buildid is known to the server, the server will attempt to +extract the contents of an ELF/DWARF section named SECTION from the +debuginfo file matching BUILDID. If the debuginfo file can't be found +or the section has type SHT_NOBITS, then the server will attempt to extract +the section from the executable matching BUILDID. If the section is +succesfully extracted then this request results in a binary object +of the section's contents. Note that this result is the raw binary +contents of the section, not an ELF file. + .SS /metrics This endpoint returns a Prometheus formatted text/plain dump of a diff --git a/doc/debuginfod_find_debuginfo.3 b/doc/debuginfod_find_debuginfo.3 index f131813e..7d68f161 100644 --- a/doc/debuginfod_find_debuginfo.3 +++ b/doc/debuginfod_find_debuginfo.3 @@ -43,10 +43,15 @@ LOOKUP FUNCTIONS .BI " int " build_id_len "," .BI " const char *" filename "," .BI " char ** " path ");" +.BI "int debuginfod_find_section(debuginfod_client *" client "," +.BI " const unsigned char *" build_id "," +.BI " int " build_id_len "," +.BI " const char * " section "," +.BI " char ** " path ");" .BI "int debuginfod_find_metadata(debuginfod_client *" client "," .BI " const char *" key "," .BI " const char *" value "," -.BI " char** " metadata ");" +.BI " char ** " path ");" OPTIONAL FUNCTIONS @@ -102,6 +107,16 @@ accepts both forms. Specifically, debuginfod canonicalizes path names according to RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing any \fB//\fP to \fB/\fP in the path. +.BR debuginfod_find_section () +queries the debuginfod server URLs contained in +.BR $DEBUGINFOD_URLS +for the binary contents of an ELF/DWARF section contained in a debuginfo +or executable file with the given \fIbuild_id\fP. \fIsection\fP 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 \fIbuild_id\fP in order to retrieve +and extract the section. + 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. @@ -114,7 +129,7 @@ A handle may be reused for a series of lookups, which can improve performance due to retention of connections and caches. .BR debuginfod_find_metadata (), -likewise queries all debuginfod server URLs contained in +queries queries all debuginfod server URLs contained in .BR $DEBUGINFOD_URLS but instead retrieves metadata. The query search mode is specified in the \fIkey\fP parameter, and its parameter \fIvalue\fP. See @@ -132,13 +147,6 @@ to the client cache and a file descriptor to that file is returned. The caller needs to \fBclose\fP() this descriptor. Otherwise, a negative error code is returned. -The one exception is \fBdebuginfod_find_metadata\fP, which likewise -returns negative error codes, but on success returns 0 and sets -\fI*metadata\fP to a string-form JSON array of the found matching -metadata. This should be freed by the caller. See -\fIdebuginfod-find(1)\fP for more information on the metadata being -returned. - .SH "OPTIONAL FUNCTIONS" A small number of optional functions are available to tune or query @@ -253,11 +261,8 @@ void *debuginfod_so = dlopen(DEBUGINFOD_SONAME, RTLD_LAZY); .in .SH "SECURITY" -.BR debuginfod_find_debuginfo (), -.BR debuginfod_find_executable (), -and -.BR debuginfod_find_source () -\fBdo not\fP include any particular security +.BR debuginfod_find_* () +functions \fBdo not\fP include any particular security features. They trust that the binaries returned by the debuginfod(s) are accurate. Therefore, the list of servers should include only trustworthy ones. If accessed across HTTP rather than HTTPS, the diff --git a/doc/debuginfod_find_section.3 b/doc/debuginfod_find_section.3 new file mode 100644 index 00000000..16279936 --- /dev/null +++ b/doc/debuginfod_find_section.3 @@ -0,0 +1 @@ +.so man3/debuginfod_find_debuginfo.3 |