=head1 NAME

nbd_set_tls_certificates - set the path to the TLS certificates
directory

=head1 SYNOPSIS

 #include <libnbd.h>

 int nbd_set_tls_certificates (
       struct nbd_handle *h, const char *dir
     );

=head1 DESCRIPTION

Set the path to the TLS certificates directory.  If not
set and TLS is used then a compiled in default is used.
For root this is C</etc/pki/libnbd/>.  For non-root this is
C<$HOME/.pki/libnbd> and C<$HOME/.config/pki/libnbd>.  If
none of these directories can be found then the system
trusted CAs are used.

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

=head1 HANDLE STATE

nbd_set_tls_certificates
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.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_TLS_CERTIFICATES 1

=head1 SEE ALSO

L<nbd_create(3)>,
L<nbd_set_tls(3)>,
L<libnbd(3)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
