1SPATCH(1) General Commands Manual SPATCH(1)
2
6 spatch - apply a semantic patch file to a set of C files
7
10 spatch --sp-file <SP> <files> [-o <outfile> ] [--iso-file <iso> ] [
11 options ]
12
14 spatch is a program matching and transformation tool for C. The pro‐
15 grammer describes the code to match and the transformation to perform
16 as a semantic patch, which looks like a standard patch, but can trans‐
17 form multiple files at any number of code sites.
18 Further information about spatch is available at http://coc‐
21 cinelle.lip6.fr/.
22 Semantic patch examples can be found at http://coccinellery.org/, and
24 at the scripts/coccinelle directory of the Linux Kernel source code.
25
28 Here is a summary of the most commonly used options (also see the "Con‐
29 figuration Mechanism" section below):
30 --sp-file <file>
33 the semantic patch file
34 --dir <dir>
36 process all files in directory recursively
37 --iso-file <file>
39 (default=/usr/lib64/coccinelle/standard.iso)
40 --macro-file <file>
42 (default=/usr/lib64/coccinelle/standard.h)
43 --debug
45 print some information to help debug the matching process
46 --all-includes
48 causes all available include files to be used
49 --no-includes
51 causes not even local include files to be used
52 -I <dir>
54 the directory containing the include files
55 --include-headers
57 process header files independently
58 --use-glimpse
60 works with --dir, use information generated by glimpseindex
61 -o <file>
63 the output file. If none is specified, a patch is generated on
64 the standard output
65 --in-place
67 do the modification on the file directly
68 --out-place
70 store modifications in a .cocci_res file
71 --version
73 show the version of spatch
74 --date show the date on which spatch was compiled
76 --shorthelp
78 see short list of options
79 --longhelp
81 see all the available options in different categories
82 -help, --help
84 show summary of options.
85
88 ./spatch --sp-file foo.cocci foo.c
89 Apply the semantic patch foo.cocci to the C file foo.c. The semantic
91 patch is applied modulo a set of isomorphisms contained in standard.iso
92 (standard.iso is by default located in /usr/lib64/coccinelle/stan‐
93 dard.iso). A patch showing the effect of the application, if any, will
94 be generated on the standard output.
95 ./spatch --sp-file foo.cocci foo.c -o /tmp/newfoo.c
97 The same as the above, except that a modified version of foo.c is
99 stored in /tmp/newfoo.c.
100 It is also possible to apply spatch to all of the C files in a direc‐
102 tory:
103 ./spatch --cocci-file foo.cocci --dir foodir
105 If the semantic patch is not working as expected, the option --debug
107 shows selection of information about the application of a semantic
108 patch to a file or directory.
109
112 MAIN OPTIONS
113 --sp-file
115 <file> the semantic patch file
116 -o <file> the output file
118 --in-place
120 do the modification on the file directly
121 --backup-suffix
123 suffix to use when making a backup for inplace
124 --out-place
126 store modifications in a .cocci_res file
127 --reverse
129 invert the semantic patch before applying it
130 -U set number of diff context lines
132 --partial-match
134 report partial matches of the SP on the C file
135 --iso-file
137 <file> (default=/usr/local/lib/coccinelle/standard.iso)
138 --macro-file
140 <file>
141 --macro-file-builtins
143 <file> (default=/usr/local/lib/coccinelle/standard.h)
144 --recursive-includes
146 causes all available include files, both those included in the C
147 file(s) and those included in header files, to be used
148 --all-includes
150 causes all available include files included in the C file(s) to
151 be used
152 --no-includes
154 causes not even local include files to be used
155 --local-includes
157 causes local include files to be used
158 --ignore-unknown-options
160 For integration in a toolchain (must be set before the first
161 unknown option)
162 --include-headers
164 process header files independently
165 -I <dir> containing the header files (optional)
167 --preprocess
169 run the C preprocessor before applying the semantic match
170 -c gcc/cpp compatibility mode
172 --dir <dir> process all files in directory recursively
174 --use-glimpse
176 works with --dir, use info generated by glimpseindex
177 --use-idutils
179 find relevant files using id-utils
180 --patch
182 <dir> path name with respect to which a patch should be created
183 "" for a file in the current directory
185 --kbuild-info
187 <file> improve --dir by grouping related c files
188 --pyoutput
190 Sets output routine: Standard values: <coccilib.output.Gtk|coc‐
191 cilib.output.Console>
192 --version
194 guess what
195 --date guess what
197 --shorthelp
199 see short list of options
200 --longhelp
202 see all the available options in different categories
203 ALIASES AND OBSOLETE OPTIONS
205 --sp command line semantic patch
207 --iso short option of --iso-file
209 --cocci-file
211 <file> the semantic patch file
212 MOST USEFUL SHOW OPTIONS
214 --show-diff
216 --no-show-diff
218 --force-diffshow
220 diff even if only spacing changes
221 --show-flow
223 --ctl-inline-let
225 --ctl-show-mcodekind
227 --show-bindings
229 --show-transinfo
231 --show-misc
233 --show-trying
235 show the name of each function being processed
236 --show-dependencies
238 show the dependencies related to each rule
239 VERBOSE SUBSYSTEMS OPTIONS
241 --verbose-ctl-engine
243 --verbose-match
245 --verbose-engine
247 --graphical-trace
249 generate a pdf file representing the matching process
250 --gt-without-label
252 remove graph label (requires option -graphical-trace)
253 --parse-error-msg
255 --verbose-parsing
257 --type-error-msg
259 OTHER SHOW OPTIONS
261 --show-c
263 --show-cocci
265 --show-before-fixed-flow
267 --show-ctl-tex
269 --show-ctl-text
271 --show-SP
273 DEBUG C PARSING/UNPARSING
275 --debug-cpp
277 --debug-lexer
279 --debug-etdt
281 --debug-typedef
283 --filter-msg
285 filter some cpp message when the macro is a "known" cpp con‐
286 struct
287 --filter-define-error
289 --filter-msg-define-error
291 filter the error msg
292 --filter-passed-level
294 --debug-unparsing
296 SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE
298 --quiet
300 --very-quiet
302 --debug
304 --pad
306 BENCH OPTIONS
308 --profile
310 gather timing information about the main coccinelle functions
311 --bench
313 <level> for profiling the CTL engine
314 --timeout
316 <sec> timeout in seconds
317 --steps
319 max number of model checking steps per code unit
320 --iso-limit
322 max depth of iso application
323 --no-iso-limit
325 disable limit on max depth of iso application
326 --track-iso
328 gather information about isomorphism usage
329 --disable-iso
331 disable a specific isomorphism
332 --profile-iso
334 gather information about the cost of isomorphism usage
335 CHANGE OF ALGORITHM OPTIONS
337 --keep-comments
339 keep comments around removed code
340 --loop
342 --no-loops
344 drop all back edges derived from looping constructs - unsafe
345 --no-gotos
347 drop all jumps derived from gotos - unsafe
348 --no-saved-typedefs
350 drop all inferred typedefs from one parse of some code to the
351 next
352 --ocaml-regexps
354 use OCaml Str regular expressions for constraints
355 --l1
357 --ifdef-to-if
359 convert ifdef to if (experimental)
360 --no-ifdef-to-if
362 convert ifdef to if (experimental)
363 --disable-multi-pass
365 --noif0-passing
367 --defined
369 --undefined
371 --noadd-typedef-root
373 --disallow-nested-exps
375 disallow an expression pattern from matching a term and its sub‐
376 term
377 --disable-worth-trying-opt
379 --only-return-is-error-exitif this flag is not set, then break and con‐
381 tinue are also error exits
382 --allow-inconsistent-paths
384 if this flag is set don't check for inconsistent paths; danger‐
385 ous
386 --no-safe-expressions
388 make an expression disjunction not prioritise the topmost dis‐
389 junct
390 --int-bits
392 the number of bits in an unsigned int
393 --long-bits
395 the number of bits in an unsigned long
396 --linux-spacing
398 spacing of + code follows the conventions of Linux
399 --smpl-spacing
401 spacing of + code follows the semantic patch
402 -D indicate that a virtual rule should be considered to be matched
404 --c++ make a small attempt to parse C++ files. The supported exten‐
406 sions for source files are .cpp, .cxx, .cc, and for header files
407 are .h, .hpp and .hxx. Note that this option disables the pro‐
408 cessing of .c files as Coccinelle behaviour is different for
409 C++.
410 MISC OPTIONS
412 --debugger
414 option to set if launch spatch in ocamldebug
415 --disable-once
417 to print more messages
418 --show-trace-profile
420 show trace
421 --save-tmp-files
423 CONCURRENCY
425 --index
427 the processor to use for this run of spatch
428 --max the number of processors available
430 --mod-distrib
432 use mod to distribute files among the processors
433 PAD OPTIONS
435 --use-cache
437 use .ast_raw pre-parsed cached C file
438 --cache-prefix
440 directory of cached ASTs, sets --use-cache
441 --cache-limit
443 maximum number of cached ASTs, sets --use-cache
444 TEST MODE AND TEST OPTIONS (WORKS WITH TESTS/ OR .OK FILES)
446 The test options don't work with the --sp-file and so on.
447 --test <file> launch spatch on tests/file.[c,cocci]
449 --testall
451 launch spatch on all files in tests/ having a .res
452 --test-okfailed
454 generates .{ok,failed,spatch_ok} files using .res files
455 --test-regression-okfailed
457 process the .{ok,failed,spatch_ok} files in current dir
458 --compare-with-expected
460 use also file.res
461 --expected-score-file
463 which score file to compare with in --testall
464 --no-update-score-file
466 do not update the score file when --testall succeeds
467 --relax-include-path
469 ACTION MODE
471 The action options don't work with the --sp-file and so on.
472 It's for the other (internal) uses of the spatch program.
473 --tokens-c
475 <file>
476 --parse-c
478 <file or dir>
479 --parse-h
481 <file or dir>
482 --parse-ch
484 <file or dir>
485 --parse-i
487 <file or dir>
488 --parse
490 <file or dir>
491 --show-flow
493 <file or file:function>
494 --control-flow
496 <file or file:function>
497 --control-flow-to-file
499 <file or file:function>
500 --test-cfg-ifdef
502 <file>
503 --parse-unparse
505 <file>
506 --type-c
508 <file>
509 --compare-c
511 <file1> <file2>
512 --comment-annotater-c
514 <file>
515 --compare-c-hardcoded
517 --test-attributes
519 <file>
520 --test-cpp
522 <file>
523 --extract-macros
525 <file or dir>
526 --extract-macros-select
528 <file or dir>
529 --xxx <file1> <>
531 --parse-cocci
533 <file>
534 --compare-c
536 <file1> <file2>
537
540 Coccinelle uses a simple text format to store customizations into in
541 which the configuration file is processed is as follows, where the
542 later lines always extend and may override earlier ones:
543 o Your current user's home directory is processed first
545 o Your directory from which spatch is called is processed next
546 o The directory provided with the --dir option is processed last, if
547 used
548 Such a configuration file may look like this:
550 [spatch]
552 options = --jobs 4
553 options = --show-trying
554
557 /usr/lib64/coccinelle/standard.iso
558 This file contains the default set of isomorphisms.
559 /usr/lib64/coccinelle/standard.h
560 This file contains the default set of macro hints.
561 .cocciconfig
562 This file contains the custom set of spatch options.
563
566 COCCINELLE_HOME
567 The path to the Coccinelle share directory. Default is
568 /usr/lib64/coccinelle
569
572 Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller. "Documenting and
573 Automating Collateral Evolutions in Linux Device Driver", EuroSys 2008
574 , Glasgow, Scotland, April 2008, pp. 247-260.
575 Julien Brunel, Damien Doligez, René Rydhof Hansen, Julia L. Lawall,
577 Gilles Muller. "A foundation for flow-based program matching: using
578 temporal logic and model checking", POPL 2009 , Savannah, GA, USA, Jan‐
579 uary 21-23, 2009, pp. 114-126.
580
583 spatch was written by Julia Lawall <julia.lawall@lip6.fr>, Yoann Padi‐
584 oleau <yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrh@cs.aau.dk>,
585 Henrik Stuart <henrik@hstuart.dk>, Nicolas Palix <nico‐
586 las.palix@imag.fr>, Peter Senna Tschudin <peter.senna@gmail.com>,
587 Sébastien Hinderer <Sebastien.Hinderer@inria.fr>, Xavier Clerc
588 <xavier.clerc@inria.fr> and Matthieu Caneill
589 <matthieu.caneill42@gmail.com>.
590 This manual page was written by Yoann Padioleau <yoann.padi‐
593 oleau@gmail.com>, Julia Lawall <julia.lawall@lip6.fr>, Nicolas Palix
594 <nicolas.palix@imag.fr> and Peter Senna Tschudin
595 <peter.senna@gmail.com>.
596
599 Send a mail to <cocci@systeme.lip6.fr>
600
603 Copyright 2012, 2015, INRIA and University of Grenoble-Alpes LIG.
604 Copyright 2010, 2011, University of Copenhagen DIKU and INRIA. Copy‐
605 right 2005-2009, Ecole des Mines de Nantes, University of Copenhagen.
606 spatch is free software: you can redistribute it and/or modify it under
607 the terms of the GNU General Public License as published by the Free
608 Software Foundation, according to version 2 of the License.
609
612 patch(1), diff(1)
613 Feb 26, 2015 SPATCH(1)