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 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

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)