Overview

Module eqc_c

• Description
• Data Types
• Function Index
• Function Details

Copyright © Quviq AB, 2009-2023

Version: 1.46.3

Description

This module provides functions for testing code written in C.

The purpose of this module is to make it easy to test C programs with QuickCheck. To do this it provides a way to call C functions from Erlang together with a number of functions to manipulate C values.

Introduction

 // Add two integers
 int plus (int x, int y) {
   return x + y;
 }

 // Sum an array of integers
 int sum (int *array, int len) {
   int n;
   int sum = 0;
   for (n = 0; n < len; n++)
     sum += array[n];
   return sum;
 } 

 1> eqc_c:start(example).
 ok 

 2> example:plus(3, 4).
 7 

 3> P = eqc_c:create_array(int, [1, 2, 3, 4]).
 {ptr,int,1048864}
 4> example:sum(P, 4).
 10
 

Details

• The specified C source is compiled together with some generated code and a C library provided with the QuickCheck distribution to produce a binary executable. This executable is started and communicates with the Erlang system using file descriptors 3 and 4 for input and output, respectively (except on Windows systems, where stdin and stdout are used). This means that if the C code uses these file descriptors for anything the interface might not work.
• An Erlang module with the specified name is loaded, containing Erlang wrappers for the functions in the C program (see start/2 for information on how to specify for which functions to create wrappers). These functions will pass their arguments (after type checking them) to the compiled C program and return the result of calling the corresponding C function. See the definition of the supported C types for how C values are represented in Erlang.
• An Erlang header file with the same name as the generated Erlang module is created in the current directory containing record definitions for the C structs that appear in the source file.

Global variables

To access global variables appearing in the C program, the following functions are provided: address_of/1, value_of/1, and set_value/2. The address_of/1 function gives you a pointer to the global variable of the specified name, and can also be used to get pointers to exported functions. value_of/1 and set_value/2 allows you to get and set the value of a global variable.

Working with arrays

 int xs[3] = {1, 2, 3};
 struct arr { int ys[2]; };
 

 3> eqc_c:value_of(xs).
 [1,2,3]
 4> eqc_c:alloc({struct, arr}, {arr, [4,5]}).
 {ptr,{struct,arr},4297064576}
 

 int sum(int a[2])
 {
   return a[0] + a[1];
 }
 

 5> eqc_c:type_of(sum).
 {func,int,[{ptr,{array,int}}]}
 

 6> P = eqc_c:create_array(int, [7,11]).
 {ptr,int,4297064592}
 7> example:sum(P).
 18
 

Note that a pointer to an integer is happily accepted as a pointer to an array of integers.

 void hello(char *s)
 {
   printf("Hello %s!\n", s);
 }
 

 8> example:hello("world").
 Hello world!
 ok
 

 9> example:hello(eqc_c:create_string("world")).
 Hello world!
 ok
 

Note that values created in this way will not be freed and can thus cause a memory leak.

Badly behaved C programs

 5> eqc_c:deref({ptr, int, 0}).
 ** exception error: bus_error 

In the case of a looping C program a timeout exception is raised in the Erlang process. The timeout value can be set when starting the C program (see start/2) or using set_timeout/1. Note: when a timeout occurs a new instance of the C program is started and will be used for subsequent function calls, but the old instance is still running, possibly consuming a lot of resources.

Current limitations

At the moment there is no support for functions with variable arity. These can appear in your C program, but you will not be able to call functions with variable arity from Erlang.

Data Types

ptr()

ptr() = {ptr, type(), integer()} | 'NULL'

The value of a C pointer. Contains the memory address as well as the type of the value pointed to.

type()

type() = void | bool | char | unsigned_char | short | unsigned_short | int | unsigned_int | long | unsigned_long | long_long | unsigned_long_long | int128 | unsigned_int128 | float | double | long_double | float128 | complex_float | complex_double | complex_long_double | {ptr, type()} | {func, type(), [type()]} | {closure, type(), [type()]} | {array, integer(), type()} | {array, type()} | {struct, atom()} | {union, atom()} | {enum, atom()} | string()

Supported C types.

