Difference between revisions of "C API"

From CRIU
Jump to navigation Jump to search
m
m (→‎set service address: apply documentation change proposed in https://github.com/checkpoint-restore/criu/issues/1954)
 
(22 intermediate revisions by 6 users not shown)
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>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 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/checkpoint-restore/criu/tree/criu-dev/test/others/libcriu test/others/libcriu].
 +
 
 +
[[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.svg 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.svg 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.
Note.svg Note: images_dir_fd is required at dump/restore, all other options might be left unset.

The client must open directory for/with images by itself and set images_dir_fd to the opened directory fd. CRIU will open /proc/client_pid/fd/images_dir_fd, 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:

# 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.