1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
|
.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\&.
|