• void can only appear as the target of a pointer or as a return type for a function.
• bool is the boolean type from stdbool.h (C99) and is represented in Erlang by the atoms true and false.
• char, unsigned_char, short, unsigned_short, int, unsigned_int, long, unsigned_long, long_long, unsigned_long_long, int128, and unsigned_int128 are represented in Erlang as integers.
• float, double, long_double , and float128 are represented as Erlang floats. Note: depending on the platform, precision may be lost for long doubles.
• complex_float, complex_double, and complex_long_double are represented as pairs of Erlang floats, with the first component being the real part and the second component the imaginary part.
• A pointer of type {ptr, T} is represented as a ptr() with the type field set to T.
• The type {func, Ret, Args} is the type of a function returning a value of type Ret (possibly void) and whose arguments have types Args. Function types can only appear as targets of pointers.
• A closure (or block) type {closure, Ret, Args} has the same shape as a function type. Closures are supported by some C compilers, for instance gcc on MacOS X 10.6.
• The value of an array type {array, T} or {array, Len, T} is represented in Erlang as a list of values of type T. If a length Len is specified the list should have Len elements. See working with arrays above for more details.
• Values of a struct type are represented as values of an Erlang record with the same name and corresponding fields. For instance, the C struct

   struct coord {
     int x, y;
   };     

  is modelled by the Erlang record

   -record(coord, {x, y}). 

  For anonymous structs a name is chosen depending on how the struct is defined. In particular, if it is defined inside a typedef it gets the name of the introduced type. For instance, the definition

   typedef struct {
     int x, y;
   } coord; 

  will result in the same Erlang record being generated as in the previous example.
