Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SPATCH(1)		    General Commands Manual		     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_ ] [ op-
       tions ]

DESCRIPTION
       spatch is a program matching and	transformation tool for	C.   The  pro-
       grammer	describes  the code to match and the transformation to perform
       as a semantic patch, which looks	like a standard	patch, but can	trans-
       form multiple files at any number of code sites.

       Further	 information   about   spatch	is  available  at  http://coc-
       cinelle.lip6.fr/.

       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:

       --sp-file _file_
	      the semantic patch file

       --dir _dir_
	      process all files	in directory recursively

       --iso-file _file_
	      (default=@SHAREDIR@/standard.iso)

       --macro-file _file_
	      (default=@SHAREDIR@/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	 @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	direc-
       tory:

	 ./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 un-
	      known 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|coc-
	      cilib.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  con-
	      struct

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

       --disable-worth-trying-opt

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

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

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

       --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	exten-
	      sions for	source files are .cpp, .cxx, .cc, and for header files
	      are .h, .hpp and .hxx. Note that this option disables  the  pro-
	      cessing  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>

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

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

REFERENCES
       Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller.  "Documenting and Au-
       tomating	 Collateral Evolutions in Linux	Device Driver",	EuroSys	2008 ,
       Glasgow,	Scotland, April	2008, pp. 247-260.

       Julien Brunel, Damien Doligez, RenA(C) 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, Jan-
       uary 21-23, 2009, pp. 114-126.

AUTHOR
       spatch  was written by Julia Lawall <julia.lawall@lip6.fr>, Yoann Padi-
       oleau <yoann.padioleau@gmail.com>, Rene Rydhof Hansen  <rrh@cs.aau.dk>,
       Henrik	  Stuart    <henrik@hstuart.dk>,    Nicolas    Palix	<nico-
       las.palix@imag.fr>,  Peter  Senna   Tschudin   <peter.senna@gmail.com>,
       SA(C)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.padi-
       oleau@gmail.com>, Julia Lawall  <julia.lawall@lip6.fr>,	Nicolas	 Palix
       <nicolas.palix@imag.fr>	   and	   Peter     Senna    Tschudin	  <pe-
       ter.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.	 Copy-
       right 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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | MORE OPTIONS | FILES | ENVIRONMENT | REFERENCES | AUTHOR | REPORTING BUGS | COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=spatch&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help