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)