C API

libcriu is a C API for CRIU, a simple wrapper around our RPC. Although you can use RPC directly, libcriu is a wrapper providing the interface that is much easier to use from C code. Note that RPC is supported in the first place, and if you want the most recent set of features you should probably use RPC directly.

Introduction

libcriu functions are defined in lib/criu.h.

To create a library lib/libcriu.so, run make in the main directory.

Preparation

init options

Call int criu_init_opts(void) to initialize request options.

Note: it should be called before using any other functions from libcriu, except criu_check(). Also you should use it to reinitialize options. It returns 0 on success and -1 on fail.

set service address

Use void criu_set_service_address(char *address) to specify path to a CRIU service socket. Call it with NULL to make libcriu use the default address (currently criu_service.socket in the local directory). Note that a CRIU service must be running at that address for the C API to work; you cannot use the C API standalone. To start a CRIU service, run criu service --address /path/to/criu_service.socket. The path given in this command is the path that needs to be passed to criu_set_service_address.

set dump/restore options

Use criu_set_* functions to setup dump/restore options.

void criu_set_pid(int pid);
void criu_set_images_dir_fd(int fd); /* must be set for dump/restore */
void criu_set_leave_running(bool leave_running);
void criu_set_ext_unix_sk(bool ext_unix_sk);
void criu_set_tcp_established(bool tcp_established);
void criu_set_evasive_devices(bool evasive_devices);
void criu_set_shell_job(bool shell_job);
void criu_set_file_locks(bool file_locks);
void criu_set_log_level(int log_level);
void criu_set_log_file(char *log_file);

Note: This set of calls is not thread safe! For thread safety the same calls with _local suffix should be used

If no pid is set on dump, CRIU will dump the calling process itself.

Note: If a calling process is not run as root, the whole process tree to be dumped must have the same uid, otherwise CRIU refuses to dump. See Usage#Security.

Note: images_dir_fd is required at dump/restore, all other options might be left unset. The client must open directory for/with images by itself and set images_dir_fd to the opened directory fd. CRIU will open /proc/client_pid/fd/images_dir_fd, so it will work even if the client is in another namespace.

The logic of setting request is the same as when setting options in console. Here is an example:

# criu restore -D /path/to/imgs_dir -v4 -o restore.log

is equal to:

criu_init_opts();
criu_set_service_address("/path/to/criu/service/socket");

int fd = open("/path/to/imgs_dir", O_DIRECTORY);
criu_set_images_dir_fd(fd);

criu_set_log_file("restore.log");
criu_set_log_level(4);

criu_restore();

Operations

Use the following functions to perform CRIU actions.

check

int criu_check(void);

dump

int criu_dump(void);

restore

int criu_restore(void);

restore as a child

This one is special. It will fork and exec criu swrk (Service WoRKer) to allow restoring process as a caller child. Calling "exec" implies some restrictions, as, for example, one should make sure, that criu binary is present in PATH and has suid bit set (see Usage#Security).

int criu_restore_child(void);

Return values

Here is a table of return and errno values of the above functions:

Return value	errno	Description
0	undefined	Success
>0	undefined	Success (criu_restore() only)
-EBADE	RPC error (if provided(see include/cr-errno.h), 0 otherwise)	RPC has returned fail.
-ECONNREFUSED	errno	Unable to connect to CRIU.
-ECOMM	errno	Unable to send/recv msg to/from CRIU.
-EINVAL	undefined	CRIU doesn't support this type of request. You should probably update CRIU.
-EBADMSG	undefined	Unexpected response from CRIU. You should probably update CRIU.

Examples

You could find example of using libcriu at test/others/libcriu.