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)