dbgserver: add man pages for libdbgserver functions

5 files changed, 79 insertions, 1 deletions

diff --git a/config/elfutils.spec.in b/config/elfutils.spec.in
index 9c145450..51b27236 100644
--- a/config/elfutils.spec.in
+++ b/config/elfutils.spec.in
@@ -280,6 +280,9 @@ rm -rf ${RPM_BUILD_ROOT}
 %{_libdir}/libdbgserver-%{version}.so
 %{_bindir}/dbgserver-find
 %{_mandir}/man1/dbgserver-find.1*
+%{_mandir}/man3/dbgserver_find_debuginfo.3*
+%{_mandir}/man3/dbgserver_find_executable.3*
+%{_mandir}/man3/dbgserver_find_source.3*
 
 
 %files dbgserver
diff --git a/dbgserver/Makefile.am b/dbgserver/Makefile.am
index 35d9387c..81c3582a 100644
--- a/dbgserver/Makefile.am
+++ b/dbgserver/Makefile.am
@@ -58,6 +58,7 @@ AM_LDFLAGS = -Wl,-rpath-link,../libelf:../libdw:.
 bin_PROGRAMS = dbgserver dbgserver-find
 dbgserver_SOURCES = dbgserver.cxx
 man8_MANS = dbgserver.8
+man3_MANS = dbgserver_find_debuginfo.3 dbgserver_find_source.3 dbgserver_find_executable.3
 man1_MANS = dbgserver-find.1
 dbgserver_LDADD = $(libdw) $(libelf) $(libeu) $(libdbgserver) $(libmicrohttpd_LIBS) $(libcurl_LIBS) $(sqlite3_LIBS) $(libarchive_LIBS) -lpthread -ldl
 
@@ -97,7 +98,7 @@ uninstall: uninstall-am
 	rm -f $(DESTDIR)$(libdir)/libdbgserver.so
 	rmdir --ignore-fail-on-non-empty $(DESTDIR)$(includedir)/elfutils
 
-EXTRA_DIST = libdbgserver.map dbgserver.8 dbgserver-find.1
+EXTRA_DIST = libdbgserver.map dbgserver.8 dbgserver-find.1 dbgserver_find_debuginfo.3 dbgserver_find_source.3 dbgserver_find_executable.3
 MOSTLYCLEANFILES = $(am_libdbgserver_pic_a_OBJECTS) libdbgserver.so.$(VERSION)
 CLEANFILES += $(am_libdbgserver_pic_a_OBJECTS) libdbgserver.so
 
diff --git a/dbgserver/dbgserver_find_debuginfo.3 b/dbgserver/dbgserver_find_debuginfo.3
new file mode 100644
index 00000000..d3f7ae33
--- /dev/null
+++ b/dbgserver/dbgserver_find_debuginfo.3
@@ -0,0 +1,72 @@
+'\"! tbl | nroff \-man
+'\" t macro stdmacro
+
+.de SAMPLE
+.br
+.RS 0
+.nf
+.nh
+..
+.de ESAMPLE
+.hy
+.fi
+.RE
+..
+
+.TH DBGSERVER_FIND_DEBUGINFO 3
+.SH NAME
+dbgserver_find_debuginfo \- request debuginfo from debuginfo server
+
+.SH SYNOPSIS
+.nf
+.B #include <elfutils/dbgserver-client.h>
+.PP
+.BI "dbgserver_find_debuginfo(const unsigned char *" build_id_bytes ", int " build_id_len ", char ** " path ");"
+.BI "dbgserver_find_executable(const unsigned char *" build_id_bytes ", int " build_id_len ", char ** " path ");"
+.BI "dbgserver_find_source(const unsigned char *" build_id_bytes ", int " build_id_len ", const char *" filename ", char ** " path ");"
+
+.SH DESCRIPTION
+TODO
+
+.SH "SECURITY"
+.BR dbgserver_find_debuginfo (),
+.BR dbgserver_find_executable (),
+and
+.BR dbgserver_find_source ()
+\fBdo not\fP include any particular security
+features.  They trust that the binaries returned by the dbgserver(s)
+are accurate.  Therefore, the list of servers should include only
+trustworthy ones.  If accessed across HTTP rather than HTTPS, the
+network should be trustworthy.
+
+.SH "ENVIRONMENT VARIABLES"
+
+.TP 21
+.B DBGSERVER_URLS
+This environment variable contains a list of URL prefixes for trusted
+dbgserver instances.  Alternate URL prefixes are separated by space.
+
+.TP 21
+.B DBGSERVER_TIMEOUT
+This environment variable governs the timeout for each dbgserver HTTP
+connection.  A server that fails to respond within this many seconds
+is skipped.  The default is 5.
+
+.TP 21
+.B DBGSERVER_CACHE_PATH
+This environment variable governs the location of the cache where
+downloaded files are kept.  It is cleaned periodically as this
+program is reexecuted.  The default is $HOME/.dbgserver_client_cache.
+
+.\" XXX describe cache eviction policy
+
+.SH "FILES"
+.LP
+.PD .1v
+.TP 20
+.B $HOME/.dbgserver_client_cache
+Default cache directory.
+.PD
+
+.SH "SEE ALSO"
+.I "dbgserver(8)"
diff --git a/dbgserver/dbgserver_find_executable.3 b/dbgserver/dbgserver_find_executable.3
new file mode 100644
index 00000000..1e24f286
--- /dev/null
+++ b/dbgserver/dbgserver_find_executable.3
@@ -0,0 +1 @@
+.so man3/dbgserver_find_debuginfo.3
diff --git a/dbgserver/dbgserver_find_source.3 b/dbgserver/dbgserver_find_source.3
new file mode 100644
index 00000000..1e24f286
--- /dev/null
+++ b/dbgserver/dbgserver_find_source.3
@@ -0,0 +1 @@
+.so man3/dbgserver_find_debuginfo.3