SPATCH(1)

NAME
spatch - apply a semantic patch file to a set of C files

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

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

OPTIONS
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>
    (default=/usr/lib/coccinelle/standard.iso)

--macro-file <file>
    (default=/usr/lib/coccinelle/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 /usr/lib/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

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-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: Default value: coccilib.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-diff
    show 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 construct

--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 expression pattern from matching a term and its subterm

--disable-worth-trying-opt

--only-return-is-error-exitif this flag is not set, then break and continue are also error exits

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

--no-safe-expressions
    make an expression disjunction not prioritise the topmost disjunct

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

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

--cpptestall
    launch spatch on all files in cpptests/ (C++ code) 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 or --cpptestall

--no-update-score-file
    do not update the score file when --testall or --cpptestall 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>

CONFIGURATION MECHANISM

Coccinelle uses a simple text format to store customizations into .cocciconfig files, that can be per project, user, or target. The order 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:

    [spatch]
    	options = --jobs 4
    	options = --show-trying

FILES
/usr/lib/coccinelle/standard.iso
    This file contains the default set of isomorphisms.
/usr/lib/coccinelle/standard.h
    This file contains the default set of macro hints.
.cocciconfig
    This file contains the custom set of spatch options.

ENVIRONMENT

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

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

AUTHOR
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@inria.fr>

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.

SEE ALSO
patch(1), diff(1)