hexec1

Usage

Overview

hexec is a tool to hook into process exececution calls (exec family of syscalls). You can define an expression that is executed against any hooked exec call. This expression may also contain a replacement exec call.

Options summary

Here is a summary of the options to hexec.

  --help    | -h        Print a options/expr summary page
  --version | -v        Print hexec version
  --log-out | -lo       set output file for error and -print output

Options

-h

Print a options/expr summary page

--help

Print a options/expr summary page

-lo

Set the output file for error and -print output. This can be required if writing to stderr could cause malfunction because some processes read from stderr and expect a well defined output.

Expressions

The expression is executed against all process execution calls. If the expression returns true, the original call is skipped.

<expr> -and <expr>

<expr> -a <expr>

<expr> <expr>

Returns true if both expressions return true. If the left returns false, the right expression is never executed.

<expr> -or <expr>

<expr> -o <expr>

Returns true if one of both expressions returns true. If the left returns true, the right expression is never executed.

-path <pattern>

Returns true if the path of the executable matches <pattern>. <pattern> is a bash compatible wild card pattern.

-ipath <pattern>

Same as -path, but case insensitive.

-name <pattern>

Returns true if the base name of the executable matches <pattern>. <pattern> is a bash compatible wild card pattern.

-iname <pattern>

Same as -name, but case insensitive.

-contains <str>

Returns true if the path of the executable containes the string <str>.

-icontains <str>

Same as -contains, but case insensitive.

-print

Print all arguments to the called process. Returns always true.

-exec <cmd> [args...] ;

Executes <cmd> with [args...] as arguments. This expression must be terminated with a semicolon. You can use argument placeholders in <cmd> and [args...] (see below). This expression always returns true.

NOTE: Please be aware that you may need to escape or quote the terminating semicolon to not confuse your shell.

-sh <script>

Interprets <script> as a shell script by invoking /bin/sh with the arguments -c '<script>'. You can use argument placeholders inside <script>. Please note that -sh only expects a single argument and not a variable list of arguments (as -exec does). Using -sh is the same as using -exec sh -c <script>.

PLACEHOLDERS FOR -exec EXPRESSION

Every -exec expression can use placeholders in the argument list to obtain information from the original exec call. Each placeholder starts with { and ends with }. Use \{ if you want to use a { in your argument list. The placeholders are replaced when the -exec expression is evaluated.

Placeholder types:

{n}

Will be replaced with the number of arguments in the original call.

{<idx>}

Will be replaced with the original argument at index <idx>. Example: {1} would give the first argument. You can prepend <idx> with placeholder flags.

{}

Will be replaced with all arguments from the original call. Each argument is seperated with a space. You can use placeholder flags.

NOTE: The executable name is also considered as argument. This means that a call like "echo test" will result in two arguments, "echo" and "test".

Placeholder flags

s

Every argument is inserted as single argument instead of concatenating all arguments.
Consider the arguments 'a', 'b' and 'c'. Without s, -exec {} \; would result in -exec 'a b c' \;, which in many cases is not what you want. -exec {s} \; howewer would result in -exec 'a' 'b' 'c' \;.

q

Quote every single argument.

e

Escape all non alpha-numeric characters. This flag is very useful when using a "sh -c <...>" in the -exec expression.

Examples

-exec echo {} \; with the call 'a' 'b' 'c'

results in: 'echo' 'a b c'

-exec echo {q} \; with the call 'a' 'b' 'c'

results in: 'echo' 'a' 'b' 'c'

-exec sh -c 'echo {}; {}' \; with the call 'sh' '-c' 'gcc d.c >> log.txt'

results in: 'sh' '-c' 'echo sh -c gcc d.c >> log.txt; sh -c gcc d.c >> log.txt'
Please note that this will not do what you may expect, as the >> is handled wrong in this case.

-exec sh -c 'echo {e}; {}' \; with the call 'sh' '-c' 'gcc d.c >> log.txt'

results in: 'sh' '-c' 'echo sh \-c gcc\ d\.c\ \>\>\ log\.txt; sh -c gcc d.c >> log.txt'

Changes to processes

hexec will add some environment variables to the hooked processes. These are (may not be complete):

Please do never modify these environment variables. Also take care when you use these variables, because the name and content of the variables may change in the future.

Examples

hexec -name 'gcc' -exec ccache {s} \; make

Calls make, which will then call gcc several times. The executable name of each hooked process execution is tested against the file pattern "gcc" and "ccache {s}" is called each time a match is found. '{s}' will be replaced with the original (the hooked) call. In this example, a call to "gcc -o test.o test.c" would be replaced with "ccache gcc -o test.o test.c"

How it works

TODO