<!DOCTYPE html>
<html>
<!-- This is an automatically generated file. Do not edit.
" SPDX-License-Identifier: MIT
-->
<head>
<meta charset="utf-8"/>
<style>
/* $OpenBSD: mandoc.css,v 1.33 2019/06/02 16:50:46 schwarze Exp $ */
/*
* Standard style sheet for mandoc(1) -Thtml and man.cgi(8).
*
* Written by Ingo Schwarze <schwarze@openbsd.org>.
* I place this file into the public domain.
* Permission to use, copy, modify, and distribute it for any purpose
* with or without fee is hereby granted, without any conditions.
*/
/* Tooltips removed. */
/* Global defaults. */
html { max-width: 65em;
--bg: #FFFFFF;
--fg: #000000; }
body { background: var(--bg);
color: var(--fg);
font-family: Helvetica,Arial,sans-serif; }
h1 { font-size: 110%; }
table { margin-top: 0em;
margin-bottom: 0em;
border-collapse: collapse; }
/* Some browsers set border-color in a browser style for tbody,
* but not for table, resulting in inconsistent border styling. */
tbody { border-color: inherit; }
tr { border-color: inherit; }
td { vertical-align: top;
padding-left: 0.2em;
padding-right: 0.2em;
border-color: inherit; }
ul, ol, dl { margin-top: 0em;
margin-bottom: 0em; }
li, dt { margin-top: 1em; }
.permalink { border-bottom: thin dotted;
color: inherit;
font: inherit;
text-decoration: inherit; }
* { clear: both }
/* Search form and search results. */
fieldset { border: thin solid silver;
border-radius: 1em;
text-align: center; }
input[name=expr] {
width: 25%; }
table.results { margin-top: 1em;
margin-left: 2em;
font-size: smaller; }
/* Header and footer lines. */
table.head { width: 100%;
border-bottom: 1px dotted #808080;
margin-bottom: 1em;
font-size: smaller; }
td.head-vol { text-align: center; }
td.head-rtitle {
text-align: right; }
table.foot { width: 100%;
border-top: 1px dotted #808080;
margin-top: 1em;
font-size: smaller; }
td.foot-os { text-align: right; }
/* Sections and paragraphs. */
.manual-text {
margin-left: 3.8em; }
.Nd { }
section.Sh { }
h1.Sh { margin-top: 1.2em;
margin-bottom: 0.6em;
margin-left: -3.2em; }
section.Ss { }
h2.Ss { margin-top: 1.2em;
margin-bottom: 0.6em;
margin-left: -1.2em;
font-size: 105%; }
.Pp { margin: 0.6em 0em; }
.Sx { }
.Xr { }
/* Displays and lists. */
.Bd { }
.Bd-indent { margin-left: 3.8em; }
.Bl-bullet { list-style-type: disc;
padding-left: 1em; }
.Bl-bullet > li { }
.Bl-dash { list-style-type: none;
padding-left: 0em; }
.Bl-dash > li:before {
content: "\2014 "; }
.Bl-item { list-style-type: none;
padding-left: 0em; }
.Bl-item > li { }
.Bl-compact > li {
margin-top: 0em; }
.Bl-enum { padding-left: 2em; }
.Bl-enum > li { }
.Bl-compact > li {
margin-top: 0em; }
.Bl-diag { }
.Bl-diag > dt {
font-style: normal;
font-weight: bold; }
.Bl-diag > dd {
margin-left: 0em; }
.Bl-hang { }
.Bl-hang > dt { }
.Bl-hang > dd {
margin-left: 5.5em; }
.Bl-inset { }
.Bl-inset > dt { }
.Bl-inset > dd {
margin-left: 0em; }
.Bl-ohang { }
.Bl-ohang > dt { }
.Bl-ohang > dd {
margin-left: 0em; }
.Bl-tag { margin-top: 0.6em;
margin-left: 5.5em; }
.Bl-tag > dt {
float: left;
margin-top: 0em;
margin-left: -5.5em;
padding-right: 0.5em;
vertical-align: top; }
.Bl-tag > dd {
clear: right;
column-count: 1; /* Force block formatting context. */
width: 100%;
margin-top: 0em;
margin-left: 0em;
margin-bottom: 0.6em;
vertical-align: top; }
.Bl-compact { margin-top: 0em; }
.Bl-compact > dd {
margin-bottom: 0em; }
.Bl-compact > dt {
margin-top: 0em; }
.Bl-column { }
.Bl-column > tbody > tr { }
.Bl-column > tbody > tr > td {
margin-top: 1em; }
.Bl-compact > tbody > tr > td {
margin-top: 0em; }
.Rs { font-style: normal;
font-weight: normal; }
.RsA { }
.RsB { font-style: italic;
font-weight: normal; }
.RsC { }
.RsD { }
.RsI { font-style: italic;
font-weight: normal; }
.RsJ { font-style: italic;
font-weight: normal; }
.RsN { }
.RsO { }
.RsP { }
.RsQ { }
.RsR { }
.RsT { text-decoration: underline; }
.RsU { }
.RsV { }
.eqn { }
.tbl td { vertical-align: middle; }
.HP { margin-left: 3.8em;
text-indent: -3.8em; }
/* Semantic markup for command line utilities. */
table.Nm { }
code.Nm { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Fl { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Cm { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Ar { font-style: italic;
font-weight: normal; }
.Op { display: inline; }
.Ic { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Ev { font-style: normal;
font-weight: normal;
font-family: monospace; }
.Pa { font-style: italic;
font-weight: normal; }
/* Semantic markup for function libraries. */
.Lb { }
code.In { font-style: normal;
font-weight: bold;
font-family: inherit; }
a.In { }
.Fd { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Ft { font-style: italic;
font-weight: normal; }
.Fn { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Fa { font-style: italic;
font-weight: normal; }
.Vt { font-style: italic;
font-weight: normal; }
.Va { font-style: italic;
font-weight: normal; }
.Dv { font-style: normal;
font-weight: normal;
font-family: monospace; }
.Er { font-style: normal;
font-weight: normal;
font-family: monospace; }
/* Various semantic markup. */
.An { }
.Lk { }
.Mt { }
.Cd { font-style: normal;
font-weight: bold;
font-family: inherit; }
.Ad { font-style: italic;
font-weight: normal; }
.Ms { font-style: normal;
font-weight: bold; }
.St { }
.Ux { }
/* Physical markup. */
.Bf { display: inline; }
.No { font-style: normal;
font-weight: normal; }
.Em { font-style: italic;
font-weight: normal; }
.Sy { font-style: normal;
font-weight: bold; }
.Li { font-style: normal;
font-weight: normal;
font-family: monospace; }
/* Tooltip support. */
h1.Sh, h2.Ss { position: relative; }
.An, .Ar, .Cd, .Cm, .Dv, .Em, .Er, .Ev, .Fa, .Fd, .Fl, .Fn, .Ft,
.Ic, code.In, .Lb, .Lk, .Ms, .Mt, .Nd, code.Nm, .Pa, .Rs,
.St, .Sx, .Sy, .Va, .Vt, .Xr {
display: inline-block;
position: relative; }
/* Overrides to avoid excessive margins on small devices. */
@media (max-width: 37.5em) {
.manual-text {
margin-left: 0.5em; }
h1.Sh, h2.Ss { margin-left: 0em; }
.Bd-indent { margin-left: 2em; }
.Bl-hang > dd {
margin-left: 2em; }
.Bl-tag { margin-left: 2em; }
.Bl-tag > dt {
margin-left: -2em; }
.HP { margin-left: 2em;
text-indent: -2em; }
}
/* Overrides for a dark color scheme for accessibility. */
@media (prefers-color-scheme: dark) {
html { --bg: #1E1F21;
--fg: #EEEFF1; }
:link { color: #BAD7FF; }
:visited { color: #F6BAFF; }
}
</style>
<title>FEBUG-ABI(3)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">FEBUG-ABI(3)</td>
<td class="head-vol">Library Functions Manual</td>
<td class="head-rtitle">FEBUG-ABI(3)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">struct febug_message</code>,
<code class="Nm">struct stop_febug_message</code>, <code class="Nm">struct
attn_febug_message</code> — <span class="Nd">User-space debugfs
ABI</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In" href="https://git.sr.ht/~nabijaczleweli/febug/tree/trunk/item/include/febug-abi.h">febug-abi.h</a>></code></p>
<p class="Pp"><b class="Sy">struct febug_message;</b></p>
<p class="Pp"><b class="Sy">struct stop_febug_message;</b></p>
<p class="Pp"><b class="Sy">struct attn_febug_message;</b></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The febug ABI consists of two messages sent from the program
wishing to be debugged to <a class="Xr" href="febug.8.html">febug(8)</a>, and one sent from
<a class="Xr" href="febug.8.html">febug(8)</a> to the program.</p>
<p class="Pp">To be debugged, the program must create a socket with
<code class="Li">socket(AF_UNIX, SOCK_SEQPACKET, 0)</code> and
<a class="Xr">connect(2)</a> to the appropriate end-point
(<span class="Pa">/var/run/febug.sock</span>, conventionally). The
filesystem will then immediately acquire effective credentials from the
client. After <a class="Xr" href="febug.8.html">febug(8)</a> receives credentials, a directory
corresponding to the debugged process' PID will be created in the
filesystem.</p>
<p class="Pp" id="All"><a class="permalink" href="#All"><i class="Em">All</i></a>
messages must be sent in a single <a class="Xr">send(2)</a> or
<a class="Xr">sendmsg(2)</a> call, specifying the exact size of the message,
as that's what's used to differentiate between different messages.
<a class="Xr" href="febug.8.html">febug(8)</a> will ignore messages (whose sizes) it does not
recognise.</p>
<p class="Pp">Afterward, for each variable of interest, the process should send
a 4096-byte <b class="Sy">febug_message</b>, defined as follows:</p>
<div class="Bd Pp Bd-indent">
<pre>
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. */];
};
</pre>
</div>
<p class="Pp">Wherein:</p>
<dl class="Bl-tag">
<dt id="variable_id"></dt>
<dd><a class="permalink" href="#variable_id"><i class="Em">variable_id</i></a>
is the locally unique identifier of the variable (e.g. a pointer to that
variable).</dd>
<dt id="variable_type"></dt>
<dd><a class="permalink" href="#variable_type"><i class="Em">variable_type</i></a>
is the moral equivalent of <var class="Vt">void *</var>
<var class="Va">userdata</var> — it is simply passed back to the
program, unchanged (e.g. a function pointer to a formatter).</dd>
<dt id="signal"></dt>
<dd><a class="permalink" href="#signal"><i class="Em">signal</i></a> is the
signal to send to the program when a variable is to be read (see below).
<a class="permalink" href="#name"><i class="Em" id="name">name</i></a> 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.</dd>
</dl>
<p class="Pp">When <a class="Xr" href="febug.8.html">febug(8)</a> receives
<b class="Sy">febug_message</b>, it creates a file under the process'
directory. When that file is opened, <a class="Xr" href="febug.8.html">febug(8)</a> will:</p>
<ol class="Bl-enum">
<li>send the process an <b class="Sy">attn_febug_message</b> with a single
file descriptor via <code class="Dv">SCM_RIGHTS</code> auxilliary data
(confer <a class="Xr">cmsg(3)</a>) representing the write end of a pipe
— subsequent reads are serviced directly by the opposing end.</li>
<li><a class="Xr">kill(2)</a> the process with the signal from the
<var class="Va">signal</var> field if it wasn't
<code class="Dv">SIGKILL</code>.</li>
</ol>
<p class="Pp">Note, that the sent file descriptor <i class="Em">must</i> be
closed by the program when it's done serialising the variable, and
therefore, if the process opts not to receive a signal, it
<i class="Em">must</i> handle the message through some other mechanism.</p>
<p class="Pp"><b class="Sy">attn_febug_message</b> is 16 bytes, and defined as
follows:</p>
<div class="Bd Pp Bd-indent">
<pre>
struct [[packed]] attn_febug_message {
uint64_t variable_id;
uint64_t variable_type;
};
</pre>
</div>
<p class="Pp">Both fields correspond to the ones sent in the
<b class="Sy">febug_message</b> that installed the variable.</p>
<p class="Pp" id="stop_febug_message">The process may receive any amount of
<b class="Sy">attn_febug_message</b> until it sends an 8-byte
<a class="permalink" href="#stop_febug_message"><b class="Sy">stop_febug_message</b></a>,
defined as follows:</p>
<div class="Bd Pp Bd-indent">
<pre>
struct [[packed]] stop_febug_message {
uint64_t variable_id;
};
</pre>
</div>
<p class="Pp">Upon receipt, the corresponding variable, if any, is removed from
the filesystem.</p>
<p class="Pp">When the process' end of the socket is closed, all extant
variables are freed, and the process' directory is removed.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr" href="libfebug.3.html">libfebug(3)</a> and <a class="Xr" href="libfebug++.3.html">libfebug++(3)</a>
— libraries that wrap this ABI.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">Written by <span class="An">наб</span>
<<a class="Mt" href="mailto:nabijaczleweli@nabijaczleweli.xyz">nabijaczleweli@nabijaczleweli.xyz</a>></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SPECIAL_THANKS"><a class="permalink" href="#SPECIAL_THANKS">SPECIAL
THANKS</a></h1>
<p class="Pp">To all who support further development, in particular:</p>
<ul class="Bl-bullet Bl-compact">
<li>ThePhD</li>
<li>Embark Studios</li>
</ul>
</section>
<section class="Sh">
<h1 class="Sh" id="REPORTING_BUGS"><a class="permalink" href="#REPORTING_BUGS">REPORTING
BUGS</a></h1>
<p class="Pp"><a class="Lk" href="https://todo.sr.ht/~nabijaczleweli/febug">febug
tracker</a></p>
<p class="Pp">febug mailing list:
<<a class="Mt" href="mailto:~nabijaczleweli/febug@lists.sr.ht">~nabijaczleweli/febug@lists.sr.ht</a>>
archived at
<a class="Lk" href="https://lists.sr.ht/~nabijaczleweli/febug">https://lists.sr.ht/~nabijaczleweli/febug</a></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 30, 2021</td>
<td class="foot-os">OpenBSD 6.8</td>
</tr>
</table>
</body>
</html>