=head1 NAME

nbd_set_keepalive - set keepalive on the socket

=head1 SYNOPSIS

 #include <libnbd.h>

 int nbd_set_keepalive (
       struct nbd_handle *h, bool enable
     );

=head1 DESCRIPTION

Set the keepalive (C<SO_KEEPALIVE>) flag on the
socket after creating it.

On operating systems and protocols that support it, this means the
OS sends periodic messages to the NBD server to detect if the socket
is still connected.  If this feature is not supported then setting
this does nothing.

If using TCP on Linux, keepalive can be tuned by calling
L<nbd_set_tcp_option(3)>.

This only works if called on the handle before calls such as
L<nbd_connect_tcp(3)> where libnbd itself creates the socket.
It does not apply to L<nbd_connect_socket(3)> where a socket
is created somewhere else and passed to libnbd.

=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_set_keepalive
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.26.

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

=head1 SEE ALSO

L<nbd_connect_socket(3)>,
L<nbd_connect_tcp(3)>,
L<nbd_create(3)>,
L<nbd_get_keepalive(3)>,
L<nbd_set_tcp_option(3)>,
L<libnbd(3)>,
L<setsockopt(2)>,
L<socket(7)>.

=head1 AUTHORS

Eric Blake

Richard W.M. Jones

=head1 COPYRIGHT

Copyright Red Hat
