Command line reference

Synopsis

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

Description

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.

See also

To learn more about Dwarf, check out: