DWGREP(1)

✨ DWGREP(1) — bestie edition ✨

okay so. you know grep? this is grep but for Dwarf 🧚 and honestly it's giving main character energy. welcome to the manual for dwgrep, bestie 💖

---

🌸 NAME 🌸

dwgrep — grep for Dwarf. that's it. that's the whole vibe. 💅

---

🎀 SYNOPSIS 🎀

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

---

🦋 DESCRIPTION 🦋

so basically, Dwgrep is a tool for querying Dwarf (debuginfo) graphs. and the queries? you write them in a whole little language called Zwerg ✨ — the syntax lives on the project web pages (scroll down, bestie, there's links in SEE ALSO 👀). the engine itself is also available as a shared library which can be used from C. no cap. 🫶

---

💅 OPTIONS 💅

• -H, --with-filename — prints the filename for each match. this is the default when there's more than one file to search. so if you're juggling multiple files, it just does this automatically. iconic. ✨
• -a=ARG — passes a string argument to the running script. a command line argument like -a X is handled like --a '"X"', except with appropriate escaping. 🎀
• -c, --count — prints only a count of query results, not the results themselves. just the number, bestie. lowkey so useful. 🔢
• -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 — loads the 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 — suppresses printing the filename on output. this is the default when there's less than two files to search. 🤫
• -q, --silent, --quiet — suppresses all normal output. exits immediately with zero status if any match is found, even if an error was detected. sneak mode activated. 🤐
• -s, --no-messages — suppresses error messages. all normal output is still produced, but error messages (if any) are not shown. 💜

heads up though: currently libzwerg produces some error messages on its own (e.g. division by zero), and those are still displayed. so like, not fully silent, sorry bestie 😭

• --help — shows help and exits. 🫶
• --version — shows version in the format MAJOR.MINOR and exits. 🔥
• --a=ARG — passes 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 the program stack before the 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:

• 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> 🏠

---

👑 AUTHOR 👑

Petr Machata 🫶

---

💖 COPYRIGHT 💖

2014, 2015, 2017, 2018, Petr Machata

---

and that's the whole thing, bestie 🎀 version 0.4, dated Jul 23, 2025 — go query some debuginfo, you absolute icon 💅✨🦋