Line 1: |
Line 1: |
− | '''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, 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 == | + | == Introduction == |
− | You could find libcriu header at '''lib/criu.h'''.
| |
− | To create '''lib/libcriu.so''' run '''make''' in the main directory.
| |
| | | |
− | == Setup options == | + | 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. |
| + | |
| + | == Preparation == |
| | | |
| === 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> | + | |
| + | <source lang="c"> |
| void criu_set_pid(int pid); | | void criu_set_pid(int pid); |
| void criu_set_images_dir_fd(int fd); /* must be set for dump/restore */ | | void criu_set_images_dir_fd(int fd); /* must be set for dump/restore */ |
Line 26: |
Line 33: |
| void criu_set_log_level(int log_level); | | void criu_set_log_level(int log_level); |
| void criu_set_log_file(char *log_file); | | void criu_set_log_file(char *log_file); |
− | </pre> | + | </source> |
| | | |
− | If no pid is set on dump, CRIU will dump client process by default.
| + | {{Note|This set of calls is not thread safe! For thread safety the same calls with _local suffix should be used}} |
− | '''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.
| + | If no pid is set on dump, CRIU will dump the calling process itself. |
− | Client must open directory for/with images by himself and set images_dir_fd to it's fd.
| + | {{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]].}} |
− | CRIU will open /proc/<client's_pid>/fd/<images_dir_fd>, so it will work, if client is in another namespace. | + | |
| + | {{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: | | 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> | + | <source lang="c"> |
| criu_init_opts(); | | criu_init_opts(); |
| criu_set_service_address("/path/to/criu/service/socket"); | | criu_set_service_address("/path/to/criu/service/socket"); |
Line 49: |
Line 60: |
| | | |
| criu_restore(); | | criu_restore(); |
− | </pre> | + | </source> |
| + | |
| + | == Operations == |
| + | |
| + | Use the following functions to perform CRIU actions. |
| + | |
| + | === check === |
| + | |
| + | int criu_check(void); |
| + | |
| + | === dump === |
| + | |
| + | int criu_dump(void); |
| | | |
− | == check/dump/restore == | + | === restore === |
− | Use this functions to check/dump/restore:
| |
− | <pre>
| |
− | int criu_check(void);
| |
− | int criu_dump(void);
| |
− | int criu_restore(void);
| |
− | </pre>
| |
| | | |
− | Here is a table of return values and errno's of this functions: | + | 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" | | {| class="wikitable" |
| |- | | |- |
Line 74: |
Line 101: |
| | >0 | | | >0 |
| | undefined | | | undefined |
− | | Success(criu_restore() only) | + | | Success (<code>criu_restore()</code> only) |
| | | |
| |- | | |- |
| | -EBADE | | | -EBADE |
− | | RPC error(if provided, for now undefined) | + | | 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. | | | RPC has returned fail. |
| | | |
Line 103: |
Line 130: |
| | | |
| == Examples == | | == Examples == |
− | You could find example of using libcriu at test/libcriu. | + | |
| + | You could find example of using libcriu at [https://github.com/xemul/criu/tree/master/test/others/libcriu test/others/ibcriu]. |
| + | |
| + | [[Category: API]] |
| + | [[Category: Outdated]] |