gdbserver

gdbserver [options] COMM PROGRAM [ARGUMENTS...]
gdbserver [options] COMM --attach PID

COMM
    The communication method and address for GDB to connect. This can be `HOST:PORT` (e.g., `localhost:1234`, `:1234` for any interface) for TCP/IP, or a device path (e.g., `/dev/ttyS0`) for serial communication.

PROGRAM
    The executable program to be debugged. This program will be launched by gdbserver.

ARGUMENTS
    Arguments passed directly to the PROGRAM being debugged.

--attach PID
    Attach to an already running process specified by its Process ID (PID) instead of launching a new program.

--debug
    Enables verbose debugging output from gdbserver itself, useful for troubleshooting connection issues.

--once
    Configures gdbserver to exit immediately after the first GDB client disconnects. Useful for single-shot debugging sessions.

--multi
    Configures gdbserver to remain active and listen for new GDB client connections even after an existing client disconnects. Allows multiple debugging sessions without restarting gdbserver.

--wrapper COMMAND
    Specifies a wrapper command to execute the target PROGRAM. For example, `COMMAND` could be `valgrind`.

--help
    Displays a help message with command-line options and exits.

--version
    Displays gdbserver's version information and exits.

gdbserver is a crucial utility within the GNU Debugger (GDB) ecosystem, acting as a remote target stub. It enables debugging of programs running on a different system or process than where the primary GDB instance is located.

The tool starts the target program under its control (or attaches to an already running one) and then listens for incoming connections from a GDB client. Upon connection, gdbserver communicates with GDB using the GDB Remote Serial Protocol, translating debugging requests (like setting breakpoints, stepping, reading/writing memory, inspecting registers) into actions on the target system. This makes it indispensable for scenarios such as debugging embedded systems, cross-platform development, or analyzing processes in isolated environments where directly running GDB is not feasible or desired.

When using gdbserver, security is paramount. Since it provides full control over the target process, it should only be deployed in trusted environments or secured networks. Unrestricted network access to the gdbserver port can pose a significant security risk. Furthermore, gdbserver needs appropriate permissions to operate, especially when attaching to system processes or debugging programs owned by other users. The version and architecture of gdbserver should ideally match the target system and the debugged program for optimal compatibility.

gdbserver communicates with the GDB client using the GDB Remote Serial Protocol. This standard text-based protocol allows GDB to send commands and receive data from the remote target, facilitating all aspects of the debugging process, from setting breakpoints to inspecting memory and registers.

A common debugging workflow involves starting gdbserver on the target machine (e.g., `gdbserver :1234 my_app`). Then, on the development machine, launch GDB and connect to the remote target using `target remote target_ip:1234`. Once connected, GDB operates as if debugging a local process, providing a seamless debugging experience.

One of gdbserver's most powerful applications is in cross-architecture debugging. It allows developers to debug programs compiled for a different CPU architecture (e.g., ARM) from a development machine running a different architecture (e.g., x86_64) by having the appropriate gdbserver binary on the target system.

gdbserver is an integral part of the GNU Debugger (GDB) project, specifically designed to address the challenges of debugging programs on remote or embedded targets. Its development enabled GDB to extend its powerful debugging capabilities beyond local execution, becoming a cornerstone for cross-development and low-level system debugging. The GDB Remote Serial Protocol, upon which gdbserver relies, has been a robust and stable part of the GDB architecture for many years, facilitating broad compatibility across various target platforms and host environments.

gdb(1), objdump(1), readelf(1)