Provided by: coccinelle_1.1.1.deb-1build2_amd64 bug

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

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

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:

           [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@systeme.lip6.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)

                                           Feb 26, 2015                                 SPATCH(1)