hexec(1)

📦 version 0.2.1, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ hexec(1) ✨

okay bestie, buckle UP, because we're talking about hexec — it's the manual page for the process execution hooking tool, and it's genuinely so much fun 💅

🌸 NAME 🌸

hexec — a process execution hooking tool 🎀

🦋 SYNOPSIS 🦋

hexec <OPTIONS> [expr] [cmd] [args...]

💖 DESCRIPTION 💖

So like. hexec is a tool that hooks into process execution calls — we're talking the whole exec family of syscalls, all of them 👑

You get to define an expression, and that expression gets run against any hooked exec call. And here's the gag: that expression can also contain a replacement exec call. So you're not just watching, you're participating. main character energy fr fr ✨

⭐ OPTIONS SUMMARY ⭐

here's the little quick-look rundown 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 — prints the options/expr summary page. cute little cheatsheet moment 💖
  • --help — same thing, prints the options/expr summary page 🫶
  • -lo — sets the output file for error output and for -print output. You might genuinely need this one, because if you're writing to stderr that can cause malfunctions — some processes read from stderr and expect a very specific, well-defined output. so yeah, redirect your vibes elsewhere 🙈

🌈 EXPRESSIONS 🌈

The expression gets executed against all process execution calls. And the rule is: if the expression returns true, the original call gets skipped. periodt 💅

  • <expr> -and <expr>
  • <expr> -a <expr>
  • <expr> <expr>

Returns true if both expressions return true. And lowkey the efficient part: if the left one returns false, the right expression is never executed. no wasted work, we love to see it ⭐

  • <expr> -or <expr>
  • <expr> -o <expr>

Returns true if one of both expressions returns true. Same shortcut energy: if the left returns true, the right expression is never executed ✨

  • -path <pattern> — returns true if the path of the executable matches <pattern>. And <pattern> is a bash compatible wild card pattern. slay 🦋
  • -ipath <pattern> — same as -path, but case insensitive. iykyk 👑
  • -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 contains the string <str> 🎀
  • -icontains <str> — same as -contains, but case insensitive ✨
  • -print — prints 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 so you don't confuse your shell. genuinely, do not forget this one 😭
  • -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 (the way -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 grab info from the original exec call. Each placeholder starts with { and ends with }. And if you literally want a { in your argument list, use \{. The placeholders get replaced when the -exec expression is evaluated ✨

💜 Placeholder types 💜

  • {n} — gets replaced with the number of arguments in the original call.
  • {<idx>} — gets replaced with the original argument at index <idx>. Example: {1} would give you the first argument. You can prepend <idx> with placeholder flags 👑
  • {} — gets replaced with all arguments from the original call. Each argument is separated with a space. You can use placeholder flags 💅
NOTE: the executable name is also considered an argument. So a call like "echo test" will result in two arguments: "echo" and "test". don't forget this, it catches everyone 🙈

🍓 PLACEHOLDER FLAGS 🍓

  • s — every argument is inserted as a single argument instead of concatenating all the arguments together.

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} \; however would result in -exec 'a' 'b' 'c' \;. the difference is everything bestie 🔥

  • q — quote every single argument.
  • e — escape all non alpha-numeric characters. This flag is very useful when you're using a "sh -c <...>" in the -exec expression. lowkey essential ✨

🌸 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 the ones (and this list 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. it's giving "handle with care" 🙈

🔥 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

...bestie they literally wrote TODO. iconic honestly 😭

💀 BUGS 💀

"I'm sure there are alot...it's still beta :)" — direct quote, and honestly? respect the honesty 🫶

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

aaaand that's the whole page bestie 💅 this was the hexec(1) manual, from November 2008, and yeah the page footer literally just says hexec(1) again because manpages love being extra. go forth and hook some exec calls, you absolute legend 🦋✨🎀

📦 where this page comes from