2 %\section{The SmPL Grammar}
4 % This section presents the SmPL grammar. This definition follows closely
5 % our implementation using the Menhir parser generator \cite{menhir}.
7 This
document presents the grammar of the SmPL language used by the
8 \href{http://coccinelle.lip6.fr/
}{Coccinelle tool
}. For the most
9 part, the grammar is written using standard notation. In some rules,
10 however, the left-hand side is in all uppercase letters. These are
11 macros, which take one or more grammar rule right-hand-sides as
12 arguments. The grammar also uses some unspecified nonterminals, such
13 as
\T{id
},
\T{const
}, etc. These refer to the sets suggested by
14 the name,
{\em i.e.
},
\T{id
} refers to the set of possible
15 C-language identifiers, while
\T{const
} refers to the set of
16 possible C-language constants.
19 A PDF version of this documentation is available at
20 \url{http://coccinelle.lip6.fr/docs/main_grammar.pdf
}.
22 A HTML version of this documentation is available online at
23 \url{http://coccinelle.lip6.fr/docs/main_grammar.html
}.
30 \CASE{\any{\NT{include
\_cocci}} \some{\NT{changeset
}}}
32 \RULE{\rt{include
\_cocci}}
33 \CASE{using
\NT{string
}}
34 \CASE{using
\NT{pathToIsoFile
}}
35 \CASE{virtual
\T{id
} \ANY{,
\T{id
}}}
38 \CASE{\NT{metavariables
} \NT{transformation
}}
39 \CASE{\NT{script
\_metavariables} \T{script
\_code}}
40 % \CASE{\NT{metavariables} \ANY{--- filename +++ filename} \NT{transformation}}
44 \T{script
\_code} is any code in the chosen scripting language. Parsing of
45 the semantic patch does not check the validity of this code; any errors are
46 first detected when the code is executed. Furthermore,
\texttt{@
} should
47 not be use in this code. Spatch scans the script code for the next
48 \texttt{@
} and considers that to be the beginning of the next rule, even if
49 \texttt{@
} occurs within e.g., a comment.
51 \texttt{virtual
} keyword is used to declare virtual rules. Virtual
52 rules may be subsequently used as a dependency for the rules in the
53 SmPL file. Whether a virtual rule is defined or not is controlled by
54 the
\texttt{-D
} option on the command line.
56 % Between the metavariables and the transformation rule, there can be a
57 % specification of constraints on the names of the old and new files,
58 % analogous to the filename specifications in the standard patch syntax.
59 % (see Figure \ref{scsiglue_patch}).
61 \section{Metavariables for transformations
}
63 The
\NT{rulename
} portion of the metavariable declaration can specify
64 properties of a rule such as its name, the names of the rules that it
65 depends on, the isomorphisms to be used in processing the rule, and whether
66 quantification over paths should be universal or existential. The optional
67 annotation
{\tt expression
} indicates that the pattern is to be considered
68 as matching an expression, and thus can be used to avoid some parsing
71 The
\NT{metadecl
} portion of the metavariable declaration defines various
72 types of metavariables that will be used for matching in the transformation
76 \RULE{\rt{metavariables
}}
77 \CASE{@@
\any{\NT{metadecl
}} @@
}
78 \CASE{@
\NT{rulename
} @
\any{\NT{metadecl
}} @@
}
81 \CASE{\T{id
} \OPT{extends
\T{id
}} \OPT{depends on
\NT{dep
}} \opt{\NT{iso
}}
82 \opt{\NT{disable-iso
}} \opt{\NT{exists
}} \opt{expression
}}
86 \CASE{\NT{dep
} \&\&
\NT{dep
}}
87 \CASE{\NT{dep
} ||
\NT{dep
}}
97 \CASE{using
\NT{string
} \ANY{,
\NT{string
}}}
99 \RULE{\rt{disable-iso
}}
100 \CASE{disable
\NT{COMMA
\_LIST}\mth{(
}\T{id
}\mth{)
}}
105 % \CASE{\opt{reverse} forall}
107 \RULE{\rt{COMMA
\_LIST}\mth{(
}\rt{elem
}\mth{)
}}
108 \CASE{\NT{elem
} \ANY{,
\NT{elem
}}}
111 The keyword
\KW{disable
} is normally used with the names of
112 isomorphisms defined in standard.iso or whatever isomorphism file has been
113 included. There are, however, some other isomorphisms that are built into
114 the implementation of Coccinelle and that can be disabled as well. Their
115 names are given below. In each case, the text describes the standard
116 behavior. Using
\NT{disable-iso
} with the given name disables this behavior.
119 \item \KW{optional
\_storage}: A SmPL function definition that does not
120 specify any visibility (i.e., static or extern), or a SmPL variable
121 declaration that does not specify any storage (i.e., auto, static,
122 register, or extern), matches a function declaration or variable
123 declaration with any visibility or storage, respectively.
124 \item \KW{optional
\_qualifier}: This is similar to
\KW{optional
\_storage},
125 except that here is it the qualifier (i.e., const or volatile) that does
126 not have to be specified in the SmPL code, but may be present in the C code.
127 \item \KW{value
\_format}: Integers in various formats, e.g.,
1 and
0x1, are
128 considered to be equivalent in the matching process.
129 \item \KW{optional
\_declarer\_semicolon}: Some declarers (top-level terms
130 that look like function calls but serve to declare some variable) don't
131 require a semicolon. This isomorphism allows a SmPL declarer with a semicolon
132 to match such a C declarer, if no transformation is specified on the SmPL
134 \item \KW{comm
\_assoc}: An expression of the form
\NT{exp
} \NT{bin
\_op}
135 \KW{...
}, where
\NT{bin
\_op} is commutative and associative, is
136 considered to match any top-level sequence of
\NT{bin
\_op} operators
137 containing
\NT{exp
} as the top-level argument.
140 The possible types of metavariable declarations are defined by the grammar
141 rule below. Metavariables should occur at least once in the transformation
142 immediately following their declaration. Fresh identifier metavariables
143 must only be used in
{\tt +
} code. These properties are not expressed in
144 the grammar, but are checked by a subsequent analysis. The metavariables
145 are designated according to the kind of terms they can match, such as a
146 statement, an identifier, or an expression. An expression metavariable can
147 be further constrained by its type. A declaration metavariable matches the
148 declaration of one or more variables, all sharing the same type
149 specification (
{\em e.g.
},
{\tt int a,b,c=
3;
}). A field metavariable does
150 the same, but for structure fields.
154 \CASE{metavariable
\NT{ids
} ;
}
155 \CASE{fresh identifier
\NT{ids
} ;
}
156 \CASE{identifier
\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_regexp}\mth{)
} ;
}
157 \CASE{identifier
\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_virt\_or\_not\_eq}\mth{)
} ;
}
158 \CASE{parameter
\opt{list
} \NT{ids
} ;
}
159 \CASE{parameter list
[ \NT{id
} ] \NT{ids
} ;
}
160 \CASE{parameter list
[ \NT{const
} ] \NT{ids
} ;
}
161 \CASE{type
\NT{ids
} ;
}
162 \CASE{statement
\opt{list
} \NT{ids
} ;
}
163 \CASE{declaration
\NT{ids
} ;
}
164 \CASE{field
\opt{list
} \NT{ids
} ;
}
165 \CASE{typedef
\NT{ids
} ;
}
166 \CASE{declarer name
\NT{ids
} ;
}
167 % \CASE{\opt{local} function \NT{pmid\_with\_not\_eq\_list} ;}
168 \CASE{declarer
\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_regexp}\mth{)
} ;
}
169 \CASE{declarer
\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
170 \CASE{iterator name
\NT{ids
} ;
}
171 \CASE{iterator
\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_regexp}\mth{)
} ;
}
172 \CASE{iterator
\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
173 % \CASE{error \NT{pmid\_with\_not\_eq\_list} ; }
174 \CASE{\opt{local
} idexpression
\opt{\NT{ctype
}} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
175 \CASE{\opt{local
} idexpression
\OPT{\ttlb \NT{ctypes
}\ttrb~
\any{*
}} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
176 \CASE{\opt{local
} idexpression
\some{*
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
177 \CASE{expression list
\NT{ids
} ;
}
178 \CASE{expression
\some{*
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
179 \CASE{expression enum
\any{*
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
180 \CASE{expression struct
\any{*
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
181 \CASE{expression union
\any{*
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
182 \CASE{expression
\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_ceq}\mth{)
} ;
}
183 \CASE{expression list
[ \NT{id
} ] \NT{ids
} ;
}
184 \CASE{expression list
[ \NT{const
} ] \NT{ids
} ;
}
185 \CASE{\NT{ctype
} [ ] \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
186 \CASE{\NT{ctype
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_ceq}\mth{)
} ;
}
187 \CASE{\ttlb \NT{ctypes
}\ttrb~
\any{*
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_ceq}\mth{)
} ;
}
188 \CASE{\ttlb \NT{ctypes
}\ttrb~
\any{*
} [ ] \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
189 \CASE{constant
\opt{\NT{ctype
}} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
190 \CASE{constant
\OPT{\ttlb \NT{ctypes
}\ttrb~
\any{*
}} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq}\mth{)
} ;
}
191 \CASE{position
\opt{any
} \NT{COMMA
\_LIST}\mth{(
}\NT{pmid
\_with\_not\_eq\_mid}\mth{)
} ;
}
194 A metavariable declaration local idexpression v means that v is restricted
195 to be a local variable. If it should just be a variable, but not
196 necessarily a local one, then drop local. A more complex description of a
197 location, such as a->b is considered to be an expression, not an
200 Constant is for constants, such as
27. But it also considers an identifier
201 that is all capital letters (possibly containing numbers) as a constant as
202 well, because the names gives to macros in Linux usually have this form.
204 An identifier is the name of a structure field, a macro, a function, or a
205 variable. Is is the name of something rather than an expression that has a
206 value. But an identifier can be used in the position of an expression as
207 well, where it represents a variable.
209 It is possible to specify that an expression list or a parameter list
210 metavariable should match a specific number of expressions or parameters.
212 It is possible to specify some information about the definition of a fresh
213 identifier. See the wiki.
218 \CASE{\NT{COMMA
\_LIST}\mth{(
}\NT{pmid
}\mth{)
}}
227 \RULE{\rt{mid
}} \CASE{\T{rulename
\_id}.
\T{id
}}
229 \RULE{\rt{pmid
\_with\_regexp}}
230 \CASE{\NT{pmid
} \~
{}=
\NT{regexp
}}
231 \CASE{\NT{pmid
} !\~
{}=
\NT{regexp
}}
233 \RULE{\rt{pmid
\_with\_not\_eq}}
234 \CASE{\NT{pmid
} \OPT{!=
\NT{id
\_or\_meta}}}
236 \OPT{!=
\ttlb~
\NT{COMMA
\_LIST}\mth{(
}\NT{id
\_or\_meta}\mth{)
} \ttrb}}
238 \RULE{\rt{pmid
\_with\_virt\_or\_not\_eq}}
239 \CASE{virtual.
\T{id
}}
240 \CASE{\NT{pmid
\_with\_not\_eq}}
242 \RULE{\rt{pmid
\_with\_not\_ceq}}
243 \CASE{\NT{pmid
} \OPT{!=
\NT{id
\_or\_cst}}}
244 \CASE{\NT{pmid
} \OPT{!=
\ttlb~
\NT{COMMA
\_LIST}\mth{(
}\NT{id
\_or\_cst}\mth{)
} \ttrb}}
246 \RULE{\rt{id
\_or\_cst}}
250 \RULE{\rt{id
\_or\_meta}}
252 \CASE{\T{rulename
\_id}.
\T{id
}}
254 \RULE{\rt{pmid
\_with\_not\_eq\_mid}}
255 \CASE{\NT{pmid
} \OPT{!=
\NT{mid
}}}
256 \CASE{\NT{pmid
} \OPT{!=
\ttlb~
\NT{COMMA
\_LIST}\mth{(
}\NT{mid
}\mth{)
} \ttrb}}
259 Subsequently, we refer to arbitrary metavariables as
260 \mth{\msf{metaid
}^
{\mbox{\scriptsize{\it{ty
}}}}}, where
{\it{ty
}}
261 indicates the
{\it metakind
} used in the declaration of the variable.
262 For example,
\mth{\msf{metaid
}^
{\ssf{Type
}}} refers to a metavariable
263 that was declared using
\texttt{type
} and stands for any type.
265 {\tt metavariable
} declares a metavariable for which the parser tried to
266 figure out the metavariable type based on the usage context. Such a
267 metavariable must be used consistently. These metavariables cannot be used
268 in all contexts; specifically, they cannot be used in context that would
269 make the parsing ambiguous. Some examples are the leftmost term of an
270 expression, such as the left-hand side of an assignment, or the type in a
271 variable declaration. These restrictions may seems somewhat arbitrary from
272 the user's point of view. Thus, it is better to use metavariables with
273 metavariable types. If Coccinelle is given the argument
{\tt
274 -parse
\_cocci}, it will print information about the type that is inferred
275 for each metavariable.
277 The
\NT{ctype
} and
\NT{ctypes
} nonterminals are used by both the grammar of
278 metavariable declarations and the grammar of transformations, and are
279 defined on page~
\pageref{types
}.
281 An identifier metavariable with
{\tt virtual
} as its ``rule name'' is given
282 a value on the command line. For example, if a semantic patch contains a
283 rule that declares an identifier metavariable with the name
{\tt
284 virtual.alloc
}, then the command line could contain
{\tt -D
285 alloc=kmalloc
}. There should not be space around the
{\tt =
}. An
286 example is in
{\tt demos/vm.cocci
} and
{\tt demos/vm.c
}.
289 \paragraph*
{Warning:
} Each metavariable declaration causes the declared
290 metavariables to be immediately usable, without any inheritance
291 indication. Thus the following are correct:
300 [...
] // some semantic patch code
311 [...
] // some semantic patch code
316 But the following is not correct:
325 [...
] // some semantic patch code
329 This applies to position variables, type metavariables, identifier
330 metavariables that may be used in specifying a structure type, and
331 metavariables used in the initialization of a fresh identifier. In the
332 case of a structure type, any identifier metavariable indeed has to be
333 declared as an identifier metavariable in advance. The syntax does not
334 permit
{\tt r.n
} as the name of a structure or union type in such a
337 \section{Metavariables for scripts
}
339 Metavariables for scripts can only be inherited from transformation rules.
340 In the spirit of scripting languages such as Python that use dynamic
341 typing, metavariables for scripts do not include type declarations.
344 \RULE{\rt{script
\_metavariables}}
345 \CASE{@ script:
\NT{language
} \OPT{\NT{rulename
}} \OPT{depends on
\NT{dep
}} @
346 \any{\NT{script
\_metadecl}} @@
}
347 \CASE{@ initialize:
\NT{language
} \OPT{depends on
\NT{dep
}} @
}
348 \CASE{@ finalize:
\NT{language
} \OPT{depends on
\NT{dep
}} @
}
350 \RULE{\rt{language
}} \CASE{python
} \CASE{ocaml
}
352 \RULE{\rt{script
\_metadecl}}
353 \CASE{\T{id
} <
{}<
\T{rulename
\_id}.
\T{id
} ;
}
357 Currently, the only scripting languages that are supported are Python and
358 OCaml, indicated using
{\tt python
} and
{\tt ocaml
}, respectively. The
359 set of available scripting languages may be extended at some point.
361 Script rules declared with
\KW{initialize
} are run before the treatment of
362 any file. Script rules declared with
\KW{finalize
} are run when the
363 treatment of all of the files has completed. There can be at most one of
364 each per scripting language (thus currently at most one of each).
365 Initialize and finalize script rules do not have access to SmPL
366 metavariables. Nevertheless, a finalize script rule can access any
367 variables initialized by the other script rules, allowing information to be
368 transmitted from the matching process to the finalize rule.
370 A script metavariable that does not specify an origin, using
\texttt{<<
},
371 is newly declared by the script. This metavariable should be assigned to a
372 string and can be inherited by subsequent rules as an identifier. In
373 Python, the assignment of such a metavariable $x$ should refer to the
374 metavariable as
{\tt coccinelle.\(x\)
}. Examples are in the files
375 \texttt{demos/pythontococci.cocci
} and
\texttt{demos/camltococci.cocci
}.
377 In an ocaml script, the following extended form of
\textit{script
\_metadecl}
381 \RULE{\rt{script
\_metadecl}}
382 \CASE{(
\T{id
},
\T{id
}) <
{}<
\T{rulename
\_id}.
\T{id
} ;
}
383 \CASE{\T{id
} <
{}<
\T{rulename
\_id}.
\T{id
} ;
}
388 In a declaration of the form
\texttt{(
\T{id
},
\T{id
}) <
{}<
389 \T{rulename
\_id}.
\T{id
} ;
}, the left component of
\texttt{(
\T{id
},
\T{id
})
}
390 receives a string representation of the value of the inherited metavariable
391 while the right component receives its abstract syntax tree. The file
392 \texttt{parsing
\_c/ast
\_c.ml
} in the Coccinelle implementation gives some
393 information about the structure of the abstract syntax tree. Either the
394 left or right component may be replaced by
\verb+_+, indicating that the
395 string representation or abstract syntax trees representation is not
396 wanted, respectively.
398 The abstract syntax tree of a metavariable declared using
{\tt
399 metavariable
} is not available.
401 \section{Transformation
}
403 The transformation specification essentially has the form of C code,
404 except that lines to remove are annotated with
\verb+-+ in the first
405 column, and lines to add are annotated with
\verb-+-. A
406 transformation specification can also use
{\em dots
}, ``
\verb-...-'',
407 describing an arbitrary sequence of function arguments or instructions
408 within a control-flow path. Dots may be modified with a
{\tt when
}
409 clause, indicating a pattern that should not occur anywhere within the
410 matched sequence. Finally, a transformation can specify a disjunction
411 of patterns, of the form
\mtt{(
\mth{\mita{pat
}_1
} |
\mita{\ldots} |
412 \mth{\mita{pat
}_n
} )
} where each
\texttt{(
},
\texttt{|
} or
413 \texttt{)
} is in column
0 or preceded by
\texttt{\textbackslash}.
415 The grammar that we present for the transformation is not actually the
416 grammar of the SmPL code that can be written by the programmer, but is
417 instead the grammar of the slice of this consisting of the
{\tt -
}
418 annotated and the unannotated code (the context of the transformed lines),
419 or the
{\tt +
} annotated code and the unannotated code. For example, for
420 parsing purposes, the following transformation
421 %presented in Section \ref{sec:seq2}
422 is split into the two variants shown below and each is parsed
427 \begin{lstlisting
}[language=Cocci
]
428 proc_info_func(...)
{
440 \begin{tabular
}{p
{5cm
}p
{3cm
}p
{5cm
}}
441 \begin{lstlisting
}[language=Cocci
]
442 proc_info_func(...)
{
449 \begin{lstlisting
}[language=Cocci
]
450 proc_info_func(...)
{
461 Requiring that both slices parse correctly ensures that the rule matches
462 syntactically valid C code and that it produces syntactically valid C code.
463 The generated parse trees are then merged for use in the subsequent
464 matching and transformation process.
466 The grammar for the minus or plus slice of a transformation is as follows:
470 \RULE{\rt{transformation
}}
471 \CASE{\some{\NT{include
}}}
472 \CASE{\NT{OPTDOTSEQ
}\mth{(
}\NT{expr
},
\NT{when
}\mth{)
}}
473 \CASE{\NT{OPTDOTSEQ
}\mth{(
}\some{\NT{decl
\_stmt}},
\NT{when
}\mth{)
}}
474 \CASE{\NT{OPTDOTSEQ
}\mth{(
}\NT{fundecl
},
\NT{when
}\mth{)
}}
477 \CASE{\#include
\T{include
\_string}}
479 % \RULE{\rt{fun\_decl\_stmt}}
480 % \CASE{\NT{decl\_stmt}}
481 % \CASE{\NT{fundecl}}
484 % \CASE{\ttlb \NT{initialize\_list} \ttrb}
485 % \CASE{\NT{toplevel\_seq\_start\_after\_dots\_init}}
487 % \RULE{\rt{toplevel\_seq\_start\_after\_dots\_init}}
488 % \CASE{\NT{stmt\_dots} \NT{toplevel\_after\_dots}}
489 % \CASE{\NT{expr} \opt{\NT{toplevel\_after\_exp}}}
490 % \CASE{\NT{decl\_stmt\_expr} \opt{\NT{toplevel\_after\_stmt}}}
492 % \RULE{\rt{stmt\_dots}}
493 % \CASE{... \any{\NT{when}}}
494 % \CASE{<... \any{\NT{when}} \NT{nest\_after\_dots} ...>}
495 % \CASE{<+... \any{\NT{when}} \NT{nest\_after\_dots} ...+>}
498 \CASE{when !=
\NT{when
\_code}}
499 \CASE{when =
\NT{rule
\_elem\_stmt}}
500 \CASE{when
\NT{COMMA
\_LIST}\mth{(
}\NT{any
\_strict}\mth{)
}}
501 \CASE{when true !=
\NT{expr
}}
502 \CASE{when false !=
\NT{expr
}}
504 \RULE{\rt{when
\_code}}
505 \CASE{\NT{OPTDOTSEQ
}\mth{(
}\some{\NT{decl
\_stmt}},
\NT{when
}\mth{)
}}
506 \CASE{\NT{OPTDOTSEQ
}\mth{(
}\NT{expr
},
\NT{when
}\mth{)
}}
508 \RULE{\rt{rule
\_elem\_stmt}}
509 \CASE{\NT{one
\_decl}}
511 \CASE{return
\opt{\NT{expr
}};
}
514 \CASE{\bs(
\NT{rule
\_elem\_stmt} \SOME{\bs|
\NT{rule
\_elem\_stmt}}\bs)
}
516 \RULE{\rt{any
\_strict}}
522 % \RULE{\rt{nest\_after\_dots}}
523 % \CASE{\NT{decl\_stmt\_exp} \opt{\NT{nest\_after\_stmt}}}
524 % \CASE{\opt{\NT{exp}} \opt{\NT{nest\_after\_exp}}}
526 % \RULE{\rt{nest\_after\_stmt}}
527 % \CASE{\NT{stmt\_dots} \NT{nest\_after\_dots}}
528 % \CASE{\NT{decl\_stmt} \opt{\NT{nest\_after\_stmt}}}
530 % \RULE{\rt{nest\_after\_exp}}
531 % \CASE{\NT{stmt\_dots} \NT{nest\_after\_dots}}
533 % \RULE{\rt{toplevel\_after\_dots}}
534 % \CASE{\opt{\NT{toplevel\_after\_exp}}}
535 % \CASE{\NT{exp} \opt{\NT{toplevel\_after\_exp}}}
536 % \CASE{\NT{decl\_stmt\_expr} \NT{toplevel\_after\_stmt}}
538 % \RULE{\rt{toplevel\_after\_exp}}
539 % \CASE{\NT{stmt\_dots} \opt{\NT{toplevel\_after\_dots}}}
541 % \RULE{\rt{decl\_stmt\_expr}}
542 % \CASE{TMetaStmList$^\ddag$}
543 % \CASE{\NT{decl\_var}}
545 % \CASE{(\NT{stmt\_seq} \ANY{| \NT{stmt\_seq}})}
547 % \RULE{\rt{toplevel\_after\_stmt}}
548 % \CASE{\NT{stmt\_dots} \opt{\NT{toplevel\_after\_dots}}}
549 % \CASE{\NT{decl\_stmt} \NT{toplevel\_after\_stmt}}
554 \RULE{\rt{OPTDOTSEQ
}\mth{(
}\rt{grammar
\_ds},
\rt{when
\_ds}\mth{)
}}
555 \CASE{}\multicolumn{3}{r
}{\hspace{1cm
}
556 \KW{\opt{...
\opt{\NT{when
\_ds}}} \NT{grammar
\_ds}
557 \ANY{...
\opt{\NT{when
\_ds}} \NT{grammar
\_ds}}
558 \opt{...
\opt{\NT{when
\_ds}}}}
561 % \CASE{\opt{... \opt{\NT{when\_ds}}} \NT{grammar}
562 % \ANY{... \opt{\NT{when\_ds}} \NT{grammar}}
563 % \opt{... \opt{\NT{when\_ds}}}}
564 % \CASE{<... \any{\NT{when\_ds}} \NT{grammar} ...>}
565 % \CASE{<+... \any{\NT{when\_ds}} \NT{grammar} ...+>}
570 Lines may be annotated with an element of the set $\
{\mtt{-
},
\mtt{+
},
571 \mtt{*
}\
}$ or the singleton $
\mtt{?
}$, or one of each set.
\mtt{?
}
572 represents at most one match of the given pattern.
\mtt{*
} is used for
573 semantic match,
\emph{i.e.
}, a pattern that highlights the fragments
574 annotated with
\mtt{*
}, but does not perform any modification of the
575 matched code.
\mtt{*
} cannot be mixed with
\mtt{-
} and
\mtt{+
}. There are
576 some constraints on the use of these annotations:
578 \item Dots,
{\em i.e.
} \texttt{...
}, cannot occur on a line marked
580 \item Nested dots,
{\em i.e.
}, dots enclosed in
{\tt <
} and
{\tt >
}, cannot
581 occur on a line with any marking.
584 Each element of a disjunction must be a proper term like an
585 expression, a statement, an identifier or a declaration. Thus, the
586 rule on the left below is not a syntactically correct SmPL rule. One may
587 use the rule on the right instead.
590 \begin{tabular
}{l@
{\hspace{5cm
}}r
}
591 \begin{lstlisting
}[language=Cocci
]
606 \begin{lstlisting
}[language=Cocci
]
625 Some kinds of terms can only appear in + code. These include comments,
626 ifdefs, and attributes (
\texttt{\_\_attribute\_\_((...))
}).
634 \CASE{\NT{COMMA
\_LIST}\mth{(
}\NT{ctype
}\mth{)
}}
637 \CASE{\opt{\NT{const
\_vol}} \NT{generic
\_ctype} \any{*
}}
638 \CASE{\opt{\NT{const
\_vol}} void
\some{*
}}
639 \CASE{(
\NT{ctype
} \ANY{|
\NT{ctype
}})
}
641 \RULE{\rt{const
\_vol}}
645 \RULE{\rt{generic
\_ctype}}
646 \CASE{\NT{ctype
\_qualif}}
647 \CASE{\opt{\NT{ctype
\_qualif}} char
}
648 \CASE{\opt{\NT{ctype
\_qualif}} short
}
649 \CASE{\opt{\NT{ctype
\_qualif}} int
}
650 \CASE{\opt{\NT{ctype
\_qualif}} long
}
651 \CASE{\opt{\NT{ctype
\_qualif}} long long
}
654 \CASE{size
\_t} \CASE{ssize
\_t} \CASE{ptrdiff
\_t}
655 \CASE{enum
\NT{id
} \
{ \NT{PARAMSEQ
}\mth{(
}\NT{dot
\_expr},
\NT{exp
\_whencode}\mth{)
} \OPT{,
} \
}}
656 \CASE{\OPT{struct
\OR union
} \T{id
} \OPT{\
{ \any{\NT{struct
\_decl\_list}} \
}}}
658 \RULE{\rt{ctype
\_qualif}}
662 \RULE{\rt{struct
\_decl\_list}}
663 \CASE{\NT{struct
\_decl\_list\_start}}
665 \RULE{\rt{struct
\_decl\_list\_start}}
666 \CASE{\NT{struct
\_decl}}
667 \CASE{\NT{struct
\_decl} \NT{struct
\_decl\_list\_start}}
668 \CASE{...
\opt{when !=
\NT{struct
\_decl}}$^
\dag$
\opt{\NT{continue
\_struct\_decl\_list}}}
670 \RULE{\rt{continue
\_struct\_decl\_list}}
671 \CASE{\NT{struct
\_decl} \NT{struct
\_decl\_list\_start}}
672 \CASE{\NT{struct
\_decl}}
674 \RULE{\rt{struct
\_decl}}
675 \CASE{\NT{ctype
} \NT{d
\_ident};
}
676 \CASE{\NT{fn
\_ctype} (* \NT{d\_ident}) (\NT{PARAMSEQ}\mth{(}\NT{name\_opt\_decl}, \mth{\varepsilon)});)}
677 \CASE{\opt{\NT{const\_vol}} \T{id} \NT{d\_ident};}
680 \CASE{\T{id} \any{[\opt{\NT{expr}}]}}
682 \RULE{\rt{fn\_ctype}}
683 \CASE{\NT{generic\_ctype} \any{*}}
686 \RULE{\rt{name\_opt\_decl}}
689 \CASE{\NT{fn\_ctype}}
692 $^\dag$ The optional \texttt{when} construct ends at the end of the line.
694 \section{Function declarations}
699 \CASE{\opt{\NT{fn\_ctype}} \any{\NT{funinfo}} \NT{funid}
700 (\opt{\NT{PARAMSEQ}\mth{(}\NT{param}, \mth{\varepsilon)}})
701 \ttlb~\opt{\NT{stmt\_seq}} \ttrb}
704 \CASE{\opt{\NT{fn\_ctype}} \any{\NT{funinfo}} \NT{funid}
705 (\opt{\NT{PARAMSEQ}\mth{(}\NT{param}, \mth{\varepsilon)}});}
720 \CASE{\mth{\T{metaid}^{\ssf{Id}}}}
721 \CASE{\NT{OR}\mth{(}\NT{stmt}\mth{)}}
722 % \CASE{\mth{\T{metaid}^{\ssf{Func}}}}
723 % \CASE{\mth{\T{metaid}^{\ssf{LocalFunc}}}}
726 \CASE{\NT{type} \T{id}}
727 \CASE{\mth{\T{metaid}^{\ssf{Param}}}}
728 \CASE{\mth{\T{metaid}^{\ssf{ParamList}}}}
731 \CASE{\NT{ctype} \NT{id}}
732 \CASE{\NT{fn\_ctype} (* \NT{id}) (\NT{PARAMSEQ}\mth{(}\NT{name\_opt\_decl}, \mth{\varepsilon)})}
734 \CASE{\mth{\T{metaid}^{\ssf{Param}}}}
738 \RULE{\rt{PARAMSEQ}\mth{(}\rt{gram\_p}, \rt{when\_p}\mth{)}}
739 \CASE{\NT{COMMA\_LIST}\mth{(}\NT{gram\_p} \OR \ldots \opt{\NT{when\_p}}\mth{)}}
742 To match a function it is not necessary to provide all of the annotations
743 that appear before the function name. For example, the following semantic
746 \begin{lstlisting}[language=Cocci]
754 matches a function declared as follows:
756 \begin{lstlisting}[language=C]
757 static int foo() { return 12; }
761 This behavior can be turned off by disabling the \KW{optional\_storage}
762 isomorphism. If one adds code before a function declaration, then the
763 effect depends on the kind of code that is added. If the added code is a
764 function definition or CPP code, then the new code is placed before
765 all information associated with the function definition, including any
766 comments preceeding the function definition. On the other hand, if the new
767 code is associated with the function, such as the addition of the keyword
768 {\tt static}, the new code is placed exactly where it appears with respect
769 to the rest of the function definition in the semantic patch. For example,
771 \begin{lstlisting}[language=Cocci]
780 causes static to be placed just before the function name. The following
781 causes it to be placed just before the type
783 \begin{lstlisting}[language=Cocci]
793 It may be necessary to consider several cases to ensure that the added ode
794 is placed in the right position. For example, one may need one pattern
795 that considers that the function is declared {\tt inline} and another that
796 considers that it is not.
800 \section{Declarations}
803 \RULE{\rt{decl\_var}}
804 % \CASE{\NT{type} \opt{\NT{id} \opt{[\opt{\NT{dot\_expr}}]}
805 % \ANY{, \NT{id} \opt{[ \opt{\NT{dot\_expr}}]}}};}
806 \CASE{\NT{common\_decl}}
807 \CASE{\opt{\NT{storage}} \NT{ctype} \NT{COMMA\_LIST}\mth{(}\NT{d\_ident}\mth{)} ;}
808 \CASE{\opt{\NT{storage}} \opt{\NT{const\_vol}} \T{id} \NT{COMMA\_LIST}\mth{(}\NT{d\_ident}\mth{)} ;}
809 \CASE{\opt{\NT{storage}} \NT{fn\_ctype} ( * \NT{d\_ident} ) ( \NT{PARAMSEQ}\mth{(}\NT{name\_opt\_decl}, \mth{\varepsilon)} ) = \NT{initialize} ;}
810 \CASE{typedef \NT{ctype} \NT{typedef\_ident} ;}
812 \RULE{\rt{one\_decl}}
813 \CASE{\NT{common\_decl}}
814 \CASE{\opt{\NT{storage}} \NT{ctype} \NT{id};}
815 % \CASE{\NT{storage} \NT{ctype} \NT{id} \opt{[\opt{\NT{dot\\_expr}}]} = \NT{nest\\_expr};}
816 \CASE{\opt{\NT{storage}} \opt{\NT{const\_vol}} \T{id} \NT{d\_ident} ;}
818 \RULE{\rt{common\_decl}}
821 \CASE{\opt{\NT{storage}} \NT{ctype} \NT{d\_ident} = \NT{initialize} ;}
822 \CASE{\opt{\NT{storage}} \opt{\NT{const\_vol}} \T{id} \NT{d\_ident} = \NT{initialize} ;}
823 \CASE{\opt{\NT{storage}} \NT{fn\_ctype} ( * \NT{d\_ident} ) ( \NT{PARAMSEQ}\mth{(}\NT{name\_opt\_decl}, \mth{\varepsilon)} ) ;}
824 \CASE{\NT{decl\_ident} ( \OPT{\NT{COMMA\_LIST}\mth{(}\NT{expr}\mth{)}} ) ;}
826 \RULE{\rt{initialize}}
827 \CASE{\NT{dot\_expr}}
828 \CASE{\mth{\T{metaid}^{\ssf{Initialiser}}}}
829 \CASE{\ttlb~\opt{\NT{COMMA\_LIST}\mth{(}\NT{init\_list\_elem}\mth{)}}~\ttrb}
831 \RULE{\rt{init\_list\_elem}}
832 \CASE{\NT{dot\_expr}}
833 \CASE{\NT{designator} = \NT{dot\_expr}}
834 \CASE{\mth{\T{metaid}^{\ssf{Initialiser}}}}
835 \CASE{\mth{\T{metaid}^{\ssf{InitialiserList}}}}
836 \CASE{\NT{id} : \NT{dot\_expr}}
838 \RULE{\rt{designator}}
840 \CASE{[ \NT{dot\_expr} ]}
841 \CASE{[ \NT{dot\_expr} ... \NT{dot\_expr} ]}
843 \RULE{\rt{decl\_ident}}
844 \CASE{\T{DeclarerId}}
845 \CASE{\mth{\T{metaid}^{\ssf{Declarer}}}}
848 An initializer for a structure can be ordered or unordered. It is
849 considered to be unordered if there is at least one key-value pair
850 initializer, e.g., \texttt{.x = e}.
854 The first rule {\em statement} describes the various forms of a statement.
855 The remaining rules implement the constraints that are sensitive to the
856 context in which the statement occurs: {\em single\_statement} for a
857 context in which only one statement is allowed, and {\em decl\_statement}
858 for a context in which a declaration, statement, or sequence thereof is
864 \CASE{\mth{\T{metaid}^{\ssf{Stmt}}}}
866 \CASE{if (\NT{dot\_expr}) \NT{single\_stmt} \opt{else \NT{single\_stmt}}}
867 \CASE{for (\opt{\NT{dot\_expr}}; \opt{\NT{dot\_expr}}; \opt{\NT{dot\_expr}})
869 \CASE{while (\NT{dot\_expr}) \NT{single\_stmt}}
870 \CASE{do \NT{single\_stmt} while (\NT{dot\_expr});}
871 \CASE{\NT{iter\_ident} (\any{\NT{dot\_expr}}) \NT{single\_stmt}}
872 \CASE{switch (\opt{\NT{dot\_expr}}) \ttlb \any{\NT{case\_line}} \ttrb}
873 \CASE{return \opt{\NT{dot\_expr}};}
874 \CASE{\ttlb~\opt{\NT{stmt\_seq}} \ttrb}
875 \CASE{\NT{NEST}\mth{(}\some{\NT{decl\_stmt}}, \NT{when}\mth{)}}
876 \CASE{\NT{NEST}\mth{(}\NT{expr}, \NT{when}\mth{)}}
881 \CASE{\ttlb \NT{stmt\_seq} \ttrb}
883 \RULE{\rt{single\_stmt}}
885 \CASE{\NT{OR}\mth{(}\NT{stmt}\mth{)}}
887 \RULE{\rt{decl\_stmt}}
888 \CASE{\mth{\T{metaid}^{\ssf{StmtList}}}}
889 \CASE{\NT{decl\_var}}
891 \CASE{\NT{OR}\mth{(}\NT{stmt\_seq}\mth{)}}
893 \RULE{\rt{stmt\_seq}}
894 \CASE{\any{\NT{decl\_stmt}}
895 \opt{\NT{DOTSEQ}\mth{(}\some{\NT{decl\_stmt}},
896 \NT{when}\mth{)} \any{\NT{decl\_stmt}}}}
897 \CASE{\any{\NT{decl\_stmt}}
898 \opt{\NT{DOTSEQ}\mth{(}\NT{expr},
899 \NT{when}\mth{)} \any{\NT{decl\_stmt}}}}
901 \RULE{\rt{case\_line}}
902 \CASE{default :~\NT{stmt\_seq}}
903 \CASE{case \NT{dot\_expr} :~\NT{stmt\_seq}}
905 \RULE{\rt{iter\_ident}}
906 \CASE{\T{IteratorId}}
907 \CASE{\mth{\T{metaid}^{\ssf{Iterator}}}}
911 \RULE{\rt{OR}\mth{(}\rt{gram\_o}\mth{)}}
912 \CASE{( \NT{gram\_o} \ANY{\ttmid \NT{gram\_o}})}
914 \RULE{\rt{DOTSEQ}\mth{(}\rt{gram\_d}, \rt{when\_d}\mth{)}}
915 \CASE{\ldots \opt{\NT{when\_d}} \ANY{\NT{gram\_d} \ldots \opt{\NT{when\_d}}}}
917 \RULE{\rt{NEST}\mth{(}\rt{gram\_n}, \rt{when\_n}\mth{)}}
918 \CASE{<\ldots \opt{\NT{when\_n}} \NT{gram\_n} \ANY{\ldots \opt{\NT{when\_n}} \NT{gram\_n}} \ldots>}
919 \CASE{<+\ldots \opt{\NT{when\_n}} \NT{gram\_n} \ANY{\ldots \opt{\NT{when\_n}} \NT{gram\_n}} \ldots+>}
923 OR is a macro that generates a disjunction of patterns. The three
924 tokens \T{(}, \T{\ttmid}, and \T{)} must appear in the leftmost
925 column, to differentiate them from the parentheses and bit-or tokens
926 that can appear within expressions (and cannot appear in the leftmost
927 column). These token may also be preceded by \texttt{\bs}
928 when they are used in an other column. These tokens are furthermore
929 different from (, \(\mid\), and ), which are part of the grammar
932 \section{Expressions}
934 A nest or a single ellipsis is allowed in some expression contexts, and
935 causes ambiguity in others. For example, in a sequence \mtt{\ldots
936 \mita{expr} \ldots}, the nonterminal \mita{expr} must be instantiated as an
937 explicit C-language expression, while in an array reference,
938 \mtt{\mth{\mita{expr}_1} \mtt{[} \mth{\mita{expr}_2} \mtt{]}}, the
939 nonterminal \mth{\mita{expr}_2}, because it is delimited by brackets, can
940 be also instantiated as \mtt{\ldots}, representing an arbitrary expression. To
941 distinguish between the various possibilities, we define three nonterminals
942 for expressions: {\em expr} does not allow either top-level nests or
943 ellipses, {\em nest\_expr} allows a nest but not an ellipsis, and {\em
944 dot\_expr} allows both. The EXPR macro is used to express these variants
949 \CASE{\NT{EXPR}\mth{(}\NT{expr}\mth{)}}
951 \RULE{\rt{nest\_expr}}
952 \CASE{\NT{EXPR}\mth{(}\NT{nest\_expr}\mth{)}}
953 \CASE{\NT{NEST}\mth{(}\NT{nest\_expr}, \NT{exp\_whencode}\mth{)}}
955 \RULE{\rt{dot\_expr}}
956 \CASE{\NT{EXPR}\mth{(}\NT{dot\_expr}\mth{)}}
957 \CASE{\NT{NEST}\mth{(}\NT{dot\_expr}, \NT{exp\_whencode}\mth{)}}
958 \CASE{...~\opt{\NT{exp\_whencode}}}
960 \RULE{\rt{EXPR}\mth{(}\rt{exp}\mth{)}}
961 \CASE{\NT{exp} \NT{assign\_op} \NT{exp}}
964 \CASE{\NT{unary\_op} \NT{exp}}
965 \CASE{\NT{exp} \NT{bin\_op} \NT{exp}}
966 \CASE{\NT{exp} ?~\NT{dot\_expr} :~\NT{exp}}
967 \CASE{(\NT{type}) \NT{exp}}
968 \CASE{\NT{exp} [\NT{dot\_expr}]}
969 \CASE{\NT{exp} .~\NT{id}}
970 \CASE{\NT{exp} -> \NT{id}}
971 \CASE{\NT{exp}(\opt{\NT{PARAMSEQ}\mth{(}\NT{arg}, \NT{exp\_whencode}\mth{)}})}
973 % \CASE{\mth{\T{metaid}^{\ssf{Func}}}}
974 % \CASE{\mth{\T{metaid}^{\ssf{LocalFunc}}}}
975 \CASE{\mth{\T{metaid}^{\ssf{Exp}}}}
976 % \CASE{\mth{\T{metaid}^{\ssf{Err}}}}
977 \CASE{\mth{\T{metaid}^{\ssf{Const}}}}
979 \CASE{(\NT{dot\_expr})}
980 \CASE{\NT{OR}\mth{(}\NT{exp}\mth{)}}
983 \CASE{\NT{nest\_expr}}
984 \CASE{\mth{\T{metaid}^{\ssf{ExpList}}}}
986 \RULE{\rt{exp\_whencode}}
987 \CASE{when != \NT{expr}}
989 \RULE{\rt{assign\_op}}
990 \CASE{= \OR -= \OR += \OR *= \OR /= \OR \%=}
991 \CASE{\&= \OR |= \OR \caret= \OR \lt\lt= \OR \gt\gt=}
994 \CASE{* \OR / \OR \% \OR + \OR -}
995 \CASE{\lt\lt \OR \gt\gt \OR \caret\xspace \OR \& \OR \ttmid}
996 \CASE{< \OR > \OR <= \OR >= \OR == \OR != \OR \&\& \OR \ttmid\ttmid}
998 \RULE{\rt{unary\_op}}
999 \CASE{++ \OR -- \OR \& \OR * \OR + \OR - \OR !}
1003 \section{Constants, Identifiers and Types for Transformations}
1012 \CASE{"\any{[\^{}"]}"}
1015 \CASE{\T{id} \OR \mth{\T{metaid}^{\ssf{Id}}}
1016 \OR {\NT{OR}\mth{(}\NT{stmt}\mth{)}}}
1018 \RULE{\rt{typedef\_ident}}
1019 \CASE{\T{id} \OR \mth{\T{metaid}^{\ssf{Type}}}}
1022 \CASE{\NT{ctype} \OR \mth{\T{metaid}^{\ssf{Type}}}}
1024 \RULE{\rt{pathToIsoFile}}
1028 \CASE{"\any{[\^{}"]}"}
1033 A \verb+//+ or \verb+/* */+ comment that is annotated with + in the
1034 leftmost column is considered to be added code. A \verb+//+ or
1035 \verb+/* */+ comment wthout such an annotation is considered to be a
1036 comment about the SmPL code, and thus is not matched in the C code.
1038 %%% Local Variables:
1040 %%% TeX-master: "main_grammar"
1043 %%% ispell-local-dictionary: "american"