From 0d58af6aec6eec7f52f95ad287887873a51bf1bf Mon Sep 17 00:00:00 2001
From: Daniel Stenberg <daniel@haxx.se>
Date: Thu, 7 Oct 2010 19:51:28 +0200
Subject: [PATCH] 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                             |  1 +
 docs/libssh2_session_handshake.3 | 42 ++++++++++++++++++++++++++++++++
 docs/libssh2_session_startup.3   |  4 ++-
 include/libssh2.h                |  2 ++
 src/session.c                    | 26 ++++++++++++++++----
 5 files changed, 69 insertions(+), 6 deletions(-)
 create mode 100644 docs/libssh2_session_handshake.3

diff --git a/TODO b/TODO
index e9916de..3199574 100644
--- a/TODO
+++ b/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:
 
diff --git a/docs/libssh2_session_handshake.3 b/docs/libssh2_session_handshake.3
new file mode 100644
index 0000000..e73da8f
--- /dev/null
+++ b/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)
diff --git a/docs/libssh2_session_startup.3 b/docs/libssh2_session_startup.3
index 44bbb5d..f971968 100644
--- a/docs/libssh2_session_startup.3
+++ b/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)
 
diff --git a/include/libssh2.h b/include/libssh2.h
index 8c99182..6040ab8 100644
--- a/include/libssh2.h
+++ b/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,
diff --git a/src/session.c b/src/session.c
index 86d96e2..e79888a 100644
--- a/src/session.c
+++ b/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
  *