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   debuginfod-find
13       [OPTION]... debuginfo PATH debuginfod-find [OPTION]... executable BUIL‐
14       DID   debuginfod-find   [OPTION]...   executable  PATH  debuginfod-find
15       [OPTION]... source BUILDID /FILENAME debuginfod-find [OPTION]... source
16       PATH /FILENAME
17
18

DESCRIPTION

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

OPTIONS

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

SECURITY

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

ENVIRONMENT VARIABLES

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

FILES

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