Main References:

1. INTRODUCTION TO COCCINELLE AND SMPL.
2. The SmPL Grammar (version 1.0.6 ).
3. Finding Error Handling Bugs in OpenSSL using Coccinelle.
4. Hunting bugs with Coccinelle.
5. GitHub Conccinelle Repo.
6. Examples.
7. More examples.

StackOverflow Threads:

• Pointer issues in Coccinelle.
• Limit Coccinelle matches to expression of given type .
• Match arbitrary-depth nested fields in struct in Coccinelle.
• Detect passing pointer to uninitialized variable.
• Coccinelle help to replace a function with variable args.
• What is the correct type to use for declaring a metavariable that possibly could match either variables or members in a struct?.
• C: Convert A ? B : C into if (A) B else C.
• coccinelle: replace single letter variables (i -> ii).
• Adding missing NULL checks after malloc with coccinelle.

Briefly...

Coccinelle is a program matching and transformation engine which provides the language SmPL (Semantic Patch Language) for specifying desired matches and transformations in C code. -- Coccinelle website.

Coccinelle allows you to "templatize" patches so that they can be applied over an entire codebase and match the same "pattern" in a way that abstracts out things like whitespace, variable names etc.

All Coccinelle scripts look something like this:

@@
// Metavariable declarations
@@

// Transformations

Metavariables allow you to abstract out things like types, expressions, statements etc. The transformations dictate how the code should be changed.

Run Spatch

Check your COCCI script: spatch --parse-cocci mysp.cocci

Run your COCCI script:spatch --sp-file mysp.cocci file.c or spatch --sp-file mysp.cocci --dir directory.

An Example...

An example I had recently was very similar to the ARRAY_SIZE() example. There were many places in the code where I was doing sizeof(ptr->field) / sizeof(byte_t), where ptr could be any variable name that refers to a struct pointer and field could be any member of that struct. It could appear anywhere in the code as say size_t num_blocks = sizeof(new_block->info) / sizeof(byte_t), or PrintBlockInfo(some_block, sizeof(some_block->data) / sizeof(byte_t)), for example. I wanted to be able to transform each of these to size_t num_blocks = NBLOCKS(new_block->data) and PrintBlockInfo(some_block, NBLOCKS(some_block->info)), respectively.

These transformations are not something that could be easily accomplished with a regular expression. One immediate problem is that in sizeof(ptr->field) / sizeof(byte_t), ptr needs to be of the type block_descr_t. Changing this for other types might not be the correct thing to do, and certainly would read strangely for non-block types. Coccinelle to the rescue!

@@
typedef block_descr_t;
typedef byte_t;
block_descr_t *T;
identifier F;
@@

- sizeof(T->F) / sizeof(byte_t) //< Coccinelle is clever - it knows T must be of type ...
+ NBLOCKS(F)                    //< ... `block_descr_t` to match :) 

Lets create the following test file:

typedef unsigned char byte_t;
typedef struct { byte_t header; byte_t crc[2]; } block_info_t;
typedef struct { byte_t crc[2], byte_t data[20]; } block_data_t;
typedef struct { block_info_t info; block_data_t data; } block_descr_t;

void func(block_descr_t *desc)
{
	const size_t num_blocks = sizeof(desc->info) / sizeof(byte_t);

	struct { byte_t byte_array[5]; } not_a_block;
	const size_t just_bytes = sizeof(not_a_block->byte_array) / sizeof(byte_t);
}

void dump_block(block_descr_t *desc)
{
	for (size_t idx = 0; idx < sizeof(desc->info) / sizeof(byte_t); ++idx)
	{
		printf("%u", desc->info[idx]);
	}
}

void dump_block_stats(block_descr_t *desc)
{
	printf("At line %u, num data|info blocks: %u|%u\n", 
		__LINE__,
		sizeof(desc->data) / sizeof(byte_t),
		sizeof(desc->info) / sizeof(byte_t));
}

If we run the Coccinelle script on the above C file (minus the annotation comments) we get the following diff produced:

