https://criu.org/api.php?action=feedcontributions&user=Kkantor&feedformat=atomCRIU - User contributions [en]2024-03-29T07:28:28ZUser contributionsMediaWiki 1.35.6https://criu.org/index.php?title=C_API&diff=3025C API2016-08-23T02:07:17Z<p>Kkantor: /* Examples */</p>
<hr />
<div>'''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.<br />
<br />
== Introduction ==<br />
<br />
libcriu functions are defined in <code>lib/criu.h</code>.<br />
<br />
To create a library <code>lib/libcriu.so</code>, run <code>make</code> in the main directory.<br />
<br />
{{Warning|The library is not thread- and fork- safe}}<br />
<br />
== Preparation ==<br />
<br />
=== init options ===<br />
<br />
Call <code>int criu_init_opts(void)</code> to initialize request options.<br />
<br />
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.<br />
<br />
=== set service address ===<br />
<br />
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>).<br />
<br />
=== set dump/restore options ===<br />
Use <code>criu_set_*</code> functions to setup dump/restore options.<br />
<br />
<source lang="c"><br />
void criu_set_pid(int pid);<br />
void criu_set_images_dir_fd(int fd); /* must be set for dump/restore */<br />
void criu_set_leave_running(bool leave_running);<br />
void criu_set_ext_unix_sk(bool ext_unix_sk);<br />
void criu_set_tcp_established(bool tcp_established);<br />
void criu_set_evasive_devices(bool evasive_devices);<br />
void criu_set_shell_job(bool shell_job);<br />
void criu_set_file_locks(bool file_locks);<br />
void criu_set_log_level(int log_level);<br />
void criu_set_log_file(char *log_file);<br />
</source><br />
<br />
If no pid is set on dump, CRIU will dump the calling process itself.<br />
{{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]].}}<br />
<br />
{{Note|<code>images_dir_fd</code> is '''required''' at dump/restore, all other options might be left unset.<br />
The client must open directory for/with images by itself and set <code>images_dir_fd</code> to the opened directory fd.<br />
CRIU will open <code>/proc/''client_pid''/fd/''images_dir_fd''</code>, so it will work even if the client is in another namespace.}}<br />
<br />
The logic of setting request is the same as when setting options in console. Here is an example:<br />
<br />
# criu restore -D /path/to/imgs_dir -v4 -o restore.log<br />
<br />
is equal to:<br />
<source lang="c"><br />
criu_init_opts();<br />
criu_set_service_address("/path/to/criu/service/socket");<br />
<br />
int fd = open("/path/to/imgs_dir", O_DIRECTORY);<br />
criu_set_images_dir_fd(fd);<br />
<br />
criu_set_log_file("restore.log");<br />
criu_set_log_level(4);<br />
<br />
criu_restore();<br />
</source><br />
<br />
== Operations ==<br />
<br />
Use the following functions to perform CRIU actions.<br />
<br />
=== check ===<br />
<br />
int criu_check(void);<br />
<br />
=== dump ===<br />
<br />
int criu_dump(void);<br />
<br />
=== restore ===<br />
<br />
int criu_restore(void);<br />
<br />
=== restore as a child ===<br />
<br />
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]]).<br />
<br />
int criu_restore_child(void);<br />
<br />
=== Return values ===<br />
<br />
Here is a table of return and errno values of the above functions:<br />
{| class="wikitable"<br />
|-<br />
! Return value<br />
! errno<br />
! Description<br />
<br />
|-<br />
| 0<br />
| undefined<br />
| Success<br />
<br />
|-<br />
| >0<br />
| undefined<br />
| Success (<code>criu_restore()</code> only)<br />
<br />
|-<br />
| -EBADE<br />
| RPC error (if provided(see [https://github.com/xemul/criu/blob/master/include/cr-errno.h#L8 include/cr-errno.h]), 0 otherwise)<br />
| RPC has returned fail.<br />
<br />
|-<br />
| -ECONNREFUSED<br />
| errno<br />
| Unable to connect to CRIU.<br />
<br />
|-<br />
| -ECOMM<br />
| errno<br />
| Unable to send/recv msg to/from CRIU.<br />
<br />
|-<br />
| -EINVAL<br />
| undefined<br />
| CRIU doesn't support this type of request. You should probably update CRIU.<br />
<br />
|-<br />
| -EBADMSG<br />
| undefined<br />
| Unexpected response from CRIU. You should probably update CRIU.<br />
|}<br />
<br />
== Examples ==<br />
<br />
You could find example of using libcriu at [https://github.com/xemul/criu/tree/master/test/others/libcriu test/others/ibcriu].<br />
<br />
[[Category: API]]</div>Kkantor