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 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. | + | '''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 == |
| | | |
| libcriu functions are defined in <code>lib/criu.h</code>. | | libcriu functions are defined in <code>lib/criu.h</code>. |
Line 7: |
Line 7: |
| To create a library <code>lib/libcriu.so</code>, run <code>make</code> in the main directory. | | To create a library <code>lib/libcriu.so</code>, run <code>make</code> in the main directory. |
| | | |
− | == Setup options == | + | == Preparation == |
| | | |
| === init options === | | === init options === |
Line 17: |
Line 17: |
| === set service address === | | === 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>). | + | 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>criu_service.socket</code> in the local directory). Note that a CRIU service must be running at that address for the C API to work; you cannot use the C API standalone. To start a CRIU service, run <code>criu service --address /path/to/criu_service.socket</code>. The path given in this command is the path that needs to be passed to <code>criu_set_service_address</code>. |
| | | |
| === set dump/restore options === | | === set dump/restore options === |
| Use <code>criu_set_*</code> 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 33: |
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> |
| + | |
| + | {{Note|This set of calls is not thread safe! For thread safety the same calls with _local suffix should be used}} |
| | | |
| If no pid is set on dump, CRIU will dump the calling process itself. | | If no pid is set on dump, CRIU will dump the calling process itself. |
Line 40: |
Line 42: |
| {{Note|<code>images_dir_fd</code> is '''required''' at dump/restore, all other options might be left unset. | | {{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. | | 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 even if the client is in another namespace.}} | + | 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: |
| | | |
− | #criu restore -D /path/to/imgs_dir -v4 -o restore.log | + | # 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 58: |
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); |
| + | |
| + | === restore === |
| + | |
| + | int criu_restore(void); |
| + | |
| + | === restore as a child === |
| | | |
− | == check/dump/restore ==
| + | 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]]). |
| | | |
− | Use this functions to check/dump/restore:
| + | int criu_restore_child(void); |
− | <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: | + | === Return values === |
| + | |
| + | Here is a table of return and errno values of the above functions: |
| {| class="wikitable" | | {| class="wikitable" |
| |- | | |- |
Line 84: |
Line 101: |
| | >0 | | | >0 |
| | undefined | | | undefined |
− | | Success(criu_restore() only) | + | | Success (<code>criu_restore()</code> only) |
| | | |
| |- | | |- |
| | -EBADE | | | -EBADE |
− | | RPC error(if provided, 0 otherwise) | + | | 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 114: |
Line 131: |
| == Examples == | | == Examples == |
| | | |
− | You could find example of using libcriu at test/libcriu. | + | You could find example of using libcriu at [https://github.com/checkpoint-restore/criu/tree/criu-dev/test/others/libcriu test/others/libcriu]. |
| + | |
| + | [[Category: API]] |
| + | [[Category: Outdated]] |