$ spatch -sp_file junk.cocci junk.c
init_defs_builtins: /usr/lib/coccinelle/standard.h
HANDLING: junk.c
diff =
--- junk.c
+++ /tmp/cocci-output-11849-4d0df1-junk.c
@@ -5,12 +5,12 @@ typedef struct { block_info_t info; bloc

 void func(block_descr_t *desc)
 {
-    const size_t num_blocks = sizeof(desc->info) / sizeof(byte_t);
+    const size_t num_blocks = NBLOCKS(info);

     struct { byte_t byte_array[5]; } not_a_block;
     const size_t just_bytes = sizeof(not_a_block->byte_array) / sizeof(byte_t);
 }

 void dump_block(block_descr_t *desc)
 {
-    for (size_t idx = 0; idx < sizeof(desc->info) / sizeof(byte_t); ++idx)
+    for (size_t idx = 0; idx < NBLOCKS(info); ++idx)
     {
         printf("%u", desc->info[idx]);
     }
@@ -20,6 +20,6 @@ void func2(block_descr_t *desc)
 {
     printf("At line %u, num data|info blocks: %u|%u\n",
         __LINE__,
-        sizeof(desc->data) / sizeof(byte_t),
-        sizeof(desc->info) / sizeof(byte_t));
+        NBLOCKS(data),
+        NBLOCKS(info));
 }

So, we can see that the replacement has been made intelligently in multiple different contexts and it has also only done the replacement for the desired type too - note how not_a_block has correctly not been transformed. Sweeeet!

The Whole Transformation Is A Match

The whole of the transformation section has to match for the transformation to be applied. This is what I meant by a "templatized" patch.

Lets have a look at an example of removing the cast from calls to malloc():

@@
type I;
expression E;
identifier p;
@@

-I *p = (I *)malloc(E);
+I *p = malloc(E); 

Applying this to the following file will remove the cast:

int main(void)
{
    int *some_int_prt = (int *)malloc(10 * sizeof(int));
    // ^^^ The patch will replace the above with
    // int *some_int_prt = malloc(10 * sizeof(int));

    return 0;
}

Let's modify the patch as follows - its contrived but hey:

@@
type I;
expression E, E2;
identifier p, p2;
@@

I p2 = E2; // < We've artificially added this line for the example's sake.

-I *p = (I *)malloc(E);
+I *p = malloc(E); 

Apply this to the above C file and nothing happens - no patch is created. Why? The reason is that the whole patch must be able to match some section of the program it is applied over. In the C file above, although the malloc() line will match the second rule, there is nothing matching the first rule, I p2 = E2.

The above patch would only modify a file that looked like this:

int main(void)
{
    int variable_1 = 2; // < This line is necessary so that the second patch file can match!

    int *some_int_prt = (int *)malloc(10 * sizeof(int));
    // ^^^ The patch will replace the above with
    // int *some_int_prt = malloc(10 * sizeof(int));

    return 0;
}

The patch would not, however, match this file:

int main(void)
{
    int variable_1 = 2; //< This line is necessary so that the second patch file can match!

    call_some_function();

    int *some_int_prt = (int *)malloc(10 * sizeof(int));
    // ^^^ The patch will replace the above with
    // int *some_int_prt = malloc(10 * sizeof(int));

    return 0;
}

It does not find a match for precisely the sale reason - call_some_function() does not appear in the semantic patch between the first integer variable declaration and the pointer declaration and assignment. To make it match we would have to use ellipses (...) to match arbitrary code between the first integer declaration and the pointer declaration:

@@
type I;
expression E, E2;
identifier p, p2;
@@

I p2 = E2; //< We've artificially added this line for the example's sake.
... //< Match arbirary program flow
-I *p = (I *)malloc(E);
+I *p = malloc(E); 

Types Of Metavariables

@@
type I;
identifier D;
@@
- I *D = (I *)malloc(...);
+ I *D = malloc(...);

Rules

@@
// Meta variables
@@

// Transformations

@rulename@
// Meta variables
@@

// Transformations

@includes_kernel_h@
@@

#include <linux/kernel.h>

@depends on includes_kernel_h@
type T;
T[] E;
@@

- (sizeof(E)/sizeof(*E))
+ ARRAY_SIZE(E)

Dots

int main(void)
{
   Special_t a =  {
      // Arbitrary initialisation;
      .m1 = 10,
      .m2 = 20,
   };

   printf("Any amount of arbitrary code can go here!\n") ;
   a.m3 = rand();
   if (a.m2 == a.m3) {
      printf("You got lucky :)\n");
   }

   some_func(&a, &a);

   return 0;
}

@@
Type T;
identifier var, var2;
identifier some_func;
@@

T var = ...;
...
- some_func(&var, &var2);
+ another_newer_func(&var, &var2, false);

--- test.c
      +++ /tmp/cocci-output-22579-7874ae-test.c
      @@ -9,6 +9,6 @@ int main(void)
              printf("You got lucky :)\n");
          }
      
      -   some_func(&a, &a);
      +   another_newer_func(&a, &a, false);
          return 0;
       }

Positions