SPATCH(1)SPATCH(1)NAMEspatch - apply a semantic patch file to a set of C files
SYNOPSISspatch--sp-file <SP> <files> [-o <outfile> ] [--iso-file <iso> ] [
options ]
DESCRIPTIONspatch is a program matching and transformation tool for C. The pro‐
grammer describes the code to match and the transformation to perform
as a semantic patch, which looks like a standard patch, but can trans‐
form multiple files at any number of code sites.
Further information about spatch is available at http://coc‐
cinelle.lip6.fr/.
Semantic patch examples can be found at http://coccinellery.org/, and
at the scripts/coccinelle directory of the Linux Kernel source code.
OPTIONS
Here is a summary of the most commonly used options:
--sp-file <file>
the semantic patch file
--dir <dir>
process all files in directory recursively
--iso-file <file>
(default=@SHAREDIR@/standard.iso)
--macro-file <file>
(default=@SHAREDIR@/standard.h)
--debug
print some information to help debug the matching process
--all-includes
causes all available include files to be used
--no-includes
causes not even local include files to be used
-I <dir>
the directory containing the include files
--include-headers
process header files independently
--use-glimpse
works with --dir, use information generated by glimpseindex
-o <file>
the output file. If none is specified, a patch is generated on
the standard output
--in-place
do the modification on the file directly
--out-place
store modifications in a .cocci_res file
--version
show the version of spatch--date show the date on which spatch was compiled
--shorthelp
see short list of options
--longhelp
see all the available options in different categories
-help, --help
show summary of options.
EXAMPLES
./spatch --sp-file foo.cocci foo.c
Apply the semantic patch foo.cocci to the C file foo.c. The semantic
patch is applied modulo a set of isomorphisms contained in standard.iso
(standard.iso is by default located in @SHAREDIR@/standard.iso). A
patch showing the effect of the application, if any, will be generated
on the standard output.
./spatch --sp-file foo.cocci foo.c -o /tmp/newfoo.c
The same as the above, except that a modified version of foo.c is
stored in /tmp/newfoo.c.
It is also possible to apply spatch to all of the C files in a direc‐
tory:
./spatch --cocci-file foo.cocci --dir foodir
If the semantic patch is not working as expected, the option --debug
shows selection of information about the application of a semantic
patch to a file or directory.
MORE OPTIONS
MAIN OPTIONS
--sp-file
<file> the semantic patch file
-o <file> the output file
--in-place
do the modification on the file directly
--backup-suffix
suffix to use when making a backup for inplace
--out-place
store modifications in a .cocci_res file
--reverse
invert the semantic patch before applying it
-U set number of diff context lines
--partial-match
report partial matches of the SP on the C file
--iso-file
<file> (default=/usr/local/lib/coccinelle/standard.iso)
--macro-file
<file>
--macro-file-builtins
<file> (default=/usr/local/lib/coccinelle/standard.h)
--recursive-includes
causes all available include files, both those included in the C
file(s) and those included in header files, to be used
--all-includes
causes all available include files included in the C file(s) to
be used
--no-includes
causes not even local include files to be used
--local-includes
causes local include files to be used
--ignore-unknown-options
For integration in a toolchain (must be set before the first
unknown option)
--include-headers
process header files independently
-I <dir> containing the header files (optional)
--preprocess
run the C preprocessor before applying the semantic match
-c gcc/cpp compatibility mode
--dir <dir> process all files in directory recursively
--use-glimpse
works with --dir, use info generated by glimpseindex
--use-google
find relevant files using google code search
--use-idutils
find relevant files using id-utils
--patch
<dir> path name with respect to which a patch should be created
"" for a file in the current directory
--kbuild-info
<file> improve --dir by grouping related c files
--pyoutput
Sets output routine: Standard values: <coccilib.output.Gtk|coc‐
cilib.output.Console>
--version
guess what
--date guess what
--shorthelp
see short list of options
--longhelp
see all the available options in different categories
ALIASES AND OBSOLETE OPTIONS
--sp command line semantic patch
--iso short option of --iso-file
--cocci-file
<file> the semantic patch file
MOST USEFUL SHOW OPTIONS
--show-diff
--no-show-diff
--force-diffshow
diff even if only spacing changes
--show-flow
--ctl-inline-let
--ctl-show-mcodekind
--show-bindings
--show-transinfo
--show-misc
--show-trying
show the name of each function being processed
--show-dependencies
show the dependencies related to each rule
VERBOSE SUBSYSTEMS OPTIONS
--verbose-ctl-engine
--verbose-match
--verbose-engine
--graphical-trace
generate a pdf file representing the matching process
--gt-without-label
remove graph label (requires option -graphical-trace)
--parse-error-msg
--verbose-parsing
--type-error-msg
OTHER SHOW OPTIONS
--show-c
--show-cocci
--show-before-fixed-flow
--show-ctl-tex
--show-ctl-text
--show-SP
DEBUG C PARSING/UNPARSING
--debug-cpp
--debug-lexer
--debug-etdt
--debug-typedef
--filter-msg
filter some cpp message when the macro is a "known" cpp con‐
struct
--filter-define-error
--filter-msg-define-error
filter the error msg
--filter-passed-level
--debug-unparsing
SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE
--quiet
--very-quiet
--debug
--pad
BENCH OPTIONS
--profile
gather timing information about the main coccinelle functions
--bench
<level> for profiling the CTL engine
--timeout
<sec> timeout in seconds
--steps
max number of model checking steps per code unit
--iso-limit
max depth of iso application
--no-iso-limit
disable limit on max depth of iso application
--track-iso
gather information about isomorphism usage
--disable-iso
disable a specific isomorphism
--profile-iso
gather information about the cost of isomorphism usage
CHANGE OF ALGORITHM OPTIONS
--keep-comments
keep comments around removed code
--loop
--no-loops
drop all back edges derived from looping constructs - unsafe
--no-gotos
drop all jumps derived from gotos - unsafe
--no-saved-typedefs
drop all inferred typedefs from one parse of some code to the
next
--ocaml-regexps
use OCaml Str regular expressions for constraints
--l1
--ifdef-to-if
convert ifdef to if (experimental)
--no-ifdef-to-if
convert ifdef to if (experimental)
--disable-multi-pass
--noif0-passing
--defined
--undefined
--noadd-typedef-root
--disallow-nested-exps
disallow an expresion pattern from matching a term and its sub‐
term
--disable-worth-trying-opt
--only-return-is-error-exitif this flag is not set, then break and con‐
tinue are also error exits
--allow-inconsistent-paths
if this flag is set don't check for inconsistent paths; danger‐
ous
--no-safe-expressions
make an expression disjunction not prioritise the topmost dis‐
junct
--int-bits
the number of bits in an unsigned int
--long-bits
the number of bits in an unsigned long
--linux-spacing
spacing of + code follows the conventions of Linux
--smpl-spacing
spacing of + code follows the semantic patch
-D indicate that a virtual rule should be considered to be matched
--c++ make a small attempt to parse C++ files. The supported exten‐
sions for source files are .cpp, .cxx, .cc, and for header files
are .h, .hpp and .hxx. Note that this option disables the pro‐
cessing of .c files as Coccinelle behaviour is different for
C++.
MISC OPTIONS
--debugger
option to set if launch spatch in ocamldebug
--disable-once
to print more messages
--show-trace-profile
show trace
--save-tmp-files
CONCURRENCY
--index
the processor to use for this run of spatch--max the number of processors available
--mod-distrib
use mod to distribute files among the processors
PAD OPTIONS
--use-cache
use .ast_raw pre-parsed cached C file
--cache-prefix
directory of cached ASTs, sets --use-cache
--cache-limit
maximum number of cached ASTs, sets --use-cache
TEST MODE AND TEST OPTIONS (WORKS WITH TESTS/ OR .OK FILES)
The test options don't work with the --sp-file and so on.
--test <file> launch spatch on tests/file.[c,cocci]
--testall
launch spatch on all files in tests/ having a .res
--test-okfailed
generates .{ok,failed,spatch_ok} files using .res files
--test-regression-okfailed
process the .{ok,failed,spatch_ok} files in current dir
--compare-with-expected
use also file.res
--expected-score-file
which score file to compare with in --testall
--no-update-score-file
do not update the score file when --testall succeeds
--relax-include-path
ACTION MODE
The action options don't work with the --sp-file and so on.
It's for the other (internal) uses of the spatch program.
--tokens-c
<file>
--parse-c
<file or dir>
--parse-h
<file or dir>
--parse-ch
<file or dir>
--parse-i
<file or dir>
--parse
<file or dir>
--show-flow
<file or file:function>
--control-flow
<file or file:function>
--control-flow-to-file
<file or file:function>
--test-cfg-ifdef
<file>
--parse-unparse
<file>
--type-c
<file>
--compare-c
<file1> <file2>
--comment-annotater-c
<file>
--compare-c-hardcoded
--test-attributes
<file>
--test-cpp
<file>
--extract-macros
<file or dir>
--extract-macros-select
<file or dir>
--xxx <file1> <>
--parse-cocci
<file>
--compare-c
<file1> <file2>
FILES
@SHAREDIR@/standard.iso
This file contains the default set of isomorphisms.
@SHAREDIR@/standard.h
This file contains the default set of macro hints.
ENVIRONMENT
COCCINELLE_HOME
The path to the Coccinelle share directory. Default is
@SHAREDIR@
REFERENCES
Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller. "Documenting and
Automating Collateral Evolutions in Linux Device Driver", EuroSys 2008
, Glasgow, Scotland, April 2008, pp. 247-260.
Julien Brunel, Damien Doligez, René Rydhof Hansen, Julia L. Lawall,
Gilles Muller. "A foundation for flow-based program matching: using
temporal logic and model checking", POPL 2009 , Savannah, GA, USA, Jan‐
uary 21-23, 2009, pp. 114-126.
AUTHORspatch was written by Julia Lawall <julia.lawall@lip6.fr>, Yoann Padi‐
oleau <yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrh@cs.aau.dk>,
Henrik Stuart <henrik@hstuart.dk>, Nicolas Palix <nico‐
las.palix@imag.fr>, Peter Senna Tschudin <peter.senna@gmail.com>,
Sébastien Hinderer <Sebastien.Hinderer@inria.fr>, Xavier Clerc
<xavier.clerc@inria.fr> and Matthieu Caneill
<matthieu.caneill42@gmail.com>.
This manual page was written by Yoann Padioleau <yoann.padi‐
oleau@gmail.com>, Julia Lawall <julia.lawall@lip6.fr>, Nicolas Palix
<nicolas.palix@imag.fr> and Peter Senna Tschudin
<peter.senna@gmail.com>.
REPORTING BUGS
Send a mail to <cocci@systeme.lip6.fr>
COPYRIGHT
Copyright 2012, 2015, INRIA and University of Grenoble-Alpes LIG.
Copyright 2010, 2011, University of Copenhagen DIKU and INRIA. Copy‐
right 2005-2009, Ecole des Mines de Nantes, University of Copenhagen.
spatch is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation, according to version 2 of the License.
SEE ALSOpatch(1), diff(1)
Feb 26, 2015 SPATCH(1)
