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 http://coccinelle.lip6.fr/.

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=/usr/pkg/share/coccinelle/standard.iso)

-macro_file <file>
    (default=/usr/pkg/share/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/pkg/share/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/share/coccinelle/standard.iso)

--macro-file
    <file>

--macro-file-builtins
    <file> (default=/usr/local/share/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|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-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 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 expresion 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

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
/usr/pkg/share/coccinelle/standard.iso
    This file contains the default set of isomorphisms.
/usr/pkg/share/coccinelle/standard.h
    This file contains the default set of macro hints.

ENVIRONMENT

COCCINELLE_HOME
    The path to the Coccinelle share directory. Default is /usr/pkg/share/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.

AUTHOR
spatch was written by Julia Lawall <julia@diku.dk>, Yoann Padioleau <yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrhansen@diku.dk> and Henrik Stuart <henrik@hstuart.dk>.

This manual page was written by Yoann Padioleau <yoann.padioleau@gmail.com> and Julia Lawall <julia@diku.dk>.

REPORTING BUGS
Send a mail to <cocci@diku.dk>

COPYRIGHT
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)