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
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
|
=head1 NAME
nbd_aio_pread_structured - read from the NBD server
=head1 SYNOPSIS
#include <libnbd.h>
typedef struct {
int (*callback) (void *user_data, const void *subbuf,
size_t count, uint64_t offset,
unsigned status, int *error);
void *user_data;
void (*free) (void *user_data);
} nbd_chunk_callback;
typedef struct {
int (*callback) (void *user_data, int *error);
void *user_data;
void (*free) (void *user_data);
} nbd_completion_callback;
int64_t nbd_aio_pread_structured (
struct nbd_handle *h, void *buf, size_t count,
uint64_t offset,
nbd_chunk_callback chunk_callback,
nbd_completion_callback completion_callback,
uint32_t flags
);
=head1 DESCRIPTION
Issue a read 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>.
Note that you must ensure C<buf> is valid until the command has
completed. Furthermore, if the C<error> parameter to
C<completion_callback> is set or if L<nbd_aio_command_completed(3)>
reports failure, and if L<nbd_get_pread_initialize(3)> returns true,
then libnbd sanitized C<buf>, but it is unspecified whether the
contents of C<buf> will read as zero or as partial results from the
server. If L<nbd_get_pread_initialize(3)> returns false, then
libnbd did not sanitize C<buf>, and the contents are undefined
on failure.
Other parameters behave as documented in L<nbd_pread_structured(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>, C<buf>.
For more information see L<libnbd(3)/Non-NULL parameters>.
=head1 HANDLE STATE
nbd_aio_pread_structured
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_PREAD_STRUCTURED 1
=head1 SEE ALSO
L<nbd_aio_command_completed(3)>,
L<nbd_aio_pread(3)>,
L<nbd_create(3)>,
L<nbd_get_pread_initialize(3)>,
L<nbd_pread_structured(3)>,
L<nbd_set_pread_initialize(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
|
