=head1 NAME

nbd_set_tls_priority - set the TLS priority string

=head1 SYNOPSIS

 #include <libnbd.h>

 int nbd_set_tls_priority (
       struct nbd_handle *h, const char *priority
     );

=head1 DESCRIPTION

Set the TLS priority string.  This controls
which ciphers, key exchange methods and MACs are used and
in what order.  See L<"Priority strings" in the GnuTLS
manual|https://gnutls.org/manual/html_node/Priority-Strings.html>

The default is picked at compile time, either using
C<./configure --with-tls-priority=PRIORITY> or if that
was not set then C<"NORMAL">.

It is not recommended to change this unless you know
what you are doing.  It may be dangerous to set this
from an untrusted source, since it may allow you to
read some local configuration files, and possibly
downgrade TLS security.

This function may be called regardless of whether TLS is
supported, but will have no effect unless L<nbd_set_tls(3)>
is also used to request or require TLS.

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

=head1 HANDLE STATE

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

 ┌─────────────────────────────────────┬─────────────────────────┐
 │ Handle created, before connecting   │ ✅ allowed              │
 │ Connecting                          │ ❌ error                │
 │ Connecting & handshaking (opt_mode) │ ❌ error                │
 │ Connected to the server             │ ❌ error                │
 │ Connection shut down                │ ❌ error                │
 │ Handle dead                         │ ❌ error                │
 └─────────────────────────────────────┴─────────────────────────┘

=head1 VERSION

This function first appeared in libnbd 1.24.

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_TLS_PRIORITY 1

=head1 SEE ALSO

L<nbd_create(3)>,
L<nbd_get_tls_priority(3)>,
L<nbd_set_tls(3)>,
L<nbd_set_uri_allow_tls_priority(3)>,
L<libnbd(3)>,
L<https://gnutls.org/manual/html_node/Priority-Strings.html>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
