dwgrep(1)

1DWGREP(1)                           dwgrep                           DWGREP(1)
2
3
4

NAME

6       dwgrep - grep for Dwarf
7

SYNOPSIS

9          dwgrep [OPTIONS] PATTERN [FILE...]
10          dwgrep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]
11

DESCRIPTION

13       Dwgrep  is  a  tool for querying Dwarf (debuginfo) graphs.  Queries are
14       written in a language called Zwerg, the syntax of which is described on
15       project  web  pages  (see  below).  The engine itself is available as a
16       shared library which can be used from C.
17

OPTIONS

19       -H, --with-filename
20              Print the filename for each match.  This  is  the  default  when
21              there is more than one file to search.
22
23       -a=ARG Pass  a  string  argument  to the running script. A command line
24              argument such as -a X is handled like  --a  '"X"',  except  with
25              appropriate escaping.
26
27       -c, --count
28              Print only a count of query results, not the results themselves.
29
30       -e, --expr=EXPR
31              EXPR  is  a  query to run.  At most one -e or -f option shall be
32              present.  The selected query is run over the input file(s).
33
34       -f, --file=FILE
35              Load query from FILE.  A Zwerg script stored in the  given  file
36              is  read  and  run over the input file(s).  At most one -e or -f
37              option shall be present.
38
39       -h, --no-filename
40              Suppress printing filename on output.  This is the default  when
41              there is less than two files to search.
42
43       -q, --silent, --quiet
44              Suppress  all  normal output.  Exit immediately with zero status
45              if any match is found, even if an error was detected.
46
47       -s, --no-messages
48              Suppress error messages.  All normal  output  is  produced,  but
49              error messages (if any) are not shown.
50
51              Note that currently libzwerg produces some error messages on its
52              own (e.g. division by zero), and those are still displayed.
53
54       --help Show help and exit.
55
56       --version
57              Show version in the format MAJOR.MINOR and exit.
58
59       --a=ARG
60              Pass an evaluated argument to the running script.  The  argument
61              is  parsed as a Zwerg program and interpreted on an empty stack.
62              TOS of each yielded stack is taken and pushed to  program  stack
63              before query is executed.
64
65              Formally,  a command line such as this: dwgrep -e PROG --a X --a
66              Y ...  is interpreted like the following Zwerg snippet:
67
68                 let .X := *X*;
69                 let .Y := *Y*;
70                 ...
71                 .X .Y *PROG*
72
73              In particular this means that if an argument  yields  more  than
74              once,  the  whole  following computation is “forked” and in each
75              branch the argument has a different value.
76
77              ELF files mentioned on the command line are passed as the  first
78              command line argument. I.e. a dwgrep invocation such as this:
79
80                 dwgrep -e PROG --a X --a Y ... file1 file2 ...
81
82              Is handled as follows:
83
84                 dwgrep -e PROG --a '("file1", "file2", ...) dwopen' --a X --a Y ...
85
86              Thus  one  can  bind the explicitly-mentioned command line argu‐
87              ments to named variables and leave the ELF files  themselves  as
88              implicit  argument  of  the  expression itself, as is usual when
89              writing argument-less queries. Consider:
90
91                 dwgrep file1 file2 -e 'entry foo bar baz'
92                 dwgrep file1 file2 --a A --a B -e '(|A B| entry foo bar baz)'
93

EXAMPLES

95       Find ELF files:
96
97          $ dwgrep -sh $(find /usr/lib64/ -type f) -e 'name'
98          /usr/lib64/libogrove.so.0.0.1
99          /usr/lib64/libmp3lame.so.0.0.0
100          /usr/lib64/libgimpcolor-2.0.so.0.600.12
101          /usr/lib64/libmx-gtk-1.0.so.0.0.0
102          /usr/lib64/libkpimidentities.so.4.6.0
103          [... etc ...]
104
105       Find ELF files that include Dwarf information:
106
107          $ dwgrep -sh $(find /usr/lib64/ -type f) -e '?(unit) name'
108          /usr/lib64/python3.2/config-3.2mu/python.o
109          /usr/lib64/libxqilla.so.5.0.4
110          [... etc ...]
111
112       Find namespace names defined in one of them:
113
114          $ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
115                  entry ?TAG_namespace name' | sort -u
116          __debug
117          __detail
118          __gnu_cxx
119          __gnu_debug
120          std
121          xercesc_3_0
122          XQParser
123
124       Find names of variables defined in the namespace xercesc_3_0:
125
126          $ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
127                  entry ?TAG_namespace (name == "xercesc_3_0")
128                  child ?TAG_variable name' | sort -u
129          chAmpersand
130          chAsterisk
131          chAt
132          chBackSlash
133          chBang
134          [... etc ...]
135
136       Of those, only list the ones that don’t start in ch:
137
138          $ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
139                  entry ?TAG_namespace (name == "xercesc_3_0")
140                  child ?TAG_variable name
141                  (!~ "ch.*")' | sort -u
142          gControlCharMask
143          gDefOutOfMemoryErrMsg
144          gFirstNameCharMask
145          gNameCharMask
146
147       Look where they are declared:
148
149          $ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
150                  entry ?TAG_namespace (name == "xercesc_3_0")
151                  child ?TAG_variable (name !~ "ch.*")
152                  @AT_decl_file' | sort -u
153          /usr/include/xercesc/util/OutOfMemoryException.hpp
154          /usr/include/xercesc/util/XMLChar.hpp
155
156       Use formatting strings to include line number information in the mix:
157
158          $ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
159                  entry ?TAG_namespace (name == "xercesc_3_0")
160                  child ?TAG_variable (name !~ "ch.*")
161                  "%(@AT_decl_file%): %(dup @AT_decl_line%)"' | sort -u
162          /usr/include/xercesc/util/OutOfMemoryException.hpp: 32
163          /usr/include/xercesc/util/XMLChar.hpp: 33
164          /usr/include/xercesc/util/XMLChar.hpp: 34
165          /usr/include/xercesc/util/XMLChar.hpp: 35
166          [... etc ...]
167
168       More examples are available in documentation on syntax and in the tuto‐
169       rial.
170

AUTHOR

182       Petr Machata
183

COPYRIGHT

185       2020, 2015, 2017, 2018, Petr Machata
186
187
188
189
1900.4                              Oct 25, 2020                        DWGREP(1)