docs/spatch.1.in

   1 .\"  -*- nroff -*-
   2 .\" Please adjust this date whenever revising the manpage.
   3 .TH SPATCH 1 "aug 02, 2012"
   4
   5 .\" see http://www.fnal.gov/docs/products/ups/ReferenceManual/html/manpages.html
   6 .\" see http://www.linuxjournal.com/article/1158
   7 .\" see http://www.schweikhardt.net/man_page_howto.html
   8 .\" groff -Tascii -man ./spatch.1 | more
   9 .\"
  10 .\" Some roff macros, for reference:
  11 .\" .nh        disable hyphenation
  12 .\" .hy        enable hyphenation
  13 .\" .ad l      left justify
  14 .\" .ad b      justify to both left and right margins
  15 .\" .nf        disable filling
  16 .\" .fi        enable filling
  17 .\" .br        insert line break
  18 .\" .sp <n>    insert n+1 empty lines
  19 .\" for manpage-specific macros, see man(7)
  20 .\"
  21 .\" TeX users may be more comfortable with the \fB<whatever>\fP and
  22 .\" \fI<whatever>\fP escape sequences to invode bold face and italics,
  23 .\" respectively. Also \fR for roman.
  24 .\" pad: src: deputy man page
  25 .SH NAME
  26 spatch \- apply a semantic patch file to a set of C files
  27
  28 .SH SYNOPSIS
  29 .B spatch
  30 .B -sp_file
  31 .I <SP>
  32 .I <files>
  33 .B [-o
  34 .I <outfile>
  35 .B ]
  36 .B [-iso_file
  37 .I <iso>
  38 .B ]
  39 .B [
  40 .I options
  41 .B ]
  42 .\"
  43 .SH DESCRIPTION
  44 \fBspatch\fP is a program matching and transformation tool for C.
  45 The programmer describes the code to match and the transformation to
  46 perform as a semantic patch, which looks like a standard patch, but can
  47 transform multiple files at any number of code sites.
  48
  49 .PP
  50 Further information about spatch is available at
  51 \fBhttp://coccinelle.lip6.fr/\fP.
  52
  53 .SH OPTIONS
  54 Here is a summary of the most commonly used options:
  55
  56 .TP
  57 .B -sp_file \fI<file>\fP
  58 the semantic patch file
  59 .TP
  60 .B -dir                 \fI<dir>\fP
  61 process all files in directory recursively
  62 .TP
  63 .B -iso_file            \fI<file>\fP
  64 (default=@SHAREDIR@/standard.iso)
  65 .TP
  66 .B -macro_file          \fI<file>\fP
  67 (default=@SHAREDIR@/standard.h)
  68 .TP
  69 .B -debug
  70 print some information to help debug the matching process
  71 .TP
  72 .B -all_includes
  73 causes all available include files to be used
  74 .TP
  75 .B -no_includes
  76 causes not even local include files to be used
  77 .TP
  78 .B -I                   \fI<dir>\fP
  79 the directory containing the include files
  80 .TP
  81 .B -include_headers
  82 process header files independently
  83 .TP
  84 .B -use_glimpse
  85 works with -dir, use information generated by glimpseindex
  86 .TP
  87 .B -o                   \fI<file>\fP
  88 the output file. If none is specified, a patch is generated on the standard
  89 output
  90 .TP
  91 .B -in_place
  92 do the modification on the file directly
  93 .TP
  94 .B -out_place
  95 store modifications in a .cocci_res file
  96 .TP
  97 .B -version
  98 show the version of spatch
  99 .TP
 100 .B -date
 101 show the date on which spatch was compiled
 102 .TP
 103 .B -shorthelp
 104 see short list of options
 105 .TP
 106 .B -longhelp
 107 see all the available options in different categories
 108 .TP
 109 .B \-help, \-\-help
 110 show summary of options.
 111
 112 .SH EXAMPLES
 113
 114   ./spatch -sp_file foo.cocci foo.c
 115
 116 Apply the semantic patch foo.cocci to the C file foo.c.  The semantic patch
 117 is applied modulo a set of isomorphisms contained in standard.iso
 118 (standard.iso is by default located in
 119 @SHAREDIR@/standard.iso).  A patch showing the effect of
 120 the application, if any, will be generated on the standard output.
 121
 122   ./spatch -sp_file foo.cocci foo.c -o /tmp/newfoo.c
 123
 124 The same as the above, except that a modified version of foo.c is stored in
 125 /tmp/newfoo.c.
 126
 127 It is also possible to apply spatch to all of the C files in
 128 a directory:
 129
 130   ./spatch -cocci_file foo.cocci -dir foodir
 131
 132 If the semantic patch is not working as expected, the option -debug
 133 shows selection of information about the application of
 134 a semantic patch to a file or directory.
 135
 136 .SH MORE OPTIONS
 137 .IP "MAIN OPTIONS"
 138 .TP
 139 \fB\-\-sp\-file\fR
 140 <file> the semantic patch file
 141 .TP
 142 \fB\-o\fR
 143 <file> the output file
 144 .TP
 145 \fB\-\-in\-place\fR
 146 do the modification on the file directly
 147 .TP
 148 \fB\-\-backup\-suffix\fR
 149 suffix to use when making a backup for inplace
 150 .TP
 151 \fB\-\-out\-place\fR
 152 store modifications in a .cocci_res file
 153 .TP
 154 \fB\-\-reverse\fR
 155 invert the semantic patch before applying it
 156 .TP
 157 \fB\-U\fR
 158 set number of diff context lines
 159 .TP
 160 \fB\-\-partial\-match\fR
 161 report partial matches of the SP on the C file
 162 .TP
 163 \fB\-\-iso\-file\fR
 164 <file> (default=/usr/local/share/coccinelle/standard.iso)
 165 .TP
 166 \fB\-\-macro\-file\fR
 167 <file>
 168 .TP
 169 \fB\-\-macro\-file\-builtins\fR
 170 <file> (default=/usr/local/share/coccinelle/standard.h)
 171 .TP
 172 \fB\-\-recursive\-includes\fR
 173 causes all available include files, both those included in the C file(s) and those included in header files, to be used
 174 .TP
 175 \fB\-\-all\-includes\fR
 176 causes all available include files included in the C file(s) to be used
 177 .TP
 178 \fB\-\-no\-includes\fR
 179 causes not even local include files to be used
 180 .TP
 181 \fB\-\-local\-includes\fR
 182 causes local include files to be used
 183 .TP
 184 \fB\-\-ignore\-unknown\-options\fR
 185 For integration in a toolchain (must be set before the first unknown option)
 186 .TP
 187 \fB\-\-include\-headers\fR
 188 process header files independently
 189 .TP
 190 \fB\-I\fR
 191 <dir> containing the header files (optional)
 192 .TP
 193 \fB\-\-preprocess\fR
 194 run the C preprocessor before applying the semantic match
 195 .TP
 196 \fB\-c\fR
 197 gcc/cpp compatibility mode
 198 .TP
 199 \fB\-\-dir\fR
 200 <dir> process all files in directory recursively
 201 .TP
 202 \fB\-\-use\-glimpse\fR
 203 works with \fB\-dir\fR, use info generated by glimpseindex
 204 .TP
 205 \fB\-\-use\-google\fR
 206 find relevant files using google code search
 207 .TP
 208 \fB\-\-use\-idutils\fR
 209 find relevant files using id\-utils
 210 .TP
 211 \fB\-\-patch\fR
 212 <dir> path name with respect to which a patch should be created
 213 .IP
 214 "" for a file in the current directory
 215 .TP
 216 \fB\-\-kbuild\-info\fR
 217 <file> improve \fB\-dir\fR by grouping related c files
 218 .TP
 219 \fB\-\-pyoutput\fR
 220 Sets output routine: Standard values: <coccilib.output.Gtk|coccilib.output.Console>
 221 .TP
 222 \fB\-\-version\fR
 223 guess what
 224 .TP
 225 \fB\-\-date\fR
 226 guess what
 227 .TP
 228 \fB\-\-shorthelp\fR
 229 see short list of options
 230 .TP
 231 \fB\-\-longhelp\fR
 232 see all the available options in different categories
 233 .PP
 234 .IP "ALIASES AND OBSOLETE OPTIONS"
 235 .TP
 236 \fB\-\-sp\fR
 237 command line semantic patch
 238 .TP
 239 \fB\-\-iso\fR
 240 short option of \fB\-\-iso\-file\fR
 241 .TP
 242 \fB\-\-cocci\-file\fR
 243 <file> the semantic patch file
 244 .PP
 245 .IP "MOST USEFUL SHOW OPTIONS"
 246 .HP
 247 \fB\-\-show\-diff\fR
 248 .HP
 249 \fB\-\-no\-show\-diff\fR
 250 .TP
 251 \fB\-\-force\-diffshow\fR
 252 diff even if only spacing changes
 253 .HP
 254 \fB\-\-show\-flow\fR
 255 .HP
 256 \fB\-\-ctl\-inline\-let\fR
 257 .HP
 258 \fB\-\-ctl\-show\-mcodekind\fR
 259 .HP
 260 \fB\-\-show\-bindings\fR
 261 .HP
 262 \fB\-\-show\-transinfo\fR
 263 .HP
 264 \fB\-\-show\-misc\fR
 265 .TP
 266 \fB\-\-show\-trying\fR
 267 show the name of each function being processed
 268 .TP
 269 \fB\-\-show\-dependencies\fR
 270 show the dependencies related to each rule
 271 .PP
 272 .IP "VERBOSE SUBSYSTEMS OPTIONS"
 273 .HP
 274 \fB\-\-verbose\-ctl\-engine\fR
 275 .HP
 276 \fB\-\-verbose\-match\fR
 277 .HP
 278 \fB\-\-verbose\-engine\fR
 279 .TP
 280 \fB\-\-graphical\-trace\fR
 281 generate a pdf file representing the matching process
 282 .TP
 283 \fB\-\-gt\-without\-label\fR
 284 remove graph label (requires option \fB\-graphical\-trace\fR)
 285 .HP
 286 \fB\-\-parse\-error\-msg\fR
 287 .HP
 288 \fB\-\-verbose\-parsing\fR
 289 .HP
 290 \fB\-\-type\-error\-msg\fR
 291 .PP
 292 .IP "OTHER SHOW OPTIONS"
 293 .HP
 294 \fB\-\-show\-c\fR
 295 .HP
 296 \fB\-\-show\-cocci\fR
 297 .HP
 298 \fB\-\-show\-before\-fixed\-flow\fR
 299 .HP
 300 \fB\-\-show\-ctl\-tex\fR
 301 .HP
 302 \fB\-\-show\-ctl\-text\fR
 303 .HP
 304 \fB\-\-show\-SP\fR
 305 .PP
 306 .IP "DEBUG C PARSING/UNPARSING"
 307 .HP
 308 \fB\-\-debug\-cpp\fR
 309 .HP
 310 \fB\-\-debug\-lexer\fR
 311 .HP
 312 \fB\-\-debug\-etdt\fR
 313 .HP
 314 \fB\-\-debug\-typedef\fR
 315 .TP
 316 \fB\-\-filter\-msg\fR
 317 filter some cpp message when the macro is a "known" cpp construct
 318 .HP
 319 \fB\-\-filter\-define\-error\fR
 320 .TP
 321 \fB\-\-filter\-msg\-define\-error\fR
 322 filter the error msg
 323 .HP
 324 \fB\-\-filter\-passed\-level\fR
 325 .HP
 326 \fB\-\-debug\-unparsing\fR
 327 .PP
 328 .IP "SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE"
 329 .HP
 330 \fB\-\-quiet\fR
 331 .HP
 332 \fB\-\-very\-quiet\fR
 333 .HP
 334 \fB\-\-debug\fR
 335 .HP
 336 \fB\-\-pad\fR
 337 .PP
 338 .IP "BENCH OPTIONS"
 339 .TP
 340 \fB\-\-profile\fR
 341 gather timing information about the main coccinelle functions
 342 .TP
 343 \fB\-\-bench\fR
 344 <level> for profiling the CTL engine
 345 .TP
 346 \fB\-\-timeout\fR
 347 <sec> timeout in seconds
 348 .TP
 349 \fB\-\-steps\fR
 350 max number of model checking steps per code unit
 351 .TP
 352 \fB\-\-iso\-limit\fR
 353 max depth of iso application
 354 .TP
 355 \fB\-\-no\-iso\-limit\fR
 356 disable limit on max depth of iso application
 357 .TP
 358 \fB\-\-track\-iso\fR
 359 gather information about isomorphism usage
 360 .TP
 361 \fB\-\-disable\-iso\fR
 362 disable a specific isomorphism
 363 .TP
 364 \fB\-\-profile\-iso\fR
 365 gather information about the cost of isomorphism usage
 366 .PP
 367 .IP "CHANGE OF ALGORITHM OPTIONS"
 368 .TP
 369 \fB\-\-keep\-comments\fR
 370 keep comments around removed code
 371 .HP
 372 \fB\-\-loop\fR
 373 .TP
 374 \fB\-\-no\-loops\fR
 375 drop all back edges derived from looping constructs \- unsafe
 376 .TP
 377 \fB\-\-no\-gotos\fR
 378 drop all jumps derived from gotos \- unsafe
 379 .TP
 380 \fB\-\-no\-saved\-typedefs\fR
 381 drop all inferred typedefs from one parse of some code to the next
 382 .TP
 383 \fB\-\-ocaml\-regexps\fR
 384 use OCaml Str regular expressions for constraints
 385 .HP
 386 \fB\-\-l1\fR
 387 .TP
 388 \fB\-\-ifdef\-to\-if\fR
 389 convert ifdef to if (experimental)
 390 .TP
 391 \fB\-\-no\-ifdef\-to\-if\fR
 392 convert ifdef to if (experimental)
 393 .HP
 394 \fB\-\-disable\-multi\-pass\fR
 395 .HP
 396 \fB\-\-noif0\-passing\fR
 397 .HP
 398 \fB\-\-defined\fR
 399 .HP
 400 \fB\-\-undefined\fR
 401 .HP
 402 \fB\-\-noadd\-typedef\-root\fR
 403 .TP
 404 \fB\-\-disallow\-nested\-exps\fR
 405 disallow an expresion pattern from matching a term and its subterm
 406 .HP
 407 \fB\-\-disable\-worth\-trying\-opt\fR
 408 .HP
 409 \fB\-\-only\-return\-is\-error\-exitif\fR this flag is not set, then break and continue are also error exits
 410 .TP
 411 \fB\-\-allow\-inconsistent\-paths\fR
 412 if this flag is set don't check for inconsistent paths; dangerous
 413 .TP
 414 \fB\-\-no\-safe\-expressions\fR
 415 make an expression disjunction not prioritise the topmost disjunct
 416 .TP
 417 \fB\-\-int\-bits\fR
 418 the number of bits in an unsigned int
 419 .TP
 420 \fB\-\-long\-bits\fR
 421 the number of bits in an unsigned long
 422 .TP
 423 \fB\-\-linux\-spacing\fR
 424 spacing of + code follows the conventions of Linux
 425 .TP
 426 \fB\-\-smpl\-spacing\fR
 427 spacing of + code follows the semantic patch
 428 .TP
 429 \fB\-D\fR
 430 indicate that a virtual rule should be considered to be matched
 431 .TP
 432 \fB\-\-c\fR++
 433 make a small attempt to parse C++ files
 434 .PP
 435 .IP "MISC OPTIONS"
 436 .TP
 437 \fB\-\-debugger\fR
 438 option to set if launch spatch in ocamldebug
 439 .TP
 440 \fB\-\-disable\-once\fR
 441 to print more messages
 442 .TP
 443 \fB\-\-show\-trace\-profile\fR
 444 show trace
 445 .HP
 446 \fB\-\-save\-tmp\-files\fR
 447 .PP
 448 .IP "CONCURRENCY"
 449 .TP
 450 \fB\-\-index\fR
 451 the processor to use for this run of spatch
 452 .TP
 453 \fB\-\-max\fR
 454 the number of processors available
 455 .TP
 456 \fB\-\-mod\-distrib\fR
 457 use mod to distribute files among the processors
 458 .PP
 459 .IP "PAD OPTIONS"
 460 .TP
 461 \fB\-\-use\-cache\fR
 462 use .ast_raw pre\-parsed cached C file
 463 .TP
 464 \fB\-\-cache\-prefix\fR
 465 directory of cached ASTs, sets \fB\-use\-cache\fR
 466 .TP
 467 \fB\-\-cache\-limit\fR
 468 maximum number of cached ASTs, sets \fB\-use\-cache\fR
 469 .PP
 470 .IP "TEST MODE AND TEST OPTIONS (WORKS WITH TESTS/ OR .OK FILES)"
 471 The test options don't work with the \fB\-\-sp\-file\fR and so on.
 472 .TP
 473 \fB\-\-test\fR
 474 <file> launch spatch on tests/file.[c,cocci]
 475 .TP
 476 \fB\-\-testall\fR
 477 launch spatch on all files in tests/ having a .res
 478 .TP
 479 \fB\-\-test\-okfailed\fR
 480 generates .{ok,failed,spatch_ok} files using .res files
 481 .TP
 482 \fB\-\-test\-regression\-okfailed\fR
 483 process the .{ok,failed,spatch_ok} files in current dir
 484 .TP
 485 \fB\-\-compare\-with\-expected\fR
 486 use also file.res
 487 .TP
 488 \fB\-\-expected\-score\-file\fR
 489 which score file to compare with in \fB\-testall\fR
 490 .TP
 491 \fB\-\-no\-update\-score\-file\fR
 492 do not update the score file when \fB\-testall\fR succeeds
 493 .HP
 494 \fB\-\-relax\-include\-path\fR
 495 .PP
 496 .IP "ACTION MODE"
 497 The action options don't work with the \fB\-\-sp\-file\fR and so on.
 498 It's for the other (internal) uses of the spatch program.
 499 .TP
 500 \fB\-\-tokens\-c\fR
 501 <file>
 502 .TP
 503 \fB\-\-parse\-c\fR
 504 <file or dir>
 505 .TP
 506 \fB\-\-parse\-h\fR
 507 <file or dir>
 508 .TP
 509 \fB\-\-parse\-ch\fR
 510 <file or dir>
 511 .TP
 512 \fB\-\-parse\-i\fR
 513 <file or dir>
 514 .TP
 515 \fB\-\-parse\fR
 516 <file or dir>
 517 .TP
 518 \fB\-\-show\-flow\fR
 519 <file or file:function>
 520 .TP
 521 \fB\-\-control\-flow\fR
 522 <file or file:function>
 523 .TP
 524 \fB\-\-control\-flow\-to\-file\fR
 525 <file or file:function>
 526 .TP
 527 \fB\-\-test\-cfg\-ifdef\fR
 528 <file>
 529 .TP
 530 \fB\-\-parse\-unparse\fR
 531 <file>
 532 .TP
 533 \fB\-\-type\-c\fR
 534 <file>
 535 .TP
 536 \fB\-\-compare\-c\fR
 537 <file1> <file2>
 538 .TP
 539 \fB\-\-comment\-annotater\-c\fR
 540 <file>
 541 .HP
 542 \fB\-\-compare\-c\-hardcoded\fR
 543 .TP
 544 \fB\-\-test\-attributes\fR
 545 <file>
 546 .TP
 547 \fB\-\-test\-cpp\fR
 548 <file>
 549 .TP
 550 \fB\-\-extract\-macros\fR
 551 <file or dir>
 552 .TP
 553 \fB\-\-extract\-macros\-select\fR
 554 <file or dir>
 555 .TP
 556 \fB\-\-xxx\fR
 557 <file1> <>
 558 .TP
 559 \fB\-\-parse\-cocci\fR
 560 <file>
 561 .TP
 562 \fB\-\-compare\-c\fR
 563 <file1> <file2>
 564
 565 .SH FILES
 566 .I @SHAREDIR@/standard.iso
 567 .RS
 568 This file contains the default set of isomorphisms.
 569 .RE
 570 .I @SHAREDIR@/standard.h
 571 .RS
 572 This file contains the default set of macro hints.
 573
 574 .SH ENVIRONMENT
 575 .IP COCCINELLE_HOME
 576 The path to the Coccinelle share directory. Default is
 577 .I @SHAREDIR@
 578
 579 .SH REFERENCES
 580 Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller
 581 "Documenting and Automating Collateral Evolutions in Linux Device Driver"
 582 .I EuroSys 2008,
 583 Glasgow, Scotland (April 2008) pp. 247-260.
 584
 585 .SH AUTHOR
 586 \fBspatch\fP was written by Julia Lawall <julia@diku.dk>, Yoann Padioleau
 587 <yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrhansen@diku.dk> and
 588 Henrik Stuart <henrik@hstuart.dk>.
 589 .PP
 590 This manual page was written by Yoann Padioleau <yoann.padioleau@gmail.com>
 591 and Julia Lawall <julia@diku.dk>.
 592
 593 .SH REPORTING BUGS
 594 Send a mail to <cocci@diku.dk>
 595
 596 .SH COPYRIGHT
 597 Copyright 2010, 2011, University of Copenhagen DIKU and INRIA.
 598 Copyright 2005-2009, Ecole des Mines de Nantes, University of Copenhagen.
 599 spatch is free software: you can redistribute it and/or modify
 600 it under the terms of the GNU General Public License as published by
 601 the Free Software Foundation, according to version 2 of the License.
 602
 603 .SH SEE ALSO
 604 \fIpatch\fP(1), \fIdiff\fP(1)
 605