Writing a Linux Debugger Part 1: Setup
This series has been expanded into a book! It covers many more topics in much greater detail. You can now pre-order Building a Debugger.
Debuggers are one of the most valuable tools in any developer’s kit. However, although these tools are in such widespread use, there aren’t a lot of resources which tell you how they work and how to write one1, especially when compared to other toolchain technologies like compilers. In this post series we’ll learn what makes debuggers tick and write one for debugging Linux programs.
This tutorial is split into 10 parts and you can find the final code, along with branches for each part, on GitHub.
If you’re on Windows, you can still follow along using WSL.
Our debugger will support the following features:
- Launch, halt, and continue execution
- Set breakpoints on
- Memory addresses
- Source code lines
- Function entry
- Read and write registers and memory
- Single stepping
- Instruction
- Step in
- Step out
- Step over
- Print current source location
- Print backtrace
- Print values of simple variables
In the final part I’ll also outline how you could add the following to your debugger:
- Remote debugging
- Shared library and dynamic loading support
- Expression evaluation
- Multi-threaded debugging support
I’ll be focusing on C and C++ for this project, but it should work just as well with any language which compiles down to machine code and outputs standard DWARF debug information (if you don’t know what that is yet, don’t worry, this will be covered soon). Additionally, my focus will be on getting something up and running which works most of the time, so things like robust error handling will be eschewed in favour of simplicity.
Series index
- Setup
- Breakpoints
- Registers and memory
- Elves and dwarves
- Source and signals
- Source-level stepping
- Source-level breakpoints
- Stack unwinding
- Handling variables
- Advanced topics
Getting set up
Before we jump into things, let’s get our environment set up. I’ll be using two dependencies in this tutorial: Linenoise for handling our command line input, and libelfin for parsing the debug information. You could use the more traditional libdwarf instead of libelfin, but the interface is nowhere near as nice, and libelfin also provides a mostly complete DWARF expression evaluator, which will save you a lot of time if you want to read variables. Make sure that you use the fbreg branch of my fork of libelfin, as it hacks on some extra support for reading variables on x86.
Once you’ve either installed these on your system, or got them building as dependencies with whatever build system you prefer, it’s time to get started. I set them to build along with the rest of my code in my CMake files.
Launching the executable
Before we actually debug anything, we’ll need to launch the debugee program. We’ll do this with the classic fork/exec pattern.
We call fork
and this causes our program to split into two processes. If we are in the child process, fork
returns 0
, and if we are in the parent process, it returns the process ID of the child process.
If we’re in the child process, we want to replace whatever we’re currently executing with the program we want to debug.
Here we have our first encounter with ptrace
, which is going to become our best friend when writing our debugger. ptrace
allows us to observe and control the execution of another process by reading registers, reading memory, single stepping and more. The API is very ugly; it’s a single function which you provide with an enumerator value for what you want to do, and then some arguments which will either be used or ignored depending on which value you supply. The signature looks like this:
request
is what we would like to do to the traced process; pid
is the process ID of the traced process; addr
is a memory address, which is used in some calls to designate an address in the tracee; and data
is some request-specific resource. The return value often gives error information, so you probably want to check that in your real code; I’m omitting it for brevity. You can have a look at the man pages for more information.
The request we send in the above code, PTRACE_TRACEME
, indicates that this process should allow its parent to trace it. All of the other arguments are ignored, because API design isn’t important /s.
Next, we call execl
, which is one of the many exec
flavours. We execute the given program, passing the name of it as a command-line argument and a nullptr
to terminate the list. You can pass any other arguments needed to execute your program here if you like.
After we’ve done this, we’re finished with the child process; we’ll let it keep running until we’re finished with it.
Adding our debugger loop
Now that we’ve launched the child process, we want to be able to interact with it. For this, we’ll create a debugger
class, give it a loop for listening to user input, and launch that from our parent fork of our main
function. We’ll also print out the child pid, as it’ll come in useful in later articles.
In our run
function, we need to wait until the child process has finished launching, then keep on getting input from linenoise until we get an EOF (ctrl+d).
When the traced process is launched, it will be sent a SIGTRAP
signal, which is a trace or breakpoint trap. We can wait until this signal is sent using the waitpid
function.
After we know the process is ready to be debugged, we listen for user input. The linenoise
function takes a prompt to display and handles user input by itself. This means we get a nice command line with history and navigation commands without doing much work at all. When we get the input, we give the command to a handle_command
function which we’ll write shortly, then we add this command to the linenoise history and free the resource.
Handling input
Our commands will follow a similar format to gdb and lldb. To continue the program, a user will type continue
or cont
or even just c
. If they want to set a breakpoint on an address, they’ll write break 0xDEADBEEF
, where 0xDEADBEEF
is the desired address in hexadecimal format. Let’s add support for these commands.
split
and is_prefix
are a couple of small helper functions:
We’ll add continue_execution
to the debugger
class.
For now our continue_execution
function will use ptrace
to tell the process to continue, then waitpid
until it’s signalled.
Finishing up
Now you should be able to compile some C or C++ program, run it through your debugger, see it halting on entry, and be able to continue execution from your debugger. In the next part we’ll learn how to get our debugger to set breakpoints. If you come across any issues, please let me know in the comments!
You can find the code for this post here.
Let me know what you think of this article on twitter @TartanLlama or leave a comment below!