dwgrep - Man Page

grep for Dwarf

Synopsis

dwgrep [OPTIONS] PATTERN [FILE...]
dwgrep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

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

Options

-H, --with-filename

Print the filename for each match. This is the default when there is more than one file to search.

-a=ARG

Pass a string argument to the running script. A command line argument such as -a X is handled like --a '"X"', except with appropriate escaping.

-c, --count

Print only a count of query results, not the results themselves.

-e, --expr=EXPR

EXPR is a query to run. At most one -e or -f option shall be present. The selected query is run over the input file(s).

-f, --file=FILE

Load query from FILE. A Zwerg script stored in the given file is read and run over the input file(s). At most one -e or -f option shall be present.

-h, --no-filename

Suppress printing filename on output. This is the default when there is less than two files to search.

-q, --silent, --quiet

Suppress all normal output. Exit immediately with zero status if any match is found, even if an error was detected.

-s, --no-messages

Suppress error messages. All normal output is produced, but error messages (if any) are not shown.

Note that currently libzwerg produces some error messages on its own (e.g. division by zero), and those are still displayed.

--help

Show help and exit.

--version

Show version in the format MAJOR.MINOR and exit.

--a=ARG

Pass an evaluated argument to the running script. The argument is parsed as a Zwerg program and interpreted on an empty stack. TOS of each yielded stack is taken and pushed to program stack before query is executed.

Formally, a command line such as this: dwgrep -e PROG --a X --a Y ... is interpreted like the following Zwerg snippet:

let .X := *X*;
let .Y := *Y*;
...
.X .Y *PROG*

In particular this means that if an argument yields more than once, the whole following computation is "forked" and in each branch the argument has a different value.

ELF files mentioned on the command line are passed as the first command line argument. I.e. a dwgrep invocation such as this:

dwgrep -e PROG --a X --a Y ... file1 file2 ...

Is handled as follows:

dwgrep -e PROG --a '("file1", "file2", ...) dwopen' --a X --a Y ...

Thus one can bind the explicitly-mentioned command line arguments to named variables and leave the ELF files themselves as implicit argument of the expression itself, as is usual when writing argument-less queries. Consider:

dwgrep file1 file2 -e 'entry foo bar baz'
dwgrep file1 file2 --a A --a B -e '(|A B| entry foo bar baz)'

Examples

Find ELF files:

$ dwgrep -sh $(find /usr/lib64/ -type f) -e 'name'
/usr/lib64/libogrove.so.0.0.1
/usr/lib64/libmp3lame.so.0.0.0
/usr/lib64/libgimpcolor-2.0.so.0.600.12
/usr/lib64/libmx-gtk-1.0.so.0.0.0
/usr/lib64/libkpimidentities.so.4.6.0
[... etc ...]

Find ELF files that include Dwarf information:

$ dwgrep -sh $(find /usr/lib64/ -type f) -e '?(unit) name'
/usr/lib64/python3.2/config-3.2mu/python.o
/usr/lib64/libxqilla.so.5.0.4
[... etc ...]

Find namespace names defined in one of them:

$ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
        entry ?TAG_namespace name' | sort -u
__debug
__detail
__gnu_cxx
__gnu_debug
std
xercesc_3_0
XQParser

Find names of variables defined in the namespace xercesc_3_0:

$ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
        entry ?TAG_namespace (name == "xercesc_3_0")
        child ?TAG_variable name' | sort -u
chAmpersand
chAsterisk
chAt
chBackSlash
chBang
[... etc ...]

Of those, only list the ones that don't start in ch:

$ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
        entry ?TAG_namespace (name == "xercesc_3_0")
        child ?TAG_variable name
        (!~ "ch.*")' | sort -u
gControlCharMask
gDefOutOfMemoryErrMsg
gFirstNameCharMask
gNameCharMask

Look where they are declared:

$ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
        entry ?TAG_namespace (name == "xercesc_3_0")
        child ?TAG_variable (name !~ "ch.*")
        @AT_decl_file' | sort -u
/usr/include/xercesc/util/OutOfMemoryException.hpp
/usr/include/xercesc/util/XMLChar.hpp

Use formatting strings to include line number information in the mix:

$ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
        entry ?TAG_namespace (name == "xercesc_3_0")
        child ?TAG_variable (name !~ "ch.*")
        "%(@AT_decl_file%): %(dup @AT_decl_line%)"' | sort -u
/usr/include/xercesc/util/OutOfMemoryException.hpp: 32
/usr/include/xercesc/util/XMLChar.hpp: 33
/usr/include/xercesc/util/XMLChar.hpp: 34
/usr/include/xercesc/util/XMLChar.hpp: 35
[... etc ...]

More examples are available in documentation on syntax and in the tutorial.

dwgrep - Man Page

Synopsis

Description

Options

Examples

See Also

Author

Copyright

Info