~npalix/coccinelle/upstream

.\"  -*- nroff -*-
.\" Please adjust this date whenever revising the manpage.
.TH SPATCH 1 "Feb 26, 2015"

.\" see http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html
.\" see http://www.linuxjournal.com/article/1158
.\" see http://www.schweikhardt.net/man_page_howto.html
.\" groff -Tascii -man ./spatch.1 | more
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.\"
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively. Also \fR for roman.
.\" pad: src: deputy man page
.SH NAME
spatch \- apply a semantic patch file to a set of C files

.SH SYNOPSIS
.B spatch
.B \-\-sp\-file
.I <SP>
.I <files>
.B [-o
.I <outfile>
.B ]
.B [\-\-iso\-file
.I <iso>
.B ]
.B [
.I options
.B ]
.\"
.SH DESCRIPTION
\fBspatch\fP is a program matching and transformation tool for C.
The programmer describes the code to match and the transformation to
perform as a semantic patch, which looks like a standard patch, but can
transform multiple files at any number of code sites.

.PP
Further information about spatch is available at
\fBhttp://coccinelle.lip6.fr/\fP.

Semantic patch examples can be found at \fBhttp://coccinellery.org/\fP,
and at the \fBscripts/coccinelle\fP directory of the Linux Kernel source
code.

.SH OPTIONS
Here is a summary of the most commonly used options:

.TP
.B \-\-sp\-file \fI<file>\fP
the semantic patch file
.TP
.B \-\-dir                 \fI<dir>\fP
process all files in directory recursively
.TP
.B \-\-iso\-file            \fI<file>\fP
(default=@SHAREDIR@/standard.iso)
.TP
.B \-\-macro\-file          \fI<file>\fP
(default=@SHAREDIR@/standard.h)
.TP
.B \-\-debug
print some information to help debug the matching process
.TP
.B \-\-all\-includes
causes all available include files to be used
.TP
.B \-\-no\-includes
causes not even local include files to be used
.TP
.B -I                   \fI<dir>\fP
the directory containing the include files
.TP
.B \-\-include\-headers
process header files independently
.TP
.B \-\-use\-glimpse
works with \-\-dir, use information generated by glimpseindex
.TP
.B -o                   \fI<file>\fP
the output file. If none is specified, a patch is generated on the standard
output
.TP
.B \-\-in\-place
do the modification on the file directly
.TP
.B \-\-out\-place
store modifications in a .cocci_res file
.TP
.B \-\-version
show the version of spatch
.TP
.B \-\-date
show the date on which spatch was compiled
.TP
.B \-\-shorthelp
see short list of options
.TP
.B \-\-longhelp
see all the available options in different categories
.TP
.B \-help, \-\-help
show summary of options.

.SH 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 directory:

  ./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.

