=head1 NAME

nbd_opt_info - request the server for information about an export

=head1 SYNOPSIS

 #include <libnbd.h>

 int nbd_opt_info (
       struct nbd_handle *h
     );

=head1 DESCRIPTION

Request that the server supply information
about the export name
previously specified by the most recent L<nbd_set_export_name(3)>
or L<nbd_connect_uri(3)>.  This can only be used if
L<nbd_set_opt_mode(3)> enabled option mode.

If successful, functions like L<nbd_is_read_only(3)> and
L<nbd_get_size(3)> will report details about that export.  If
L<nbd_set_request_meta_context(3)> is set (the default) and
structured replies or extended headers were negotiated, it is also
valid to use L<nbd_can_meta_context(3)> after this call.  However,
it may be more efficient to clear that setting and manually
utilize L<nbd_opt_list_meta_context(3)> with its callback approach,
for learning which contexts an export supports.  In general, if
L<nbd_opt_go(3)> is called next, that call will likely succeed
with the details remaining the same, although this is not
guaranteed by all servers.

Not all servers understand this request, and even when it is
understood, the server might fail the request even when a
corresponding L<nbd_opt_go(3)> would succeed.

=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>.
For more information see L<libnbd(3)/Non-NULL parameters>.

=head1 HANDLE STATE

nbd_opt_info
can be called when the handle is in the following state:

 ┌─────────────────────────────────────┬─────────────────────────┐
 │ Handle created, before connecting   │ ❌ error                │
 │ 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.4.

If you need to test if this function is available at compile time
check if the following macro is defined:

 #define LIBNBD_HAVE_NBD_OPT_INFO 1

=head1 SEE ALSO

L<nbd_aio_opt_info(3)>,
L<nbd_can_meta_context(3)>,
L<nbd_connect_uri(3)>,
L<nbd_create(3)>,
L<nbd_get_size(3)>,
L<nbd_is_read_only(3)>,
L<nbd_opt_go(3)>,
L<nbd_opt_list_meta_context(3)>,
L<nbd_set_export_name(3)>,
L<nbd_set_opt_mode(3)>,
L<nbd_set_request_meta_context(3)>,
L<libnbd(3)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
