release: updated to hold 1.2.7 info

This makefile compiles already all files fine for static lib, but needs
final touch when I have OpenSSL fully working with shared libs and Watcom.

.gitignore

@@ -32,3 +32,4 @@ install-sh
 mkinstalldirs
 tags
 libssh2.pc
+TAGS

COPYING

@@ -1,5 +1,7 @@
 /* Copyright (c) 2004-2007 Sara Golemon <sarag@libssh2.org>
+ * Copyright (c) 2005,2006 Mikhail Gusarov <dottedmag@dottedmag.net>
  * Copyright (c) 2006-2007 The Written Word, Inc.
+ * Copyright (c) 2007 Eli Fant <elifantu@mail.ru>
  * Copyright (c) 2009 Daniel Stenberg
  * Copyright (C) 2008, 2009 Simon Josefsson
  * All rights reserved.

Makefile.am

@@ -21,13 +21,18 @@ VCPROJ = win32/libssh2.vcproj
 
 DISTCLEANFILES = $(DSP)
 
+VMSFILES = vms/libssh2_make_example.dcl vms/libssh2_make_help.dcl	\
+vms/libssh2_make_kit.dcl vms/libssh2_make_lib.dcl vms/man2help.c	\
+vms/readme.vms vms/libssh2_config.h
+
+
 WIN32FILES = win32/Makefile.win32 win32/libssh2.dsw     \
 win32/config.mk win32/Makefile win32/test/Makefile.win32 \
 win32/libssh2_config.h win32/tests.dsp win32/rules.mk $(DSP) \
 win32/msvcproj.head win32/msvcproj.foot
 
 EXTRA_DIST = $(WIN32FILES) buildconf $(NETWAREFILES) get_ver.awk HACKING \
- maketgz NMakefile TODO RELEASE-NOTES libssh2.pc.in
+ maketgz NMakefile TODO RELEASE-NOTES libssh2.pc.in $(VMSFILES)
 
 ACLOCAL_AMFLAGS = -I m4
 

Makefile.inc

@@ -1,5 +1,7 @@
 CSOURCES = channel.c comp.c crypt.c hostkey.c kex.c mac.c misc.c \
  packet.c publickey.c scp.c session.c sftp.c userauth.c transport.c \
- version.c knownhost.c agent.c openssl.c libgcrypt.c pem.c
+ version.c knownhost.c agent.c openssl.c libgcrypt.c pem.c keepalive.c \
+ global.c
 
-HHEADERS = libssh2_priv.h openssl.h libgcrypt.h transport.h channel.h comp.h mac.h misc.h
+HHEADERS = libssh2_priv.h openssl.h libgcrypt.h transport.h channel.h \
+ comp.h mac.h misc.h packet.h userauth.h session.h

NEWS

@@ -1,3 +1,97 @@
+libssh2 1.2.7 (August 17, 2010)
+
+This release includes the following changes:
+
+ o Added Watcom makefile
+
+This release includes the following bugfixes:
+
+ o Better handling of invalid key files
+ o inputchecks: make lots of API functions check for NULL pointers
+ o libssh2_session_callback_set: extended the man page
+ o SFTP: limit write() to not produce overly large packets
+ o agent: make libssh2_agent_userauth() work blocking properly
+ o _libssh2_userauth_publickey: reject method names longer than the data
+ o channel_free: ignore problems with channel_close()
+ o typedef: make ssize_t get typedef without LIBSSH2_WIN32
+ o _libssh2_wait_socket: poll needs milliseconds
+ o libssh2_wait_socket: reset error code to "leak" EAGAIN less
+ o Added include for sys/select.h to get fd.set on some platforms
+ o session_free: free more data to avoid memory leaks
+ o openssl: make use of the EVP interface
+ o Fix underscore typo for 64-bit printf format specifiers on Windows
+ o Make libssh2_debug() create a correctly terminated string
+ o userauth_hostbased_fromfile: packet length too short
+ o handshake: Compression enabled at the wrong time
+ o Don't overflow MD5 server hostkey
+
+libssh2 1.2.6 (June 10, 2010)
+
+This release includes the following changes:
+
+ o Added libssh2_sftp_statvfs() and libssh2_sftp_fstatvfs()
+ o Added libssh2_knownhost_checkp()
+ o Added libssh2_scp_send64()
+
+This release includes the following bugfixes:
+
+ o wait_socket: make c89 compliant and use two fd_sets for select()
+ o OpenSSL AES-128-CTR detection
+ o proper keyboard-interactive user dialog in the sftp.c example
+ o build procedure for VMS
+ o fixed libssh2.dsw to use the generated libssh2.dsp
+ o several Windows-related build fixes
+ o fail to init SFTP if session isn't already authenticated
+ o many tiny fixes that address clang-analyzer warnings
+ o sftp_open: deal with short channel_write calls
+ o libssh2_publickey_init: fixed to work better non-blocking
+ o sftp_close_handle: add precation to not access NULL pointer
+ o sftp_readdir: simplified and bugfixed
+ o channel_write: if data has been sent, don't return EAGAIN
+
+Version 1.2.5 (April 13, 2010)
+
+This release includes the following changes:
+
+ o Added Add keep-alive support: libssh2_keepalive_config() and
+   libssh2_keepalive_send()
+ o Added libssh2_knownhost_addc(), libssh2_init() and libssh2_exit()
+ o Added LIBSSH2_SFTP_S_IS***() macros
+
+This release includes the following bugfixes:
+
+ o fix memory leak in libssh2_session_startup()
+ o added missing error codes - shown as hangs in blocking mode
+ o fix memory leak in userauth_keyboard_interactive()
+ o libssh2_knownhost_del: fix write to freed memory
+ o Send and receive channel EOF before sending SSH_MSG_CHANNEL_CLOSE
+ o Use AES-CTR from OpenSSL when available
+ o Fixed gettimeofday to compile with Visual C++ 6
+ o NULL dereference when window adjusting a non-existing channel
+ o avoid using poll on interix and mac os x systems
+ o fix scp memory leak
+ o Correctly clear blocking flag after sending multipart packet
+ o Reduce used window sizes by factor 10
+ o libssh2_userauth_publickey_fromfile_ex() handles a NULL password
+ o sftp_init() deal with _libssh2_channel_write() short returns
+
+ o Use poll instead of select when available.  By Paul Querna.
+
+ o Add APIs to have libssh2 automatically send keep-alive requests.
+   The APIs are libssh2_keepalive_config, and libssh2_keepalive_send.
+   By Simon Josefsson.
+
+ o Add global init/exit points, to do crypto initialization in one place.
+   The APIs are libssh2_init and libssh2_exit.  By Lars Nordin.
+
+* (February 15 2010) Daniel Stenberg:
+- Added 46 new man pages for public convenience macros. The man pages  are
+  just short redirects to the actual underlying function. The were all
+  initially created by a script.
+
+- Committed the patch by Yoichi Iwaki in bug #2929647, which fixed a memory
+  leak when an 'outbuf' was still allocated when a session was freed.
+
 Version 1.2.4 (February 13, 2010)
 
  o Resolve compile issues on Solaris x64 and UltraSPARC

RELEASE-NOTES

@@ -1,18 +1,34 @@
-libssh2 1.2.4
+libssh2 1.2.7
 
 This release includes the following changes:
 
- o 
+ o Added Watcom makefile
 
 This release includes the following bugfixes:
 
- o Resolve compile issues on Solaris x64 and UltraSPARC
+ o Better handling of invalid key files
- o Allow compiling with OpenSSL when AES isn't available
+ o inputchecks: make lots of API functions check for NULL pointers
- o Fix Tru64 socklen_t compile issue with example/direct_tcpip.c
+ o libssh2_session_callback_set: extended the man page
+ o SFTP: limit write() to not produce overly large packets
+ o agent: make libssh2_agent_userauth() work blocking properly
+ o _libssh2_userauth_publickey: reject method names longer than the data
+ o channel_free: ignore problems with channel_close()
+ o typedef: make ssize_t get typedef without LIBSSH2_WIN32
+ o _libssh2_wait_socket: poll needs milliseconds
+ o libssh2_wait_socket: reset error code to "leak" EAGAIN less
+ o Added include for sys/select.h to get fd.set on some platforms
+ o session_free: free more data to avoid memory leaks
+ o openssl: make use of the EVP interface
+ o Fix underscore typo for 64-bit printf format specifiers on Windows
+ o Make libssh2_debug() create a correctly terminated string
+ o userauth_hostbased_fromfile: packet length too short
+ o handshake: Compression enabled at the wrong time
+ o Don't overflow MD5 server hostkey
 
 This release would not have looked like this without help, code, reports and
 advice from friends like these:
 
- Dan Fandrich, Dave McCaldon, Peter Stuge
+ Alexander Lamaison, Guenter Knauf, Peter Stuge, Simon Josefsson, Lars Nordin,
+ John Little, Daniel Stenberg, TJ Saunders, Tor Arntsen
  
         Thanks! (and sorry if I forgot to mention someone)

TODO

@@ -2,11 +2,12 @@ Things TODO
 ===========
 
 * make sure the windowing code adapts better to slow situations so that it
-  doesn't then use as much memory as today
+  doesn't then use as much memory as today. Possibly by an app-controllable
+  "Window mode"?
 
-* Introduce a 'libssh2_socket_t' type for sockets in internal code
+* Introduce a function that can free data that is returned allocated from the
-
+  lib, like when libssh2_session_last_error() is asked to return the string
-* Provide a libssh2_scp_send() API for files larger than 4GB (32bit size)
+  with 'want_buf' set to non-zero.
 
 * Add more info to the man pages.
 
@@ -42,3 +43,18 @@ At next SONAME bump
 
   libssh2_hostkey_hash => libssh2_session_hostkey_hash
   libssh2_banner_set => libssh2_session_banner_set
+
+* change 'int' to 'libssh2_socket_t' in the public API for sockets.
+
+* Use 'size_t' for string lengths in all functions.
+
+* Add a comment field to struct libssh2_knownhost.
+
+* remove the existing libssh2_knownhost_add() function and rename
+  libssh2_knownhost_addc to become the new libssh2_knownhost_add instead
+
+* remove the existing libssh2_scp_send_ex() function and rename
+  libssh2_scp_send64 to become the new libssh2_scp_send instead.
+
+* remove the existing libssh2_knownhost_check() functin and rename
+  libssh2_knownhost_checkp() to become the new libssh2_knownhost_check instead

buildconf

@@ -2,20 +2,15 @@
 
 LIBTOOLIZE="libtoolize"
 
-if [ "x`which $LIBTOOLIZE`" == "x" ];
+if [ "x`which $LIBTOOLIZE`" = "x" ]; then
-then
+    LIBTOOLIZE="glibtoolize"
-  LIBTOOLIZE="glibtoolize";
 fi
 
-if [ "x`which $LIBTOOLIZE`" == "x" ];
+if [ "x`which $LIBTOOLIZE`" = "x" ]; then
-then
+    echo "Neither libtoolize nor glibtoolize could be found!"
-  echo "Neither libtoolize nor glibtoolize could be found!";
+    exit 1
-  exit 1
 fi
 
-
-
-
 ${LIBTOOLIZE} --copy --automake --force
 ${ACLOCAL:-aclocal} -I m4 $ACLOCAL_FLAGS
 ${AUTOHEADER:-autoheader}

configure.ac

@@ -111,6 +111,14 @@ if test "$ac_cv_libgcrypt" = "yes"; then
 fi
 AM_CONDITIONAL(LIBGCRYPT, test "$ac_cv_libgcrypt" = "yes")
 
+# Not all OpenSSL have AES-CTR functions.
+if test "$ac_cv_libssl" = "yes"; then
+  save_LDFLAGS="$LDFLAGS"
+  LDFLAGS="$LDFLAGS $LIBSSL"
+  AC_CHECK_FUNCS(EVP_aes_128_ctr)
+  LDFLAGS="$save_LDFLAGS"
+fi
+
 # Look for Libz
 if test "$use_libz" != "no"; then
   AC_LIB_HAVE_LINKFLAGS([z], [], [#include <zlib.h>])
@@ -147,12 +155,12 @@ AC_MSG_CHECKING([whether to enable pedantic and debug compiler options])
 AC_ARG_ENABLE(debug,
 AC_HELP_STRING([--enable-debug],[Enable pedantic and debug options])
 AC_HELP_STRING([--disable-debug],[Disable debug options]),
-[ case "$enableval" in
+[ case "$enable_debug" in
   no)
        AC_MSG_RESULT(no)
        ;;
   *)   AC_MSG_RESULT(yes)
-
+    enable_debug=yes
     CPPFLAGS="$CPPFLAGS -DLIBSSH2DEBUG"
     CFLAGS="$CFLAGS -g"
 
@@ -162,6 +170,7 @@ AC_HELP_STRING([--disable-debug],[Disable debug options]),
        ;;
   esac
  ],
+       enable_debug=no
        AC_MSG_RESULT(no)
 )
 
@@ -220,7 +229,25 @@ case $host in
     ;;
 esac
 
-AC_CHECK_FUNCS(poll gettimeofday select strtoll)
+case $host in
+  *darwin*|*interix*)
+    dnl poll() does not work on these platforms
+    dnl Interix: "does provide poll(), but the implementing developer must
+    dnl have been in a bad mood, because poll() only works on the /proc
+    dnl filesystem here"
+    dnl Mac OS X's poll has funny behaviors, like:
+    dnl not being able to do poll on no fildescriptors (10.3?)
+    dnl not being able to poll on some files (like anything in /dev)
+    dnl not having reliable timeout support
+    dnl inconsistent return of POLLHUP where other implementations give POLLIN
+    AC_MSG_NOTICE([poll use is disabled on this platform])
+    ;;
+  *)
+    AC_CHECK_FUNCS(poll)
+    ;;
+esac
+
+AC_CHECK_FUNCS(gettimeofday select strtoll)
 
 dnl Check for select() into ws2_32 for Msys/Mingw
 if test "$ac_cv_func_select" != "yes"; then
@@ -259,3 +286,17 @@ AC_CONFIG_FILES([Makefile
                  docs/Makefile
                  libssh2.pc])
 AC_OUTPUT
+
+AC_MSG_NOTICE([summary of build options:
+
+  version:          ${VERSION}
+  Host type:        ${host}
+  Install prefix:   ${prefix}
+  Compiler:         ${CC}
+  Compiler flags:   ${CFLAGS}
+  Library types:    Shared=${enable_shared}, Static=${enable_static}
+  Crypto library:   openssl: ${ac_cv_libssl:-no} (AES-CTR: ${ac_cv_func_EVP_aes_128_ctr:-N/A}) libgcrypt: ${ac_cv_libgcrypt:-no}
+  Debug build:      $enable_debug
+  Path to sshd:     $ac_cv_path_SSHD (only for self-tests)
+  libz compression: $ac_cv_libz
+])

docs/Makefile.am

@@ -13,41 +13,64 @@ dist_man_MANS = \
 	libssh2_banner_set.3 \
 	libssh2_base64_decode.3 \
 	libssh2_channel_close.3 \
+	libssh2_channel_direct_tcpip.3 \
 	libssh2_channel_direct_tcpip_ex.3 \
 	libssh2_channel_eof.3 \
+	libssh2_channel_exec.3 \
+	libssh2_channel_flush.3 \
 	libssh2_channel_flush_ex.3 \
+	libssh2_channel_flush_stderr.3 \
 	libssh2_channel_forward_accept.3 \
 	libssh2_channel_forward_cancel.3 \
+	libssh2_channel_forward_listen.3 \
 	libssh2_channel_forward_listen_ex.3 \
 	libssh2_channel_free.3 \
 	libssh2_channel_get_exit_status.3 \
 	libssh2_channel_handle_extended_data.3 \
 	libssh2_channel_handle_extended_data2.3 \
+	libssh2_channel_ignore_extended_data.3 \
 	libssh2_channel_open_ex.3 \
+	libssh2_channel_open_session.3 \
 	libssh2_channel_process_startup.3 \
+	libssh2_channel_read.3 \
 	libssh2_channel_read_ex.3 \
+	libssh2_channel_read_stderr.3 \
 	libssh2_channel_receive_window_adjust.3 \
 	libssh2_channel_receive_window_adjust2.3 \
+	libssh2_channel_request_pty.3 \
 	libssh2_channel_request_pty_ex.3 \
+	libssh2_channel_request_pty_size.3 \
 	libssh2_channel_request_pty_size_ex.3 \
 	libssh2_channel_send_eof.3 \
 	libssh2_channel_set_blocking.3 \
+	libssh2_channel_setenv.3 \
 	libssh2_channel_setenv_ex.3 \
+	libssh2_channel_shell.3 \
+	libssh2_channel_subsystem.3 \
 	libssh2_channel_wait_closed.3 \
 	libssh2_channel_wait_eof.3 \
+	libssh2_channel_window_read.3 \
 	libssh2_channel_window_read_ex.3 \
+	libssh2_channel_window_write.3 \
 	libssh2_channel_window_write_ex.3 \
+	libssh2_channel_write.3 \
 	libssh2_channel_write_ex.3 \
+	libssh2_channel_write_stderr.3 \
+	libssh2_channel_x11_req.3 \
 	libssh2_channel_x11_req_ex.3 \
+	libssh2_exit.3 \
 	libssh2_free_host_entry.3 \
 	libssh2_host_entry_match.3 \
 	libssh2_hostkey_hash.3 \
+	libssh2_init.3 \
 	libssh2_knownhost_add.3 \
+	libssh2_knownhost_addc.3 \
 	libssh2_knownhost_check.3 \
+	libssh2_knownhost_checkp.3 \
 	libssh2_knownhost_del.3 \
+	libssh2_knownhost_free.3 \
 	libssh2_knownhost_get.3 \
 	libssh2_knownhost_init.3 \
-	libssh2_knownhost_free.3 \
 	libssh2_knownhost_readfile.3 \
 	libssh2_knownhost_readline.3 \
 	libssh2_knownhost_writefile.3 \
@@ -55,22 +78,28 @@ dist_man_MANS = \
 	libssh2_new_host_entry.3 \
 	libssh2_poll.3 \
 	libssh2_poll_channel_read.3 \
+	libssh2_publickey_add.3 \
 	libssh2_publickey_add_ex.3 \
 	libssh2_publickey_init.3 \
 	libssh2_publickey_list_fetch.3 \
 	libssh2_publickey_list_free.3 \
+	libssh2_publickey_remove.3 \
 	libssh2_publickey_remove_ex.3 \
 	libssh2_publickey_shutdown.3 \
 	libssh2_scp_recv.3 \
+	libssh2_scp_send.3 \
 	libssh2_scp_send_ex.3 \
+	libssh2_scp_send64.3 \
 	libssh2_session_abstract.3 \
 	libssh2_session_block_directions.3 \
 	libssh2_session_callback_set.3 \
+	libssh2_session_disconnect.3 \
 	libssh2_session_disconnect_ex.3 \
 	libssh2_session_flag.3 \
 	libssh2_session_free.3 \
 	libssh2_session_get_blocking.3 \
 	libssh2_session_hostkey.3 \
+	libssh2_session_init.3 \
 	libssh2_session_init_ex.3 \
 	libssh2_session_last_errno.3 \
 	libssh2_session_last_error.3 \
@@ -78,30 +107,54 @@ dist_man_MANS = \
 	libssh2_session_methods.3 \
 	libssh2_session_set_blocking.3 \
 	libssh2_session_startup.3 \
+	libssh2_sftp_close.3 \
 	libssh2_sftp_close_handle.3 \
+	libssh2_sftp_closedir.3 \
+	libssh2_sftp_fsetstat.3 \
+	libssh2_sftp_fstat.3 \
 	libssh2_sftp_fstat_ex.3 \
+	libssh2_sftp_fstatvfs.3 \
 	libssh2_sftp_init.3 \
 	libssh2_sftp_last_error.3 \
+	libssh2_sftp_lstat.3 \
+	libssh2_sftp_mkdir.3 \
 	libssh2_sftp_mkdir_ex.3 \
+	libssh2_sftp_open.3 \
 	libssh2_sftp_open_ex.3 \
+	libssh2_sftp_opendir.3 \
 	libssh2_sftp_read.3 \
+	libssh2_sftp_readdir.3 \
 	libssh2_sftp_readdir_ex.3 \
+	libssh2_sftp_readlink.3 \
+	libssh2_sftp_realpath.3 \
+	libssh2_sftp_rename.3 \
 	libssh2_sftp_rename_ex.3 \
+	libssh2_sftp_rewind.3 \
+	libssh2_sftp_rmdir.3 \
 	libssh2_sftp_rmdir_ex.3 \
 	libssh2_sftp_seek.3 \
+	libssh2_sftp_setstat.3 \
 	libssh2_sftp_shutdown.3 \
+	libssh2_sftp_stat.3 \
 	libssh2_sftp_stat_ex.3 \
+	libssh2_sftp_statvfs.3 \
+	libssh2_sftp_symlink.3 \
 	libssh2_sftp_symlink_ex.3 \
 	libssh2_sftp_tell.3 \
 	libssh2_sftp_tell64.3 \
+	libssh2_sftp_unlink.3 \
 	libssh2_sftp_unlink_ex.3 \
 	libssh2_sftp_write.3 \
 	libssh2_trace.3 \
 	libssh2_trace_sethandler.3 \
 	libssh2_userauth_authenticated.3 \
+	libssh2_userauth_hostbased_fromfile.3 \
 	libssh2_userauth_hostbased_fromfile_ex.3 \
+	libssh2_userauth_keyboard_interactive.3 \
 	libssh2_userauth_keyboard_interactive_ex.3 \
 	libssh2_userauth_list.3 \
+	libssh2_userauth_password.3 \
 	libssh2_userauth_password_ex.3 \
+	libssh2_userauth_publickey_fromfile.3 \
 	libssh2_userauth_publickey_fromfile_ex.3 \
 	libssh2_version.3

docs/libssh2_channel_direct_tcpip.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_direct_tcpip 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_direct_tcpip - convenience macro for \fIlibssh2_channel_direct_tcpip_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_direct_tcpip(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_direct_tcpip_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_direct_tcpip_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_direct_tcpip_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_direct_tcpip_ex(3)\fP

docs/libssh2_channel_eof.3

@@ -13,6 +13,7 @@ libssh2_channel_eof(LIBSSH2_CHANNEL *channel);
 
 Check if the remote host has sent an EOF status for the selected stream.
 .SH RETURN VALUE
-Returns 1 if the remote host has sent EOF, otherwise 0.
+Returns 1 if the remote host has sent EOF, otherwise 0. Negative on
+failure.
 .SH SEE ALSO
 .BR libssh2_channel_close(3)

docs/libssh2_channel_exec.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_exec 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_exec - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_exec(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_process_startup(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_process_startup(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_process_startup(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_process_startup(3)\fP

docs/libssh2_channel_flush.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_flush 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_flush - convenience macro for \fIlibssh2_channel_flush_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_flush(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_flush_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_flush_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_flush_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_flush_ex(3)\fP

docs/libssh2_channel_flush_stderr.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_flush_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_flush_stderr - convenience macro for \fIlibssh2_channel_flush_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_flush_stderr(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_flush_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_flush_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_flush_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_flush_ex(3)\fP

docs/libssh2_channel_forward_listen.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_forward_listen 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_forward_listen - convenience macro for \fIlibssh2_channel_forward_listen_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_forward_listen(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_forward_listen_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_forward_listen_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_forward_listen_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_forward_listen_ex(3)\fP

docs/libssh2_channel_ignore_extended_data.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_ignore_extended_data 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_ignore_extended_data - convenience macro for \fIlibssh2_channel_handle_extended_data(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_ignore_extended_data(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_handle_extended_data(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_handle_extended_data(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_handle_extended_data(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_handle_extended_data(3)\fP

docs/libssh2_channel_open_session.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_open_session 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_open_session - convenience macro for \fIlibssh2_channel_open_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_open_session(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_open_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_open_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_open_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_open_ex(3)\fP

docs/libssh2_channel_read.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_read 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_read - convenience macro for \fIlibssh2_channel_read_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_read(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_read_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_read_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_read_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_read_ex(3)\fP

docs/libssh2_channel_read_stderr.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_read_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_read_stderr - convenience macro for \fIlibssh2_channel_read_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_read_stderr(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_read_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_read_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_read_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_read_ex(3)\fP

docs/libssh2_channel_request_pty.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_request_pty 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_request_pty - convenience macro for \fIlibssh2_channel_request_pty_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_request_pty(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_request_pty_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_request_pty_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_request_pty_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_request_pty_ex(3)\fP

docs/libssh2_channel_request_pty_size.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_request_pty_size 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_request_pty_size - convenience macro for \fIlibssh2_channel_request_pty_size_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_request_pty_size(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_request_pty_size_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_request_pty_size_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_request_pty_size_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_request_pty_size_ex(3)\fP

docs/libssh2_channel_setenv.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_setenv 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_setenv - convenience macro for \fIlibssh2_channel_setenv_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_setenv(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_setenv_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_setenv_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_setenv_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_setenv_ex(3)\fP

docs/libssh2_channel_shell.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_shell 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_shell - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_shell(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_process_startup(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_process_startup(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_process_startup(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_process_startup(3)\fP

docs/libssh2_channel_subsystem.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_subsystem 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_subsystem - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_subsystem(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_process_startup(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_process_startup(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_process_startup(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_process_startup(3)\fP

docs/libssh2_channel_window_read.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_window_read 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_window_read - convenience macro for \fIlibssh2_channel_window_read_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_window_read(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_window_read_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_window_read_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_window_read_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_window_read_ex(3)\fP

docs/libssh2_channel_window_write.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_window_write 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_window_write - convenience macro for \fIlibssh2_channel_window_write_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_window_write(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_window_write_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_window_write_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_window_write_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_window_write_ex(3)\fP

docs/libssh2_channel_write.3

@@ -0,0 +1,20 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_write 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_write - convenience macro for \fIlibssh2_channel_write_ex(3)\fP
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+
+#define libssh2_channel_write(channel, buf, buflen) \\
+  libssh2_channel_write_ex((channel), 0, (buf), (buflen))
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_write_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_write_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_write_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_write_ex(3)\fP

docs/libssh2_channel_write_ex.3

@@ -4,16 +4,12 @@
 .SH NAME
 libssh2_channel_write_ex - write data to a channel stream blocking
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 
-ssize_t
+ssize_t libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel,
-libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel, int stream_id, char *buf, size_t buflen);
+                                 int stream_id, char *buf,
-
+                                 size_t buflen);
-ssize_t
-libssh2_channel_write(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen);
-
-ssize_t
-libssh2_channel_write_stderr(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen);
 .SH DESCRIPTION
 Write data to a channel stream. All channel streams have one standard I/O
 substream (stream_id == 0), and may have up to 2^32 extended data streams as
@@ -29,7 +25,12 @@ defines a stream ID of 1 to be the stderr substream.
 \fIbuflen\fP - size of the data to write
 
 \fIlibssh2_channel_write(3)\fP and \fIlibssh2_channel_write_stderr(3)\fP are
-macros.
+convenience macros for this function.
+
+\fIlibssh2_channel_write_ex(3)\fP will use as much as possible of the buffer
+and put it into a single SSH protocol packet. This means that to get maximum
+performance when sending larger files, you should try to always pass in at
+least 32K of data to this function.
 .SH RETURN VALUE
 Actual number of bytes written or negative on failure.
 LIBSSH2_ERROR_EAGAIN when it would otherwise block. While

docs/libssh2_channel_write_stderr.3

@@ -0,0 +1,20 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_write_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_write_stderr - convenience macro for \fIlibssh2_channel_write_ex(3)\fP
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+
+#define libssh2_channel_write_stderr(channel, buf, buflen)  \\
+  libssh2_channel_write_ex((channel), SSH_EXTENDED_DATA_STDERR, (buf), (buflen))
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_write_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_write_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_write_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_write_ex(3)\fP

docs/libssh2_channel_x11_req.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_channel_x11_req 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_channel_x11_req - convenience macro for \fIlibssh2_channel_x11_req_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_channel_x11_req(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_channel_x11_req_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_channel_x11_req_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_channel_x11_req_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_channel_x11_req_ex(3)\fP

docs/libssh2_exit.3

@@ -0,0 +1,14 @@
+.TH libssh2_exit 3 "19 Mar 2010" "libssh2 1.2.5" "libssh2 manual"
+.SH NAME
+libssh2_exit - global library deinitialization
+.SH SYNOPSIS
+#include <libssh2.h>
+
+void
+libssh2_exit(void);
+.SH DESCRIPTION
+Exit the libssh2 functions and free's all memory used internal.
+.SH AVAILABILITY
+Added in libssh2 1.2.5
+.SH SEE ALSO
+.BR libssh2_init(3)

docs/libssh2_init.3

@@ -0,0 +1,20 @@
+.TH libssh2_init 3 "19 Mar 2010" "libssh2 1.2.5" "libssh2 manual"
+.SH NAME
+libssh2_init - global library initialization
+.SH SYNOPSIS
+#include <libssh2.h>
+
+#define LIBSSH2_INIT_NO_CRYPTO 0x0001
+
+int
+libssh2_init(int flags);
+.SH DESCRIPTION
+Initialize the libssh2 functions.  This typically initialize the
+crypto library.  It uses a global state, and is not thread safe -- you
+must make sure this function is not called concurrently.
+.SH RETURN VALUE
+Returns 0 if succeeded, or a negative value for error.
+.SH AVAILABILITY
+Added in libssh2 1.2.5
+.SH SEE ALSO
+.BR libssh2_exit(3)

docs/libssh2_knownhost_add.3

@@ -1,10 +1,11 @@
 
-.\" Copyright (c) 2009 by Daniel Stenberg
+.\" Copyright (c) 2009, 2010 by Daniel Stenberg
 .\"
 .TH libssh2_knownhost_add 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
 .SH NAME
 libssh2_knownhost_add - add a known host
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 
 int libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts,
@@ -13,6 +14,11 @@ int libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts,
                           int typemask,
                           struct libssh2_knownhost **store);
 .SH DESCRIPTION
+We discourage use of this function as of libssh2 1.2.5. Instead we strongly
+urge users to use \fIlibssh2_knownhost_addc(3)\fP instead, which as a more
+complete API. \fIlibssh2_knownhost_add(3)\fP is subject for removal in a
+future release.
+
 Adds a known host to the collection of known hosts identified by the 'hosts'
 handle.
 
@@ -51,8 +57,10 @@ this pointer.
 Returns a regular libssh2 error code, where negative values are error codes
 and 0 indicates success.
 .SH AVAILABILITY
-Added in libssh2 1.2
+Added in libssh2 1.2, deprecated since libssh2 1.2.5. Use
+\fIlibssh2_knownhost_addc(3)\fP instead!
 .SH SEE ALSO
 .BR libssh2_knownhost_init(3)
 .BR libssh2_knownhost_free(3)
 .BR libssh2_knownhost_check(3)
+.BR libssh2_knownhost_addc(3)

docs/libssh2_knownhost_addc.3

@@ -0,0 +1,68 @@
+
+.\" Copyright (c) 2009, 2010 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_add 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_add - add a known host
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_addc(LIBSSH2_KNOWNHOSTS *hosts,
+                           char *host, char *salt,
+                           char *key, size_t keylen,
+                           const char *comment, size_t commentlen,
+                           int typemask,
+                           struct libssh2_knownhost **store);
+.SH DESCRIPTION
+Adds a known host to the collection of known hosts identified by the 'hosts'
+handle.
+
+\fIhost\fP is a pointer the host name in plain text or hashed. If hashed, it
+must be provided base64 encoded. The host name can be the IP numerical address
+of the host or the full name.
+
+If you want to add a key for a specific port number for the given host, you
+must provide the host name like '[host]:port' with the actual characters '['
+and ']' enclosing the host name and a colon separating the host part from the
+port number. For example: \&"[host.example.com]:222".
+
+\fIsalt\fP is a pointer to the salt used for the host hashing, if the host is
+provided hashed. If the host is provided in plain text, salt has no meaning.
+The salt has to be provided base64 encoded with a trailing zero byte.
+
+\fIkey\fP is a pointer to the key for the given host.
+
+\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP
+argument
+
+\fIcomment\fP is a pointer to a comment for the key.
+
+\fIcommentlen\fP is the total size in bytes of the comment pointed to by the \fIcomment\fP argument
+
+\fItypemask\fP is a bitmask that specifies format and info about the data
+passed to this function. Specificly, it details what format the host name is,
+what format the key is and what key type it is.
+
+The host name is given as one of the following types:
+LIBSSH2_KNOWNHOST_TYPE_PLAIN, LIBSSH2_KNOWNHOST_TYPE_SHA1 or
+LIBSSH2_KNOWNHOST_TYPE_CUSTOM.
+
+The key is encoded using one of the following encodings:
+LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64.
+
+The key is using one of these algorithms:
+LIBSSH2_KNOWNHOST_KEY_RSA1, LIBSSH2_KNOWNHOST_KEY_SSHRSA or
+LIBSSH2_KNOWNHOST_KEY_SSHDSS.
+
+\fIstore\fP should point to a pointer that gets filled in to point to the
+known host data after the addition. NULL can be passed if you don't care about
+this pointer.
+.SH RETURN VALUE
+Returns a regular libssh2 error code, where negative values are error codes
+and 0 indicates success.
+.SH AVAILABILITY
+Added in libssh2 1.2.5
+.SH SEE ALSO
+.BR libssh2_knownhost_init(3)
+.BR libssh2_knownhost_free(3)
+.BR libssh2_knownhost_check(3)

docs/libssh2_knownhost_check.3

@@ -8,7 +8,8 @@ libssh2_knownhost_check - check a host+key against the list of known hosts
 #include <libssh2.h>
 
 int libssh2_knownhost_check(LIBSSH2_KNOWNHOSTS *hosts,
-                            char *host, char *key, size_t keylen,
+                            const char *host,
+                            const char *key, size_t keylen,
                             int typemask,
                             struct libssh2_knownhost **knownhost);
 .SH DESCRIPTION

docs/libssh2_knownhost_checkp.3

@@ -0,0 +1,63 @@
+.\"
+.\" Copyright (c) 2009-2010 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_check 3 "1 May 2010" "libssh2 1.2.6" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_checkp - check a host+key against the list of known hosts
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_checkp(LIBSSH2_KNOWNHOSTS *hosts,
+                             const char *host, int port,
+                             const char *key, size_t keylen,
+                             int typemask,
+                             struct libssh2_knownhost **knownhost);
+.SH DESCRIPTION
+Checks a host and its associated key against the collection of known hosts,
+and returns info back about the (partially) matched entry.
+
+\fIhost\fP is a pointer the host name in plain text. The host name can be the
+IP numerical address of the host or the full name.
+
+\fIport\fP is the port number used by the host (or a negative number
+to check the generic host). If the port number is given, libssh2 will
+check the key for the specific host + port number combination in
+addition to the plain host name only check.
+
+\fIkey\fP is a pointer to the key for the given host.
+
+\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP
+argument
+
+\fItypemask\fP is a bitmask that specifies format and info about the data
+passed to this function. Specificly, it details what format the host name is,
+what format the key is and what key type it is.
+
+The host name is given as one of the following types:
+LIBSSH2_KNOWNHOST_TYPE_PLAIN or LIBSSH2_KNOWNHOST_TYPE_CUSTOM.
+
+The key is encoded using one of the following encodings:
+LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64.
+
+\fIknownhost\fP if set to non-NULL, it must be a pointer to a 'struct
+libssh2_knownhost' pointer that gets filled in to point to info about a known
+host that matches or partially matches.
+.SH RETURN VALUE
+\fIlibssh2_knownhost_check(3)\fP returns info about how well the provided
+host + key pair matched one of the entries in the list of known hosts.
+
+LIBSSH2_KNOWNHOST_CHECK_FAILURE - something prevented the check to be made
+
+LIBSSH2_KNOWNHOST_CHECK_NOTFOUND - no host match was found
+
+LIBSSH2_KNOWNHOST_CHECK_MATCH - hosts and keys match.
+
+LIBSSH2_KNOWNHOST_CHECK_MISMATCH - host was found, but the keys didn't match!
+.SH AVAILABILITY
+Added in libssh2 1.2.6
+.SH EXAMPLE
+See the ssh2_exec.c example as provided in the tarball.
+.SH SEE ALSO
+.BR libssh2_knownhost_init(3)
+.BR libssh2_knownhost_free(3)
+.BR libssh2_knownhost_add(3)

docs/libssh2_knownhost_writeline.3

@@ -35,7 +35,7 @@ and 0 indicates success.
 
 If the provided buffer is deemed too small to fit the data libssh2 wants to
 store in it, LIBSSH2_ERROR_BUFFER_TOO_SMALL will be returned. The application
-is then adviced to call the function again with a larger buffer. The
+is then advised to call the function again with a larger buffer. The
 \fIoutlen\fP size will then hold the requested size.
 .SH AVAILABILITY
 Added in libssh2 1.2

docs/libssh2_poll.3

@@ -8,7 +8,9 @@ libssh2_poll - poll for activity on a socket, channel or listener
 
 int libssh2_poll(LIBSSH2_POLLFD *fds, unsigned int nfds, long timeout);
 .SH DESCRIPTION
-This function is deprecated. Do note use.
+This function is deprecated. Do note use. We encourage users to instead use
+the \fIpoll(3)\fP or \fIselect(3)\fP functions to check for socket activity or
+when specific sockets are ready to get recevied from or send to.
 
 Poll for activity on a socket, channel, listener, or any combination of these
 three types. The calling semantics for this function generally match

docs/libssh2_publickey_add.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_publickey_add 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_publickey_add - convenience macro for \fIlibssh2_publickey_add_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_publickey_add(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_publickey_add_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_publickey_add_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_publickey_add_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_publickey_add_ex(3)\fP

docs/libssh2_publickey_remove.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_publickey_remove 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_publickey_remove - convenience macro for \fIlibssh2_publickey_remove_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_publickey_remove(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_publickey_remove_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_publickey_remove_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_publickey_remove_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_publickey_remove_ex(3)\fP

docs/libssh2_scp_send.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_scp_send 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_scp_send - convenience macro for \fIlibssh2_scp_send_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_scp_send(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_scp_send_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_scp_send_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_scp_send_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_scp_send_ex(3)\fP

docs/libssh2_scp_send64.3

@@ -0,0 +1,49 @@
+.\" $Id: libssh2_scp_send_ex.3,v 1.3 2009/03/17 10:34:27 bagder Exp $
+.\"
+.TH libssh2_scp_send64 3 "17 Apr 2010" "libssh2 1.2.6" "libssh2 manual"
+.SH NAME
+libssh2_scp_send64 - Send a file via SCP
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+
+LIBSSH2_CHANNEL *
+libssh2_scp_send64(LIBSSH2_SESSION *session, const char *path, int mode,
+                   libssh2_uint64_t size, time_t mtime, time_t atime);
+.SH DESCRIPTION
+\fIsession\fP - Session instance as returned by 
+.BR libssh2_session_init_ex(3)
+
+\fIpath\fP - Full path and filename of file to transfer to. That is the remote
+file name.
+
+\fImode\fP - File access mode to create file with
+
+\fIsize\fP - Size of file being transmitted (Must be known ahead of
+time). Note that this needs to be passed on as variable type
+libssh2_uint64_t. This type is 64 bit on modern operating systems and
+compilers.
+
+\fImtime\fP - mtime to assign to file being created
+
+\fIatime\fP - atime to assign to file being created (Set this and 
+mtime to zero to instruct remote host to use current time).
+
+Send a file to the remote host via SCP.
+.SH RETURN VALUE
+Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors.
+
+.SH ERRORS
+\fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
+
+\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
+
+\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - 
+
+\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would
+block.
+.SH AVAILABILITY
+This function was added in libssh2 1.2.6 and is meant to replace the former
+\fIlibssh2_scp_send_ex(3)\fP function.
+.SH SEE ALSO
+.BR libssh2_channel_open_ex(3)

docs/libssh2_scp_send_ex.3

@@ -4,11 +4,16 @@
 .SH NAME
 libssh2_scp_send_ex - Send a file via SCP
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 
 LIBSSH2_CHANNEL *
-libssh2_scp_send_ex(LIBSSH2_SESSION *session, const char *path, int mode, size_t size, long mtime, long atime);
+libssh2_scp_send_ex(LIBSSH2_SESSION *session, const char *path, int mode,
+                    size_t size, long mtime, long atime);
 .SH DESCRIPTION
+This function has been deemed deprecated since libssh2 1.2.6. See
+\fIlibssh2_scp_send64(3)\fP.
+
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
 
@@ -38,6 +43,8 @@ Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors.
 
 \fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would
 block.
-
+.SH AVAILABILITY
+This function was marked deprecated in libssh2 1.2.6 as
+ \fIlibssh2_scp_send64(3)\fP has been introduced to replace this function.
 .SH SEE ALSO
 .BR libssh2_channel_open_ex(3)

docs/libssh2_session_callback_set.3

@@ -4,12 +4,16 @@
 .SH NAME
 libssh2_session_callback_set - set a callback function
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 
-void *
+void *libssh2_session_callback_set(LIBSSH2_SESSION *session,
-libssh2_session_callback_set(LIBSSH2_SESSION *session, int cbtype, void *callback);
+                                   int cbtype, void *callback);
-
 .SH DESCRIPTION
+Sets a custom callback handler for a previously initialized session
+object. Callbacks are triggered by the receipt of special packets at the
+Transport layer. To disable a callback, set it to NULL.
+
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
 
@@ -17,14 +21,19 @@ libssh2_session_callback_set(LIBSSH2_SESSION *session, int cbtype, void *callbac
 
 \fIcallback\fP - Pointer to custom callback function. The prototype for 
 this function must match the associated callback declaration macro.
-
+.SH CALLBACK TYPES
-Sets a custom callback handler for a previously initialized session 
+.IP LIBSSH2_CALLBACK_IGNORE
-object. Callbacks are triggered by the receipt of special packets at 
+Called when a SSH_MSG_IGNORE message is received
-the Transport layer. To disable a callback, set it to NULL.
+.IP LIBSSH2_CALLBACK_DEBUG
-
+Called when a SSH_MSG_DEBUG message is received
+.IP LIBSSH2_CALLBACK_DISCONNECT
+Called when a SSH_MSG_DISCONNECT message is received
+.IP LIBSSH2_CALLBACK_MACERROR
+Called when a mismatched MAC has been detected in the transport layer
+.IP LIBSSH2_CALLBACK_X11
+Called when an X11 connection has been accepted
 .SH RETURN VALUE
-Pointer to previous callback handler. Returns NULL if no 
+Pointer to previous callback handler. Returns NULL if no prior callback
-prior callback handler was set.
+handler was set or the callback type was unknown.
-
 .SH SEE ALSO
 .BR libssh2_session_init_ex(3)

docs/libssh2_session_disconnect.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_session_disconnect 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_session_disconnect - convenience macro for \fIlibssh2_session_disconnect_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_session_disconnect(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_session_disconnect_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_session_disconnect_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_session_disconnect_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_session_disconnect_ex(3)\fP

docs/libssh2_session_free.3

@@ -9,7 +9,7 @@ libssh2_session_free - frees resources associated with a session instance
 int 
 libssh2_session_free(LIBSSH2_SESSION *session);
 .SH DESCRIPTION
-Frees resources associated with a session instance. Typically called after
+Frees all resources associated with a session instance. Typically called after
 .BR libssh2_session_disconnect_ex(3)
 .SH RETURN VALUE
 Return 0 on success or negative on failure.  It returns

docs/libssh2_session_init.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_session_init 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_session_init - convenience macro for \fIlibssh2_session_init_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_session_init(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_session_init_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_session_init_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_session_init_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_session_init_ex(3)\fP

docs/libssh2_sftp_close.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_close 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_close - convenience macro for \fIlibssh2_sftp_close_handle(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_close(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_close_handle(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_close_handle(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_close_handle(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_close_handle(3)\fP

docs/libssh2_sftp_closedir.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_closedir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_closedir - convenience macro for \fIlibssh2_sftp_close_handle(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_closedir(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_close_handle(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_close_handle(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_close_handle(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_close_handle(3)\fP

docs/libssh2_sftp_fsetstat.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_fsetstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_fsetstat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_fsetstat(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_fstat_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_fstat_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_fstat_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_fstat_ex(3)\fP

docs/libssh2_sftp_fstat.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_fstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_fstat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_fstat(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_fstat_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_fstat_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_fstat_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_fstat_ex(3)\fP

docs/libssh2_sftp_fstat_ex.3

@@ -2,32 +2,88 @@
 .\"
 .TH libssh2_sftp_fstat_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual"
 .SH NAME
-libssh2_sftp_fstat_ex - get or set attributes on a file handle
+libssh2_sftp_fstat_ex - get or set attributes on an SFTP file handle
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
 int 
-libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat)
+libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle,
-
+                      LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat)
-int 
-libssh2_sftp_fstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs)
-
-int 
-libssh2_sftp_fsetstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs)
 
+#define libbssh2_sftp_fstat(handle, attrs) \\
+    libssh2_sftp_fstat_ex((handle), (attrs), 0)
+#define libssh2_sftp_fsetstat(handle, attrs) \\
+    libssh2_sftp_fstat_ex((handle), (attrs), 1)
+.fi
 .SH DESCRIPTION
 \fIhandle\fP - SFTP File Handle as returned by 
 .BR libssh2_sftp_open_ex(3)
 
-\fIattrs\fP - Pointer to attribute structure to set file metadata 
+\fIattrs\fP - Pointer to an LIBSSH2_SFTP_ATTRIBUTES structure to set file
-from or into depending on the value of setstat.
+metadata from or into depending on the value of setstat.
 
 \fIsetstat\fP - When non-zero, the file's metadata will be updated 
 with the data found in attrs according to the values of attrs->flags 
 and other relevant member attributes.
 
 Get or Set statbuf type data for a given LIBSSH2_SFTP_HANDLE instance.
+.SH DATA TYPES
+LIBSSH2_SFTP_ATTRIBUTES is a typedefed struct that is defined as below
+
+.nf
+struct _LIBSSH2_SFTP_ATTRIBUTES {
+
+    /* If flags & ATTR_* bit is set, then the value in this
+     * struct will be meaningful Otherwise it should be ignored
+     */
+    unsigned long flags;
+
+    /* size of file, in bytes */
+    libssh2_uint64_t filesize;
+
+    /* numerical representation of the user and group owner of
+     * the file
+     */
+    unsigned long uid, gid;
+
+    /* bitmask of permissions */
+    unsigned long permissions;
+
+    /* access time and modified time of file */
+    unsigned long atime, mtime;
+};
+.fi
+
+You will find a full set of defines and macros to identify flags and
+permissions on the \fBlibssh2_sftp.h\fP header file, but some of the
+most common ones are:
+
+To check for specific user permissions, the set of defines are in the
+pattern LIBSSH2_SFTP_S_I<action><who> where <action> is R, W or X for
+read, write and excutable and <who> is USR, GRP and OTH for user,
+group and other. So, you check for a user readable file, use the bit
+\fILIBSSH2_SFTP_S_IRUSR\fP while you want to see if it is executable
+for other, you use \fILIBSSH2_SFTP_S_IXOTH\fP and so on.
+
+To check for specific file types, you would previously (before libssh2
+1.2.5) use the standard posix S_IS***() macros, but since 1.2.5
+libssh2 offers its own set of macros for this functionality:
+.IP LIBSSH2_SFTP_S_ISLNK
+Test for a symbolic link
+.IP LIBSSH2_SFTP_S_ISREG
+Test for a regular file
+.IP LIBSSH2_SFTP_S_ISDIR
+Test for a directory
+.IP LIBSSH2_SFTP_S_ISCHR
+Test for a character special file
+.IP LIBSSH2_SFTP_S_ISBLK
+Test for a block special file
+.IP LIBSSH2_SFTP_S_ISFIFO
+Test for a pipe or FIFO special file
+.IP LIBSSH2_SFTP_S_ISSOCK
+Test for a socket
 .SH RETURN VALUE
 Return 0 on success or negative on failure.  It returns
 LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
