Provided by: creduce_2.10.0-1~18.04_amd64 
NAME
creduce - C and C++ program reducer
DESCRIPTION
creduce 2.10.0 (fb91843) -- a C and C++ program reducer
C-Reduce requires an "interestingness test" and one or more files to reduce, which must be writable. The
interestingness test is an executable program (usually a shell script) that returns 0 when a partially
reduced file is interesting (a candidate for further reduction) and returns non-zero when a partially
reduced file is not interesting (not a candidate for further reduction -- all uninteresting files are
discarded).
C-Reduce runs the interestingness test in a fresh temporary directory containing only the partially
reduced file(s). Thus, when the interestingness test examines a partially reduced file, it must do so
using a relative path to the current working directory. On the other hand, when the interestingness test
refers to any file that is not being reduced, this should be done using an absolute path.
The interestingness test should be deterministic and should not expect any command line arguments.
C-Reduce can and does introduce infinite loops during reduction. Therefore, if your interestingness test
runs the compiled program, this should be done under a timeout. You can implement the timeout yourself,
for example using the UNIX "timeout" command, or alternatively you can give C-Reduce a timeout (which is
on by default, but is set very long: 5 minutes). An advantage of using C-Reduce's timeout is that when a
test is killed due to timing out, a message will be printed. If you do implement a timeout yourself, we
recommend that your interestingness test returns exit code 124 when a subcommand times out. This will not
affect the reduction but it will cause C-Reduce to print a message stating the interestingness test
reported a timeout. It is important to ensure that timeouts are not occurring too often (especially
during C-Reduce's initial passes) or else C-Reduce will work poorly.
There is a particularly subtle issue regarding timeouts, which is that the interestingness test may slow
down due to resource contention when C-Reduce runs multiple copies of it on different cores. We have
observed slowdowns of up to 50% due to (we suspect) cache thrashing. You must take this slowdown into
account when choosing a timeout or else timeouts might occur very frequently.
As a quick example of an interestingness test, if you consider a file to be interesting if GCC's
vectorizer fires while compiling it, you might write this shell script:
gcc -w -O3 foo.c -S && grep xmm foo.s
To see if your interestingness test is working, try running these commands:
DIR=`mktemp -d` cp file_to_reduce [optionally, more files to reduce] $DIR cd $DIR
/path/to/interestingness_test echo $?
This should result in "0" being echoed to the terminal. If this does not happen, the interestingness test
is flawed and C-Reduce won't be able to make use of it.
If you haven't written an interestingness test before, please refer to this tutorial for additional
guidance:
https://embed.cs.utah.edu/creduce/using/
If at all possible, run C-Reduce on preprocessed code, generated for example using:
gcc -E -P file.c
If you cannot reduce preprocessed code, you can either reduce just the non-preprocessed file or else
perform a multi-file reduction on the file and its transitive includes (or any subset of them). In the
first case you need to set the CREDUCE_INCLUDE_PATH environment variable to a colonseparated list of
include directories in order for clang_delta to find them.
If your interestingness test involves a cross compiler and the characteristics of the cross target
differs from the host you will need to set CREDUCE_TARGET_TRIPLE to match the cross target. This is
particularly important if you are working with non-preprocessed code and use CREDUCE_INCLUDE_PATH.
Press "s" at any time to skip to the next pass (this feature is disabled unless the Perl module
Term::ReadKey is available on your system).
Summary of options:
--abs-timing
Print timestamps about reduction progress using absolute time
--add-pass <pass> <sub-pass> <priority>
Add the specified pass to the schedule
--also-interesting <exitcode>
A process exit code (somewhere in the range 64-113 would be usual) that, when returned by the
interestingness test, will cause C-Reduce to save a copy of the variant [default: -1]
--debug
Print debug information
--die-on-pass-bug
Terminate C-Reduce if a pass encounters an otherwise non-fatal problem
--max-improvement <bytes>
Largest improvement in file size from a single transformation that C-Reduce should accept (useful
only to slow C-Reduce down)
--n <N>
Number of cores to use; C-Reduce tries to automatically pick a good setting but its choice may be
too low or high for your situation
--no-cache
Don't cache behavior of passes
--no-default-passes
Start with an empty pass schedule
--no-give-up
Don't give up on a pass that hasn't made progress for 50000 iterations
--no-kill
Wait for parallel instances to terminate on their own instead of killing them (only useful for
debugging)
--not-c
Don't run passes that are specific to C and C++, use this mode for reducing other languages
--print-diff
Show changes made by transformations, for debugging
--save-temps
Don't delete /tmp/creduce-xxxxxx directories on termination
--shaddap
Suppress output about non-fatal internal errors
--skip-initial-passes
Skip initial passes (useful if input is already partially reduced)
--skip-key-off
Disable skipping the rest of the current pass when "s" is pressed
--sllooww
Try harder to reduce, but perhaps take a long time to do so
--tidy Do not make a backup copy of each file to reduce as file.orig
--timeout
Interestingness test timeout in seconds [default: 300]
--timing
Print timestamps about reduction progress
--version
Print the version information
usage: creduce [options] interestingness_test file_to_reduce [optionally, more files to reduce]
creduce --help for more information
SEE ALSO
The full documentation for creduce is maintained as a Texinfo manual. If the info and creduce programs
are properly installed at your site, the command
info creduce
should give you access to the complete manual.