Changes

'''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]].

'''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.

== Beginning ==

== Beginning ==

You could find libcriu header at '''lib/criu.h'''.

 

To create '''lib/libcriu.so''' run '''make''' in the main directory.

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.

== Setup options ==

== Setup options ==

=== init 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.

 

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 ===

=== 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.

 

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 ===

=== set dump/restore options ===

Use criu_set_* functions to setup dump/restore options.

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

 

<pre>

<pre>

void criu_set_pid(int pid);

void criu_set_pid(int pid);

</pre>

</pre>

If no pid is set on dump, CRIU will dump client process by default.

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

'''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|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 may not be set.

{{Note|<code>images_dir_fd</code> is '''required''' at dump/restore, all other options might be left unset.

Client must open directory for/with images by himself and set images_dir_fd to it's fd.

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 /proc/<client's_pid>/fd/<images_dir_fd>, so it will work, if client is in another namespace.

CRIU will open /proc/<client's_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:

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

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

 

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

 

is equal to:

is equal to:

<pre>

<pre>

== check/dump/restore ==

== check/dump/restore ==

Use this functions to check/dump/restore:

Use this functions to check/dump/restore:

<pre>

<pre>

== Examples ==

== Examples ==

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

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