• Union type values are represented in the same way as struct values--with a record containing a field for each variant of the union. When getting a union value from C all the fields will be populated. On the other hand, when passing a union value to the C code only a single field should be set and the others should be eqc_c_undefined, which is the default value. For example, given the C code

   union u {
     int x;
     bool y;
   };
   union u i = { .x = 0 }; 

  we could have the following interaction

   5> eqc_c:value_of(i).
   #u{x = 0,y = false}
   6> eqc_c:set_value(i, #u{y = true}).
   ok
   7> eqc_c:value_of(i).
   #u{x = 1,y = true} 

  For convenience it is also allowed to pass a value matching one of the variants as a union value. So, in place of the set_value call above we could write

   6> eqc_c:set_value(i, true).
   ok 

• Values of enumeration types are represented as atoms. For instance, the values of the enumeration type

   enum colour { red, green, blue }; 

  are the atoms red, green, and blue.
• Defined types are introduced by typedefs in the C code and can be used interchangeably with their definitions. For instance, given

   typedef int MyInt; 

  we can call

   1> eqc_c:alloc("MyInt", 17).
   {ptr,int,2097440} 

  Note how the typedef has been expanded in the value of the pointer.

Function Index

Function Details

add_to_ptr/2

Add N to a pointer. Equivalent to Ptr += N in C. In other words the value of the resulting pointer depends on the size of the type pointed to.

address_of/1

Get a pointer to a C function or global variable.

alloc/1

Allocate memory for an object of type Type. The allocated memory is initialized with zeroes.

alloc/2

Allocate memory for an object of type Type and initialize it to the value X. Type checks the value before allocating the memory.

array_index/2

Return the value at the given index of an array. Equivalent to the C code Ptr[Index]. Indexing starts at index 0.

array_index/3

Set the value at the given index of an array. Equivalent to the C code Ptr[Index] = Val. Indexing starts at index 0.

cast_ptr/2

Change the type of a pointer. Equivalent to the C code (Type *)Ptr. Note: This is unsafe and should be used with care.

create_array/2

Allocate an array of the given type containing the values Xs. The values are type checked before allocation.

create_string/1

Allocate a C string containing the given string.

deref/1

Dereference a pointer.

expand_type/1

Expand all type definitions in a type.

free/1

Free the memory pointed to by a pointer. Equivalent to the C code free(Ptr).

read_array/2

Read the elements of an array. Since C arrays do not store their length, the length has to be supplied separately.

read_string/1

Read the value of a null terminated C string.

restart/0

Restart the C program. Just restarts the executable, no recompilation is performed.

running/0

Check if the C program is running.

set_timeout/1

Set the timeout for C function calls to N milliseconds. Can also be set from start/2.

set_value/2

Equivalent to store(address_of(X), V).

Set the value of a global variable.

sizeof/1

The size in bytes required to store an object of the given type. Equivalent to sizeof(Type) in C.

start/1

Equivalent to start(Module, [definitions_only]).

start/2

Set up an interface to a given C file. Generates and loads an Erlang wrapper Module for the C file specified by the c_src option (atom_to_list(Module) ++ ".c" by default). For instance, if foo.c defines a function int plus(int x, int y), calling eqc_c:start(foo, []) allows plus to be called as foo:plus(1, 2).

{c_src, string()}

The name of the C source file (default: atom_to_list(Module) ++ ".c").

definitions_only

Only generate wrappers for function definitions (and not function prototypes).

{exclude_functions, [atom() | string()]}

Do not generate wrappers for the specified functions.

{include_functions, [atom() | string()]}

Only generate wrappers for the specified functions.

keep_files

Don't remove temporary files

{hrl, string() | none}

The name of the Erlang header file to be created containing generated record definitions, or none if no file should be created (default: atom_to_list(Module) ++ ".hrl").

{rename, [{CName::atom() | string(), ErlName::atom() | string()}]}

Give specific Erlang names to certain C functions. Multiple C functions can be given the same Erlang name. If they have different number of arguments, Erlang already treats them as distinct functions. In case multiple functions with the same arity are overloaded, there is a runtime disambiguation based on the arguments passed to the function. More precisely, if the given arguments type check against the argument types of exactly one of the overloaded functions, this function gets called, otherwise an error is raised.

{timeout, integer()}

Specify the timeout (in milliseconds) for C function calls (default 500 ms).

{casts, atom() | [atom()]}

Specify callback modules for performing runtime conversions of C values. The given modules should export two functions to_c/2 and from_c/2, which given a C type and a value performs the desired conversions. The functions should throw an exception for types that are not to be converted.

A typical use case is when the C program could have used an enum type, but didn't. For instance, if the C code defines

 typedef int Answer;
 #define YES 1
 #define NO  0

a casts module might define

 to_c("Answer", yes) -> 1;
 to_c("Answer", no)  -> 0.

 from_c("Answer, 1) -> yes;
 from_c("Answer, 0) -> no.

See also the eqc_c_enum module for a tool to generate to_c and from_c functions in cases like this one.

verbose

Print the commands used to build the C code.

silent

Don't print warnings and errors from the C compiler.

return_error

Return an error tuple with the error message from the C compiler on failure.

{cc, string()}

Specifies how to call the C compiler (default: gcc).

{cpp, string()}

Specifies how to call the C preprocessor (default: gcc).

{coutput_flag, string()}

The flag to specify the output file of the C compiler (default: "-o").

{cmacro_flag, string()}

The flag to pass to the C compiler to define a preprocessing macro (default: "-D").

{cflags, string()}

Additional flags to the C compiler.

{cppflag, string()}

Specifies the flag to use when preprocessing (default: "-E").

{cppflags, string()}

Additional flags to the C preprocessor.

{wrapper_src, string()}

Specifies the location of the C wrapper library (default: filename:join(code:lib_dir(eqc,include),"eqc_c_lib.c").

{additional_files, [string()]}

Additional files (C sources or object files) to compile or link.

{exec_command_line, fun((string()) -> {string(), [string()]})}

Specifies the command line to start up the C executable as a function from the name of the generated executable to a pair of the program to run and a list of its arguments (default: fun(Exe) -> {Exe, []} end). For instance, to start up the C program with Valgrind you can use fun(Exe) -> {os:find_executable("valgrind"), [Exe]} end.

start_functions/2

Equivalent to start(Module, [{include_functions, Functions}]).

stop/0

Stop the C program.

store/2

Store a value at the location pointed to by a pointer. Equivalent to the C code *Ptr = Val. The value is type checked against the type of the pointer.

type_info/1

Get information on a type. For defined types, type_info returns the definition without expanding nested typedefs (to get the fully expanded type use expand_type/1). For struct and union types, the list of fields is returned, where each field is a pair of a type and a field name. For enum types, the list of tags is returned.

type_of/1

Equivalent to type_of(X, false).

Get the type of a C function or global variable.

type_of/2

Get the type of a C function or global variable. If Expand is true, type definitions are unfolded. For instance, given the C program

 typedef unsigned int UINT;
 UINT some_int = 42;
 

 2> eqc_c:type_of(some_int, true).
 unsigned_int
 3> eqc_c:type_of(some_int, false).
 "UINT"
 

value_of/1

Equivalent to deref(address_of(X)).

Get the value of a global variable.

write_array/2

Store values in the array pointed to be the first argument. The values are type checked against the type of the pointer.

Overview

Generated by EDoc