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
|
=head1 NAME
nbd_set_export_name - set the export name
=head1 SYNOPSIS
#include <libnbd.h>
int nbd_set_export_name (
struct nbd_handle *h, const char *export_name
);
=head1 DESCRIPTION
Some NBD servers can serve multiple disk images ("exports").
The export is picked by the client, by requesting an export name
during the negotiation phase. The default export is the
empty string C<"">.
Some NBD servers ignore this and serve the same content regardless.
This is only relevant when connecting to servers using the
newstyle protocol as the oldstyle protocol did not support
export names.
The NBD protocol limits export names to 4096 bytes, but servers
may not support the full length. The encoding of export names
is always UTF-8.
When option mode is not in use, the export name must be set
before beginning a connection. However, when L<nbd_set_opt_mode(3)>
has enabled option mode, it is possible to change the export
name prior to L<nbd_opt_go(3)>. In particular, the use of
L<nbd_opt_list(3)> during negotiation can be used to determine
a name the server is likely to accept, and L<nbd_opt_info(3)> can
be used to learn details about an export before connecting.
This call may be skipped if using L<nbd_connect_uri(3)> to connect
to a URI that includes an export name.
=head1 RETURN VALUE
If the call is successful the function returns C<0>.
=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<export_name>.
For more information see L<libnbd(3)/Non-NULL parameters>.
=head1 HANDLE STATE
nbd_set_export_name
can be called when the handle is in the following states:
┌─────────────────────────────────────┬─────────────────────────┐
│ Handle created, before connecting │ ✅ allowed │
│ Connecting │ ❌ error │
│ Connecting & handshaking (opt_mode) │ ✅ allowed │
│ Connected to the server │ ❌ error │
│ 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_SET_EXPORT_NAME 1
=head1 SEE ALSO
L<nbd_connect_uri(3)>,
L<nbd_create(3)>,
L<nbd_get_canonical_export_name(3)>,
L<nbd_get_export_name(3)>,
L<nbd_opt_go(3)>,
L<nbd_opt_info(3)>,
L<nbd_opt_list(3)>,
L<nbd_set_opt_mode(3)>,
L<libnbd(3)>.
=head1 AUTHORS
Eric Blake
Richard W.M. Jones
=head1 COPYRIGHT
Copyright Red Hat
|
