hexec(1) hexec(1)
NAME
hexec - a process execution hooking tool
SYNOPSIS
hexec <OPTIONS> [expr] [cmd] [args...]
DESCRIPTION
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):
LD_PRELOAD
hexec adds libhexec-hook.so to the list of preloaded libraries.
HEXEC_EXPR_SHM
Contains the name of the internal shared memory object.
HEXEC_LOG_FD
Contains the file descriptor for error and -print output.
Please do never modify these environment variables. Also take care when you use these variables, because the name and content of the vari-
ables 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
BUGS
I'm sure there are alot...it's still beta :)
AUTHOR
hexec was written by Alexander Block http://blocksoftware.net/
If you wish to report a problem or make a suggestion then please email ablock@blocksoftware.net
hexec is released under the GNU General Public License version 2 or later. Please see the file COPYING for license details.
November 2008 hexec(1)