febug

anyway, here's user-space debugfs

What?

Co-operative (between the program and you) debugging:

```

systemctl start febug

$ findmnt /run/febug /run/febug febug fuse.febug rw,nosuid,nodev,relatime,userid=0,groupid=0,defaultpermissions,allowother $ ./out/examples/vector-sort & [1] 1409 $ LDLIBRARYPATH=out ./out/examples/string-qsort & [2] 1410 $ ls /run/febug/ 1409 1410 $ ls -l /run/febug/ dr-xr-x--- 4 nabijaczleweli users 0 Jan 15 19:52 1409 dr-xr-x--- 3 nabijaczleweli users 0 Jan 15 19:52 1410 $ ls /run/febug/1409/ comparisons cooldata $ cat /run/febug/1409/* 24 -3 -2 -3 -2 -3 -2 3 -1 -2 -3 0 1 2 3 -1 -2 -3 0 1 2 3 -1 -2 -3 0 1 2 3 -1 2 1 0 1 2 3 -1 0 -1 0 1 2 3 $ cat /run/febug/1409/* 45 -3 -2 -3 -2 -3 -2 -3 -2 -2 -3 -3 -2 -1 3 -1 1 0 0 1 2 3 2 -1 3 0 1 2 3 -1 2 1 0 1 2 3 -1 0 -1 0 1 2 3 $ grep . /run/febug/*/* /run/febug/1409/comparisons:71 /run/febug/1409/cooldata:-3 -3 -3 -3 -3 -3 -2 -2 -2 -2 -2 -2 -1 3 -1 1 0 0 1 2 3 2 -1 3 0 1 2 3 -1 2 1 0 1 2 3 -1 0 -1 0 1 2 3 /run/febug/1410/cool_data:3012987654ACEFOLJKODNIEMIGHBPPbdWwnfTpXQcreRlVvUSitZQWjRTYUazuqwertyuiopoxyhmYsgkq $ kill %1 $ ls /run/febug/ 1410 ```

How?

UNIX-domain SOCKSEQPACKET (or SOCKSTREAM, if not available) at [/var]/run/febug.sock by default, with a corresponding mount at [/var]/run/febug
Debuggable client connects
When credentials are available, a directory appears, à la procfs
When client wants a variable debugged it sends a febug_message (variable_id, variable_type, signal, and name (see febug-abi.h)) – name gets a file under the directory
On open() of the file, the client is sent an attn_febug_message (variable_id and variable_type) and the write end of a pipe and (if signal wasn't SIGKILL) notified
read()s copy directly from the corresponding end of the pipe – the client must close() it by the time it returns from the signal handler (or, if using some other mechanism, when otherwise done representing)
When the variable goes out of scope, the client sends a stop_febug_message (variable_id) to deregister, disappearing the file
When client hangs up, its directory disappears

Or, perhaps (server is box, program is oval, user is trapezium):

Building

For a Linux system: * install libfuse3-dev, pkg-config, and mandoc * make

For FreeBSD: * install gmake, fusefs-libs3, and pkgconf * gmake

For NetBSD: * install devel/gmake * gmake LTO=n

For OpenBSD: * install gmake * gmake CXX=c++ LTO=n

For the Macintosh: * install macFUSE and mandoc * make

For other platforms: * ports welcome!

To build the Rust crate, its examples, and documentation, install cargo/rust/lang/rust[-bin]/rust and run [g]make rust-build rust-doc, but that is irrelevant to the casual builder.

dot(1) from graphviz is also needed to regenerate the diagram. though that itself is optional.

(End-user-visible) platform differences

When built for Linux, the default socket path is /run/febug.sock, otherwise it's /var/run/febug.sock.

On OpenBSD and Darwin the processes are authenticated by their effective UID/GID/PID.

Darwin doesn't support SOCKSEQPACKET, SOCKSTREAM is used instead.

Running

For a system-wide instance, run febug /run/febug/ & (or /var/run/febug/, or wherever else, as the case may be) as root.

To run a user-local instance, the fusermount3 helper is required, and export FEBUG_SOCKET=/run/user/$(id -u)/febug.sock followed by febug /run/user/$(id -u)/febug/ & should work for programs using libfebug and libfebug++; programs using a different ABI wrapper are encouraged to respect this environment variable as well.

init/ contains systemd units for these two use-cases (though that path has to be set manually in the debugged programs' environment), FreeBSD/NetBSD and OpenBSD rc.d scripts for the global one.

See the files in out/examples/, which sort with sleeps in comparison functions, for how they operate.

Installation

From Debian repository

The following line in /etc/apt/sources.list or equivalent: apt deb [signed-by=/etc/apt/keyrings/nabijaczleweli.asc] https://debian.nabijaczleweli.xyz sid main

With my PGP key (the two URLs are interchangeable): sh sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://debian.nabijaczleweli.xyz/nabijaczleweli.gpg.key sudo wget -O/etc/apt/keyrings/nabijaczleweli.asc https://nabijaczleweli.xyz/pgp.txt (you may need to create /etc/apt/keyrings on apt <2.4.0 (<=bullseye) manually).

Then the usual sh sudo apt update sudo apt install febug libfebug0 libfebug-dev libfebug++-dev will work on amd64, x32, and i386.

See the repository README or the source package for more information.

From pkgsrc

sh git clone https://git.sr.ht/~nabijaczleweli/febug-pkgsrc /usr/pkgsrc/devel/febug # or, indeed, where-ever the pkgsrc root is

And make install under devel/febug will work out-of-box on NetBSD and OpenBSD, but will need pkg install fusefs-libs3 on FreeBSD.

Reporting bugs

There's the tracker, but also see the list below.

Contributing

Send a patch inline, as an attachment, or a git link and a ref to pull from to the list (~nabijaczleweli/febug@lists.sr.ht) or me directly. I'm not picky, just please include the repo name in the subject prefix.

Discussion

Please use the tracker, the list, or Twitter.

Special thanks

To all who support further development on Patreon, in particular:

ThePhD
Embark Studios
Jasper Bekkers