Your company here — click to reach over 10,000 unique daily visitors

spatch - Man Page

apply a semantic patch file to a set of C files


spatch --sp-file <SP> <files> [-o <outfile> ] [--iso-file <iso> ] [ options ]


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

Further information about spatch is available at https://coccinelle.gitlabpages.inria.fr/website/.

Semantic patch examples can be found at http://coccinellery.org/, and at the scripts/coccinelle directory of the Linux Kernel source code.


Here is a summary of the most commonly used options (also see the "Configuration Mechanism" section below):

--sp-file <file>

the semantic patch file

--dir <dir>

process all files in directory recursively

--iso-file <file>


--macro-file <file>



print some information to help debug the matching process


causes all available include files to be used


causes not even local include files to be used

-I <dir>

the directory containing the include files


process header files independently


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


do the modification on the file directly


store modifications in a .cocci_res file


show the version of spatch


show the date on which spatch was compiled


see short list of options


see all the available options in different categories

-help,  --help

show summary of options.


 ./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 /usr/lib64/coccinelle/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.

More Options


<file> the semantic patch file


<file> the output file


do the modification on the file directly


suffix to use when making a backup for inplace


store modifications in a .cocci_res file


invert the semantic patch before applying it


set number of diff context lines


report partial matches of the SP on the C file


<file> (default=/usr/local/lib/coccinelle/standard.iso)




<file> (default=/usr/local/lib/coccinelle/standard.h)


causes all available include files, both those included in the C file(s) and those included in header files, to be used


causes all available include files included in the C file(s) to be used


causes not even local include files to be used


causes local include files to be used


For integration in a toolchain (must be set before the first unknown option)


process header files independently


<dir> containing the header files (optional)


run the C preprocessor before applying the semantic match


gcc/cpp compatibility mode


<dir> process all files in directory recursively


works with --dir, use info generated by glimpseindex


find relevant files using id-utils


<dir> path name with respect to which a patch should be created

"" for a file in the current directory


<file> improve --dir by grouping related c files


Sets output routine: Default value: coccilib.output.Console


guess what


guess what


see short list of options


see all the available options in different categories


command line semantic patch


short option of --iso-file


<file> the semantic patch file





show diff even if only spacing changes








show the name of each function being processed


show the dependencies related to each rule






generate a pdf file representing the matching process


remove graph label (requires option -graphical-trace)















filter some cpp message when the macro is a "known" cpp construct



filter the error msg








gather timing information about the main coccinelle functions


<level> for profiling the CTL engine


<sec> timeout in seconds


max number of model checking steps per code unit


max depth of iso application


disable limit on max depth of iso application


gather information about isomorphism usage


disable a specific isomorphism


gather information about the cost of isomorphism usage


keep comments around removed code



drop all back edges derived from looping constructs - unsafe


drop all jumps derived from gotos - unsafe


drop all inferred typedefs from one parse of some code to the next


use OCaml Str regular expressions for constraints



convert ifdef to if (experimental)


convert ifdef to if (experimental)







disallow an expression pattern from matching a term and its subterm


this flag is not set, then break and continue are also error exits

if this flag is set don't check for inconsistent paths; dangerous


make an expression disjunction not prioritise the topmost disjunct


the number of bits in an unsigned int


the number of bits in an unsigned long


spacing of + code follows the conventions of Linux


spacing of + code follows the semantic patch


indicate that a virtual rule should be considered to be matched


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


option to set if launch spatch in ocamldebug


to print more messages


show trace



the processor to use for this run of spatch


the number of processors available


use mod to distribute files among the processors


use .ast_raw pre-parsed cached C file


directory of cached ASTs, sets --use-cache


maximum number of cached ASTs, sets --use-cache


The test options don't work with the --sp-file and so on.


<file> launch spatch on tests/file.[c,cocci]


launch spatch on all files in tests/ having a .res


generates .{ok,failed,spatch_ok} files using .res files


process the .{ok,failed,spatch_ok} files in current dir


use also file.res


which score file to compare with in --testall


do not update the score file when --testall succeeds



The action options don't work with the --sp-file and so on. It's for the other (internal) uses of the spatch program.




<file or dir>


<file or dir>


<file or dir>


<file or dir>


<file or dir>


<file or file:function>


<file or file:function>


<file or file:function>








<file1> <file2>









<file or dir>


<file or dir>


<file1> <>




<file1> <file2>

Configuration Mechanism

Coccinelle uses a simple text format to store customizations into in which the configuration file is processed is as follows, where the later lines always extend and may override earlier ones:

 o Your current user's home directory is processed first
 o Your directory from which spatch is called is processed next
 o The directory provided with the --dir option is processed last, if used

Such a configuration file may look like this:

	options = --jobs 4
	options = --show-trying



This file contains the default set of isomorphisms.


This file contains the default set of macro hints.


This file contains the custom set of spatch options.



The path to the Coccinelle share directory. Default is /usr/lib64/coccinelle


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, January 21-23, 2009, pp. 114-126.


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

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

Reporting Bugs

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

See Also

patch(1), diff(1)

Referenced By

pycocci(1), spgen(1).

Feb 26, 2015