Your company here — click to reach over 10,000 unique daily visitors

dwgrep - Man Page

grep for Dwarf


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.


-H,  --with-filename

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


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.


Show help and exit.


Show version in the format MAJOR.MINOR and exit.


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)'


Find ELF files:

$ dwgrep -sh $(find /usr/lib64/ -type f) -e 'name'
[... etc ...]

Find ELF files that include Dwarf information:

$ dwgrep -sh $(find /usr/lib64/ -type f) -e '?(unit) name'
[... etc ...]

Find namespace names defined in one of them:

$ dwgrep /usr/lib64/libxqilla.so.5.0.4 -e '
        entry ?TAG_namespace name' | sort -u

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
[... 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

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

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:


Petr Machata


May 13, 2024 0.4