.\" Automatically generated by Pandoc 2.11.0.4
.\"
.TH "INTERCEPT" "1" "Sep 14, 2020" "Bear User Manuals" ""
.hy
.SH NAME
.PP
intercept - intercept command executions in user space.
.SH SYNOPSIS
.PP
intercept [\f[I]options\f[R]] -- [\f[I]build command\f[R]]
.SH DESCRIPTION
.PP
For intercepting the compiler executions, intercept uses the
\f[C]LD_PRELOAD\f[R] or \f[C]DYLD_INSERT_LIBRARIES\f[R] mechanisms
provided by the dynamic linker.
When the dynamic linker is not working (because the executable is not a
dynamically linked executable or security protection disables the
linker) then intercept uses compiler wrappers to record the compiler
calls.
The wrapper sends execution report and calls the real compiler.
(Not only compilers, but linkers, assemblers and other tools are also
wrapped.)
.PP
The reports are collected by the \f[C]intercept\f[R] over a gRPC
interface, and digested into an output JSON file.
.SH OPTIONS
.TP
--version
Print version number.
.TP
--help
Print help message.
.TP
--verbose
Enable verbose logging.
.TP
--output \f[I]file\f[R]
Specify output file.
(Default file name provided.) The output is a command execution list,
with some extra information.
The syntax is detailed in a separate section.
.TP
--force-preload
Force to use the dynamic linker method to intercept the children
processes.
.TP
--force-wrapper
Force to use the compiler wrapper method to intercept the children
processes.
.SH EXIT STATUS
.PP
The exit status of the program is the exit status of the build command.
Except when the program itself crashes, then it sets to non zero.
.SH OUTPUT FILE
.PP
It\[cq]s a JSON file, with the command execution history.
(Plus some metadata, that is useful for debugging the application.)
.IP
.nf
\f[C]
{
  \[dq]context\[dq]: {
    \[dq]host_info\[dq]: {
      \[dq]_CS_GNU_LIBC_VERSION\[dq]: \[dq]glibc 2.30\[dq],
      \[dq]_CS_GNU_LIBPTHREAD_VERSION\[dq]: \[dq]NPTL 2.30\[dq],
      \[dq]_CS_PATH\[dq]: \[dq]/usr/bin\[dq],
      \[dq]machine\[dq]: \[dq]x86_64\[dq],
      \[dq]release\[dq]: \[dq]5.5.13-200.fc31.x86_64\[dq],
      \[dq]sysname\[dq]: \[dq]Linux\[dq],
      \[dq]version\[dq]: \[dq]#1 SMP Wed Mar 25 21:55:30 UTC 2020\[dq]
    },
    \[dq]intercept\[dq]: \[dq]library preload\[dq]
  },
  \[dq]executions\[dq]: [
    {
      \[dq]command\[dq]: {
        \[dq]arguments\[dq]: [
          \[dq]sleep\[dq],
          \[dq]1\[dq]
        ],
        \[dq]environment\[dq]: {
          \[dq]PATH\[dq]: \[dq]/usr/local/bin:/usr/local/sbin:/usr/bin:/usr/sbin\[dq]
        },
        \[dq]program\[dq]: \[dq]/usr/bin/sleep\[dq],
        \[dq]working_dir\[dq]: \[dq]/home/lnagy/Code/Bear.git\[dq]
      },
      \[dq]run\[dq]: {
        \[dq]events\[dq]: [
          {
            \[dq]at\[dq]: \[dq]2020-02-16T21:00:00.000Z\[dq],
            \[dq]type\[dq]: \[dq]start\[dq]
          },
          {
            \[dq]at\[dq]: \[dq]2020-02-16T21:00:00.000Z\[dq],
            \[dq]status\[dq]: 0,
            \[dq]type\[dq]: \[dq]stop\[dq]
          }
        ],
        \[dq]pid\[dq]: 503092,
        \[dq]ppid\[dq]: 503083
      }
    }
  ]
}
\f[R]
.fi
.SH TROUBLESHOOTING
.PP
The potential problems you can face with are: the build with and without
the interception behaves differently (eg.: the build crash with the
\f[C]intercept\f[R] tool, but succeed otherwise).
The output is empty and it failed to intercept the children process
execution by the build command.
.PP
There could be many reasons for any of these failures.
It\[cq]s better to consult with the project wiki page for known
problems, before open a bug report.
.PP
The most common cause for empty outputs is that the build command was
not executed any commands.
The reason for that could be, because incremental builds not running the
compilers if everything is up to date.
Remember, \f[C]intercept\f[R] is not understanding the build file (eg.:
makefile), but intercepts the executed commands.
.SH SEE ALSO
.PP
bear(1)
.SH COPYRIGHT
.PP
Copyright (C) 2012-2021 by L\['a]szl\['o] Nagy
<https://github.com/rizsotto/Bear>
.SH AUTHORS
L\['a]szl\['o] Nagy.