febug

anyway, here's user-space debugfs

Debian manpages

FreeBSD manpages

NetBSD manpages

OpenBSD manpages

Library rustdoc

What?

# systemctl start febug
$ findmnt /run/febug
/run/febug febug  fuse.febug rw,nosuid,nodev,relatime,user_id=0,group_id=0,default_permissions,allow_other
$ ./out/examples/vector-sort &
[1] 1409
$ LD_LIBRARY_PATH=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     cool_data
$ 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/1450/comparisons:71
/run/febug/1450/cool_data:-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/1451/cool_data:3012987654ACEFOLJKODNIEMIGHBPPbdWwnfTpXQcreRlVvUSitZQWjRTYUazuqwertyuiopoxyhmYsgkq
$ kill %1
$ ls /run/febug/
1410

How?

1. UNIX-domain SOCK_SEQPACKET at [/var]/run/febug.sock by default, with a corresponding mount at [/var]/run/febug
2. Debuggable client connects
3. When credentials are available, a directory appears, à la procfs
4. 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
5. 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
6. 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)
7. When the variable goes out of scope, the client sends a stop_febug_message (variable_id) to deregister, disappearing the file
8. 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 lang/clang – the GCC 7.5 shipped with NetBSD 9.1 is too ancient
• gmake CC=clang CXX=clang++ LTO=n

For OpenBSD:

• install gmake
• gmake CXX=c++ LTO=n

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 the processes are authenticated by their effective UID/GID.

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 environment debugged programs' environment), FreeBSD/NetBSD and OpenBSD rc.d scripts for the global one.

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

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