1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
=head1 NAME
nbd_aio_cache - send cache (prefetch) command to the NBD server
=head1 SYNOPSIS
#include <libnbd.h>
typedef struct {
int (*callback) (void *user_data, int *error);
void *user_data;
void (*free) (void *user_data);
} nbd_completion_callback;
int64_t nbd_aio_cache (
struct nbd_handle *h, uint64_t count,
uint64_t offset,
nbd_completion_callback completion_callback,
uint32_t flags
);
=head1 DESCRIPTION
Issue the cache (prefetch) command to the NBD server.
To check if the command completed, call L<nbd_aio_command_completed(3)>.
Or supply the optional C<completion_callback> which will be invoked
as described in L<libnbd(3)/Completion callbacks>.
Other parameters behave as documented in L<nbd_cache(3)>.
By default, libnbd will reject attempts to use this function with
parameters that are likely to result in server failure, such as
requesting an unknown command flag. The L<nbd_set_strict_mode(3)>
function can be used to alter which scenarios should await a server
reply rather than failing fast.
=head1 RETURN VALUE
This call returns the 64 bit cookie of the command.
The cookie is E<ge> C<1>.
Cookies are unique (per libnbd handle, not globally).
=head1 ERRORS
On error C<-1> is returned.
Refer to L<libnbd(3)/ERROR HANDLING>
for how to get further details of the error.
The following parameters must not be NULL: C<h>.
For more information see L<libnbd(3)/Non-NULL parameters>.
=head1 HANDLE STATE
nbd_aio_cache
can be called when the handle is in the following state:
┌─────────────────────────────────────┬─────────────────────────┐
│ Handle created, before connecting │ ❌ error │
│ Connecting │ ❌ error │
│ Connecting & handshaking (opt_mode) │ ❌ error │
│ Connected to the server │ ✅ allowed │
│ Connection shut down │ ❌ error │
│ Handle dead │ ❌ error │
└─────────────────────────────────────┴─────────────────────────┘
=head1 VERSION
This function first appeared in libnbd 1.0.
If you need to test if this function is available at compile time
check if the following macro is defined:
#define LIBNBD_HAVE_NBD_AIO_CACHE 1
=head1 SEE ALSO
L<nbd_aio_command_completed(3)>,
L<nbd_cache(3)>,
L<nbd_can_cache(3)>,
L<nbd_create(3)>,
L<nbd_set_strict_mode(3)>,
L<libnbd(3)/Issuing asynchronous commands>,
L<libnbd(3)>.
=head1 AUTHORS
Eric Blake
Richard W.M. Jones
=head1 COPYRIGHT
Copyright Red Hat
|
