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 /var/run/criu_service.socket).
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 |
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.