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> ] [ op‐
11 tions ]
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 https://coc‐
21 cinelle.gitlabpages.inria.fr/website/.
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 un‐
161 known 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: Default value: coccilib.output.Console
191 --version
193 guess what
194 --date guess what
196 --shorthelp
198 see short list of options
199 --longhelp
201 see all the available options in different categories
202 ALIASES AND OBSOLETE OPTIONS
204 --sp command line semantic patch
206 --iso short option of --iso-file
208 --cocci-file
210 <file> the semantic patch file
211 MOST USEFUL SHOW OPTIONS
213 --show-diff
215 --no-show-diff
217 --force-diff
219 show diff even if only spacing changes
220 --show-flow
222 --ctl-inline-let
224 --ctl-show-mcodekind
226 --show-bindings
228 --show-transinfo
230 --show-misc
232 --show-trying
234 show the name of each function being processed
235 --show-dependencies
237 show the dependencies related to each rule
238 VERBOSE SUBSYSTEMS OPTIONS
240 --verbose-ctl-engine
242 --verbose-match
244 --verbose-engine
246 --graphical-trace
248 generate a pdf file representing the matching process
249 --gt-without-label
251 remove graph label (requires option -graphical-trace)
252 --parse-error-msg
254 --verbose-parsing
256 --type-error-msg
258 OTHER SHOW OPTIONS
260 --show-c
262 --show-cocci
264 --show-before-fixed-flow
266 --show-ctl-tex
268 --show-ctl-text
270 --show-SP
272 DEBUG C PARSING/UNPARSING
274 --debug-cpp
276 --debug-lexer
278 --debug-etdt
280 --debug-typedef
282 --filter-msg
284 filter some cpp message when the macro is a "known" cpp con‐
285 struct
286 --filter-define-error
288 --filter-msg-define-error
290 filter the error msg
291 --filter-passed-level
293 --debug-unparsing
295 SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE
297 --quiet
299 --very-quiet
301 --debug
303 --pad
305 BENCH OPTIONS
307 --profile
309 gather timing information about the main coccinelle functions
310 --bench
312 <level> for profiling the CTL engine
313 --timeout
315 <sec> timeout in seconds
316 --steps
318 max number of model checking steps per code unit
319 --iso-limit
321 max depth of iso application
322 --no-iso-limit
324 disable limit on max depth of iso application
325 --track-iso
327 gather information about isomorphism usage
328 --disable-iso
330 disable a specific isomorphism
331 --profile-iso
333 gather information about the cost of isomorphism usage
334 CHANGE OF ALGORITHM OPTIONS
336 --keep-comments
338 keep comments around removed code
339 --loop
341 --no-loops
343 drop all back edges derived from looping constructs - unsafe
344 --no-gotos
346 drop all jumps derived from gotos - unsafe
347 --no-saved-typedefs
349 drop all inferred typedefs from one parse of some code to the
350 next
351 --ocaml-regexps
353 use OCaml Str regular expressions for constraints
354 --l1
356 --ifdef-to-if
358 convert ifdef to if (experimental)
359 --no-ifdef-to-if
361 convert ifdef to if (experimental)
362 --disable-multi-pass
364 --noif0-passing
366 --defined
368 --undefined
370 --noadd-typedef-root
372 --disallow-nested-exps
374 disallow an expression pattern from matching a term and its sub‐
375 term
376 --disable-worth-trying-opt
378 --only-return-is-error-exitif this flag is not set, then break and con‐
380 tinue are also error exits
381 --allow-inconsistent-paths
383 if this flag is set don't check for inconsistent paths; danger‐
384 ous
385 --no-safe-expressions
387 make an expression disjunction not prioritise the topmost dis‐
388 junct
389 --int-bits
391 the number of bits in an unsigned int
392 --long-bits
394 the number of bits in an unsigned long
395 --linux-spacing
397 spacing of + code follows the conventions of Linux
398 --smpl-spacing
400 spacing of + code follows the semantic patch
401 -D indicate that a virtual rule should be considered to be matched
403 --c++ make a small attempt to parse C++ files. The supported exten‐
405 sions for source files are .cpp, .cxx, .cc, and for header files
406 are .h, .hpp and .hxx. Note that this option disables the pro‐
407 cessing of .c files as Coccinelle behaviour is different for
408 C++.
409 MISC OPTIONS
411 --debugger
413 option to set if launch spatch in ocamldebug
414 --disable-once
416 to print more messages
417 --show-trace-profile
419 show trace
420 --save-tmp-files
422 CONCURRENCY
424 --index
426 the processor to use for this run of spatch
427 --max the number of processors available
429 --mod-distrib
431 use mod to distribute files among the processors
432 PAD OPTIONS
434 --use-cache
436 use .ast_raw pre-parsed cached C file
437 --cache-prefix
439 directory of cached ASTs, sets --use-cache
440 --cache-limit
442 maximum number of cached ASTs, sets --use-cache
443 TEST MODE AND TEST OPTIONS (WORKS WITH TESTS/ OR .OK FILES)
445 The test options don't work with the --sp-file and so on.
446 --test <file> launch spatch on tests/file.[c,cocci]
448 --testall
450 launch spatch on all files in tests/ having a .res
451 --test-okfailed
453 generates .{ok,failed,spatch_ok} files using .res files
454 --test-regression-okfailed
456 process the .{ok,failed,spatch_ok} files in current dir
457 --compare-with-expected
459 use also file.res
460 --expected-score-file
462 which score file to compare with in --testall
463 --no-update-score-file
465 do not update the score file when --testall succeeds
466 --relax-include-path
468 ACTION MODE
470 The action options don't work with the --sp-file and so on.
471 It's for the other (internal) uses of the spatch program.
472 --tokens-c
474 <file>
475 --parse-c
477 <file or dir>
478 --parse-h
480 <file or dir>
481 --parse-ch
483 <file or dir>
484 --parse-i
486 <file or dir>
487 --parse
489 <file or dir>
490 --show-flow
492 <file or file:function>
493 --control-flow
495 <file or file:function>
496 --control-flow-to-file
498 <file or file:function>
499 --test-cfg-ifdef
501 <file>
502 --parse-unparse
504 <file>
505 --type-c
507 <file>
508 --compare-c
510 <file1> <file2>
511 --comment-annotater-c
513 <file>
514 --compare-c-hardcoded
516 --test-attributes
518 <file>
519 --test-cpp
521 <file>
522 --extract-macros
524 <file or dir>
525 --extract-macros-select
527 <file or dir>
528 --xxx <file1> <>
530 --parse-cocci
532 <file>
533 --compare-c
535 <file1> <file2>
536
539 Coccinelle uses a simple text format to store customizations into in
540 which the configuration file is processed is as follows, where the
541 later lines always extend and may override earlier ones:
542 o Your current user's home directory is processed first
544 o Your directory from which spatch is called is processed next
545 o The directory provided with the --dir option is processed last, if
546 used
547 Such a configuration file may look like this:
549 [spatch]
551 options = --jobs 4
552 options = --show-trying
553
556 /usr/lib64/coccinelle/standard.iso
557 This file contains the default set of isomorphisms.
558 /usr/lib64/coccinelle/standard.h
559 This file contains the default set of macro hints.
560 .cocciconfig
561 This file contains the custom set of spatch options.
562
565 COCCINELLE_HOME
566 The path to the Coccinelle share directory. Default is
567 /usr/lib64/coccinelle
568
571 Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller. "Documenting and Au‐
572 tomating Collateral Evolutions in Linux Device Driver", EuroSys 2008 ,
573 Glasgow, Scotland, April 2008, pp. 247-260.
574 Julien Brunel, Damien Doligez, René Rydhof Hansen, Julia L. Lawall,
576 Gilles Muller. "A foundation for flow-based program matching: using
577 temporal logic and model checking", POPL 2009 , Savannah, GA, USA, Jan‐
578 uary 21-23, 2009, pp. 114-126.
579
582 spatch was written by Julia Lawall <julia.lawall@lip6.fr>, Yoann Padi‐
583 oleau <yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrh@cs.aau.dk>,
584 Henrik Stuart <henrik@hstuart.dk>, Nicolas Palix <nico‐
585 las.palix@imag.fr>, Peter Senna Tschudin <peter.senna@gmail.com>,
586 Sébastien Hinderer <Sebastien.Hinderer@inria.fr>, Xavier Clerc
587 <xavier.clerc@inria.fr> and Matthieu Caneill
588 <matthieu.caneill42@gmail.com>.
589 This manual page was written by Yoann Padioleau <yoann.padi‐
592 oleau@gmail.com>, Julia Lawall <julia.lawall@lip6.fr>, Nicolas Palix
593 <nicolas.palix@imag.fr> and Peter Senna Tschudin <pe‐
594 ter.senna@gmail.com>.
595
598 Send a mail to <cocci@systeme.lip6.fr>
599
602 Copyright 2012, 2015, INRIA and University of Grenoble-Alpes LIG.
603 Copyright 2010, 2011, University of Copenhagen DIKU and INRIA. Copy‐
604 right 2005-2009, Ecole des Mines de Nantes, University of Copenhagen.
605 spatch is free software: you can redistribute it and/or modify it under
606 the terms of the GNU General Public License as published by the Free
607 Software Foundation, according to version 2 of the License.
608
611 patch(1), diff(1)
612 Feb 26, 2015 SPATCH(1)