FEBUG-ABI(3) Library Functions Manual FEBUG-ABI(3)

struct febug_message, struct stop_febug_message, struct attn_febug_messageUser-space debugfs ABI

#include <febug-abi.h>

struct febug_message;

struct stop_febug_message;

struct attn_febug_message;

The febug ABI consists of two messages sent from the program wishing to be debugged to febug(8), and one sent from febug(8) to the program.

To be debugged, the program must create a socket with socket(AF_UNIX, SOCK_SEQPACKET, 0) and connect(2) to the appropriate end-point (/var/run/febug.sock, conventionally). The filesystem will then immediately acquire effective credentials from the client. After febug(8) receives credentials, a directory corresponding to the debugged process' PID will be created in the filesystem.

messages must be sent in a single send(2) or sendmsg(2) call, specifying the exact size of the message, as that's what's used to differentiate between different messages. febug(8) will ignore messages (whose sizes) it does not recognise.

Afterward, for each variable of interest, the process should send a 4096-byte febug_message, defined as follows:

struct [[packed]] febug_message {
    uint64_t variable_id;
    uint64_t variable_type;
    uint8_t signal;
    char name[/* Enough to bring the overall size to 4096. */];
};

Wherein:

is the locally unique identifier of the variable (e.g. a pointer to that variable).
is the moral equivalent of void * userdata — it is simply passed back to the program, unchanged (e.g. a function pointer to a formatter).
is the signal to send to the program when a variable is to be read (see below). is the globally unique name of this variable — a NUL terminator is respected, if it occurs before the end of the array, but is not required if the name truly spans to the final byte. If the name is the same as one of an already-present variable, it will be overridden.

When febug(8) receives febug_message, it creates a file under the process' directory. When that file is opened, febug(8) will:

  1. send the process an attn_febug_message with a single file descriptor via SCM_RIGHTS auxilliary data (confer cmsg(3)) representing the write end of a pipe — subsequent reads are serviced directly by the opposing end.
  2. kill(2) the process with the signal from the signal field if it wasn't SIGKILL.

Note, that the sent file descriptor must be closed by the program when it's done serialising the variable, and therefore, if the process opts not to receive a signal, it must handle the message through some other mechanism.

attn_febug_message is 16 bytes, and defined as follows:

struct [[packed]] attn_febug_message {
    uint64_t variable_id;
    uint64_t variable_type;
};

Both fields correspond to the ones sent in the febug_message that installed the variable.

The process may receive any amount of attn_febug_message until it sends an 8-byte , defined as follows:

struct [[packed]] stop_febug_message {
    uint64_t variable_id;
};

Upon receipt, the corresponding variable, if any, is removed from the filesystem.

When the process' end of the socket is closed, all extant variables are freed, and the process' directory is removed.

libfebug(3) and libfebug++(3) — libraries that wrap this ABI.

Written by наб <nabijaczleweli@nabijaczleweli.xyz>

To all who support further development, in particular:

febug tracker

febug mailing list: <~nabijaczleweli/febug@lists.sr.ht> archived at https://lists.sr.ht/~nabijaczleweli/febug

January 20, 2021 OpenBSD 6.8