.TH "hexec" "1" "November 2008" "" ""
.SH "NAME"
hexec \- a process execution hooking tool
.SH "SYNOPSIS"

.PP 
hexec <OPTIONS> [expr] [cmd] [args\&.\&.\&.]
.PP 
.SH "DESCRIPTION"

.PP 
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\&.
.PP 
.SH "OPTIONS SUMMARY"

.PP 
Here is a summary of the options to hexec\&.
.PP 
.nf 

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

.fi 

.PP 
.SH "OPTIONS"

.PP 
.IP "\fB-h\fP"
Print a options/expr summary page
.IP "\fB--help\fP"
Print a options/expr summary page
.IP "\fB-lo\fP"
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\&.
.IP 
.SH "EXPRESSIONS"

.PP 
The expression is executed against all process execution calls\&. 
If the expression returns true, the original call is skipped\&. 
.PP 
.IP "\fB<expr> -and <expr>\fP"
.IP "\fB<expr> -a <expr>\fP"
.IP "\fB<expr> <expr>\fP"
Returns true if both expressions return true\&. If the left returns false, the right expression is never executed\&.
.IP "\fB<expr> -or <expr>\fP"
.IP "\fB<expr> -o <expr>\fP"
Returns true if one of both expressions returns true\&. If the left returns true, the right expression is never executed\&.
.IP "\fB-path <pattern>\fP"
Returns true if the path of the executable matches <pattern>\&. <pattern> is a bash compatible wild card pattern\&.
.IP "\fB-ipath <pattern>\fP"
Same as -path, but case insensitive\&.
.IP "\fB-name <pattern>\fP"
Returns true if the base name of the executable matches <pattern>\&. <pattern> is a bash compatible wild card pattern\&.
.IP "\fB-iname <pattern>\fP"
Same as -name, but case insensitive\&.
.IP "\fB-contains <str>\fP"
Returns true if the path of the executable containes the string <str>\&.
.IP "\fB-icontains <str>\fP"
Same as -contains, but case insensitive\&. 
.IP "\fB-print\fP"
Print all arguments to the called process\&. Returns always true\&.
.IP "\fB-exec <cmd> [args\&.\&.\&.] ;\fP"
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\&.
.br 
.br 
\fBNOTE\fP: Please be aware that you may need to escape or quote the terminating semicolon to not confuse your shell\&.
.IP "\fB-sh <script>\fP"
Interprets <script> as a shell script by invoking /bin/sh with the arguments \fB-c \&'<script>\&'\fP\&. 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 \fB-exec sh -c <script>\fP\&.

.PP 
.SH "PLACEHOLDERS FOR -exec EXPRESSION"

.PP 
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 \e{ if you want to use a { in your argument list\&. The placeholders are replaced when the -exec expression is evaluated\&.
.PP 
Placeholder types:
.IP "\fB{n}\fP"
Will be replaced with the number of arguments in the original call\&.
.IP "\fB{<idx>}\fP"
Will be replaced with the original argument at index <idx>\&. Example: {1} would give the first argument\&. You can prepend <idx> with placeholder flags\&.
.IP "\fB{}\fP"
Will be replaced with all arguments from the original call\&. Each argument is seperated with a space\&. You can use placeholder flags\&.

.PP 
\fBNOTE\fP: The executable name is also considered as argument\&. This means that a call like "echo test" will result in two arguments, "echo" and "test"\&.
.PP 
.SH "PLACEHOLDER FLAGS"
.IP "\fBs\fP"
Every argument is inserted as single argument instead of concatenating all arguments\&.
.br 
Consider the arguments \&'a\&', \&'b\&' and \&'c\&'\&. Without \fBs\fP, \fB-exec {} \e;\fP would result in \fB-exec \&'a b c\&' \e;\fP, which in many cases is not what you want\&. \fB-exec {s} \e;\fP howewer would result in \fB-exec \&'a\&' \&'b\&' \&'c\&' \e;\fP\&.
.IP "\fBq\fP"
Quote every single argument\&.
.IP "\fBe\fP"
Escape all non alpha-numeric characters\&. This flag is very useful when using a "sh -c <\&.\&.\&.>" in the -exec expression\&.

.PP 
Examples
.IP "\fB-exec echo {} \e;\fP with the call \fB\&'a\&' \&'b\&' \&'c\&'\fP"
results in: \&'echo\&' \&'a b c\&'
.IP "\fB-exec echo {q} \e;\fP with the call \fB\&'a\&' \&'b\&' \&'c\&'\fP"
results in: \&'echo\&' \&'a\&' \&'b\&' \&'c\&'
.IP "\fB-exec sh -c \&'echo {}; {}\&' \e;\fP with the call \fB\&'sh\&' \&'-c\&' \&'gcc d\&.c >> log\&.txt\&'\fP"
results in: \&'sh\&' \&'-c\&' \&'echo sh -c gcc d\&.c >> log\&.txt; sh -c gcc d\&.c >> log\&.txt\&' 
.br 
Please note that this will not do what you may expect, as the >> is handled wrong in this case\&.
.IP "\fB-exec sh -c \&'echo {e}; {}\&' \e;\fP with the call \fB\&'sh\&' \&'-c\&' \&'gcc d\&.c >> log\&.txt\&'\fP"
results in: \&'sh\&' \&'-c\&' \&'echo sh \e-c gcc\e d\e\&.c\e \e>\e>\e log\e\&.txt; sh -c gcc d\&.c >> log\&.txt\&' 
.br 

.IP 
.SH "CHANGES TO PROCESSES"

.PP 
hexec will add some environment variables to the hooked processes\&. 
These are (may not be complete):
.IP "\fBLD_PRELOAD\fP"
hexec adds libhexec-hook\&.so to the list of preloaded libraries\&. 
.IP "\fBHEXEC_EXPR_SHM\fP"
Contains the name of the internal shared memory object\&.
.IP "\fBHEXEC_LOG_FD\fP"
Contains the file descriptor for error and -print output\&.

.PP 
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\&.
.PP 
.SH "EXAMPLES"

.PP 
.IP "\fBhexec -name \&'gcc\&' -exec ccache {s} \e; make\fP"
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"

.PP 
.SH "HOW IT WORKS"

.PP 
TODO
.PP 
.SH "BUGS"

.PP 
I\&'m sure there are alot\&.\&.\&.it\&'s still beta :)
.PP 
.SH "AUTHOR"

.PP 
hexec was written by Alexander Block
http://blocksoftware\&.net/
.PP 
If you wish to report a problem or make a suggestion then please email
ablock@blocksoftware\&.net
.PP 
hexec is released under the GNU General Public License version 2 or
later\&. Please see the file COPYING for license details\&.