.SH MORE OPTIONS
.IP "MAIN OPTIONS"
.TP
\fB\-\-sp\-file\fR
<file> the semantic patch file
.TP
\fB\-o\fR
<file> the output file
.TP
\fB\-\-in\-place\fR
do the modification on the file directly
.TP
\fB\-\-backup\-suffix\fR
suffix to use when making a backup for inplace
.TP
\fB\-\-out\-place\fR
store modifications in a .cocci_res file
.TP
\fB\-\-reverse\fR
invert the semantic patch before applying it
.TP
\fB\-U\fR
set number of diff context lines
.TP
\fB\-\-partial\-match\fR
report partial matches of the SP on the C file
.TP
\fB\-\-iso\-file\fR
<file> (default=/usr/local/lib/coccinelle/standard.iso)
.TP
\fB\-\-macro\-file\fR
<file>
.TP
\fB\-\-macro\-file\-builtins\fR
<file> (default=/usr/local/lib/coccinelle/standard.h)
.TP
\fB\-\-recursive\-includes\fR
causes all available include files, both those included in the C file(s) and those included in header files, to be used
.TP
\fB\-\-all\-includes\fR
causes all available include files included in the C file(s) to be used
.TP
\fB\-\-no\-includes\fR
causes not even local include files to be used
.TP
\fB\-\-local\-includes\fR
causes local include files to be used
.TP
\fB\-\-ignore\-unknown\-options\fR
For integration in a toolchain (must be set before the first unknown option)
.TP
\fB\-\-include\-headers\fR
process header files independently
.TP
\fB\-I\fR
<dir> containing the header files (optional)
.TP
\fB\-\-preprocess\fR
run the C preprocessor before applying the semantic match
.TP
\fB\-c\fR
gcc/cpp compatibility mode
.TP
\fB\-\-dir\fR
<dir> process all files in directory recursively
.TP
\fB\-\-use\-glimpse\fR
works with \fB\-\-dir\fR, use info generated by glimpseindex
.TP
\fB\-\-use\-google\fR
find relevant files using google code search
.TP
\fB\-\-use\-idutils\fR
find relevant files using id\-utils
.TP
\fB\-\-patch\fR
<dir> path name with respect to which a patch should be created
.IP
"" for a file in the current directory
.TP
\fB\-\-kbuild\-info\fR
<file> improve \fB\-\-dir\fR by grouping related c files
.TP
\fB\-\-pyoutput\fR
Sets output routine: Standard values: <coccilib.output.Gtk|coccilib.output.Console>
.TP
\fB\-\-version\fR
guess what
.TP
\fB\-\-date\fR
guess what
.TP
\fB\-\-shorthelp\fR
see short list of options
.TP
\fB\-\-longhelp\fR
see all the available options in different categories
.PP
.IP "ALIASES AND OBSOLETE OPTIONS"
.TP
\fB\-\-sp\fR
command line semantic patch
.TP
\fB\-\-iso\fR
short option of \fB\-\-iso\-file\fR
.TP
\fB\-\-cocci\-file\fR
<file> the semantic patch file
.PP
.IP "MOST USEFUL SHOW OPTIONS"
.HP
\fB\-\-show\-diff\fR
.HP
\fB\-\-no\-show\-diff\fR
.TP
\fB\-\-force\-diffshow\fR
diff even if only spacing changes
.HP
\fB\-\-show\-flow\fR
.HP
\fB\-\-ctl\-inline\-let\fR
.HP
\fB\-\-ctl\-show\-mcodekind\fR
.HP
\fB\-\-show\-bindings\fR
.HP
\fB\-\-show\-transinfo\fR
.HP
\fB\-\-show\-misc\fR
.TP
\fB\-\-show\-trying\fR
show the name of each function being processed
.TP
\fB\-\-show\-dependencies\fR
show the dependencies related to each rule
.PP
.IP "VERBOSE SUBSYSTEMS OPTIONS"
.HP
\fB\-\-verbose\-ctl\-engine\fR
.HP
\fB\-\-verbose\-match\fR
.HP
\fB\-\-verbose\-engine\fR
.TP
\fB\-\-graphical\-trace\fR
generate a pdf file representing the matching process
.TP
\fB\-\-gt\-without\-label\fR
remove graph label (requires option \fB\-graphical\-trace\fR)
.HP
\fB\-\-parse\-error\-msg\fR
.HP
\fB\-\-verbose\-parsing\fR
.HP
\fB\-\-type\-error\-msg\fR
.PP
.IP "OTHER SHOW OPTIONS"
.HP
\fB\-\-show\-c\fR
.HP
\fB\-\-show\-cocci\fR
.HP
\fB\-\-show\-before\-fixed\-flow\fR
.HP
\fB\-\-show\-ctl\-tex\fR
.HP
\fB\-\-show\-ctl\-text\fR
.HP
\fB\-\-show\-SP\fR
.PP
.IP "DEBUG C PARSING/UNPARSING"
.HP
\fB\-\-debug\-cpp\fR
.HP
\fB\-\-debug\-lexer\fR
.HP
\fB\-\-debug\-etdt\fR
.HP
\fB\-\-debug\-typedef\fR
.TP
\fB\-\-filter\-msg\fR
filter some cpp message when the macro is a "known" cpp construct
.HP
\fB\-\-filter\-define\-error\fR
.TP
\fB\-\-filter\-msg\-define\-error\fR
filter the error msg
.HP
\fB\-\-filter\-passed\-level\fR
.HP
\fB\-\-debug\-unparsing\fR
.PP
.IP "SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE"
.HP
\fB\-\-quiet\fR
.HP
\fB\-\-very\-quiet\fR
.HP
\fB\-\-debug\fR
.HP
\fB\-\-pad\fR
.PP
.IP "BENCH OPTIONS"
.TP
\fB\-\-profile\fR
gather timing information about the main coccinelle functions
.TP
\fB\-\-bench\fR
<level> for profiling the CTL engine
.TP
\fB\-\-timeout\fR
<sec> timeout in seconds
.TP
\fB\-\-steps\fR
max number of model checking steps per code unit
.TP
\fB\-\-iso\-limit\fR
max depth of iso application
.TP
\fB\-\-no\-iso\-limit\fR
disable limit on max depth of iso application
.TP
\fB\-\-track\-iso\fR
gather information about isomorphism usage
.TP
\fB\-\-disable\-iso\fR
disable a specific isomorphism
.TP
\fB\-\-profile\-iso\fR
gather information about the cost of isomorphism usage
.PP
.IP "CHANGE OF ALGORITHM OPTIONS"
.TP
\fB\-\-keep\-comments\fR
keep comments around removed code
.HP
\fB\-\-loop\fR
.TP
\fB\-\-no\-loops\fR
drop all back edges derived from looping constructs \- unsafe
.TP
\fB\-\-no\-gotos\fR
drop all jumps derived from gotos \- unsafe
.TP
\fB\-\-no\-saved\-typedefs\fR
drop all inferred typedefs from one parse of some code to the next
.TP
\fB\-\-ocaml\-regexps\fR
use OCaml Str regular expressions for constraints
.HP
\fB\-\-l1\fR
.TP
\fB\-\-ifdef\-to\-if\fR
convert ifdef to if (experimental)
.TP
\fB\-\-no\-ifdef\-to\-if\fR
convert ifdef to if (experimental)
.HP
\fB\-\-disable\-multi\-pass\fR
.HP
\fB\-\-noif0\-passing\fR
.HP
\fB\-\-defined\fR
.HP
\fB\-\-undefined\fR
.HP
\fB\-\-noadd\-typedef\-root\fR
.TP
\fB\-\-disallow\-nested\-exps\fR
disallow an expresion pattern from matching a term and its subterm
.HP
\fB\-\-disable\-worth\-trying\-opt\fR
.HP
\fB\-\-only\-return\-is\-error\-exitif\fR this flag is not set, then break and continue are also error exits
.TP
\fB\-\-allow\-inconsistent\-paths\fR
if this flag is set don't check for inconsistent paths; dangerous
.TP
\fB\-\-no\-safe\-expressions\fR
make an expression disjunction not prioritise the topmost disjunct
.TP
\fB\-\-int\-bits\fR
the number of bits in an unsigned int
.TP
\fB\-\-long\-bits\fR
the number of bits in an unsigned long
.TP
\fB\-\-linux\-spacing\fR
spacing of + code follows the conventions of Linux
.TP
\fB\-\-smpl\-spacing\fR
spacing of + code follows the semantic patch
.TP
\fB\-D\fR
indicate that a virtual rule should be considered to be matched
.TP
\fB\-\-c\fR++
make a small attempt to parse C++ files. The supported extensions for
source files are .cpp, .cxx, .cc, and for header files are .h, .hpp
and .hxx. Note that this option disables the processing of .c files
as Coccinelle behaviour is different for C++.
.PP
.IP "MISC OPTIONS"
.TP
\fB\-\-debugger\fR
option to set if launch spatch in ocamldebug
.TP
\fB\-\-disable\-once\fR
to print more messages
.TP
\fB\-\-show\-trace\-profile\fR
show trace
.HP
\fB\-\-save\-tmp\-files\fR
.PP
.IP "CONCURRENCY"
.TP
\fB\-\-index\fR
the processor to use for this run of spatch
.TP
\fB\-\-max\fR
the number of processors available
.TP
\fB\-\-mod\-distrib\fR
use mod to distribute files among the processors
.PP
.IP "PAD OPTIONS"
.TP
\fB\-\-use\-cache\fR
use .ast_raw pre\-parsed cached C file
.TP
\fB\-\-cache\-prefix\fR
directory of cached ASTs, sets \fB\-\-use\-cache\fR
.TP
\fB\-\-cache\-limit\fR
maximum number of cached ASTs, sets \fB\-\-use\-cache\fR
.PP
.IP "TEST MODE AND TEST OPTIONS (WORKS WITH TESTS/ OR .OK FILES)"
The test options don't work with the \fB\-\-sp\-file\fR and so on.
.TP
\fB\-\-test\fR
<file> launch spatch on tests/file.[c,cocci]
.TP
\fB\-\-testall\fR
launch spatch on all files in tests/ having a .res
.TP
\fB\-\-test\-okfailed\fR
generates .{ok,failed,spatch_ok} files using .res files
.TP
\fB\-\-test\-regression\-okfailed\fR
process the .{ok,failed,spatch_ok} files in current dir
.TP
\fB\-\-compare\-with\-expected\fR
use also file.res
.TP
\fB\-\-expected\-score\-file\fR
which score file to compare with in \fB\-\-testall\fR
.TP
\fB\-\-no\-update\-score\-file\fR
do not update the score file when \fB\-\-testall\fR succeeds
.HP
\fB\-\-relax\-include\-path\fR
.PP
.IP "ACTION MODE"
The action options don't work with the \fB\-\-sp\-file\fR and so on.
It's for the other (internal) uses of the spatch program.
.TP
\fB\-\-tokens\-c\fR
<file>
.TP
\fB\-\-parse\-c\fR
<file or dir>
.TP
\fB\-\-parse\-h\fR
<file or dir>
.TP
\fB\-\-parse\-ch\fR
<file or dir>
.TP
\fB\-\-parse\-i\fR
<file or dir>
.TP
\fB\-\-parse\fR
<file or dir>
.TP
\fB\-\-show\-flow\fR
<file or file:function>
.TP
\fB\-\-control\-flow\fR
<file or file:function>
.TP
\fB\-\-control\-flow\-to\-file\fR
<file or file:function>
.TP
\fB\-\-test\-cfg\-ifdef\fR
<file>
.TP
\fB\-\-parse\-unparse\fR
<file>
.TP
\fB\-\-type\-c\fR
<file>
.TP
\fB\-\-compare\-c\fR
<file1> <file2>
.TP
\fB\-\-comment\-annotater\-c\fR
<file>
.HP
\fB\-\-compare\-c\-hardcoded\fR
.TP
\fB\-\-test\-attributes\fR
<file>
.TP
\fB\-\-test\-cpp\fR
<file>
.TP
\fB\-\-extract\-macros\fR
<file or dir>
.TP
\fB\-\-extract\-macros\-select\fR
<file or dir>
.TP
\fB\-\-xxx\fR
<file1> <>
.TP
\fB\-\-parse\-cocci\fR
<file>
.TP
\fB\-\-compare\-c\fR
<file1> <file2>

