Difference between revisions of "C API"
(Update link to GIT repo) |
m (→set service address: apply documentation change proposed in https://github.com/checkpoint-restore/criu/issues/1954) |
||
(7 intermediate revisions by 4 users not shown) | |||
Line 1: | Line 1: | ||
− | '''libcriu''' is a C API for CRIU, | + | '''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. |
== Introduction == | == Introduction == | ||
Line 6: | Line 6: | ||
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. | ||
− | |||
− | |||
== Preparation == | == Preparation == | ||
Line 19: | 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>/ | + | 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 === | ||
Line 36: | Line 34: | ||
void criu_set_log_file(char *log_file); | void criu_set_log_file(char *log_file); | ||
</source> | </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 131: | Line 131: | ||
== Examples == | == Examples == | ||
− | You could find example of using libcriu at [https://github.com/ | + | 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: API]] | ||
+ | [[Category: Outdated]] |
Latest revision as of 04:30, 5 August 2022
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.
Introduction[edit]
libcriu functions are defined in lib/criu.h
.
To create a library lib/libcriu.so
, run make
in the main directory.
Preparation[edit]
init options[edit]
Call int criu_init_opts(void)
to initialize request options.
Note: it should be called before using any other functions from libcriu, except criu_check()
. Also you should use it to reinitialize options. It returns 0 on success and -1 on fail.
set service address[edit]
Use void criu_set_service_address(char *address)
to specify path to a CRIU service socket. Call it with NULL to make libcriu use the default address (currently criu_service.socket
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 criu service --address /path/to/criu_service.socket
. The path given in this command is the path that needs to be passed to criu_set_service_address
.
set dump/restore options[edit]
Use criu_set_*
functions to setup dump/restore options.
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);
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.
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. |
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:
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();
Operations[edit]
Use the following functions to perform CRIU actions.
check[edit]
int criu_check(void);
dump[edit]
int criu_dump(void);
restore[edit]
int criu_restore(void);
restore as a child[edit]
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[edit]
Here is a table of return and errno values of the above functions:
Return value | errno | Description |
---|---|---|
0 | undefined | Success |
>0 | undefined | Success (criu_restore() only)
|
-EBADE | RPC error (if provided(see 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[edit]
You could find example of using libcriu at test/others/libcriu.