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.

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

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:

• Introduction to the DWARF Debugging Format <http://www.dwarfstd.org/doc/Debugging%20using%20DWARF.pdf>
• Dwarf standard <http://dwarfstd.org/Download.php>
• Project homepage <https://github.com/pmachata/dwgrep>