debuginfod-find(1)

1
2
3DEBUGINFOD-FIND(1)          General Commands Manual         DEBUGINFOD-FIND(1)
4
5
6

NAME

8       debuginfod-find - request debuginfo-related data
9
10

SYNOPSIS

12       debuginfod-find [OPTION]... debuginfo BUILDID
13       debuginfod-find [OPTION]... debuginfo PATH
14       debuginfod-find [OPTION]... executable BUILDID
15       debuginfod-find [OPTION]... executable PATH
16       debuginfod-find [OPTION]... source BUILDID /FILENAME
17       debuginfod-find [OPTION]... source PATH /FILENAME
18
19

DESCRIPTION

21       debuginfod-find  queries  one or more debuginfod servers for debuginfo-
22       related data.  In case of a match, it saves the the requested file into
23       a  local cache, prints the file name to standard output, and exits with
24       a success status of 0.  In case of any error, it exits with  a  failure
25       status and an error message to standard error.
26
27
28       The debuginfod system uses buildids to identify debuginfo-related data.
29       These are stored as binary notes in ELF/DWARF  files,  and  are  repre‐
30       sented  as  lowercase hexadecimal.  For example, for a program /bin/ls,
31       look at the ELF note GNU_BUILD_ID:
32
33       % readelf -n /bin/ls | grep -A4 build.id
34       Note section [ 4] '.note.gnu.buildid' of 36 bytes at offset 0x340:
35       Owner          Data size  Type
36       GNU                   20  GNU_BUILD_ID
37       Build ID: 8713b9c3fb8a720137a4a08b325905c7aaf8429d
38
39       Then the hexadecimal BUILDID is simply:
40
41       8713b9c3fb8a720137a4a08b325905c7aaf8429d
42
43       In place of the hexadecimal BUILDID,  debuginfod-find  also  accepts  a
44       path  name to to an ELF binary, from which it extracts the buildid.  In
45       this case, ensure the file name has some character other than [0-9a-f].
46       Files  ambiguously  named  files  like  "deadbeef" can be passed with a
47       ./deadbeef extra path component.
48
49
50
51   debuginfo BUILDID
52       If the given buildid is known to a server, this request will result  in
53       a  binary  object that contains the customary .*debug_* sections.  This
54       may be a split debuginfo file as created by strip,  or  it  may  be  an
55       original unstripped executable.
56
57
58   executable BUILDID
59       If  the  given buildid is known to the server, this request will result
60       in a binary object that contains the normal executable segments.   This
61       may  be  a  executable  stripped by strip, or it may be an original un‐
62       stripped executable.  ET_DYN shared libraries are considered  to  be  a
63       type of executable.
64
65
66   source BUILDID /SOURCE/FILE
67       If  the  given buildid is known to the server, this request will result
68       in a binary object that contains the source file mentioned.   The  path
69       should  be  absolute.  Relative path names commonly appear in the DWARF
70       file's source directory, but these paths  are  relative  to  individual
71       compilation unit AT_comp_dir paths, and yet an executable is made up of
72       multiple CUs.  Therefore, to disambiguate,  debuginfod  expects  source
73       queries  to prefix relative path names with the CU compilation-directo‐
74       ry, followed by a mandatory "/".
75
76       Note: the caller may or may not elide ../  or  /./  or  extraneous  ///
77       sorts  of  path  components in the directory names.  debuginfod accepts
78       both forms.  Specifically, debuginfod canonicalizes path names  accord‐
79       ing  to  RFC3986 section 5.2.4 (Remove Dot Segments), plus reducing any
80       // to / in the path.
81
82       For example:
83
84       #include <stdio.h>               source BUILDID /usr/include/stdio.h
85       /path/to/foo.c                   source BUILDID /path/to/foo.c
86       ../bar/foo.c AT_comp_dir=/zoo/   source BUILDID /zoo//../bar/foo.c
87
88

OPTIONS

90       -v     Increase  verbosity,  including  printing   frequent   download-
91              progress messages.
92
93
94

SECURITY

96       debuginfod-find  does not include any particular security features.  It
97       trusts that the binaries returned by the  debuginfod(s)  are  accurate.
98       Therefore,  the  list  of servers should include only trustworthy ones.
99       If accessed across HTTP rather than HTTPS, the network should be trust‐
100       worthy.   Authentication  information  through the internal libcurl li‐
101       brary  is  not  currently  enabled,  except  for  the  basic  plaintext
102       http[s]://userid:password@hostname/ style.  (The debuginfod server does
103       not perform authentication, but a front-end proxy server could.)
104
105

ENVIRONMENT VARIABLES

107       DEBUGINFOD_URLS      This environment variable contains a list  of  URL
108                            prefixes for trusted debuginfod instances.  Alter‐
109                            nate URL prefixes are separated by space.
110
111
112       DEBUGINFOD_TIMEOUT   This environment variable governs the timeout  for
113                            each  debuginfod  HTTP  connection.  A server that
114                            fails to provide at least 100K of data within this
115                            many  seconds  is  skipped. The default is 90 sec‐
116                            onds.  (Zero or negative means "no timeout".)
117
118
119       DEBUGINFOD_CACHE_PATH
120                            This environment variable governs the location  of
121                            the  cache where downloaded files are kept.  It is
122                            cleaned periodically as this program is  reexecut‐
123                            ed.   Cache  management  parameters  may be set by
124                            files  under  this  directory:  see  the  debugin‐
125                            fod_find_debuginfo(3)  man  page for details.  The
126                            default is $HOME/.debuginfod_client_cache.
127
128

FILES

130       $HOME/.debuginfod_client_cache
131                           Default cache directory.
132
133