C API

From CRIU
Revision as of 16:22, 18 December 2013 by Efiop (talk | contribs)
Jump to navigation Jump to search

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

Beginning

You could find libcriu header at lib/criu.h. To create lib/libcriu.so run make in the main directory.

Setup options

init options

Call int criu_init_opts(void) to init request options. Note: it should be called before using any other functions from libcriu except criu_check(). Also you should use it to reinit options. It return 0 on success and -1 on fail.

set service address

Use void criu_set_service_address(char *address) to specify path to CRIU service socket. Call it with NULL to make libcriu use default address: /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);

If no pid is set on dump, CRIU will dump client process by default. Note: Whole tree <pid> must have the same uid, as a client, or client's uid must be == 0, otherwise CRIU won't dump nothing at all. See Usage#Security.

Note: images_dir_fd is required at dump/restore, all other options may not be set. Client must open directory for/with images by himself and set images_dir_fd to it's fd. CRIU will open /proc/<client's_pid>/fd/<images_dir_fd>, so it will work, if 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();

check/dump/restore

Use this functions to check/dump/restore:

int criu_check(void);
int criu_dump(void);
int criu_restore(void);

Here is a table of return values and errno's of this functions:

Return value errno Description
0 undefined Success
>0 undefined Success(criu_restore() only)
-EBADE RPC error(if provided, for now undefined) 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/libcriu.