~nabijaczleweli/febug

ref: 05024b947b31387c2f1cc8f3c49c0e21e0c045bb febug/FreeBSD/libfebug.rs.3 -rw-r--r-- 7.3 KiB
05024b94 — наб autouploader FreeBSD manpage update by job 402789 9 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
.\" Automatically generated from an mdoc input file.  Do not edit.
.\"" SPDX-License-Identifier: MIT
.TH "LIBFEBUG.RS" "3" "January 21, 2021" "FreeBSD 12.1-RELEASE-p7" "FreeBSD Library Functions Manual"
.nh
.if n .ad l
.SH "NAME"
\fBfebug::start\fR,
\fBfebug::Wrapper\fR,
\fBfebug::Wrappable\fR,
\fBfebug::StaticWrappable\fR,
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR,
\fIfebug::FORMATTERS\fR
\- User-space debugfs ABI wrapper library for Rust
.SH "SYNOPSIS"
.nf
.RS 0n
[dependencies]
febug = "0.1.0-4-g4f0e645"
.RE
.fi
.PP
\fBgetenv("FEBUG_DONT")\fR
.br
\fBgetenv("FEBUG_SOCKET")\fR
.PP
\fIstatic GLOBAL_CONTROLLED_SOCKET: AtomicI32\fR
= -1;
.HP 4n
\fBfn febug::start\fR();
.HP 4n
\fBfn febug::start_raw\fR(\fIpath:\ &[u8]\fR);
.HP 4n
\fBextern 'C' fn debug_handler\fR(\fI_:\ c_int\fR);
.HP 4n
\fBbool fn febug::install_handler\fR();
.HP 4n
\fBbool fn febug::install_handler_signal\fR(\fIsignal:\ u8\fR);
.HP 4n
\fBfn febug::end\fR();
.PP
\fIstatic febug::FORMATTERS: Lazy<Mutex<BTreeMap<TypeId, fn(&mut File, usize)>>>\fR
.PP
\fBtrait febug::StaticWrappable: 'static;\fR
.br
.PD 0
.HP 4n
\fBWrapper<Self> fn febug::StaticWrappable::wrap\fR(\fI&self\fR, \fIname:\ Arguments<'_>\fR);
.PD
.HP 4n
\fBWrapper<Self> fn febug::StaticWrappable::wrap_signal\fR(\fI&self\fR, \fIsignal:\ u8\fR, \fIname:\ Arguments<'_>\fR);
.PP
\fBtrait febug::Wrappable;\fR
.br
.PD 0
.HP 4n
\fBWrapper<Self> fn febug::Wrappable::wrap\fR(\fI&self\fR, \fItp:\ u64\fR, \fIname:\ Arguments<'_>\fR);
.PD
.HP 4n
\fBWrapper<Self> fn febug::Wrappable::wrap_signal\fR(\fI&self\fR, \fItp:\ u64\fR, \fIsignal:\ u8\fR, \fIname:\ Arguments<'_>\fR);
.PP
\fBstruct febug::Wrapper<T>\fR
{ /* \[u2026] */ };
.br
.PD 0
.HP 4n
\fBWrapper<T> fn febug::Wrapper::new\fR(\fI&self\fR, \fItp:\ u64\fR, \fIdata:argument\fR, \fIname:\ fmt::Arguments\fR, \fIname:\ Arguments<'_>\fR);
.PD
.HP 4n
\fBWrapper<T> fn febug::Wrapper::new_signal\fR(\fI&self\fR, \fItp:\ u64\fR, \fIdata:argument\fR, \fIsignal:\ u8\fR, \fIname:\ fmt::Arguments\fR, \fIname:\ Arguments<'_>\fR);
.PP
\fBstruct febug::abi::FebugMessage;\fR
\fBstruct febug::abi::StopFebugMessage;\fR
\fBstruct febug::abi::AttnFebugMessage;\fR
.SH "DESCRIPTION"
\fBlibfebug.rs\fR
allows a programmer to simplify writing Rust programs debuggable with
febug(8)
by presenting a high-level interface to
febug-abi(5).
.PP
There are three compile-time environment variables that allow a programmer to customise its behaviour:
.TP 8n
\fBFEBUG_DONT\fR
.br
If set, all functions turn into no-ops;
this is intended as a way to easily disable
febug(8)
integration completely on release builds.
.TP 8n
\fBFEBUG_SIGNUM\fR
.br
The signal to request from
febug(8)
when using
\fBfebug_wrap\fR().
Defaults to
\fRSIGUSR2\fR.
.TP 8n
\fBFEBUG_SOCKET\fR
.br
The path to connect to
febug(8)
on. Defaults to
\fI/var/run/febug.sock\fR.
.PP
There are two environment variables that allow a user to customise its behaviour:
.TP 8n
\fIFEBUG_DONT\fR
If set, don't try to connect to
febug(8),
so all library functions become no-ops.
.TP 8n
\fIFEBUG_SOCKET\fR
If set, use its value instead of
\fBFEBUG_SOCKET\fR
to connect to
febug(8)
.PP
To be debugged, a program needs to, first, call
\fBfebug::start_raw\fR()
(likely via
\fBfebug::start\fR(),
which simply passes
\fIb\&"/var/run/febug.sock"\fR
thereto) to connect to
febug(8),
which, if successful, will set
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR
to the connection's file descriptor.
.PP
The program needs to install
\fBfebug::debug_handler\fR()
(or a wrapper around it) as the signal handler for
\fBFEBUG_SIGNUM\fR
(and any other signals, if different ones are explicitly requested; if
\fRSIGKILL\fR,
some event loop that answers on
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR
must be in place). It's a no-op if
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR
is -1. This finishes set-up.
A convenience
\fBfebug::install_handler\fR()
function is provided, doing just that, and returning
\fBtrue\fR
if the handler was installed.
.PP
The program should register handlers for types of variables it wishes to handle by adding entries to
\fIfebug::FORMATTERS\fR.
If no handler was registered for a type, or the lock was poisoned,
\fBfebug::debug_handler\fR()
will write a generic "not found" message.
The key is
\fBstd::any::TypeId\fR
corresponding to the debugged type; if your type is not not
\fB'static\fR,
lie here.
The handler takes the write end of the pipe as the first argument, and the variable ID as the second.
It's a no-op if
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR
is -1.
.PP
At any time, when the program wishes to expose a variable, it can construct
\fBfebug::Wrapper\fR
(likely via one of the convenience
\fBfebug::StaticWrappable\fR
or
\fBfebug::Wrappable\fR
traits), which will send a
\fBfebug_message\fR
with the specified type and signal numbers (defaulting to
\fRSIGUSR2 ),\fR
ID equal to the address of the data argument, and name formatted.
It's a no-op if
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR
is -1.
.PP
When dropped,
\fBfebug::Wrapper\fR
will send a
\fBstop_febug_message\fR.
It's a no-op if
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR
is -1.
.PP
When it wishes to stop being debugged, the program may call
\fBfebug::end\fR()
which will shutter and reset
\fIfebug::GLOBAL_CONTROLLED_SOCKET\fR,
The program may omit this if it'd be the last thing it did before exiting, since the kernel will close all FDs and free all mappings anyway.
.SH "EXAMPLES"
The following program spawns 10 threads, each successive one sorting a longer subsection of a String,
but waits a quarter-second between each comparison; the String for each thread and the amount of comparisons can be inspected via a
febug(8)
mount:
.nf
.sp
.RS 6n
// SPDX-License-Identifier: MIT


extern crate febug;

use febug::StaticWrappable;
use std::time::Duration;
use std::any::TypeId;
use std::io::Write;
use std::thread;


fn main() {
    febug::start();
    if febug::install_handler() {
        febug::FORMATTERS.lock().unwrap().insert(TypeId::of::<String>(), |of, vid| {
            let data = unsafe { &*(vid as *const String) };

            let _ = of.write_all(data.as_bytes());
            let _ = of.write_all(b"\\n");
        });
    }


    let threads = (0..10)
        .map(|i| {
            thread::spawn(move || {
                let mut sorteing = "The quick red fox jumps over the lazy brown dog... tHE QUICK RED FOX JUMPS OVER THE LAZY BROWN DOG!!"[0..(i + 1) * 10]
                    .to_string();
                let _sorteing_w = sorteing.wrap(format_args!("cool_data_{}", i));

                unsafe { sorteing.as_bytes_mut() }.sort_unstable_by(|a, b| {
                    thread::sleep(Duration::from_millis(250));
                    a.cmp(b)
                });

                thread::sleep(Duration::from_secs(2));
            })
        })
        .collect::<Vec<_>>();
    for t in threads {
        let _ = t.join();
    }
}
.RE
.fi
.SH "SEE ALSO"
febug-abi(5)
\[u2014] the ABI wrapped by this library.
.PP
libfebug(3)
\[u2014] an equivalent C library.
.PP
libfebug++(3)
\[u2014] an equivalent C++ library.
.SH "AUTHORS"
Written by
\[u043D]\[u0430]\[u0431] <\fInabijaczleweli@nabijaczleweli.xyz\fR>
.SH "SPECIAL THANKS"
To all who support further development, in particular:
.PD 0
.TP 8n
\fB\(bu\fR
ThePhD
.TP 8n
\fB\(bu\fR
Embark Studios
.PD
.SH "REPORTING BUGS"
\fIfebug tracker\fR: \fBhttps://todo.sr.ht/~nabijaczleweli/febug\fR
.PP
febug mailing list:
<\fI~nabijaczleweli/febug@lists.sr.ht\fR>
archived at
\fBhttps://lists.sr.ht/~nabijaczleweli/febug\fR