1INTERCEPT(1) INTERCEPT(1)
2
3
4
6 intercept - intercept command executions in user space.
7
9 intercept [options] -- [build command]
10
12 The command executes the given build command and generates an output
13 file which contains all process execution related events has happened
14 during the build.
15
16 The process execution events are: start, signal, termination. The out‐
17 put will contain only the child processes. Depending on the intercep‐
18 tion mode the output might only contain a subset of the executed com‐
19 mands. Interception modes are:
20
21 • preload uses the LD_PRELOAD or DYLD_INSERT_LIBRARIES mechanisms pro‐
22 vided by the dynamic linker. The pre-loaded library hijacks the
23 process execution calls, and executes a supervisor process, which re‐
24 ports the execution. The method fails when the executable statically
25 linked, or security protection disables the dynamic linker.
26
27 • wrapper mode interpose a wrapper program to the build. The wrapper
28 sends execution report and calls the original program. The method
29 fails when the build system is not flexible enough for interposing
30 build tools.
31
32 The reports are collected by the intercept over a gRPC interface, and
33 written into an output file.
34
36 --version
37 Print version number.
38
39 --help Print help message.
40
41 --verbose
42 Enable verbose logging.
43
44 --output file
45 Specify output file. (Default file name provided.) The output
46 is a command execution list, with some extra information. The
47 syntax is detailed in a separate section.
48
49 --force-preload
50 Force to use the preload method to intercept the children pro‐
51 cesses.
52
53 --force-wrapper
54 Force to use the wrapper method to intercept the children pro‐
55 cesses.
56
58 The exit status of the program is the exit status of the build command.
59 Except when the program itself crashes, then it sets to non zero.
60
62 The output file has JSON lines (https://jsonlines.org/) format, where
63 each line terminated with \n line separator and each line is a JSON ob‐
64 ject.
65
66 The JSON objects are process execution events: process start, process
67 got signal, process terminated. (For the schema of these events,
68 please consult with the source code of this project.)
69
71 The potential problems you can face with are: the build with and with‐
72 out the interception behaves differently (eg.: the build crash with the
73 intercept tool, but succeed otherwise). The output is empty, and it
74 failed to intercept the children process execution by the build com‐
75 mand.
76
77 The most common cause for empty outputs is that the build command did
78 not execute any commands. The reason for that could be, because incre‐
79 mental builds not running the compilers if everything is up-to-date.
80 Remember, intercept does not understand the build file (eg.: makefile),
81 but intercepts the executed commands.
82
83 There could be many reasons for any of these failures. It’s better to
84 consult with the project wiki page for known problems, before open a
85 bug report.
86
88 bear(1)
89
91 Copyright (C) 2012-2022 by László Nagy <https://github.com/rizsot‐
92 to/Bear>
93
95 László Nagy.
96
97
98
99Bear User Manuals Sep 04, 2021 INTERCEPT(1)