Contents

C interop using dart:ffi

Dart mobile, command-line, and server apps running on the Dart Native platform can use the dart:ffi library to call native C APIs. FFI stands for foreign function interface. Other terms for similar functionality include native interface and language bindings.

API documentation is available from the dev channel: dart:ffi API reference.

Examples

The following examples show how to use the dart:ffi library:

Example Description
hello_world How to call a C function with no arguments and no return value.
primitives How to call C functions that have arguments and return values that are ints or pointers. Also demonstrates varargs.
structs How to use structs to pass strings to and from C and to handle simple and complex C structures.
sqllite An example in the Dart SDK repo that comes with a mini tutorial.

Walkthrough of hello_world

The hello_world example has the minimum necessary code for calling a C library.

Files

The hello_world example has the following files:

Source file Description
hello.dart A Dart file that uses the hello_world() function from a C library.
pubspec.yaml The usual Dart pubspec, with a lower bounds on the SDK that’s at least 2.5.
c/hello.h Declares the hello_world() function.
c/hello.c A C file that imports hello.h and defines the hello_world() function.
c/Makefile A macOS-specific build file that compiles the C code into a dynamic library.

Building the C library creates two additional files:

Generated file Description
hello_world.dylib The dynamic library loaded by the Dart app.
c/hello.o An intermediate object file.

Building and running

Here’s an example of building the dynamic library and executing the Dart app:

$ cd c
$ make dylib
gcc -dynamiclib -undefined suppress -flat_namespace hello.o -o ../hello_world.dylib
$ cd ..
$ dart hello.dart
Hello World
$

Using dart:ffi

The hello.dart file illustrates the steps for using dart:ffi to call a C function:

  1. Import dart:ffi.
  2. Create a typedef with the FFI type signature of the C function.
  3. Create a typedef for the variable that you’ll use when calling the C function.
  4. Open the dynamic library that contains the C function.
  5. Get a reference to the C function, and put it into a variable.
  6. Call the C function.

Here’s the code for each step.

  1. Import dart:ffi.
    import 'dart:ffi' as ffi;
    
  2. Create a typedef with the FFI type signature of the C function.
    Commonly used types defined by dart:ffi library include Double, Int32, NativeFunction, Pointer, Struct, Uint8, and Void.
    typedef hello_world_func = ffi.Void Function();
    
  3. Create a typedef for the variable that you’ll use when calling the C function.
    typedef HelloWorld = void Function();
    
  4. Open the dynamic library that contains the C function.
      final dylib = ffi.DynamicLibrary.open('hello_world.dylib');
    
  5. Get a reference to the C function, and put it into a variable. This code uses the typedefs defined in steps 2 and 3, along with the dynamic library variable from step 4.
      final HelloWorld hello = dylib
       .lookup<ffi.NativeFunction<hello_world_func>>('hello_world')
       .asFunction();
    
  6. Call the C function.
      hello();
    

Once you understand the hello_world example, you should be ready to look at the other dart:ffi examples.

Bundling and loading C libraries

How you bundle (or package or distribute) a C library with your package or app and then load that library depends on your platform and the type of library. For details, see the following: