C API

2016-08-23T02:07:17Z

Kkantor: /* Examples */

'''libcriu''' is a C API for CRIU, which is 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 <code>lib/criu.h</code>.

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

{{Warning|The library is not thread- and fork- safe}}

== Preparation ==

=== init options ===

Call <code>int criu_init_opts(void)</code> to initialize request options.

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

=== set service address ===

Use <code>void criu_set_service_address(char *address)</code> to specify path to a CRIU service socket. Call it with NULL to make libcriu use the default address (currently <code>/var/run/criu_service.socket</code>).

=== set dump/restore options ===
Use <code>criu_set_*</code> functions to setup dump/restore options.

<source lang="c">
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);
</source>

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|<code>images_dir_fd</code> is '''required''' at dump/restore, all other options might be left unset.
The client must open directory for/with images by itself and set <code>images_dir_fd</code> to the opened directory fd.
CRIU will open <code>/proc/''client_pid''/fd/''images_dir_fd''</code>, 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:
<source lang="c">
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();
</source>

== 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:
{| class="wikitable"
|-
! Return value
! errno
! Description

|-
| 0
| undefined
| Success

|-
| >0
| undefined
| Success (<code>criu_restore()</code> only)

|-
| -EBADE
| RPC error (if provided(see [https://github.com/xemul/criu/blob/master/include/cr-errno.h#L8 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 [https://github.com/xemul/criu/tree/master/test/others/libcriu test/others/ibcriu].

[[Category: API]]

CRIU - User contributions [en]

C API