.SH FILES
.I @SHAREDIR@/standard.iso
.RS
This file contains the default set of isomorphisms.
.RE
.I @SHAREDIR@/standard.h
.RS
This file contains the default set of macro hints.

.SH ENVIRONMENT
.IP COCCINELLE_HOME
The path to the Coccinelle share directory. Default is
.I @SHAREDIR@

.SH REFERENCES
Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller.
"Documenting and Automating Collateral Evolutions in Linux Device Driver",
.I 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",
.I POPL 2009
, Savannah, GA, USA, January 21-23, 2009, pp. 114-126.

.SH AUTHOR
\fBspatch\fP was written by Julia Lawall <julia.lawall@lip6.fr>, Yoann Padioleau
<yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrh@cs.aau.dk>,
Henrik Stuart <henrik@hstuart.dk>, Nicolas Palix <nicolas.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>.

.PP
This manual page was written by Yoann Padioleau <yoann.padioleau@gmail.com>,
Julia Lawall <julia.lawall@lip6.fr>, Nicolas Palix <nicolas.palix@imag.fr>
and Peter Senna Tschudin <peter.senna@gmail.com>.

.SH REPORTING BUGS
Send a mail to <cocci@systeme.lip6.fr>

.SH COPYRIGHT
Copyright 2012, 2015, INRIA and University of Grenoble-Alpes LIG.
Copyright 2010, 2011, University of Copenhagen DIKU and INRIA.
Copyright 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.

.SH SEE ALSO
\fIpatch\fP(1), \fIdiff\fP(1)