libssh2_session_handshake: replaces libssh2_session_startup()

The function libssh2_session_startup() is now considered deprecated due
to the portability issue with the socket argument.
libssh2_session_handshake() is the name of the replacement.

TODO

@@ -38,6 +38,7 @@ At next SONAME bump
   libssh2_channel_receive_window_adjust()
   libssh2_poll()
   libssh2_poll_channel_read()
+  libssh2_session_startup() (libssh2_session_handshake() is the replacement)
 
 * Rename a few function:
 

docs/libssh2_session_handshake.3

@@ -0,0 +1,42 @@
+.\" $Id: libssh2_session_handshake.3,v 1.7 2009/03/16 23:25:14 bagder Exp $
+.\"
+.TH libssh2_session_handshake 3 "7 Oct 2010" "libssh2 1.2.8" "libssh2 manual"
+.SH NAME
+libssh2_session_handshake - perform the SSH handshake
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int
+libssh2_session_handshake(LIBSSH2_SESSION *session, libssh2_socket_t socket);
+.SH DESCRIPTION
+\fIsession\fP - Session instance as returned by
+.BR libssh2_session_init_ex(3)
+
+\fIsocket\fP - Connected socket descriptor. Typically a TCP connection
+though the protocol allows for any reliable transport and the library will
+attempt to use any berkeley socket.
+
+Begin transport layer protocol negotiation with the connected host.
+.SH RETURN VALUE
+Returns 0 on success, negative on failure.
+.SH ERRORS
+\fILIBSSH2_ERROR_SOCKET_NONE\fP - The socket is invalid.
+
+\fILIBSSH2_ERROR_BANNER_SEND\fP - Unable to send banner to remote host.
+
+\fILIBSSH2_ERROR_KEX_FAILURE\fP - >Encryption key exchange with the remote
+host failed.
+
+\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
+
+\fILIBSSH2_ERROR_SOCKET_DISCONNECT\fP - The socket was disconnected.
+
+\fILIBSSH2_ERROR_PROTO\fP - An invalid SSH protocol response was received on
+the socket.
+
+\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block.
+.SH AVAILABILITY
+Added in 1.2.8
+.SH SEE ALSO
+.BR libssh2_session_free(3)
+.BR libssh2_session_init_ex(3)

docs/libssh2_session_startup.3

@@ -8,8 +8,10 @@ libssh2_session_startup - begin transport layer
 
 int 
 libssh2_session_startup(LIBSSH2_SESSION *session, int socket);
-
 .SH DESCRIPTION
+Starting in libssh2 version 1.2.8 this function is considered deprecated. Use
+\fIlibssh2_session_handshake(3)\fP instead.
+
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
 

include/libssh2.h

@@ -435,6 +435,8 @@ LIBSSH2_API int libssh2_banner_set(LIBSSH2_SESSION *session,
                                    const char *banner);
 
 LIBSSH2_API int libssh2_session_startup(LIBSSH2_SESSION *session, int sock);
+LIBSSH2_API int libssh2_session_handshake(LIBSSH2_SESSION *session,
+                                          libssh2_socket_t sock);
 LIBSSH2_API int libssh2_session_disconnect_ex(LIBSSH2_SESSION *session,
                                               int reason,
                                               const char *description,

src/session.c

@@ -725,16 +725,15 @@ session_startup(LIBSSH2_SESSION *session, libssh2_socket_t sock)
 }
 
 /*
- * proto libssh2_session_startup
+ * libssh2_session_handshake()
  *
  * session: LIBSSH2_SESSION struct allocated and owned by the calling program
+ * sock:    *must* be populated with an opened and connected socket.
+ *
  * Returns: 0 on success, or non-zero on failure
- * Any memory allocated by libssh2 will use alloc/realloc/free
- * callbacks in session.
- * The 'sock' socket *must* be populated with an opened and connected socket.
  */
 LIBSSH2_API int
-libssh2_session_startup(LIBSSH2_SESSION *session, int sock)
+libssh2_session_handshake(LIBSSH2_SESSION *session, libssh2_socket_t sock)
 {
     int rc;
 
@@ -743,6 +742,23 @@ libssh2_session_startup(LIBSSH2_SESSION *session, int sock)
     return rc;
 }
 
+/*
+ * libssh2_session_startup()
+ *
+ * DEPRECATED. Use libssh2_session_handshake() instead! This function is not
+ * portable enough.
+ *
+ * session: LIBSSH2_SESSION struct allocated and owned by the calling program
+ * sock:    *must* be populated with an opened and connected socket.
+ *
+ * Returns: 0 on success, or non-zero on failure
+ */
+LIBSSH2_API int
+libssh2_session_startup(LIBSSH2_SESSION *session, int sock)
+{
+    return libssh2_session_handshake(session, (libssh2_socket_t) sock);
+}
+
 /*
  * libssh2_session_free
  *