doc/debuginfod_find_debuginfo.3 - platform/external/elfutils.git - Git at Google

 '\"! tbl | nroff \-man
 '\" t macro stdmacro

 .de SAMPLE
 .br
 .RS 0
 .nf
 .nh
 ..
 .de ESAMPLE
 .hy
 .fi
 .RE
 ..

 .TH DEBUGINFOD_FIND_* 3
 .SH NAME
 debuginfod_find_debuginfo \- request debuginfo from debuginfod

 .SH SYNOPSIS
 .nf
 .B #include <elfutils/debuginfod.h>
 .PP
 .BI "debuginfod_client *debuginfod_begin(void);"
 .BI "void debuginfod_end(debuginfod_client *" client ");"

 .BI "int debuginfod_find_debuginfo(debuginfod_client *" client ","
 .BI "                              const unsigned char *" build_id ","
 .BI "                              int " build_id_len ","
 .BI "                              char ** " path ");"
 .BI "int debuginfod_find_executable(debuginfod_client *" client ","
 .BI "                               const unsigned char *" build_id ","
 .BI "                               int " build_id_len ","
 .BI "                               char ** " path ");"
 .BI "int debuginfod_find_source(debuginfod_client *" client ","
 .BI "                           const unsigned char *" build_id ","
 .BI "                           int " build_id_len ","
 .BI "                           const char *" filename ","
 .BI "                           char ** " path ");"

 .BI "typedef int (*debuginfo_progressfn_t)(debuginfod_client *" client ","
 .BI "                                      long a, long b);"
 .BI "void debuginfod_set_progressfn(debuginfod_client *" client ","
 .BI "                               debuginfo_progressfn_t " progressfn ");"

 Link with \fB-ldebuginfod\fP.

 .SH DESCRIPTION

 .BR debuginfod_begin ()
 creates a \fBdebuginfod_client\fP connection handle that should be used
 with all other calls.
 .BR debuginfod_end ()
 should be called on the \fBclient\fP handle to release all state and
 storage when done.

 .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, followed by a mandatory "/".

 Note: the caller should not elide \fB../\fP or \fB/./\fP or extraneous
 \fB///\fP sorts of path components in the directory names, because if
 this is how those names appear in the DWARF files, that is what
 debuginfod needs to see too.

 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.

 The URLs in \fB$DEBUGINFOD_URLS\fP 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 \fBclient\fP handle should be used from only one thread at a time.

 .SH "RETURN VALUE"

 \fBdebuginfod_begin\fP returns the \fBdebuginfod_client\fP handle to
 use with all other calls.  On error \fBNULL\fP will be returned and
 \fBerrno\fP 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 caller needs to \fBclose\fP() this descriptor.  Otherwise, a
 negative error code is returned.

 .SH "PROGRESS CALLBACK"

 As the \fBdebuginfod_find_*\fP() functions may block for seconds or
 longer, a progress callback function is called periodically, if
 configured with
 .BR 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 \fIa\fP and
 denominator \fIb\fP, together represent a completion fraction
 \fIa/b\fP.  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
 \fIinterrupt\fP the download operation.  (The library does \fInot\fP
 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 \fBdebuginfod_find_*\fP() function will
 likely return with an error, but might still succeed.


 .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 (fstat(2) atime) before it's
 removed from the cache during cleaning. These files should contain only an
 ASCII decimal integer representing the interval or max unused age in seconds.
 The default is one day and one week, respectively.  Values of zero mean "immediately".

 .SH "SECURITY"
 .BR debuginfod_find_debuginfo (),
 .BR debuginfod_find_executable (),
 and
 .BR debuginfod_find_source ()
 \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
 network should be trustworthy.  Passing user authentication information
 through the internal \fIlibcurl\fP library is not currently enabled, except
 for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style.
 (The debuginfod server does not perform authentication, but a front-end
 proxy server could.)

 .SH "ENVIRONMENT VARIABLES"

 .TP 21
 .B DEBUGINFOD_URLS
 This environment variable contains a list of URL prefixes for trusted
 debuginfod instances.  Alternate URL prefixes are separated by space.

 .TP 21
 .B DEBUGINFOD_TIMEOUT
 This environment variable governs the timeout for each debuginfod HTTP
 connection.  A server that fails to respond within this many seconds
 is skipped.  The default is 5.

 .TP 21
 .B DEBUGINFOD_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/.debuginfod_client_cache.

 .SH "ERRORS"
 The following list is not comprehensive. Error codes may also
 originate from calls to various C Library functions.

 .TP
 .BR EACCESS
 Denied access to resource located at the URL.

 .TP
 .BR ECONNREFUSED
 Unable to connect to remote host.

 .TP
 .BR ECONNRESET
 Unable to either send or recieve network data.

 .TP
 .BR EHOSTUNREACH
 Unable to resolve remote host.

 .TP
 .BR EINVAL
 One or more arguments are incorrectly formatted. \fIbuild_id\fP may
 be too long (greater than 256 characters), \fIfilename\fP may not
 be an absolute path or a debuginfod URL is malformed.

 .TP
 .BR EIO
 Unable to write data received from server to local file.

 .TP
 .BR EMLINK
 Too many HTTP redirects.

 .TP
 .BR ENETUNREACH
 Unable to initialize network connection.

 .TP
 .BR 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.

 .TP
 .BR ENOMEM
 System is unable to allocate resources.

 .TP
 .BR ENOSYS
 \fB$DEBUGINFOD_URLS\fP is not defined.

 .TP
 .BR ETIME
 Query failed due to timeout. \fB$DEBUGINFOD_TIMEOUT\fP controls
 the timeout duration. See debuginfod(8) for more information.

 .SH "FILES"
 .LP
 .PD .1v
 .TP 20
 .B $HOME/.debuginfod_client_cache
 Default cache directory.
 .PD

 .SH "SEE ALSO"
 .I "debuginfod(8)"
	'\"! tbl \| nroff \-man
	'\" t macro stdmacro

	.de SAMPLE
	.br
	.RS 0
	.nf
	.nh
	..
	.de ESAMPLE
	.hy
	.fi
	.RE
	..

	.TH DEBUGINFOD_FIND_* 3
	.SH NAME
	debuginfod_find_debuginfo \- request debuginfo from debuginfod

	.SH SYNOPSIS
	.nf
	.B #include <elfutils/debuginfod.h>
	.PP
	.BI "debuginfod_client *debuginfod_begin(void);"
	.BI "void debuginfod_end(debuginfod_client *" client ");"

	.BI "int debuginfod_find_debuginfo(debuginfod_client *" client ","
	.BI " const unsigned char *" build_id ","
	.BI " int " build_id_len ","
	.BI " char ** " path ");"
	.BI "int debuginfod_find_executable(debuginfod_client *" client ","
	.BI " const unsigned char *" build_id ","
	.BI " int " build_id_len ","
	.BI " char ** " path ");"
	.BI "int debuginfod_find_source(debuginfod_client *" client ","
	.BI " const unsigned char *" build_id ","
	.BI " int " build_id_len ","
	.BI " const char *" filename ","
	.BI " char ** " path ");"

	.BI "typedef int (debuginfo_progressfn_t)(debuginfod_client " client ","
	.BI " long a, long b);"
	.BI "void debuginfod_set_progressfn(debuginfod_client *" client ","
	.BI " debuginfo_progressfn_t " progressfn ");"

	Link with \fB-ldebuginfod\fP.

	.SH DESCRIPTION

	.BR debuginfod_begin ()
	creates a \fBdebuginfod_client\fP connection handle that should be used
	with all other calls.
	.BR debuginfod_end ()
	should be called on the \fBclient\fP handle to release all state and
	storage when done.

	.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, followed by a mandatory "/".

	Note: the caller should not elide \fB../\fP or \fB/./\fP or extraneous
	\fB///\fP sorts of path components in the directory names, because if
	this is how those names appear in the DWARF files, that is what
	debuginfod needs to see too.

	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.

	The URLs in \fB$DEBUGINFOD_URLS\fP 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 \fBclient\fP handle should be used from only one thread at a time.

	.SH "RETURN VALUE"

	\fBdebuginfod_begin\fP returns the \fBdebuginfod_client\fP handle to
	use with all other calls. On error \fBNULL\fP will be returned and
	\fBerrno\fP 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 caller needs to \fBclose\fP() this descriptor. Otherwise, a
	negative error code is returned.

	.SH "PROGRESS CALLBACK"

	As the \fBdebuginfod_find_*\fP() functions may block for seconds or
	longer, a progress callback function is called periodically, if
	configured with
	.BR 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 \fIa\fP and
	denominator \fIb\fP, together represent a completion fraction
	\fIa/b\fP. 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
	\fIinterrupt\fP the download operation. (The library does \fInot\fP
	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 \fBdebuginfod_find_*\fP() function will
	likely return with an error, but might still succeed.


	.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 (fstat(2) atime) before it's
	removed from the cache during cleaning. These files should contain only an
	ASCII decimal integer representing the interval or max unused age in seconds.
	The default is one day and one week, respectively. Values of zero mean "immediately".

	.SH "SECURITY"
	.BR debuginfod_find_debuginfo (),
	.BR debuginfod_find_executable (),
	and
	.BR debuginfod_find_source ()
	\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
	network should be trustworthy. Passing user authentication information
	through the internal \fIlibcurl\fP library is not currently enabled, except
	for the basic plaintext \%\fIhttp[s]://userid:password@hostname/\fP style.
	(The debuginfod server does not perform authentication, but a front-end
	proxy server could.)

	.SH "ENVIRONMENT VARIABLES"

	.TP 21
	.B DEBUGINFOD_URLS
	This environment variable contains a list of URL prefixes for trusted
	debuginfod instances. Alternate URL prefixes are separated by space.

	.TP 21
	.B DEBUGINFOD_TIMEOUT
	This environment variable governs the timeout for each debuginfod HTTP
	connection. A server that fails to respond within this many seconds
	is skipped. The default is 5.

	.TP 21
	.B DEBUGINFOD_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/.debuginfod_client_cache.

	.SH "ERRORS"
	The following list is not comprehensive. Error codes may also
	originate from calls to various C Library functions.

	.TP
	.BR EACCESS
	Denied access to resource located at the URL.

	.TP
	.BR ECONNREFUSED
	Unable to connect to remote host.

	.TP
	.BR ECONNRESET
	Unable to either send or recieve network data.

	.TP
	.BR EHOSTUNREACH
	Unable to resolve remote host.

	.TP
	.BR EINVAL
	One or more arguments are incorrectly formatted. \fIbuild_id\fP may
	be too long (greater than 256 characters), \fIfilename\fP may not
	be an absolute path or a debuginfod URL is malformed.

	.TP
	.BR EIO
	Unable to write data received from server to local file.

	.TP
	.BR EMLINK
	Too many HTTP redirects.

	.TP
	.BR ENETUNREACH
	Unable to initialize network connection.

	.TP
	.BR 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.

	.TP
	.BR ENOMEM
	System is unable to allocate resources.

	.TP
	.BR ENOSYS
	\fB$DEBUGINFOD_URLS\fP is not defined.

	.TP
	.BR ETIME
	Query failed due to timeout. \fB$DEBUGINFOD_TIMEOUT\fP controls
	the timeout duration. See debuginfod(8) for more information.

	.SH "FILES"
	.LP
	.PD .1v
	.TP 20
	.B $HOME/.debuginfod_client_cache
	Default cache directory.
	.PD

	.SH "SEE ALSO"
	.I "debuginfod(8)"