4. Programming applications

This section deals with programming code needed if you want to create applications that use keepalive. This is not a programming manual, and it requires that you have previous knowledge in C programming and in networking concepts. I consider you familiar with sockets, and with everything concerning the general aspects of your application.

4.1. When your code needs keepalive support

Not all network applications need keepalive support. Remember that it is TCP keepalive support. So, as you can imagine, only TCP sockets can take advantage of it.

The most beautiful thing you can do when writing an application is to make it as customizable as possible, and not to force decisions. If you want to consider the happiness of your users, you should implement keepalive and let the users decide if they want to use it or not by using a configuration parameter or a switch on the command line.

4.2. The setsockopt function call

All you need to enable keepalive for a specific socket is to set the specific socket option on the socket itself. The prototype of the function is as follows:

  int setsockopt(int s, int level, int optname,
                 const void *optval, socklen_t optlen)
      

The first parameter is the socket, previously created with the socket(2); the second one must be  SOL_SOCKET, and the third must be SO_KEEPALIVE . The fourth parameter must be a boolean integer value, indicating that we want to enable the option, while the last is the size of the value passed before.

According to the manpage, 0 is returned upon success, and -1 is returned on error (and errno is properly set).

There are also three other socket options you can set for keepalive when you write your application. They all use the SOL_TCP level instead of SOL_SOCKET, and they override system-wide variables only for the current socket. If you read without writing first, the current system-wide parameters will be returned.

• TCP_KEEPCNT: overrides  tcp_keepalive_probes
• TCP_KEEPIDLE: overrides  tcp_keepalive_time
• TCP_KEEPINTVL: overrides  tcp_keepalive_intvl

4.3. Code examples

This is a little example that creates a socket, shows that keepalive is disabled, then enables it and checks that the option was effectively set.

            /* --- begin of keepalive test program --- */

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>

int main(void);

int main()
{
   int s;
   int optval;
   socklen_t optlen = sizeof(optval);

   /* Create the socket */
   if((s = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP)) < 0) {
      perror("socket()");
      exit(EXIT_FAILURE);
   }

   /* Check the status for the keepalive option */
   if(getsockopt(s, SOL_SOCKET, SO_KEEPALIVE, &optval, &optlen) < 0) {
      perror("getsockopt()");
      close(s);
      exit(EXIT_FAILURE);
   }
   printf("SO_KEEPALIVE is %s\n", (optval ? "ON" : "OFF"));

   /* Set the option active */
   optval = 1;
   optlen = sizeof(optval);
   if(setsockopt(s, SOL_SOCKET, SO_KEEPALIVE, &optval, optlen) < 0) {
      perror("setsockopt()");
      close(s);
      exit(EXIT_FAILURE);
   }
   printf("SO_KEEPALIVE set on socket\n");

   /* Check the status again */
   if(getsockopt(s, SOL_SOCKET, SO_KEEPALIVE, &optval, &optlen) < 0) {
      perror("getsockopt()");
      close(s);
      exit(EXIT_FAILURE);
   }
   printf("SO_KEEPALIVE is %s\n", (optval ? "ON" : "OFF"));

   close(s);

   exit(EXIT_SUCCESS);
}

            /* ---  end of keepalive test program  --- */