Subject: more keep-alive stuff

more keep-alive stuff

From: Simon Josefsson <>
Date: Wed, 10 Mar 2010 13:26:34 +0100


I have pushed support for sending keepalive requests. (Recall, my
earlier work on keepalive support was to _receive_ keepalive requests.)

This code hasn't been tested a lot, so I'd really appreciate if people
with applications using libssh2 can test it. Sending keepalive's is
still off by default. I've made sure that libssh2 is essentially not
doing anything else when keepalive's are off, so this should cause a
minimum of intrusion for already working code.

The two new APIs are:

 * libssh2_keepalive_config()
 * Set how often keepalive messages should be sent. WANT_REPLY
 * indicates whether the keepalive messages should request a response
 * from the server. INTERVAL is number of seconds that can pass
 * without any I/O, use 0 (the default) to disable keepalives. To
 * avoid some busy-loop corner-cases, if you specify an interval of 1
 * it will be treated as 2.
 * Note that non-blocking applications are responsible for sending the
 * keepalive messages using libssh2_keepalive_send().
LIBSSH2_API void libssh2_keepalive_config (LIBSSH2_SESSION *session,
                                           int want_reply,
                                           unsigned interval);

 * libssh2_keepalive_send()
 * Send a keepalive message if needed. SECONDS_TO_NEXT indicates how
 * many seconds you can sleep after this call before you need to call
 * it again. Returns 0 on success, or LIBSSH2_ERROR_SOCKET_SEND on
 * I/O errors.
LIBSSH2_API int libssh2_keepalive_send (LIBSSH2_SESSION *session,
                                        int *seconds_to_next);

If your application is blocking, to enable sending of keepalive
requests, you just add a call like this:

  libssh2_keepalive_config (session, 1, 5);

This will send keepalive messages every 5 seconds, and the message that
will be sent requests the server to respond to the message (because
want_reply=1). That's it!

If your application is non-blocking, you need to first call
libssh2_keepalive_config as above, but you also need to make sure you
call libssh2_keepalive_send in your select loop and use its output as
the maximum time to sleep in your select call. For example:

  while (1) {
      struct timeval tmout;
      int err = libssh2_keepalive_send(sess, &tmout.tv_sec);
      if (err) {
          // ...
      tmout.tv_usec = 0;
      // set up fd_sets
      ev = select(..., &tmout);
      // handle events

That's it. I hope it works. Let me know if you find anything weird...
I'm aware of one issue with the code, but I'm hoping it is just

Received on 2010-03-10