1SPATCH(1)                   General Commands Manual                  SPATCH(1)
2
3
4

NAME

6       spatch - apply a semantic patch file to a set of C files
7
8

SYNOPSIS

10       spatch --sp-file <SP> <files> [-o <outfile> ] [--iso-file <iso> ] [ op‐
11       tions ]
12

DESCRIPTION

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
19
20       Further   information   about   spatch  is  available  at  https://coc
21       cinelle.gitlabpages.inria.fr/website/.
22
23       Semantic patch examples can be found at  http://coccinellery.org/,  and
24       at the scripts/coccinelle directory of the Linux Kernel source code.
25
26

OPTIONS

28       Here is a summary of the most commonly used options (also see the "Con‐
29       figuration Mechanism" section below):
30
31
32       --sp-file <file>
33              the semantic patch file
34
35       --dir <dir>
36              process all files in directory recursively
37
38       --iso-file <file>
39              (default=/usr/lib64/coccinelle/standard.iso)
40
41       --macro-file <file>
42              (default=/usr/lib64/coccinelle/standard.h)
43
44       --debug
45              print some information to help debug the matching process
46
47       --all-includes
48              causes all available include files to be used
49
50       --no-includes
51              causes not even local include files to be used
52
53       -I <dir>
54              the directory containing the include files
55
56       --include-headers
57              process header files independently
58
59       --use-glimpse
60              works with --dir, use information generated by glimpseindex
61
62       -o <file>
63              the output file. If none is specified, a patch is  generated  on
64              the standard output
65
66       --in-place
67              do the modification on the file directly
68
69       --out-place
70              store modifications in a .cocci_res file
71
72       --version
73              show the version of spatch
74
75       --date show the date on which spatch was compiled
76
77       --shorthelp
78              see short list of options
79
80       --longhelp
81              see all the available options in different categories
82
83       -help, --help
84              show summary of options.
85
86

EXAMPLES

88         ./spatch --sp-file foo.cocci foo.c
89
90       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
96         ./spatch --sp-file foo.cocci foo.c -o /tmp/newfoo.c
97
98       The  same  as  the  above,  except  that a modified version of foo.c is
99       stored in /tmp/newfoo.c.
100
101       It is also possible to apply spatch to all of the C files in  a  direc‐
102       tory:
103
104         ./spatch --cocci-file foo.cocci --dir foodir
105
106       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
110

MORE OPTIONS

112       MAIN OPTIONS
113
114       --sp-file
115              <file> the semantic patch file
116
117       -o     <file> the output file
118
119       --in-place
120              do the modification on the file directly
121
122       --backup-suffix
123              suffix to use when making a backup for inplace
124
125       --out-place
126              store modifications in a .cocci_res file
127
128       --reverse
129              invert the semantic patch before applying it
130
131       -U     set number of diff context lines
132
133       --partial-match
134              report partial matches of the SP on the C file
135
136       --iso-file
137              <file> (default=/usr/local/lib/coccinelle/standard.iso)
138
139       --macro-file
140              <file>
141
142       --macro-file-builtins
143              <file> (default=/usr/local/lib/coccinelle/standard.h)
144
145       --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
149       --all-includes
150              causes all available include files included in the C file(s)  to
151              be used
152
153       --no-includes
154              causes not even local include files to be used
155
156       --local-includes
157              causes local include files to be used
158
159       --ignore-unknown-options
160              For integration in a toolchain (must be set before the first un‐
161              known option)
162
163       --include-headers
164              process header files independently
165
166       -I     <dir> containing the header files (optional)
167
168       --preprocess
169              run the C preprocessor before applying the semantic match
170
171       -c     gcc/cpp compatibility mode
172
173       --dir  <dir> process all files in directory recursively
174
175       --use-glimpse
176              works with --dir, use info generated by glimpseindex
177
178       --use-idutils
179              find relevant files using id-utils
180
181       --patch
182              <dir> path name with respect to which a patch should be created
183
184              "" for a file in the current directory
185
186       --kbuild-info
187              <file> improve --dir by grouping related c files
188
189       --pyoutput
190              Sets output routine: Default value: coccilib.output.Console
191
192       --version
193              guess what
194
195       --date guess what
196
197       --shorthelp
198              see short list of options
199
200       --longhelp
201              see all the available options in different categories
202
203       ALIASES AND OBSOLETE OPTIONS
204
205       --sp   command line semantic patch
206
207       --iso  short option of --iso-file
208
209       --cocci-file
210              <file> the semantic patch file
211
212       MOST USEFUL SHOW OPTIONS
213
214       --show-diff
215
216       --no-show-diff
217
218       --force-diff
219              show diff even if only spacing changes
220
221       --show-flow
222
223       --ctl-inline-let
224
225       --ctl-show-mcodekind
226
227       --show-bindings
228
229       --show-transinfo
230
231       --show-misc
232
233       --show-trying
234              show the name of each function being processed
235
236       --show-dependencies
237              show the dependencies related to each rule
238
239       VERBOSE SUBSYSTEMS OPTIONS
240
241       --verbose-ctl-engine
242
243       --verbose-match
244
245       --verbose-engine
246
247       --graphical-trace
248              generate a pdf file representing the matching process
249
250       --gt-without-label
251              remove graph label (requires option -graphical-trace)
252
253       --parse-error-msg
254
255       --verbose-parsing
256
257       --type-error-msg
258
259       OTHER SHOW OPTIONS
260
261       --show-c
262
263       --show-cocci
264
265       --show-before-fixed-flow
266
267       --show-ctl-tex
268
269       --show-ctl-text
270
271       --show-SP
272
273       DEBUG C PARSING/UNPARSING
274
275       --debug-cpp
276
277       --debug-lexer
278
279       --debug-etdt
280
281       --debug-typedef
282
283       --filter-msg
284              filter some cpp message when the macro is  a  "known"  cpp  con‐
285              struct
286
287       --filter-define-error
288
289       --filter-msg-define-error
290              filter the error msg
291
292       --filter-passed-level
293
294       --debug-unparsing
295
296       SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE
297
298       --quiet
299
300       --very-quiet
301
302       --debug
303
304       --pad
305
306       BENCH OPTIONS
307
308       --profile
309              gather timing information about the main coccinelle functions
310
311       --bench
312              <level> for profiling the CTL engine
313
314       --timeout
315              <sec> timeout in seconds
316
317       --steps
318              max number of model checking steps per code unit
319
320       --iso-limit
321              max depth of iso application
322
323       --no-iso-limit
324              disable limit on max depth of iso application
325
326       --track-iso
327              gather information about isomorphism usage
328
329       --disable-iso
330              disable a specific isomorphism
331
332       --profile-iso
333              gather information about the cost of isomorphism usage
334
335       CHANGE OF ALGORITHM OPTIONS
336
337       --keep-comments
338              keep comments around removed code
339
340       --loop
341
342       --no-loops
343              drop all back edges derived from looping constructs - unsafe
344
345       --no-gotos
346              drop all jumps derived from gotos - unsafe
347
348       --no-saved-typedefs
349              drop  all  inferred  typedefs from one parse of some code to the
350              next
351
352       --ocaml-regexps
353              use OCaml Str regular expressions for constraints
354
355       --l1
356
357       --ifdef-to-if
358              convert ifdef to if (experimental)
359
360       --no-ifdef-to-if
361              convert ifdef to if (experimental)
362
363       --disable-multi-pass
364
365       --noif0-passing
366
367       --defined
368
369       --undefined
370
371       --noadd-typedef-root
372
373       --disallow-nested-exps
374              disallow an expression pattern from matching a term and its sub‐
375              term
376
377       --disable-worth-trying-opt
378
379       --only-return-is-error-exitif this flag is not set, then break and con‐
380              tinue are also error exits
381
382       --allow-inconsistent-paths
383              if this flag is set don't check for inconsistent paths;  danger‐
384              ous
385
386       --no-safe-expressions
387              make  an  expression disjunction not prioritise the topmost dis‐
388              junct
389
390       --int-bits
391              the number of bits in an unsigned int
392
393       --long-bits
394              the number of bits in an unsigned long
395
396       --linux-spacing
397              spacing of + code follows the conventions of Linux
398
399       --smpl-spacing
400              spacing of + code follows the semantic patch
401
402       -D     indicate that a virtual rule should be considered to be matched
403
404       --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
410       MISC OPTIONS
411
412       --debugger
413              option to set if launch spatch in ocamldebug
414
415       --disable-once
416              to print more messages
417
418       --show-trace-profile
419              show trace
420
421       --save-tmp-files
422
423       CONCURRENCY
424
425       --index
426              the processor to use for this run of spatch
427
428       --max  the number of processors available
429
430       --mod-distrib
431              use mod to distribute files among the processors
432
433       PAD OPTIONS
434
435       --use-cache
436              use .ast_raw pre-parsed cached C file
437
438       --cache-prefix
439              directory of cached ASTs, sets --use-cache
440
441       --cache-limit
442              maximum number of cached ASTs, sets --use-cache
443
444       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
447       --test <file> launch spatch on tests/file.[c,cocci]
448
449       --testall
450              launch spatch on all files in tests/ having a .res
451
452       --test-okfailed
453              generates .{ok,failed,spatch_ok} files using .res files
454
455       --test-regression-okfailed
456              process the .{ok,failed,spatch_ok} files in current dir
457
458       --compare-with-expected
459              use also file.res
460
461       --expected-score-file
462              which score file to compare with in --testall
463
464       --no-update-score-file
465              do not update the score file when --testall succeeds
466
467       --relax-include-path
468
469       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
473       --tokens-c
474              <file>
475
476       --parse-c
477              <file or dir>
478
479       --parse-h
480              <file or dir>
481
482       --parse-ch
483              <file or dir>
484
485       --parse-i
486              <file or dir>
487
488       --parse
489              <file or dir>
490
491       --show-flow
492              <file or file:function>
493
494       --control-flow
495              <file or file:function>
496
497       --control-flow-to-file
498              <file or file:function>
499
500       --test-cfg-ifdef
501              <file>
502
503       --parse-unparse
504              <file>
505
506       --type-c
507              <file>
508
509       --compare-c
510              <file1> <file2>
511
512       --comment-annotater-c
513              <file>
514
515       --compare-c-hardcoded
516
517       --test-attributes
518              <file>
519
520       --test-cpp
521              <file>
522
523       --extract-macros
524              <file or dir>
525
526       --extract-macros-select
527              <file or dir>
528
529       --xxx  <file1> <>
530
531       --parse-cocci
532              <file>
533
534       --compare-c
535              <file1> <file2>
536
537

CONFIGURATION MECHANISM

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
543         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
548       Such a configuration file may look like this:
549
550           [spatch]
551                options = --jobs 4
552                options = --show-trying
553
554

FILES

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
563

ENVIRONMENT

565       COCCINELLE_HOME
566              The  path  to  the  Coccinelle  share  directory.   Default   is
567              /usr/lib64/coccinelle
568
569

REFERENCES

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

AUTHOR

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
590
591       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
596

REPORTING BUGS

598       Send a mail to <cocci@systeme.lip6.fr>
599
600
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
609

SEE ALSO

611       patch(1), diff(1)
612
613
614
615                                 Feb 26, 2015                        SPATCH(1)
Impressum