@@ -42,5 +98,9 @@ LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
 \fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was 
 received on the socket, or an SFTP operation caused an errorcode to 
 be returned by the server.
+.SH AVAILABILITY
+This function has been around since forever, but most of the
+LIBSSH2_SFTP_S_* defines were introduced in libssh2 0.14 and the
+LIBSSH2_SFTP_S_IS***() macros were introduced in libssh2 1.2.5.
 .SH SEE ALSO
 .BR libssh2_sftp_open_ex(3)

docs/libssh2_sftp_fstatvfs.3

@@ -0,0 +1 @@
+.so man3/libssh2_sftp_statvfs.3

docs/libssh2_sftp_last_error.3

@@ -17,7 +17,7 @@ libssh2_sftp_last_error(LIBSSH2_SFTP *sftp);
 Returns the last error code produced by the SFTP layer. Note that this only
 returns a sensible error code if libssh2 returned LIBSSH2_ERROR_SFTP_PROTOCOL
 in a previous call. Using \fBlibssh2_sftp_last_error(3)\fP without a
-preceeding SFTP protocol error, it will return an unspecified value.
+preceding SFTP protocol error, it will return an unspecified value.
 
 .SH RETURN VALUE
 Current error code state of the SFTP instance.

docs/libssh2_sftp_lstat.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_lstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_lstat - convenience macro for \fIlibssh2_sftp_stat_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_lstat(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_stat_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_stat_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_stat_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_stat_ex(3)\fP

docs/libssh2_sftp_mkdir.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_mkdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_mkdir - convenience macro for \fIlibssh2_sftp_mkdir_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_mkdir(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_mkdir_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_mkdir_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_mkdir_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_mkdir_ex(3)\fP

docs/libssh2_sftp_open.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_open 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_open - convenience macro for \fIlibssh2_sftp_open_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_open(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_open_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_open_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_open_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_open_ex(3)\fP

docs/libssh2_sftp_opendir.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_opendir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_opendir - convenience macro for \fIlibssh2_sftp_open_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_opendir(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_open_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_open_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_open_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_open_ex(3)\fP

docs/libssh2_sftp_readdir.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_readdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_readdir - convenience macro for \fIlibssh2_sftp_readdir_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_readdir(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_readdir_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_readdir_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_readdir_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_readdir_ex(3)\fP

docs/libssh2_sftp_readdir_ex.3

@@ -4,16 +4,22 @@
 .SH NAME
 libssh2_sftp_readdir_ex - read directory data from an SFTP handle
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
 int 
-libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, char *longentry, size_t longentry_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
+libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle,
-
+                        char *buffer, size_t buffer_maxlen,
-int 
+                        char *longentry, size_t longentry_maxlen,
-libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
+                        LIBSSH2_SFTP_ATTRIBUTES *attrs);
 
+#define libssh2_sftp_readdir(h, b, bl, a)      \\
+    libssh2_sftp_readdir_ex((h), (b), (bl), NULL, 0, (a))
 .SH DESCRIPTION
+Reads a block of data from a LIBSSH2_SFTP_HANDLE and returns file entry
+information for the next entry, if any.
+
 \fIhandle\fP - is the SFTP File Handle as returned by 
 .BR libssh2_sftp_open_ex(3)
 
@@ -25,25 +31,22 @@ filename is longer than the space provided by buffer_maxlen it will be
 truncated to fit.
 
 \fIlongentry\fP - is a pointer to a pre-allocated buffer of at least
-\fIlongentry_maxlen\fP bytes to read data into.
+\fIlongentry_maxlen\fP bytes to read data into. The format of the `longname'
+field is unspecified by SFTP protocol. It MUST be suitable for use in the
+output of a directory listing command (in fact, the recommended operation for
+a directory listing command is to simply display this data).
 
-\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length 
+\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length of
-of the full directory entry is longer than the space provided by 
+the full directory entry is longer than the space provided by
-longentry_maxlen it will be truncated to fit.
+\fIlongentry_maxlen\fP it will be truncated to fit.
 
 \fIattrs\fP - is a pointer to LIBSSH2_SFTP_ATTRIBUTES storage to populate 
 statbuf style data into.
-
-Read a block of data from a LIBSSH2_SFTP_HANDLE. This method is modeled 
-after the POSIX 
-.BR readdir(2)
-however, it uses a variable sized directory entry (filename) buffer and 
-returns statbuf type data in the same call.
-
 .SH RETURN VALUE
-Number of bytes actually populated into buffer, or negative on failure.  It
+Number of bytes actually populated into buffer (not counting the terminating
-returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
+zero), or negative on failure.  It returns LIBSSH2_ERROR_EAGAIN when it would
-LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
+otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it isn't
+really a failure per se.
 .SH ERRORS
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
 

docs/libssh2_sftp_readlink.3

@@ -0,0 +1,21 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_readlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_readlink - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+
+#define libssh2_sftp_readlink(sftp, path, target, maxlen) \\
+    libssh2_sftp_symlink_ex((sftp), (path), strlen(path), (target), (maxlen), \\
+    LIBSSH2_SFTP_READLINK)
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_symlink_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_symlink_ex(3)\fP

docs/libssh2_sftp_realpath.3

@@ -0,0 +1,21 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_realpath 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_realpath - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+
+#define libssh2_sftp_realpath(sftp, path, target, maxlen) \\
+  libssh2_sftp_symlink_ex((sftp), (path), strlen(path), (target), (maxlen), \\
+                          LIBSSH2_SFTP_REALPATH)
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_symlink_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_symlink_ex(3)\fP

docs/libssh2_sftp_rename.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_rename 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_rename - convenience macro for \fIlibssh2_sftp_rename_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_rename(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_rename_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_rename_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_rename_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_rename_ex(3)\fP

docs/libssh2_sftp_rewind.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_rewind 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_rewind - convenience macro for \fIlibssh2_sftp_seek64(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_rewind(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_seek64(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_seek64(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_seek64(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_seek64(3)\fP

docs/libssh2_sftp_rmdir.3

@@ -0,0 +1,20 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_rmdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_rmdir - convenience macro for \fIlibssh2_sftp_rmdir_ex(3)\fP
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+
+#define libssh2_sftp_rmdir(sftp, path) \\
+    libssh2_sftp_rmdir_ex((sftp), (path), strlen(path))
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_rmdir_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_rmdir_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_rmdir_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_rmdir_ex(3)\fP

docs/libssh2_sftp_rmdir_ex.3

@@ -4,30 +4,26 @@
 .SH NAME
 libssh2_sftp_rmdir_ex - remove an SFTP directory
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
-int 
+int libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path,
-libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len);
+                          unsigned int path_len);
-
-int 
-libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path);
-
 .SH DESCRIPTION
+Remove a directory from the remote file system.
+
 \fIsftp\fP - SFTP instance as returned by 
 .BR libssh2_sftp_init(3)
 
 \fIsourcefile\fP - Full path of the existing directory to remove.
 
-\fIsourcefile_len\fP - Length of the full path of the existing directory to remove. 
+\fIsourcefile_len\fP - Length of the full path of the existing directory to
-
+remove.
-Remove a directory from the remote file system.
-
 .SH RETURN VALUE
 Return 0 on success or negative on failure.  It returns
 LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
 LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
-
 .SH ERRORS
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
 
@@ -38,6 +34,5 @@ LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
 \fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was 
 received on the socket, or an SFTP operation caused an errorcode to 
 be returned by the server.
-
 .SH SEE ALSO
 .BR libssh2_sftp_init(3)

docs/libssh2_sftp_setstat.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_setstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_setstat - convenience macro for \fIlibssh2_sftp_stat_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_setstat(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_stat_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_stat_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_stat_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_stat_ex(3)\fP

docs/libssh2_sftp_stat.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_stat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_stat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_stat(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_fstat_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_fstat_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_fstat_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_fstat_ex(3)\fP

docs/libssh2_sftp_stat_ex.3

@@ -25,7 +25,7 @@ libssh2_sftp_setstat(LIBSSH2_SFTP *sftp, const char *path, LIBSSH2_SFTP_ATTRIBUT
 
 \fIpath\fP - Remote filesystem object to stat/lstat/setstat.
 
-\fIpath_len\fP - Lenght of the name of the remote filesystem object 
+\fIpath_len\fP - Length of the name of the remote filesystem object 
 to stat/lstat/setstat.
 
 \fIstat_type\fP - One of the three constants specifying the type of 

docs/libssh2_sftp_statvfs.3

@@ -0,0 +1,79 @@
+.TH libssh2_sftp_statvfs 3 "22 May 2010" "libssh2 1.2.6" "libssh2 manual"
+.SH NAME
+libssh2_sftp_statvfs, libssh2_sftp_fstatvfs - get file system statistics
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+#include <libssh2_sftp.h>
+
+int
+libssh2_sftp_statvfs(LIBSSH2_SFTP *sftp, const char *path,
+                     size_t path_len, LIBSSH2_SFTP_STATVFS *st);
+
+int
+libssh2_sftp_fstatvfs(LIBSSH2_SFTP_HANDLE *handle,
+                      LIBSSH2_SFTP_STATVFS *st)
+.fi
+.SH DESCRIPTION
+These functions provide statvfs(2)-like operations and require
+statvfs@openssh.com and fstatvfs@openssh.com extension support on the server.
+
+\fIsftp\fP - SFTP instance as returned by
+.BR libssh2_sftp_init(3)
+
+\fIhandle\fP - SFTP File Handle as returned by
+.BR libssh2_sftp_open_ex(3)
+
+\fIpath\fP - full path of any file within the mounted file system.
+
+\fIpath_len\fP - length of the full path.
+
+\fIst\fP - Pointer to a LIBSSH2_SFTP_STATVFS structure to place file system
+statistics into.
+
+.SH DATA TYPES
+LIBSSH2_SFTP_STATVFS is a typedefed struct that is defined as below
+
+.nf
+struct _LIBSSH2_SFTP_STATVFS {
+    libssh2_uint64_t  f_bsize;    /* file system block size */
+    libssh2_uint64_t  f_frsize;   /* fragment size */
+    libssh2_uint64_t  f_blocks;   /* size of fs in f_frsize units */
+    libssh2_uint64_t  f_bfree;    /* # free blocks */
+    libssh2_uint64_t  f_bavail;   /* # free blocks for non-root */
+    libssh2_uint64_t  f_files;    /* # inodes */
+    libssh2_uint64_t  f_ffree;    /* # free inodes */
+    libssh2_uint64_t  f_favail;   /* # free inodes for non-root */
+    libssh2_uint64_t  f_fsid;     /* file system ID */
+    libssh2_uint64_t  f_flag;     /* mount flags */
+    libssh2_uint64_t  f_namemax;  /* maximum filename length */
+};
+.fi
+
+It is unspecified whether all members of the returned struct have meaningful
+values on all file systems.
+
+The field \fIf_flag\fP is a bit mask. Bits are defined as follows:
+.IP LIBSSH2_SFTP_ST_RDONLY
+Read-only file system.
+.IP LIBSSH2_SFTP_ST_NOSUID
+Set-user-ID/set-group-ID bits are ignored by \fBexec\fP(3).
+
+.SH RETURN VALUE
+Returns 0 on success or negative on failure. If used in non-blocking mode, it
+returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
+LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
+.SH ERRORS
+\fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
+
+\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
+
+\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - 
+
+\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was
+received on the socket, or an SFTP operation caused an errorcode to be returned
+by the server.
+.SH AVAILABILITY
+Added in libssh2 1.2.6
+.SH SEE ALSO
+.BR libssh2_sftp_open_ex(3)

docs/libssh2_sftp_symlink.3

@@ -0,0 +1,21 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_symlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_symlink - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+
+#define libssh2_sftp_symlink(sftp, orig, linkpath) \\
+    libssh2_sftp_symlink_ex((sftp), (orig), strlen(orig), (linkpath), \\
+                            strlen(linkpath), LIBSSH2_SFTP_SYMLINK)
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_symlink_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_symlink_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_symlink_ex(3)\fP

docs/libssh2_sftp_symlink_ex.3

@@ -4,22 +4,20 @@
 .SH NAME
 libssh2_sftp_symlink_ex - read or set a symbolic link
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
 int 
-libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len, char *target, unsigned int target_len, int link_type);
+libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path,
-
+                        unsigned int path_len, char *target,
+                        unsigned int target_len, int link_type);
 int 
-libssh2_sftp_symlink(LIBSSH2_SFTP *sftp, const char *path, char *target);
+libssh2_sftp_realpath(LIBSSH2_SFTP *sftp, const char *path, char *target,
-
+                      unsigned int target_len);
-int 
-libssh2_sftp_readlink(LIBSSH2_SFTP *sftp, const char *path, char *target, unsigned int target_len);
-
-int 
-libssh2_sftp_realpath(LIBSSH2_SFTP *sftp, const char *path, char *target, unsigned int target_len);
-
 .SH DESCRIPTION
+Create a symlink or read out symlink information from the remote side.
+
 \fIsftp\fP - SFTP instance as returned by 
 .BR libssh2_sftp_init(3)
 
@@ -28,19 +26,24 @@ libssh2_sftp_realpath(LIBSSH2_SFTP *sftp, const char *path, char *target, unsign
 \fIpath_len\fP - Length of the name of the remote filesystem object to 
 create a symlink from or resolve.
 
-\fItarget\fP - 
+\fItarget\fP - a pointer to a buffer. The buffer has different uses depending
+what the \fIlink_type\fP argument is set to.
 .br
 \fBLIBSSH2_SFTP_SYMLINK\fP: Remote filesystem object to link to.
 .br
-\fBLIBSSH2_SFTP_READLINK\fP: Pre-allocated buffer to resolve symlink target into.
+\fBLIBSSH2_SFTP_READLINK\fP: Pre-allocated buffer to resolve symlink target
+into.
 .br
-\fBLIBSSH2_SFTP_REALPATH\fP: Pre-allocated buffer to resolve realpath target into.
+\fBLIBSSH2_SFTP_REALPATH\fP: Pre-allocated buffer to resolve realpath target
+into.
 
 \fItarget_len\fP - Length of the name of the remote filesystem target object.
 
 \fIlink_type\fP - One of the three previously mentioned constants which 
 determines the resulting behavior of this function.
 
+These are convenience macros:
+
 .BR libssh2_sftp_symlink(3)
 : Create a symbolic link between two filesystem objects.
 .br
@@ -49,12 +52,16 @@ determines the resulting behavior of this function.
 .br
 .BR libssh2_sftp_realpath(3)
 : Resolve a complex, relative, or symlinked filepath to its effective target.
-
 .SH RETURN VALUE
-Return 0 on success or negative on failure.  It returns
+When using LIBSSH2_SFTP_SYMLINK, this funtion returns 0 on success or negative
-LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
+on failure.
-LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
 
+When using LIBSSH2_SFTP_READLINK or LIBSSH2_SFTP_REALPATH, it returns the
+number of bytes it copied to the target buffer (not including the terminating
+zero) or negative on failure.
+
+It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
+LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
 .SH ERRORS
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
 

docs/libssh2_sftp_unlink.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_sftp_unlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_sftp_unlink - convenience macro for \fIlibssh2_sftp_unlink_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_sftp_unlink(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_sftp_unlink_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_sftp_unlink_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_sftp_unlink_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_sftp_unlink_ex(3)\fP

docs/libssh2_sftp_write.3

@@ -4,23 +4,29 @@
 .SH NAME
 libssh2_sftp_write - write SFTP data
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
-ssize_t 
+ssize_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle,
-libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, const char *buffer, size_t count);
+                           const char *buffer,
-
+                           size_t count);
 .SH DESCRIPTION
+\fBlibssh2_sftp_write(3)\fP writes a block of data to the SFTP server. This
+method is modeled after the POSIX write() function and uses the same calling
+semantics.
+
 \fIhandle\fP - SFTP file handle as returned by \fIlibssh2_sftp_open_ex(3)\fP.
 
-\fIbuffer\fP - points to the data to send off
+\fIbuffer\fP - points to the data to send off.
 
 \fIcount\fP - Number of bytes from 'buffer' to write. Note that it may not be
 possible to write all bytes as requested.
 
-\fBlibssh2_sftp_write(3)\fP writes a block of data to the SFTP server. This
+\fIlibssh2_sftp_handle(3)\fP will use as much as possible of the buffer and
-method is modeled after the POSIX write() function and uses the same calling
+put it into a single SFTP protocol packet. This means that to get maximum
-semantics.
+performance when sending larger files, you should try to always pass in at
+least 32K of data to this function.
 .SH RETURN VALUE
 Actual number of bytes written or negative on failure.
 

docs/libssh2_userauth_hostbased_fromfile.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_userauth_hostbased_fromfile 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_userauth_hostbased_fromfile - convenience macro for \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_userauth_hostbased_fromfile(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP

docs/libssh2_userauth_keyboard_interactive.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_userauth_keyboard_interactive 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_userauth_keyboard_interactive - convenience macro for \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_userauth_keyboard_interactive(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP

docs/libssh2_userauth_password.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_userauth_password 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_userauth_password - convenience macro for \fIlibssh2_userauth_password_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_userauth_password(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_userauth_password_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_userauth_password_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_userauth_password_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_userauth_password_ex(3)\fP

docs/libssh2_userauth_password_ex.3

@@ -5,13 +5,18 @@
 libssh2_userauth_password_ex - authenticate a session with username and password
 .SH SYNOPSIS
 #include <libssh2.h>
+.nf
+int libssh2_userauth_password_ex(LIBSSH2_SESSION *session,
+                    const char *username,
+                    unsigned int username_len,
+                    const char *password,
+                    unsigned int password_len,
+                    LIBSSH2_PASSWD_CHANGEREQ_FUNC((*passwd_change_cb)));
 
-int
+#define libssh2_userauth_password(session, username, password) \\
-libssh2_userauth_password_ex(LIBSSH2_SESSION *session, const char *username, unsigned int username_len, const char *password, unsigned int password_len, LIBSSH2_PASSWD_CHANGEREQ_FUNC((*passwd_change_cb)));
+ libssh2_userauth_password_ex((session), (username), \\
-
+                              strlen(username), \\
-int
+                              (password), strlen(password), NULL)
-libssh2_userauth_password(LIBSSH2_SESSION *session, const char *username, const char *password);
-
 .SH DESCRIPTION
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
@@ -40,13 +45,15 @@ LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
 LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se.
 
 .SH ERRORS
+Some of the errors this function may return include:
+
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
 
 \fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
 
 \fILIBSSH2_ERROR_PASSWORD_EXPIRED\fP - 
 
-\fLIBSSH2_ERROR_AUTHENTICATION_FAILED\fP -  failed, invalid username/password or public/private key.
+\fLIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - failed, invalid username/password
-
+or public/private key.
 .SH SEE ALSO
 .BR libssh2_session_init_ex(3)

docs/libssh2_userauth_publickey_fromfile.3

@@ -0,0 +1,19 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_userauth_publickey_fromfile 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual"
+.SH NAME
+libssh2_userauth_publickey_fromfile - convenience macro for \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP calls
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_userauth_publickey_fromfile(arguments)
+
+.SH DESCRIPTION
+This is a macro defined in a public libssh2 header file that is using the
+underlying function \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP.
+.SH RETURN VALUE
+See \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP
+.SH ERRORS
+See \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP
+.SH SEE ALSO
+.BR \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP

example/direct_tcpip.c

@@ -1,3 +1,4 @@
+#include "libssh2_config.h"
 #include <libssh2.h>
 
 #ifdef WIN32
@@ -18,6 +19,10 @@
 #include <unistd.h>
 #include <sys/types.h>
 
+#ifdef HAVE_SYS_SELECT_H
+#include <sys/select.h>
+#endif
+
 #ifndef INADDR_NONE
 #define INADDR_NONE (in_addr_t)-1
 #endif
@@ -81,6 +86,12 @@ int main(int argc, char *argv[])
     if (argc > 7)
         remote_destport = atoi(argv[7]);
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /* Connect to SSH server */
     sock = socket(PF_INET, SOCK_STREAM, IPPROTO_TCP);
     sin.sin_family = AF_INET;
@@ -144,7 +155,8 @@ int main(int argc, char *argv[])
             goto shutdown;
         }
     } else if (auth & AUTH_PUBLICKEY) {
-        if (libssh2_userauth_publickey_fromfile(session, username, keyfile1, keyfile2, password)) {
+        if (libssh2_userauth_publickey_fromfile(session, username, keyfile1,
+                                                keyfile2, password)) {
             printf("\tAuthentication by public key failed!\n");
             goto shutdown;
         }
@@ -191,8 +203,9 @@ int main(int argc, char *argv[])
     channel = libssh2_channel_direct_tcpip_ex(session, remote_desthost,
         remote_destport, shost, sport);
     if (!channel) {
-        fprintf(stderr, "Could not open the direct-tcpip channel!\n");
+        fprintf(stderr, "Could not open the direct-tcpip channel!\n"
-        fprintf(stderr, "(Note that this can be a problem at the server! Please review the server logs.)\n");
+                "(Note that this can be a problem at the server!"
+                " Please review the server logs.)\n");
         goto shutdown;
     }
 
@@ -271,5 +284,8 @@ shutdown:
 #else
     close(sock);
 #endif
+
+    libssh2_exit();
+
     return 0;
 }

example/scp.c

@@ -68,6 +68,12 @@ int main(int argc, char *argv[])
         scppath = argv[4];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /* Ultra basic "connect to port 22 on localhost"
      * Your code is responsible for creating the socket establishing the
      * connection
@@ -145,10 +151,10 @@ int main(int argc, char *argv[])
         }
 
         rc = libssh2_channel_read(channel, mem, amount);
-        if(rc == amount) {
+        if(rc > 0) {
             write(1, mem, rc);
         }
-        else {
+        else if(rc < 0) {
             fprintf(stderr, "libssh2_channel_read() failed: %d\n", rc);
             break;
         }
@@ -169,5 +175,8 @@ int main(int argc, char *argv[])
     close(sock);
 #endif
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/scp_nonblock.c

@@ -121,6 +121,12 @@ int main(int argc, char *argv[])
         scppath = argv[4];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /* Ultra basic "connect to port 22 on localhost"
      * Your code is responsible for creating the socket establishing the
      * connection
@@ -267,5 +273,8 @@ shutdown:
     close(sock);
 #endif
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/scp_write.c

@@ -38,7 +38,7 @@ int main(int argc, char *argv[])
     int sock, i, auth_pw = 1;
     struct sockaddr_in sin;
     const char *fingerprint;
-    LIBSSH2_SESSION *session;
+    LIBSSH2_SESSION *session = NULL;
     LIBSSH2_CHANNEL *channel;
     const char *username="username";
     const char *password="password";
@@ -47,7 +47,7 @@ int main(int argc, char *argv[])
     FILE *local;
     int rc;
     char mem[1024];
-    size_t nread, sent;
+    size_t nread;
     char *ptr;
     struct stat fileinfo;
 
@@ -75,10 +75,16 @@ int main(int argc, char *argv[])
         scppath = argv[5];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     local = fopen(loclfile, "rb");
     if (!local) {
-        fprintf(stderr, "Can't local file %s\n", loclfile);
+        fprintf(stderr, "Can't open local file %s\n", loclfile);
-        goto shutdown;
+        return -1;
     }
 
     stat(loclfile, &fileinfo);
@@ -88,6 +94,10 @@ int main(int argc, char *argv[])
      * connection
      */
     sock = socket(AF_INET, SOCK_STREAM, 0);
+    if(-1 == sock) {
+        fprintf(stderr, "failed to create socket!\n");
+        return -1;
+    }
 
     sin.sin_family = AF_INET;
     sin.sin_port = htons(22);
@@ -147,7 +157,10 @@ int main(int argc, char *argv[])
                                (unsigned long)fileinfo.st_size);
 
     if (!channel) {
-        fprintf(stderr, "Unable to open a session\n");
+        char *errmsg;
+        int errlen;
+        int err = libssh2_session_last_error(session, &errmsg, &errlen, 0);
+        fprintf(stderr, "Unable to open a session: (%d) %s\n", err, errmsg);
         goto shutdown;
     }
 
@@ -159,20 +172,21 @@ int main(int argc, char *argv[])
             break;
         }
         ptr = mem;
-        sent = 0;
 
         do {
             /* write the same data over and over, until error or completion */
             rc = libssh2_channel_write(channel, ptr, nread);
             if (rc < 0) {
                 fprintf(stderr, "ERROR %d\n", rc);
-            } else {
+                break;
-                /* rc indicates how many bytes were written this time */
-                sent += rc;
             }
-        } while (rc > 0 && sent < nread);
+            else {
-        ptr += sent;
+                /* rc indicates how many bytes were written this time */
-        nread -= sent;
+                ptr += rc;
+                nread -= rc;
+            }
+        } while (nread);
+
     } while (1);
 
     fprintf(stderr, "Sending EOF\n");
@@ -189,14 +203,20 @@ int main(int argc, char *argv[])
 
  shutdown:
 
-    libssh2_session_disconnect(session, "Normal Shutdown, Thank you for playing");
+    if(session) {
-    libssh2_session_free(session);
+        libssh2_session_disconnect(session, "Normal Shutdown, Thank you for playing");
-
+        libssh2_session_free(session);
+    }
 #ifdef WIN32
     closesocket(sock);
 #else
     close(sock);
 #endif
+    if (local)
+        fclose(local);
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/scp_write_nonblock.c

@@ -32,6 +32,7 @@
 #include <errno.h>
 #include <stdio.h>
 #include <ctype.h>
+#include <time.h>
 
 int main(int argc, char *argv[])
 {
@@ -39,7 +40,7 @@ int main(int argc, char *argv[])
     int sock, i, auth_pw = 1;
     struct sockaddr_in sin;
     const char *fingerprint;
-    LIBSSH2_SESSION *session;
+    LIBSSH2_SESSION *session = NULL;
     LIBSSH2_CHANNEL *channel;
     const char *username="username";
     const char *password="password";
@@ -50,10 +51,13 @@ int main(int argc, char *argv[])
 #if defined(HAVE_IOCTLSOCKET)
     long flag = 1;
 #endif
-    char mem[1024];
+    char mem[1024*100];
-    size_t nread, sent;
+    size_t nread;
     char *ptr;
     struct stat fileinfo;
+    time_t start;
+    long total = 0;
+    int duration;
 
 #ifdef WIN32
     WSADATA wsadata;
@@ -79,10 +83,16 @@ int main(int argc, char *argv[])
         scppath = argv[5];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     local = fopen(loclfile, "rb");
     if (!local) {
         fprintf(stderr, "Can't local file %s\n", loclfile);
-        goto shutdown;
+        return -1;
     }
 
     stat(loclfile, &fileinfo);
@@ -169,6 +179,7 @@ int main(int argc, char *argv[])
     } while (!channel);
 
     fprintf(stderr, "SCP session waiting to send file\n");
+    start = time(NULL);
     do {
         nread = fread(mem, 1, sizeof(mem), local);
         if (nread <= 0) {
@@ -176,7 +187,8 @@ int main(int argc, char *argv[])
             break;
         }
         ptr = mem;
-        sent = 0;
+
+        total += nread;
 
         do {
             /* write the same data over and over, until error or completion */
@@ -185,14 +197,19 @@ int main(int argc, char *argv[])
                 continue;
             } else if (rc < 0) {
                 fprintf(stderr, "ERROR %d\n", rc);
+                break;
             } else {
                 /* rc indicates how many bytes were written this time */
-                sent += rc;
+                nread -= rc;
+                ptr += rc;
             }
-        } while (rc > 0 && sent < nread);
+        } while (nread);
-        ptr += sent;
+    } while (!nread); /* only continue if nread was drained */
-        nread -= sent;
+
-    } while (1);
+    duration = (int)(time(NULL)-start);
+
+    printf("%ld bytes in %d seconds makes %.1f bytes/sec\n",
+           total, duration, total/(double)duration);
 
     fprintf(stderr, "Sending EOF\n");
     while (libssh2_channel_send_eof(channel) == LIBSSH2_ERROR_EAGAIN);
@@ -208,8 +225,9 @@ int main(int argc, char *argv[])
 
  shutdown:
 
-    while ((rc = libssh2_session_disconnect(session,
+    while (libssh2_session_disconnect(session,
-                                            "Normal Shutdown, Thank you for playing")) == LIBSSH2_ERROR_EAGAIN);
+                                      "Normal Shutdown, Thank you for playing") ==
+           LIBSSH2_ERROR_EAGAIN);
     libssh2_session_free(session);
 
 #ifdef WIN32
@@ -218,5 +236,8 @@ int main(int argc, char *argv[])
     close(sock);
 #endif
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftp.c

@@ -52,17 +52,45 @@ static void kbd_callback(const char *name, int name_len,
              LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses,
              void **abstract)
 {
-    (void)name;
+    int i;
-    (void)name_len;
+    size_t n;
-    (void)instruction;
+    char buf[1024];
-    (void)instruction_len;
-    if (num_prompts == 1) {
-        responses[0].text = strdup(password);
-        responses[0].length = strlen(password);
-    }
-    (void)prompts;
     (void)abstract;
-} /* kbd_callback */
+
+    printf("Performing keyboard-interactive authentication.\n");
+
+    printf("Authentication name: '");
+    fwrite(name, 1, name_len, stdout);
+    printf("'\n");
+
+    printf("Authentication instruction: '");
+    fwrite(instruction, 1, instruction_len, stdout);
+    printf("'\n");
+
+    printf("Number of prompts: %d\n\n", num_prompts);
+
+    for (i = 0; i < num_prompts; i++) {
+        printf("Prompt %d from server: '", i);
+        fwrite(prompts[i].text, 1, prompts[i].length, stdout);
+        printf("'\n");
+
+        printf("Please type response: ");
+        fgets(buf, sizeof(buf), stdin);
+        n = strlen(buf);
+        while (n > 0 && strchr("\r\n", buf[n - 1]))
+          n--;
+        buf[n] = 0;
+
+        responses[i].text = strdup(buf);
+        responses[i].length = n;
+
+        printf("Response %d from user is '", i);
+        fwrite(responses[i].text, 1, responses[i].length, stdout);
+        printf("'\n\n");
+    }
+
+    printf("Done. Sending keyboard-interactive responses to server now.\n");
+}
 
 
 int main(int argc, char *argv[])
@@ -98,6 +126,13 @@ int main(int argc, char *argv[])
     if(argc > 4) {
         sftppath = argv[4];
     }
+
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /*
      * The application code is responsible for creating the socket
      * and establishing the connection
@@ -241,5 +276,8 @@ int main(int argc, char *argv[])
     close(sock);
 #endif
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftp_RW_nonblock.c

@@ -72,6 +72,12 @@ int main(int argc, char *argv[])
     WSAStartup(MAKEWORD(2,0), &wsadata);
 #endif
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /* Ultra basic "connect to port 22 on localhost"
      * The application is responsible for creating the socket establishing
      * the connection
@@ -240,7 +246,7 @@ int main(int argc, char *argv[])
                                         nread);
                 ptr += rc;
                 nread -= nread;
-            } while (rc > 0);
+            } while (rc >= 0);
 
             if(rc != LIBSSH2_ERROR_EAGAIN) {
                 /* error or end of file */
@@ -283,6 +289,11 @@ int main(int argc, char *argv[])
 #else
     close(sock);
 #endif
+    if (tempstorage)
+        fclose(tempstorage);
     printf("all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftp_mkdir.c

@@ -70,6 +70,12 @@ int main(int argc, char *argv[])
         sftppath = argv[4];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /*
      * The application code is responsible for creating the socket
      * and establishing the connection
@@ -129,7 +135,6 @@ int main(int argc, char *argv[])
         }
     }
 
-    fprintf(stderr, "libssh2_sftp_init()!\n");
     sftp_session = libssh2_sftp_init(session);
 
     if (!sftp_session) {
@@ -140,13 +145,15 @@ int main(int argc, char *argv[])
     /* Since we have not set non-blocking, tell libssh2 we are blocking */
     libssh2_session_set_blocking(session, 1);
 
-    fprintf(stderr, "libssh2_sftp_mkdir()!\n");
     /* Make a directory via SFTP */
     rc = libssh2_sftp_mkdir(sftp_session, sftppath,
                             LIBSSH2_SFTP_S_IRWXU|
                             LIBSSH2_SFTP_S_IRGRP|LIBSSH2_SFTP_S_IXGRP|
                             LIBSSH2_SFTP_S_IROTH|LIBSSH2_SFTP_S_IXOTH);
 
+    if(rc)
+        fprintf(stderr, "libssh2_sftp_mkdir failed: %d\n", rc);
+
     libssh2_sftp_shutdown(sftp_session);
 
  shutdown:
@@ -159,6 +166,9 @@ int main(int argc, char *argv[])
 #else
     close(sock);
 #endif
-printf("all done\n");
+    printf("all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftp_mkdir_nonblock.c

@@ -73,6 +73,12 @@ int main(int argc, char *argv[])
         sftppath = argv[4];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /*
      * The application code is responsible for creating the socket
      * and establishing the connection
@@ -145,13 +151,11 @@ int main(int argc, char *argv[])
 
     fprintf(stderr, "libssh2_sftp_mkdirnb()!\n");
     /* Make a directory via SFTP */
-    while ((rc = libssh2_sftp_mkdir(sftp_session, sftppath,
+    while (libssh2_sftp_mkdir(sftp_session, sftppath,
-                                    LIBSSH2_SFTP_S_IRWXU|
+                              LIBSSH2_SFTP_S_IRWXU|
-                                    LIBSSH2_SFTP_S_IRGRP|LIBSSH2_SFTP_S_IXGRP|
+                              LIBSSH2_SFTP_S_IRGRP|LIBSSH2_SFTP_S_IXGRP|
-                                    LIBSSH2_SFTP_S_IROTH|LIBSSH2_SFTP_S_IXOTH))
+                              LIBSSH2_SFTP_S_IROTH|LIBSSH2_SFTP_S_IXOTH)
-           == LIBSSH2_ERROR_EAGAIN) {
+           == LIBSSH2_ERROR_EAGAIN);
-        ;
-    }
 
     libssh2_sftp_shutdown(sftp_session);
 
@@ -165,6 +169,9 @@ int main(int argc, char *argv[])
 #else
     close(sock);
 #endif
-printf("all done\n");
+    printf("all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftp_nonblock.c

@@ -121,6 +121,13 @@ int main(int argc, char *argv[])
     if (argc > 4) {
         sftppath = argv[4];
     }
+
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /*
      * The application code is responsible for creating the socket
      * and establishing the connection
@@ -258,8 +265,8 @@ int main(int argc, char *argv[])
 shutdown:
 
     printf("libssh2_session_disconnect\n");
-    while ((rc = libssh2_session_disconnect(session,
+    while (libssh2_session_disconnect(session,
-                                            "Normal Shutdown, Thank you")) ==
+                                      "Normal Shutdown, Thank you") ==
            LIBSSH2_ERROR_EAGAIN);
     libssh2_session_free(session);
 
@@ -269,5 +276,8 @@ shutdown:
     close(sock);
 #endif
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftp_write.c

@@ -79,10 +79,16 @@ int main(int argc, char *argv[])
         sftppath = argv[5];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     local = fopen(loclfile, "rb");
     if (!local) {
         printf("Can't local file %s\n", loclfile);
-        goto shutdown;
+        return -1;
     }
 
     /*
@@ -179,17 +185,18 @@ int main(int argc, char *argv[])
         do {
             /* write data in a loop until we block */
             rc = libssh2_sftp_write(sftp_handle, ptr, nread);
+            if(rc < 0)
+                break;
             ptr += rc;
-            nread -= nread;
+            nread -= rc;
-        } while (rc > 0);
+        } while (nread);
-    } while (1);
+
+    } while (rc > 0);
 
-    fclose(local);
     libssh2_sftp_close(sftp_handle);
     libssh2_sftp_shutdown(sftp_session);
 
- shutdown:
+shutdown:
-
     libssh2_session_disconnect(session,
                                "Normal Shutdown, Thank you for playing");
     libssh2_session_free(session);
@@ -199,6 +206,11 @@ int main(int argc, char *argv[])
 #else
     close(sock);
 #endif
-printf("all done\n");
+    if (local)
+        fclose(local);
+    printf("all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftp_write_nonblock.c

@@ -22,6 +22,9 @@
 #ifdef HAVE_NETINET_IN_H
 # include <netinet/in.h>
 #endif
+#ifdef HAVE_SYS_SELECT_H
+# include <sys/select.h>
+#endif
 # ifdef HAVE_UNISTD_H
 #include <unistd.h>
 #endif
@@ -34,6 +37,37 @@
 #include <errno.h>
 #include <stdio.h>
 #include <ctype.h>
+#include <time.h>
+
+static int waitsocket(int socket_fd, LIBSSH2_SESSION *session)
+{
+    struct timeval timeout;
+    int rc;
+    fd_set fd;
+    fd_set *writefd = NULL;
+    fd_set *readfd = NULL;
+    int dir;
+
+    timeout.tv_sec = 10;
+    timeout.tv_usec = 0;
+
+    FD_ZERO(&fd);
+
+    FD_SET(socket_fd, &fd);
+
+    /* now make sure we wait in the correct direction */
+    dir = libssh2_session_block_directions(session);
+
+    if(dir & LIBSSH2_SESSION_BLOCK_INBOUND)
+        readfd = &fd;
+
+    if(dir & LIBSSH2_SESSION_BLOCK_OUTBOUND)
+        writefd = &fd;
+
+    rc = select(socket_fd + 1, readfd, writefd, NULL, &timeout);
+
+    return rc;
+}
 
 int main(int argc, char *argv[])
 {
@@ -53,9 +87,12 @@ int main(int argc, char *argv[])
     FILE *local;
     LIBSSH2_SFTP *sftp_session;
     LIBSSH2_SFTP_HANDLE *sftp_handle;
-    char mem[1024];
+    char mem[1024 * 100];
     size_t nread;
     char *ptr;
+    time_t start;
+    long total = 0;
+    int duration;
 
 #ifdef WIN32
     WSADATA wsadata;
@@ -82,10 +119,16 @@ int main(int argc, char *argv[])
         sftppath = argv[5];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     local = fopen(loclfile, "rb");
     if (!local) {
         printf("Can't local file %s\n", loclfile);
-        goto shutdown;
+        return -1;
     }
 
     /*
@@ -136,17 +179,19 @@ int main(int argc, char *argv[])
 
     if (auth_pw) {
         /* We could authenticate via password */
-        while ((rc = libssh2_userauth_password(session, username, password)) == LIBSSH2_ERROR_EAGAIN);
+        while ((rc = libssh2_userauth_password(session, username, password)) ==
-    if (rc) {
+               LIBSSH2_ERROR_EAGAIN);
+        if (rc) {
             printf("Authentication by password failed.\n");
             goto shutdown;
         }
     } else {
         /* Or by public key */
         while ((rc = libssh2_userauth_publickey_fromfile(session, username,
-                                                "/home/username/.ssh/id_rsa.pub",
+                                                         "/home/username/.ssh/id_rsa.pub",
-                                                "/home/username/.ssh/id_rsa",
+                                                         "/home/username/.ssh/id_rsa",
-                                                password)) == LIBSSH2_ERROR_EAGAIN);
+                                                         password)) ==
+               LIBSSH2_ERROR_EAGAIN);
     if (rc) {
             printf("\tAuthentication by public key failed\n");
             goto shutdown;
@@ -157,7 +202,8 @@ int main(int argc, char *argv[])
     do {
         sftp_session = libssh2_sftp_init(session);
 
-        if ((!sftp_session) && (libssh2_session_last_errno(session) != LIBSSH2_ERROR_EAGAIN)) {
+        if (!sftp_session &&
+            (libssh2_session_last_errno(session) != LIBSSH2_ERROR_EAGAIN)) {
             fprintf(stderr, "Unable to init SFTP session\n");
             goto shutdown;
         }
@@ -172,13 +218,17 @@ int main(int argc, char *argv[])
                           LIBSSH2_SFTP_S_IRUSR|LIBSSH2_SFTP_S_IWUSR|
                           LIBSSH2_SFTP_S_IRGRP|LIBSSH2_SFTP_S_IROTH);
 
-        if ((!sftp_handle) && (libssh2_session_last_errno(session) != LIBSSH2_ERROR_EAGAIN)) {
+        if (!sftp_handle &&
+            (libssh2_session_last_errno(session) != LIBSSH2_ERROR_EAGAIN)) {
             fprintf(stderr, "Unable to open file with SFTP\n");
             goto shutdown;
         }
     } while (!sftp_handle);
 
     fprintf(stderr, "libssh2_sftp_open() is done, now send data!\n");
+
+    start = time(NULL);
+
     do {
         nread = fread(mem, 1, sizeof(mem), local);
         if (nread <= 0) {
@@ -187,15 +237,27 @@ int main(int argc, char *argv[])
         }
         ptr = mem;
 
+        total += nread;
+
         do {
             /* write data in a loop until we block */
-            while ((rc = libssh2_sftp_write(sftp_handle, ptr, nread)) == LIBSSH2_ERROR_EAGAIN) {
+            while ((rc = libssh2_sftp_write(sftp_handle, ptr, nread)) ==
-                ;
+                   LIBSSH2_ERROR_EAGAIN) {
+                waitsocket(sock, session);
             }
+            if(rc < 0)
+                break;
             ptr += rc;
-            nread -= nread;
+            nread -= rc;
-        } while (rc > 0);
+
-    } while (1);
+        } while (nread);
+    } while (rc > 0);
+
+    duration = (int)(time(NULL)-start);
+
+    printf("%ld bytes in %d seconds makes %.1f bytes/sec\n",
+           total, duration, total/(double)duration);
+
 
     fclose(local);
     libssh2_sftp_close(sftp_handle);
@@ -203,7 +265,8 @@ int main(int argc, char *argv[])
 
 shutdown:
 
-        while ((rc = libssh2_session_disconnect(session, "Normal Shutdown, Thank you for playing")) == LIBSSH2_ERROR_EAGAIN);
+    while (libssh2_session_disconnect(session, "Normal Shutdown, Thank you for playing")
+           == LIBSSH2_ERROR_EAGAIN);
     libssh2_session_free(session);
 
 #ifdef WIN32
@@ -212,5 +275,8 @@ shutdown:
     close(sock);
 #endif
     printf("all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftpdir.c

@@ -70,6 +70,13 @@ int main(int argc, char *argv[])
     if(argc > 4) {
         sftppath = argv[4];
     }
+
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /*
      * The application code is responsible for creating the socket
      * and establishing the connection
@@ -114,7 +121,7 @@ int main(int argc, char *argv[])
 
     if (auth_pw) {
         /* We could authenticate via password */
-        if ((i = libssh2_userauth_password(session, username, password))) {
+        if (libssh2_userauth_password(session, username, password)) {
             printf("Authentication by password failed.\n");
             goto shutdown;
         }
@@ -211,6 +218,9 @@ int main(int argc, char *argv[])
 #else
     close(sock);
 #endif
-printf("all done\n");
+    printf("all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/sftpdir_nonblock.c

@@ -73,6 +73,13 @@ int main(int argc, char *argv[])
     if(argc > 4) {
         sftppath = argv[4];
     }
+
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /*
      * The application code is responsible for creating the socket
      * and establishing the connection
@@ -224,5 +231,8 @@ int main(int argc, char *argv[])
     close(sock);
 #endif
     printf("all done\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/ssh2.c

@@ -68,7 +68,7 @@ static void kbd_callback(const char *name, int name_len,
 int main(int argc, char *argv[])
 {
     unsigned long hostaddr;
-    int sock, i, auth_pw = 0;
+    int rc, sock, i, auth_pw = 0;
     struct sockaddr_in sin;
     const char *fingerprint;
     char *userauthlist;
@@ -93,6 +93,12 @@ int main(int argc, char *argv[])
         password = argv[3];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /* Ultra basic "connect to port 22 on localhost".  Your code is
      * responsible for creating the socket establishing the connection
      */
@@ -247,5 +253,8 @@ int main(int argc, char *argv[])
     close(sock);
 #endif
     printf("all done!\n");
+
+    libssh2_exit();
+
     return 0;
 }

example/ssh2_agent.c

@@ -41,11 +41,11 @@ const char *username="username";
 int main(int argc, char *argv[])
 {
     unsigned long hostaddr;
-    int sock = -1, i, j, rc;
+    int sock = -1, i, rc;
     struct sockaddr_in sin;
     const char *fingerprint;
     char *userauthlist;
-    LIBSSH2_SESSION *session;
+    LIBSSH2_SESSION *session = NULL;
     LIBSSH2_CHANNEL *channel;
     LIBSSH2_AGENT *agent = NULL;
     struct libssh2_agent_publickey *identity, *prev_identity = NULL;
@@ -65,6 +65,12 @@ int main(int argc, char *argv[])
         username = argv[2];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     /* Ultra basic "connect to port 22 on localhost".  Your code is
      * responsible for creating the socket establishing the connection
      */
@@ -212,9 +218,11 @@ int main(int argc, char *argv[])
     libssh2_agent_disconnect(agent);
     libssh2_agent_free(agent);
 
-    libssh2_session_disconnect(session,
+    if(session) {
-                               "Normal Shutdown, Thank you for playing");
+        libssh2_session_disconnect(session,
-    libssh2_session_free(session);
+                                   "Normal Shutdown, Thank you for playing");
+        libssh2_session_free(session);
+    }
 
     if (sock != -1) {
 #ifdef WIN32
@@ -225,5 +233,8 @@ int main(int argc, char *argv[])
     }
 
     printf("all done!\n");
+
+    libssh2_exit();
+
     return rc;
 }

example/ssh2_exec.c

@@ -109,6 +109,12 @@ int main(int argc, char *argv[])
         commandline = argv[4];
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     hostaddr = inet_addr(hostname);
 
     /* Ultra basic "connect to port 22 on localhost"
@@ -161,12 +167,21 @@ int main(int argc, char *argv[])
     fingerprint = libssh2_session_hostkey(session, &len, &type);
     if(fingerprint) {
         struct libssh2_knownhost *host;
-        int check = libssh2_knownhost_check(nh, (char *)hostname,
+#if LIBSSH2_VERSION_NUM >= 0x010206
-                                            (char *)fingerprint, len,
+        /* introduced in 1.2.6 */
+        int check = libssh2_knownhost_checkp(nh, hostname, 22,
+                                             fingerprint, len,
+                                             LIBSSH2_KNOWNHOST_TYPE_PLAIN|
+                                             LIBSSH2_KNOWNHOST_KEYENC_RAW,
+                                             &host);
+#else
+        /* 1.2.5 or older */
+        int check = libssh2_knownhost_check(nh, hostname,
+                                            fingerprint, len,
                                             LIBSSH2_KNOWNHOST_TYPE_PLAIN|
                                             LIBSSH2_KNOWNHOST_KEYENC_RAW,
                                             &host);
-
+#endif
         fprintf(stderr, "Host check: %d, key: %s\n", check,
                 (check <= LIBSSH2_KNOWNHOST_CHECK_MISMATCH)?
                 host->key:"<none>");
@@ -289,6 +304,8 @@ shutdown:
     close(sock);
 #endif
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }
-

example/x11.c

@@ -121,11 +121,16 @@ static void x11_callback(LIBSSH2_SESSION *session, LIBSSH2_CHANNEL *channel,
             /* Connect to the local unix domain */
             ptr = strrchr(display, ':');
             temp_buff = (char *) calloc(strlen(ptr+1), sizeof(char));
+            if (!temp_buff) {
+                perror("calloc");
+                return;
+            }
             memcpy(temp_buff, ptr+1, strlen(ptr+1));
             display_port = atoi(temp_buff);
+            free(temp_buff);
 
-            sock = socket(AF_UNIX,SOCK_STREAM, 0);
+            sock = socket(AF_UNIX, SOCK_STREAM, 0);
-            if (sock <0)
+            if (sock < 0)
                 return;
             memset(&addr, 0, sizeof(addr));
             addr.sun_family = AF_UNIX;
@@ -272,6 +277,12 @@ main (int argc, char *argv[])
         fprintf (stderr, "DEBUG is ON: %d\n", set_debug_on);
     }
 
+    rc = libssh2_init (0);
+    if (rc != 0) {
+        fprintf (stderr, "libssh2 initialization failed (%d)\n", rc);
+        return 1;
+    }
+
     sock = socket (AF_INET, SOCK_STREAM, 0);
 
     sin.sin_family = AF_INET;
@@ -429,5 +440,8 @@ main (int argc, char *argv[])
       channel = NULL;
     }
     _normal_mode();
+
+    libssh2_exit();
+
     return 0;
 }

get_ver.awk

@@ -1,7 +1,10 @@
 # fetch libssh2 version number from input file and write them to STDOUT
 BEGIN {
   while ((getline < ARGV[1]) > 0) {
-    if (match ($0, /^#define LIBSSH2_VERSION[ |\t]+"[^"]+"/)) {
+    if (match ($0, /^#define LIBSSH2_COPYRIGHT "[^"]+"$/)) {
+      my_copyright_str = substr($0, 28, length($0)-28);
+    }
+    else if (match ($0, /^#define LIBSSH2_VERSION[ |\t]+"[^"]+"/)) {
       my_ver_str = substr($3, 2, length($3) - 2);
       split(my_ver_str, v, ".");
       if (v[3])
@@ -17,4 +20,5 @@ BEGIN {
   }
   print "LIBSSH2_VERSION = " my_ver "";
   print "LIBSSH2_VERSION_STR = " my_ver_str "";
+  print "LIBSSH2_COPYRIGHT_STR = " my_copyright_str "";
 }

include/libssh2.h

@@ -1,5 +1,6 @@
 /* Copyright (c) 2004-2009, Sara Golemon <sarag@libssh2.org>
  * Copyright (c) 2009 by Daniel Stenberg
+ * Copyright (c) 2010 Simon Josefsson <simon@josefsson.org>
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms,
@@ -39,6 +40,50 @@
 #ifndef LIBSSH2_H
 #define LIBSSH2_H 1
 
+#define LIBSSH2_COPYRIGHT "2004-2010 The libssh2 project and its contributors."
+
+/* We use underscore instead of dash when appending DEV in dev versions just
+   to make the BANNER define (used by src/session.c) be a valid SSH
+   banner. Release versions have no appended strings and may of course not
+   have dashes either. */
+#define LIBSSH2_VERSION                             "1.2.7_DEV"
+
+/* The numeric version number is also available "in parts" by using these
+   defines: */
+#define LIBSSH2_VERSION_MAJOR                       1
+#define LIBSSH2_VERSION_MINOR                       2
+#define LIBSSH2_VERSION_PATCH                       7
+
+/* This is the numeric version of the libssh2 version number, meant for easier
+   parsing and comparions by programs. The LIBSSH2_VERSION_NUM define will
+   always follow this syntax:
+
+         0xXXYYZZ
+
+   Where XX, YY and ZZ are the main version, release and patch numbers in
+   hexadecimal (using 8 bits each). All three numbers are always represented
+   using two digits.  1.2 would appear as "0x010200" while version 9.11.7
+   appears as "0x090b07".
+
+   This 6-digit (24 bits) hexadecimal number does not show pre-release number,
+   and it is always a greater number in a more recent release. It makes
+   comparisons with greater than and less than work.
+*/
+#define LIBSSH2_VERSION_NUM                         0x010207
+
+/*
+ * This is the date and time when the full source package was created. The
+ * timestamp is not stored in the source code repo, as the timestamp is
+ * properly set in the tarballs by the maketgz script.
+ *
+ * The format of the date should follow this template:
+ *
+ * "Mon Feb 12 11:35:33 UTC 2007"
+ */
+#define LIBSSH2_TIMESTAMP "DEV"
+
+#ifndef LIBSSH2_VERSION_ONLY
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -68,62 +113,24 @@ extern "C" {
 
 #if (defined(NETWARE) && !defined(__NOVELL_LIBC__))
 # include <sys/bsdskt.h>
+typedef unsigned char uint8_t;
 typedef unsigned int uint32_t;
 #endif
 
-#if defined(LIBSSH2_WIN32) && defined(_MSC_VER) && (_MSC_VER <= 1400)
+#ifdef _MSC_VER
+typedef unsigned char uint8_t;
+typedef unsigned int uint32_t;
 typedef unsigned __int64 libssh2_uint64_t;
 typedef __int64 libssh2_int64_t;
-typedef unsigned int uint32_t;
+# ifndef _SSIZE_T_DEFINED
-#ifndef _SSIZE_T_DEFINED
 typedef int ssize_t;
-#define _SSIZE_T_DEFINED
+# define _SSIZE_T_DEFINED
 #endif
 #else
 typedef unsigned long long libssh2_uint64_t;
 typedef long long libssh2_int64_t;
 #endif
 
-/* We use underscore instead of dash when appending DEV in dev versions just
-   to make the BANNER define (used by src/session.c) be a valid SSH
-   banner. Release versions have no appended strings and may of course not
-   have dashes either. */
-#define LIBSSH2_VERSION                             "1.2.4_DEV"
-
-/* The numeric version number is also available "in parts" by using these
-   defines: */
-#define LIBSSH2_VERSION_MAJOR                       1
-#define LIBSSH2_VERSION_MINOR                       2
-#define LIBSSH2_VERSION_PATCH                       4
-
-/* This is the numeric version of the libssh2 version number, meant for easier
-   parsing and comparions by programs. The LIBSSH2_VERSION_NUM define will
-   always follow this syntax:
-
-         0xXXYYZZ
-
-   Where XX, YY and ZZ are the main version, release and patch numbers in
-   hexadecimal (using 8 bits each). All three numbers are always represented
-   using two digits.  1.2 would appear as "0x010200" while version 9.11.7
-   appears as "0x090b07".
-
-   This 6-digit (24 bits) hexadecimal number does not show pre-release number,
-   and it is always a greater number in a more recent release. It makes
-   comparisons with greater than and less than work.
-*/
-#define LIBSSH2_VERSION_NUM                         0x010204
-
-/*
- * This is the date and time when the full source package was created. The
- * timestamp is not stored in the source code repo, as the timestamp is
- * properly set in the tarballs by the maketgz script.
- *
- * The format of the date should follow this template:
- *
- * "Mon Feb 12 11:35:33 UTC 2007"
- */
-#define LIBSSH2_TIMESTAMP "DEV"
-
 /* Part of every banner, user specified or not */
 #define LIBSSH2_SSH_BANNER                  "SSH-2.0-libssh2_" LIBSSH2_VERSION
 
@@ -368,6 +375,32 @@ typedef struct _LIBSSH2_POLLFD {
 #define LIBSSH2_ERROR_OUT_OF_BOUNDARY           -41
 #define LIBSSH2_ERROR_AGENT_PROTOCOL            -42
 
+/* Global API */
+#define LIBSSH2_INIT_NO_CRYPTO        0x0001
+
+/*
+ * libssh2_init()
+ *
+ * Initialize the libssh2 functions.  This typically initialize the
+ * crypto library.  It uses a global state, and is not thread safe --
+ * you must make sure this function is not called concurrently.
+ *
+ * Flags can be:
+ * 0:                              Normal initialize
+ * LIBSSH2_INIT_NO_CRYPTO:         Do not initialize the crypto library (ie.
+ *                                 OPENSSL_add_cipher_algoritms() for OpenSSL
+ *
+ * Returns 0 if succeeded, or a negative value for error.
+ */
+LIBSSH2_API int libssh2_init(int flags);
+
+/*
+ * libssh2_exit()
+ *
+ * Exit the libssh2 functions and free's all memory used internal.
+ */
+LIBSSH2_API void libssh2_exit(void);
+
 /* Session API */
 LIBSSH2_API LIBSSH2_SESSION *
 libssh2_session_init_ex(LIBSSH2_ALLOC_FUNC((*my_alloc)),
@@ -683,6 +716,10 @@ LIBSSH2_API LIBSSH2_CHANNEL *libssh2_scp_send_ex(LIBSSH2_SESSION *session,
                                                  const char *path, int mode,
                                                  size_t size, long mtime,
                                                  long atime);
+LIBSSH2_API LIBSSH2_CHANNEL *
+libssh2_scp_send64(LIBSSH2_SESSION *session, const char *path, int mode,
+                   libssh2_int64_t size, time_t mtime, time_t atime);
+
 #define libssh2_scp_send(session, path, mode, size) \
   libssh2_scp_send_ex((session), (path), (mode), (size), 0, 0)
 
@@ -718,7 +755,7 @@ libssh2_knownhost_init(LIBSSH2_SESSION *session);
  *
  * Add a host and its associated key to the collection of known hosts.
  *
- * The 'type' argument specifies on what format the given host is:
+ * The 'type' argument specifies on what format the given host and keys are:
  *
  * plain  - ascii "hostname.domain.tld"
  * sha1   - SHA1(<salt> <host>) base64-encoded!
@@ -731,6 +768,8 @@ libssh2_knownhost_init(LIBSSH2_SESSION *session);
  * a custom type is used, salt is ignored and you must provide the host
  * pre-hashed when checking for it in the libssh2_knownhost_check() function.
  *
+ * The keylen parameter may be omitted (zero) if the key is provided as a
+ * NULL-terminated base64-encoded string.
  */
 
 /* host format (2 bits) */
@@ -758,6 +797,41 @@ libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts,
                       const char *key, size_t keylen, int typemask,
                       struct libssh2_knownhost **store);
 
+/*
+ * libssh2_knownhost_addc
+ *
+ * Add a host and its associated key to the collection of known hosts.
+ *
+ * Takes a comment argument that may be NULL.  A NULL comment indicates
+ * there is no comment and the entry will end directly after the key
+ * when written out to a file.  An empty string "" comment will indicate an
+ * empty comment which will cause a single space to be written after the key.
+ *
+ * The 'type' argument specifies on what format the given host and keys are:
+ *
+ * plain  - ascii "hostname.domain.tld"
+ * sha1   - SHA1(<salt> <host>) base64-encoded!
+ * custom - another hash
+ *
+ * If 'sha1' is selected as type, the salt must be provided to the salt
+ * argument. This too base64 encoded.
+ *
+ * The SHA-1 hash is what OpenSSH can be told to use in known_hosts files.  If
+ * a custom type is used, salt is ignored and you must provide the host
+ * pre-hashed when checking for it in the libssh2_knownhost_check() function.
+ *
+ * The keylen parameter may be omitted (zero) if the key is provided as a
+ * NULL-terminated base64-encoded string.
+ */
+
+LIBSSH2_API int
+libssh2_knownhost_addc(LIBSSH2_KNOWNHOSTS *hosts,
+                       const char *host,
+                       const char *salt,
+                       const char *key, size_t keylen,
+                       const char *comment, size_t commentlen, int typemask,
+                       struct libssh2_knownhost **store);
+
 /*
  * libssh2_knownhost_check
  *
@@ -788,6 +862,15 @@ libssh2_knownhost_check(LIBSSH2_KNOWNHOSTS *hosts,
                         int typemask,
                         struct libssh2_knownhost **knownhost);
 
+/* this function is identital to the above one, but also takes a port
+   argument that allows libssh2 to do a better check */
+LIBSSH2_API int
+libssh2_knownhost_checkp(LIBSSH2_KNOWNHOSTS *hosts,
+                         const char *host, int port,
+                         const char *key, size_t keylen,
+                         int typemask,
+                         struct libssh2_knownhost **knownhost);
+
 /*
  * libssh2_knownhost_del
  *
@@ -939,8 +1022,8 @@ libssh2_agent_list_identities(LIBSSH2_AGENT *agent);
  */
 LIBSSH2_API int
 libssh2_agent_get_identity(LIBSSH2_AGENT *agent,
-			   struct libssh2_agent_publickey **store,
+               struct libssh2_agent_publickey **store,
-			   struct libssh2_agent_publickey *prev);
+               struct libssh2_agent_publickey *prev);
 
 /*
  * libssh2_agent_userauth()
@@ -951,8 +1034,8 @@ libssh2_agent_get_identity(LIBSSH2_AGENT *agent,
  */
 LIBSSH2_API int
 libssh2_agent_userauth(LIBSSH2_AGENT *agent,
-		       const char *username,
+               const char *username,
-		       struct libssh2_agent_publickey *identity);
+               struct libssh2_agent_publickey *identity);
 
 /*
  * libssh2_agent_disconnect()
@@ -973,6 +1056,35 @@ libssh2_agent_disconnect(LIBSSH2_AGENT *agent);
 LIBSSH2_API void
 libssh2_agent_free(LIBSSH2_AGENT *agent);
 
+
+/*
+ * 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);
+
 /* NOTE NOTE NOTE
    libssh2_trace() has no function in builds that aren't built with debug
    enabled
@@ -1000,4 +1112,6 @@ LIBSSH2_API int libssh2_trace_sethandler(LIBSSH2_SESSION *session,
 } /* extern "C" */
 #endif
 
+#endif /* LIBSSH2_VERSION_ONLY */
+
 #endif /* LIBSSH2_H */