509
edits
Changes
mLine 1:
Line 1: − + − + Line 7:
Line 7: − + Line 17:
Line 17: − + − + Line 33:
Line 33: − + + + Line 40:
Line 42: − + − + − + Line 58:
Line 60: − + + + + + + + + + + + + + + + + + + + − == check/dump/restore ==+ − Use this functions to check/dump/restore:+ − <pre> − − int criu_dump(void); − int criu_restore(void); − </pre> − + + + Line 84:
Line 101: − + − + Line 114:
Line 131: − + + + +
→set service address: apply documentation change proposed in https://github.com/checkpoint-restore/criu/issues/1954
'''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>.
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 ===
=== 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 */
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.
{{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");
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 ===
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);
int criu_check(void);
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"
|-
|-
| >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.
== 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]]