RELEASE-NOTES: synced with fabf1a45ee

Starting now, the NEWS file is generated from git using the git2news.pl
script. This makes it always accurate and up-to-date, even for daily
snapshots etc.

.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,19 @@ 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
+win32/msvcproj.head win32/msvcproj.foot win32/libssh2.rc \
+win32/Makefile.Watcom
 
 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 sftp.h crypto.h

NEWS

@@ -1,686 +1,3 @@
-Version 1.2.3 (February 3, 2010)
+The old NEWS file.
 
- o Added libssh2_trace_sethandler()
- o Added the direct_tcpip.c example
- o Fixed memory leak in userauth_publickey
- o Added support for authentication via SSH-Agent.  By Daiki Ueno.
-
- o Respond to unknown SSH_MSG_GLOBAL_REQUEST/SSH_MSG_CHANNEL_REQUEST
-   with SSH_MSG_REQUEST_FAILURE/SSH_MSG_CHANNEL_FAILURE in order to
-   make (at least) OpenSSH server keepalive work.  Before OpenSSH
-   servers (configured with a positive ClientAliveInterval) would
-   terminate connections against libssh2 clients because libssh2 did
-   not respond properly to the request.  By Simon Josefsson.
-
-Version 1.2.2 (November 16, 2009)
-
-* This release includes the following changes:
-
-  o Fix crash when server sends an invalid SSH_MSG_IGNORE message.
-    Reported by Bob Alexander <balexander@expressor-software.com> in
-    <http://thread.gmane.org/gmane.network.ssh.libssh2.devel/2530>.
-    By Simon Josefsson.
-
-  o Support for the "aes128-ctr", "aes192-ctr", "aes256-ctr" ciphers
-    as per RFC 4344 for libgcrypt and OpenSSL.  They are now the
-    preferred ciphers.  By Simon Josefsson.
-
-  o Support for the "arcfour128" cipher as per RFC 4345 for libgcrypt
-    and OpenSSL.  It is preferred over the normal "arcfour" cipher
-    which is somewhat broken.  By Simon Josefsson.
-
-  o Add support for GCC visibility features.  By Cristian Rodr<64>guez.
-
-  o Fix libssh2_channel_forward_accept.  By Juzna.
-
-  o Generate Win32 files correctly.   By Peter Stuge.
-
-  o Fix permission issue in ssh2 self test.  By Dan Fandrich.
-
-  o Use memmove instead of memcpy in one place which copies
-    overlapping memory areas.
-
-  o Cleanup hard coding of cipher modes in libgcrypt backend.  By Simon.
-
-  o Added man page for libssh2_knownhost_free.  By Daniel.
-
-Version 1.2.1 (September 28, 2009)
-
-* This release includes the following changes:
-
-  o generate and install libssh2.pc
-
-  ... and the following bugfixes:
-
-  o proper return codes returned from several functions
-  o return EAGAIN internal cleanup
-  o added knownhost.c to windows makefiles
-  o pass private-key to OpenSSL as a filename with BIO_new_file().
-  o make libssh2_scp_send/recv do blocking mode correctly
-  o libssh2_channel_wait_closed() could hang
-  o libssh2_channel_read_ex() must return 0 when closed
-  o added gettimeofday() function for win32 for the debug trace outputs
-  o transport layer bug causing invalid -39 (LIBSSH2_ERROR_BAD_USE) errors
-  o scp examples now loop correctly over libssh2_channel_write()
-
-* (August 29 2009) Daniel Stenberg:
-
- - I fixed all code to use the recently added dedicated linked list functions
-   instead of doing the same stuff spread out all over.
-
- - I also fixed a few cases where local variables where used to keep memory
-   but was used to keep state for re-invokes due to non-blocking situations
-   which would lead to segfaults.
-
-Version 1.2 (August 10, 2009)
------------------------------
-
-* (August 02 2009) Alexander Lamaison:
-
- - changed _libssh2_rsa_new_private and _libssh2_rsa_new_private so that they
-   no longer use the OpenSSL functions that take a FILE* argument.  Passing
-   CRT-created objects across a DLL boundary causes crashes on Windows of the
-   DLL and the client aren't linked to the exact same verison of the CRT. Now
-   we pass the keys as strings to avoid this issue.
-
-* (May 29 2009) Daniel Stenberg:
-
- - Updated the knownhost API and there are now 9 functions, and all of them
-   have man pages. The libssh2.h now defines HAVE_LIBSSH2_KNOWNHOST_API to
-   ease things for applications to check for the correct release before trying
-   to use it.
-
-* (May 23 2009) Daniel Stenberg:
-
- - Anonymous bug report #2795816 revealed that doing subsequent
-   libssh2_sftp_init() calls on the same session failed.
-
-* (May 20 2009) Daniel Stenberg:
-
-  - made libssh2_sftp_write() properly deal with huge/any sized input buffers.
-
-  - fixed libssh2_channel_write_ex() to return the correct return code, and
-    deal with sending off huge buffers better
-
-* (May 7 2009) Daniel Stenberg:
-
-  - linked list code. I got a bit tired of the fact that we don't have any
-    generic linked-list functions within libssh2 so I wrote up the first embryo
-    for one that I use for this new functionality. The plan would then be to
-    move all existing code that uses linked lists to use this new set.
-
-  - base64 encode. I had to add a base64 encoding function which was missing
-    in the code base so it helps to "bloat" my patch.
-
-  - The knownhost API is currently:
-
-    _init() - init a bundle of known hosts
-    _add()  - add a known host
-    _del()  - delete a known host
-    _free() - free an entire bundle of known hosts
-    _check() - check if a host+key is present in the bundle
-
-    The convenience function:
-
-    _parsefile() - reads a ~/.ssh/known_hosts file and add all entries to the
-                   given bundle
-
-   - there's no docs other than some comments in the code/headers yet
-
-  - the patch includes changes to example/simple/ssh2_exec.c that makes use of
-    a few of these functions. Using that I've verified that the functions in
-    fact can verify my localhost's key agains my ~/.ssh/known_hosts file
-
-* (Apr 30 2009) Daniel Stenberg:
-
-  Markus posted a bug report about a bad 0-return from libssh2_channel_read:
-  http://libssh2.haxx.se/mail/libssh2-devel-archive-2009-04/0076.shtml
-
-  And it was indeed a bad loop that terminated too early due to a receveived
-  close packet.
-
-* (Apr 14 2009) Daniel Stenberg:
-
-  libssh2_poll() and libssh2_poll_channel_read() are now considered and
-  documented deprecated and they will be removed at next soname bump. It also
-  saves us from fixing some rather quirky bugs in libssh2_poll()...
-
-
-Version 1.1 (April 2, 2009)
----------------------------
-
-- (Mar 28 2009) Daniel Stenberg:
-
-  Jean-Louis Charton found a memory leak in
-  libssh2_userauth_hostbased_fromfile_ex()
-
-- (Mar 25 2009) Daniel Stenberg:
-
-   * Renamed the functions in src/transport.c to be _libssh2_transport_ prefixed
-     and introduced a transport.h header.
-
-   * Fixed the blocking mode to only change behavior not the actual underlying
-     socket mode so we now always work with non-blocking sockets. This also
-     introduces a new rule of thumb in libssh2 code: we don't call the
-     external function calls internally. We use the internal (non-blocking)
-     ones!
-
-   * libssh2_channel_receive_window_adjust2 was added and
-     libssh2_channel_receive_window_adjust is now deprecated
-
-   * Introduced "local" header files with prototypes etc for different parts
-     instead of cramming everything into libssh2_priv.h. channel.h is the
-     first.
-
-- (Mar 19 2009) Daniel Stenberg: based on a patch by "E L" we now use errno
-  properly after recv() and send() calls (that internally are now known as
-  _libssh2_recv() and _libssh2_send()) so that the API and more works fine on
-  windows too!
-
-- (Mar 17 2009) Simon Josefsson:
-
-  Added a Libtool -export-symbols-regex flag to reduce the number of
-  exported symbols in shared libraries.  Reported by Mikhail Gusarov.
-
-- (Mar 16 2009) Daniel Stenberg:
-
-  I renamed a few man pages to match the exact name of the functions they
-  describe. I also added template versions for the 13 functions that
-  previously lacked man pages. While these don't contain any docs just yet, it
-  will now be easier to add the info as the foundation is there!
-
-- (Mar 15 2009) Daniel Stenberg:
-
-  * libssh2_channel_read_ex() was simplified and enhanced. It now adjusts the
-    window less frequent and uses much larger window that now allows MUCH
-    faster transfers.
-
-  * SCP send/recv now allow file names with whitespaces etc, thanks to a patch
-    by Heiner Steven
-
-- (Mar 13 2009) Daniel Stenberg: Cleanups, that do seem to have boosted SFTP
-  download performance up to 300% in some tests:
-
-  * cut off "_ex" from several internal function names
-
-  * corrected some log outputs
-
-  * simplified libssh2_channel_read_ex() and made it much faster in the process
-
-  * cut out {{{ and }}} comments that were incorrect anyway
-
-  * fixed sftp_packet_ask() to return the correct packet by using memcmp() and
-    not strncmp()
-
-  * fixed mkdir()'s wait for packet to use the correct request_id - it
-    semi-worked previously because strncmp() in sftp_packet_ask() made it
-    match far too easily.
-
-  * took away the polling functionality from sftp_packet_ask() since it wasn't
-    used
-
-- (Mar 7 2009) Olivier Hervieu pointed out a flaw in the
-  libssh2_channel_x11_req_ex() function that made it produce a crappy random
-  chunk of data. Peter Stuge improved the fix to not do out-of-boundary
-  writes. I (Daniel Stenberg) replaced the snprintf() with a plain sprintf()
-  since the size argument wasn't adding anything anyway.
-
-- (Feb 23 2009) Added libssh2_version()
-
-- (Feb 20 2009) libssh2_channel_direct_tcpip_ex() bug #1902169 fixed, which
-  caused it to fail when called a second time.
-
-- (Feb 12 2009) Romain Bondue extended Markus Moeller fix from Feb 8, based on
-  a previous (uncommitted) patch by Erik Brossler. It improves
-  libssh2_channel_write_ex in blocking situations when the socket is set non-
-  blocking.
-
-- (Feb 8 2009) Markus Moeller fixed a flaw in libssh2_channel_write_ex() that
-  would occur on EAGAIN situations.
-
-Version 1.0 (December 26 2008)
-------------------------------
-
-- (Dec 20 2008) Based on Alexander Lamaison's patch, there's now a new
-  function called libssh2_sftp_tell64() that returns the 64 bit file offset,
-  as the existing libssh2_sftp_tell() only returns a size_t.
-
-- (Dec 18 2008) Markus Moeller fixed the issue also reported by Alexander
-  Lamaison which caused SFTP reads with large buffers to fail.
-
-- Several flaws were fixed that prevented at least SFTP to work reliably
-
-- Vlad Grachov brought the new function called
-  libssh2_session_block_directions() which returns a bitmask for what
-  directions the connection blocks. It is to be used applications that use
-  non-blocking sockets and when a libssh2 function returns
-  LIBSSH2_ERROR_EAGAIN this function can be used to figure out in which
-  direction the socket would block and thus it can wait for the socket to
-  again be ready for communication in that direction before it calls libssh2
-  again.
-
-- Vincent Jaulin brought the new libssh2_channel_request_pty_size_ex()
-  function.
-
-- Carlo Bramini fixed the build for msys+mingw. Bug #1943976.
-
-- Neil Gierman provided improved Visual Studio 2008 code in bug #1946268
-
-- Bug #1862727 fixed libssh2_poll() to work on windows (by defining
-  HAVE_SELECT).
-
-- Based on bug #1815692, we introduce libssh2_sftp_seek64() that allows
-  seeking beyond the 2GB margin even on 32bit machines.
-
-- Based on a patch in bug #1878059 by Steven Ayre libssh2 now parses >2GB file
-  sizes when downloading SCP files.
-
-- Bug #2064371 pointed out that the SSH2 banner may not use dash
-  ('-'). Reported by Bjorn Stenborg.
-
-- Sean Peterson fixed a key re-exchange bug:
-  http://daniel.haxx.se/projects/libssh2/mail/libssh2-devel-archive-2008-06/0002.shtml
-
-- Mike Protts filed the bug report #1908724 that identified and fixed a problem
-  with SFTP stat on files >4GB in size. Previously it used 32bit math only.
-
-- Removed a stderr debug message that was accidentally left in (bug #1863153)
-
-- OpenSSL and libz detection changed to make cross-compiling to Mingw
-  work.  See README for parameters to use if the auto-detection does
-  not work for you.  From Simon Josefsson.
-
-- Simon Josefsson added a self-test that uses libssh2 to connect to a
-  local sshd (only enabled if if OpenSSH is installed).
-
-Version 0.18 (November 11 2007)
--------------------------------
-
-- Various changes that improve non-blocking operations and prevent stalls.
-  Especially noticable on Windows since libssh2 just didn't work properly
-  non-blocking on Windows before.
-
-- Peter O'Gorman reported how a SCP transfer would hang for him, and it was
-  fairly easy reproducable. One bug was in the transport layer, ignoring to
-  read more data while there was data left even though it couldn't decrypt the
-  data that was left due to it being too little... The other bug was in the
-  channel layer, where the libssh2_channel_receive_window_adjust() function
-  missed to set the state variables at times and thus this function would
-  misbehave on repeated invokes.
-
-- Changed the signature of libssh2_channel_setenv_ex to add const to the
-  "varname" parameter (Dan Fandrich)
-
-- Satish Mittal and David J Sullivan fixed an infinit recv() loop in
-  libssh2_banner_receive()
-
-Version 0.17 (August 6 2007)
-----------------------------
-Changes since previous version include:
-
-   o Re-indented the source code with this GNU indent setup:
-
-      --braces-on-if-line
-      --braces-after-struct-decl-line
-      --space-after-cast
-      --line-length 79
-      --comment-line-length 79
-      --cuddle-else
-      --no-tabs
-      --tab-size 8
-      --indent-level 4
-      --no-space-after-for
-      --space-after-if
-      --space-after-while
-      --no-space-after-function-call-names
-
-Version 0.16 (August 6 2007)
-----------------------------
-Changes since previous version include:
-
-   o CRLF stripping fix for PEM reading
-   o libssh2_scp_recv() error message fix
-   o added HACKING as an initial attempt to describe our source code format
-   o new public defines in include/libssh2.h to allow applictions to figure out
-     version number etc
-   o new script (maketgz) to build releases with
-   o updated files for building with MSVC and mingw
-   o keyboard-interactive would always fail due to claimed memory problem
-   o a few minor memory leaks fixed
-   o libssh2_poll() no longer relies on C99 features
-   o AIX 4 and 5 now supports non-blocking sockets
-   o large file magic checks in configure
-   o LIBSSH2_APINO was removed from the public header file
-
-This release would not have been possible without these friendly contributors:
-
-   James Housley, Simon Josefsson, Dan Fandrich, Guenter Knauf and I too did
-   some poking. (Sorry if I forgot anyone I should've mentioned here.)
-
-Of course we would have nothing without the great work by Sara Golemon that
-we're extending and building upon.
-
-Version 0.15 (June 15 2007)
----------------------------
-  Added libssh2_sftp_readdir_ex() and updated LIBSSH2_APINO to
-  200706151200 (James Housley)
-
-  Converted all of the libssh2 code to be able to work in non-blocking
-  mode.  This included some public API changes, listed below (James Housley)
-    Changed function return values:
-     int libssh2_session_free()
-     int libssh2_publickey_shutdown()
-     ssize_t libssh2_channel_read_ex()
-     ssize_t libssh2_channel_write_ex()
-
-    Added functions:
-     libssh2_session_last_errno(), libssh2_channel_handle_extended_data2(),
-     libssh2_channel_wait_closed(), libssh2_channel_wait_eof(),
-     libssh2_session_set_blocking()
-
-    Removed functions:
-     libssh2_channel_readnb_ex(), libssh2_channel_writenb_ex(),
-     libssh2_sftp_readnb(), libssh2_sftp_writenb(),
-     libssh2_sftp_mkdirnb_ex()
-
-  Added the following functions for non-blocking operations: (Daniel Stenberg)
-   libssh2_channel_readnb_ex()
-   libssh2_channel_writenb_ex()
-   libssh2_sftp_readnb()
-   libssh2_sftp_writenb()
-
-  Size parameter changed from 'int' to 'unsigned int' in several
-  public APIs.
-
-  Added (a few) man pages in docs/. (Daniel Stenberg)
-
-  Maximum SSH packet size is now some 35000 bytes.
-
-  Private include files are now in src/ and only public headers are in
-  include/.  (Daniel Stenberg)
-
-  Automake and libtool are being used (increased portability). (Daniel
-  Stenberg)
-
-  Fixed OpenSSL detection using pkg-config. (Daniel Stenberg)
-
-  Simple self test added to tests/. (Simon Josefsson)
-
-  Libgcrypt can now be used instead of OpenSSL if you specify
-  --with-libgcrypt.  (Simon Josefsson)
-
-  Fixed a memory leak in the packet handling, and better handle out of
-  memory situations. (Dan Fandrich)
-
-  Made libssh2 build with OpenSSL 0.9.6. (Dan Fandrich)
-
-  Improved portability to Solaris related to -lsocket and
-  -lnsl. (Simon Josefsson)
-
-  Clean up of README, INSTALL, NEWS, added ChangeLog. (Simon
-  Josefsson)
-
-  Improve debugging code.  Avoids many #ifdef's.
-
-  Improved session closing to avoid potentially truncated files on
-  OpenSSH servers (Dan Fandrich)
-
-  Made some function parameters in the API const (Dan Fandrich)
-
-Version 0.14
-------------
-
-  Plug leaks in EVP cipher init/shutdown. (Selcuk Gueney)
-
-  Allow socket_fd == 0 in libssh2_session_startup(). (puudeli)
-
-  Swap ordering of packet_add/packet-inspection to avoid inspect after
-  free. (Selcuk)
-
-  Swap KEX_INIT ordering, send our KEX_INIT first.
-
-  Add check for oportunistic KEX_INIT packets.  Burn bad guess if necessary.
-
-  Fix OpenSSL detection using pkg-config. (Dan Casey)
-
-Version 0.13
-------------
-
-  Fixed channel not being marked closed when CHANNEL_CLOSE package cannot be
-  sent. (David Robins)
-
-  Fixed payload packet allocation bug when invalid packet length
-  received. (David Robins)
-
-  Fixed `make install' target for MacOSX.
-
-  Add terminating NULL character to readlink()/realpath() results.
-
-  BugFix#1436593: Apply build options for HPUX targets.
-
-Version 0.12
-------------
-
-  Added support for publickey subsytem (not the same as publickey auth).
-
-  Fix x11_req.  Multiple packet_len issues and error handling logic.
-    (Thanks Simon Hart)
-
-  Fix generation of 'e' portion of Diffie-Hellman keyset.
-
-  Use appropriate order for BN_rand() rather than fixed group1-specific value.
-
-  Re-fixed libssh2_sftp_rename_ex()
-
-  Transport had right packet_len, but sftp layer still had extra 4 bytes.
-
-  Fixed build with newer OpenSSL headers.
-
-  Added extern "C" declarations to libssh2_sftp.h for C++ compatability.
-
-Version 0.11
-------------
-
-  Added libssh2_chnnale_get_exit_status() -- Mikhail
-
-  Added libssh2_channel_wait_closed() -- Mikhail
-
-  Added libssh2_userauth_keyboard_interactive_ex() -- Mikhail
-
-  Added libssh2_channel_receive_window_adjust() to be able to increase the
-  size of the receive window.
-
-  Added queueing for small window_adjust packets to avoid unnecessary packet
-  conversation.
-
-  Fixed libssh2_sftp_rename_ex() to only send flags parameter if version >= 5
-  negotiated (not currently possible, but will be and might as well keep the
-  API consistent).
-
-Version 0.10
-------------
-
-  Added developer debugging hooks.  See --enable-debug-* options to ./configure
-
-  Ignore extended data in the SFTP layer.  With no other mechanism to deal
-  with that data it'd just fill up and get stuck.
-
-  (Re)Fixed channel_write() to provide an opportunity for window space to
-  become available again.
-
-  (Re)Fixed SFTP INIT to send the correct SFTP packet length.
-
-  Fixed segfault when client and host can't agree on a hostkey/crypt/mac/comp
-  method. (Thanks puudeli)
-
-  Fixed major issue with sftp packet buffering mechanism.  Using wrong
-  blocking semantics. (No puudeli, YOU the man)
-
-  Reduced busy-looping of libssh2_sftp_packet_requirev.
-
-Version 0.9
------------
-
-  Changed blocking_read to only block as much as necessary and not an
-  arbitrary length of time. (Thanks Felix)
-
-  Fixed SFTP INIT/VERSION to exclude request_id and send correct maximum
-  version number.
-
-  Fixed SFTP to be properly BC with version 1 and 2 servers.
-
-  Fixed libssh2_poll() to recognized closed sessions/channels.
-
-  Fixed libssh2_channel_write_ex() to fully block when set to blocking mode.
-  Return actual bytes written as well.  (Thanks deadem)
-
-  Added tests for -lm and -lsocket and add them when necessary.
-
-  Added libssh2_channel_window_read_ex() and libssh2_channel_window_write_ex()
-  for examining the ssh transport windowing states.
-
-Version 0.8
------------
-
-  Fix potential segfault in compression/decompression.
-
-  Fix compatability with older versions of OpenSSL
-
-  Swapped order of none,zlib compression modes to prefer no compression by
-  default.
-
-  Added sys/uio.h for platforms (FBSD) which need it in order to define struct
-  iovec.
-
-  Added libssh2_poll() to check status of sockets/channels/listeners.
-
-  Removed unnecessary inclusion of stdio.h (holdover from debugging)
-
-Version 0.7
------------
-
-  Added libssh2_userauth_hostbased_fromfile_ex() for authenticating from hostkey.
-
-  Added configure recognition for MacOSX (Darwin) (Thanks Gabe)
-
-  Fixed extended data identification in libssh2_channel_read().
-
-  Fixed window adjust code.  Hadn't acknowledged adjustments correctly.
-
-  Removed initial_window_size requirement for sending window adjust packet.
-
-
-Version 0.6
------------
-
-  Added LIBSSH2_FLAG_SIGPIPE to enable/disable SIGPIPE generated by
-  send()/recv() calls. Default off.
-
-  Added libssh2_session_flag() to set optional session flags.
-
-  Collapsed exchanging_keys/newkeys/authenticated flags into single state
-  attribute.
-
-  Fix zlib compression issue when internal buffer state misses partial sync.
-
-  Fix segfault when libssh2_session_methods() is called prior to
-  session_startup().
-
-  Fixed client to server channel windowing.  Pervent send queue overruns.
-
-  Swapped banner send/receive order (send first, then wait for response).
-
-Version 0.5
------------
-
-  *** BC Break ***
-  Reimplemented libssh2_session_methods() to match
-  libssh2_session_method_pref() style
-
-  Fixed libssh2_attr2bin() (effects any setstat style call).
-
-  Fixed authenticating with encrypted private key.
-
-  Fixed authenticating via ssh-dss public key.
-
-  Fixed KEX_INIT cookie and packet padding to use actual random data
-
-  Added DESTDIR support to makefiles (Adam Go<47><6F>biowski -- I hope that
-  character set translates right)
-
-  Added libssh2_channel_forward_listen_ex(), libssh2_channel_forward_cancel(),
-  and libssh2_channel_forward_accept().
-
-  Added ./configure option '--disable-gex-new' to allow using the older
-  group-exchange format
-
-  Added MAC methods hmac-md5 and hmac-md5-96.
-
-Version 0.4
------------
-
-  Fixed crash when trying to free sftp_dirhandle data from a filehandle struct.
-
-  Fixed leak in sftp_open_ex(), handle->handle not freed in handle_close().
-
-  Fixed leak in sftp_symlink_ex(), result for READLINK and REALPATH not freed unless there was an error.
-
-  Added libssh2_banner_set(), specify an arbitrary banner to send on introduction.
-
-Version 0.3
------------
-
-  Fixed libssh2_channel_read_ex().  Packet loop initialized BEFORE transport polled for new packets (should have been after).
-
-  Fixed blocking issues in scp_send()/scp_recv().
-
-  Fixed degree of indirection in macerror callback.
-
-  Changed packet read mechanism to use a fixed buffer and avoid unnecessary alloc/free calls. (especially while non-block looping)
-
-  Added channel close callback.
-
-  Added SFTP support (Using its own header file: libssh2_sftp.h)
-
-Version 0.2
------------
-
-  Changed extended data ignorance mechanism:
-    libssh2_channel_ignore_extended_data() changed to libssh2_channel_handle_extended_data()
-    Macro introduced for backward compatability during beta phase.
-    *** THE LIBSSH2_CHANNEL_IGNORE_EXTENDED_DATA() MACRO WILL BE REMOVED PRIOR TO 1.0 RELEASE ***
-    libssh2_channel_handle_extended_data() may be passed one of three "ignore_mode" constants
-      LIBSSH2_CHANNEL_EXTENDED_DATA_NONE       Default behavior, queue ED packets and return them with read_ex
-      LIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE     Equivalent to libssh2_channel_ignore_extended_data()
-                                               IGNORE will implicitly flush the extended data stream(s)
-      LIBSSH2_CHANNEL_EXTENDED_DATA_MERGE      Calls to channel_read() will check both the standard data stream
-                                               and the extended data stream(s) for the first available packet
-
-  Changed libssh2_session_disconnect_ex() to return an error code when alloc fails
-
-  Added libssh2_channel_flush_ex() and basic macros: ..._flush() ..._flush_stderr()
-    flush_ex accepts either the streamid (0 for standard data, 1 for stderr) or one of the two following constants:
-      LIBSSH2_CHANNEL_FLUSH_ALL                Flush all streams
-      LIBSSH2_CHANNEL_FLUSH_EXTENDED_DATA      Flush all streams EXCEPT the standard data stream
-
-  Added libssh2_session_callback_set() for setting ignore/debug/disconnect/macerror callbacks
-
-  Added libssh2_session_method_pref() to selectively set methods and method preferences.
-
-  Added libssh2_session_methods() to determine what methods were negotiated.
-
-  Added libssh2_session_abstract() for retreiving &session->abstract
-
-  Added libssh2_session_last_error() for retreiving error codes/messages
-
-Version 0.1
------------
-
-  Initial Release:
-    KEX methods: diffie-hellman-group14-sha1, diffie-hellman-group-exchange-sha1, diffie-hellman-group1-sha1
-    Hostkey methods: ssh-rsa, ssh-dss
-    Cipher methods: aes256-cbc, rijndael-cbc@lysator.liu.se, aes192-cbc, aes128-cbc, blowfish-cbc, arcfour, cast128-cbc, 3des-cbc, none*
-    Compression methods: zlib, none
-    MAC methods: hmac-sha1, hmac-sha1-96, hmac-ripemd160, hmac-ripemd160@openssh.com none*
-    *Cipher/MAC "none" is disabled by default for security purposes,
-     Use --enable-crypt-none and/or --enable-mac-none with ./configure to enable
+NEWS is now generated from git and put into the release tarballs.

RELEASE-NOTES

@@ -1,27 +1,44 @@
-libssh2 1.2.3
+libssh2 1.2.8
 
 This release includes the following changes:
 
- o ssh-agent support with the new libssh2_agent_* functions
- o Added libssh2_trace_sethandler()
- o Added the direct_tcpip.c and ssh2_agent.c examples
+ o added libssh2_free, libssh2_channel_get_exit_signal and
+   libssh2_session_handshake
+ o SFTP read/write remade and now MUCH faster, especially on high latency
+   connections
+ o added new examples: ssh2_echo.c, sftp_append.c and sftp_write_sliding.c
+ o userauth: derive publickey from private
+ o NEWS: now generated from git
 
 This release includes the following bugfixes:
 
- o Fixed memory leak in userauth_publickey
- o Fixed publickey authentication regression
- o Silenced several compiler warnings
- o avoid returning data to memory already freed
- o transport layer fix for bogus -39 (LIBSSH2_ERROR_BAD_USE) errors
- o Fixed padding in ssh-dss signature blob encoding
- o Fixed direction blocking flag problems
- o Fixed memory leak in sftp_fstat()
+ o Support unlimited number of host names in a single line of the
+   known_hosts file.
+ o fix memory leak in userauth_keyboard_interactive()
+ o fix memory leaks (two times cipher_data) for each sftp session
+ o session_startup: manage server data before server identification
+ o SCP: allow file names with bytes > 126
+ o scp_recv: improved treatment of channel_read() returning zero
+ o libssh2_userauth_authenticated: make it work as documented
+ o variable size cleanup: match internal variable sizes better with the sizes
+   of the fields used on the wire
+ o channel_request_pty_size: fix reqPTY_state
+ o sftp_symlink: return error if receive buffer too small
+ o sftp_readdir: return error if buffer is too small
+ o libssh2_knownhost_readfile.3: clarify return value
+ o configure: stop using the deprecated AM_INIT_AUTOMAKE syntax
+ o Fixed Win32 makefile which was now broken at resource build
+ o kex_agree_hostkey: fix NULL pointer derefence
+ o _libssh2_ntohu64: fix conversion from network bytes to uint64
+ o ssize_t: proper typedef with MSVC compilers
+ o zlib: Add debug tracing of zlib errors
+ o decomp: increase decompression buffer sizes
 
 This release would not have looked like this without help, code, reports and
 advice from friends like these:
 
- Simon Josefsson, Peter Stuge, Daiki Ueno, Dave McCaldon,
- Alexander Lamaison
+ Alexander Lamaison, Alfred Gebert, Guenter Knauf, Dan Fandrich,
+ Daniel Stenberg, Jasmeet Bagga, Joey Degges, Mark Smith, Peter Stuge,
+ Pierre Joye, Simon Josefsson, TJ Saunders, Tommy Lindgren
  
-
         Thanks! (and sorry if I forgot to mention someone)

TODO

@@ -1,18 +1,24 @@
 Things TODO
 ===========
 
+* Fix the numerous malloc+copy operations for sending data, see "Buffering
+  Improvements" below for details
+
 * 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
-
-* Provide a libssh2_scp_send() API for files larger than 4GB (32bit size)
+* 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
+  with 'want_buf' set to non-zero.
 
 * Add more info to the man pages.
 
-* Decrease the number of mallocs. Everywhere.
+* Decrease the number of mallocs. Everywhere. Will get easier once the
+  buffering improvements have been done.
 
-* Use SO_NOSIGPIPE for Mac OS/BSD systems where MSG_NOSIGNAL doesn't exist/work
+* Use SO_NOSIGPIPE for Mac OS/BSD systems where MSG_NOSIGNAL doesn't
+  exist/work
 
 * Extend the test suite to actually test lots of aspects of libssh2
 
@@ -20,6 +26,13 @@ Things TODO
 
 * Expose error messages sent by the server
 
+* Make SFTP transfers ask for and send several packages at once so that it
+  doesn't have to send-waitforack-send-waitforack as much. This will be
+  easier/smoother if we implement the "New SFTP API" described below.
+
+* select() is troublesome with libssh2 when using multiple channels over
+  the same session. See "New Transport API" below for more details.
+
 At next SONAME bump
 ===================
 
@@ -37,8 +50,134 @@ At next SONAME bump
   libssh2_channel_receive_window_adjust()
   libssh2_poll()
   libssh2_poll_channel_read()
+  libssh2_session_startup() (libssh2_session_handshake() is the replacement)
 
 * Rename a few function:
 
   libssh2_hostkey_hash => libssh2_session_hostkey_hash
-  libssh2_banner_set => libssh2_session_banner_set
+  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
+
+Buffering Improvements
+======================
+
+transport_write
+
+  - If this function gets called with a total packet size that is larger than
+  32K, it should create more than one SSH packet so that it keeps the largest
+  one below 32K
+
+sftp_write
+
+  - should not copy/allocate anything for the data, only create a header chunk
+  and pass on the payload data to channel_write "pointed to"
+
+New Transport API
+=================
+
+THE PROBLEM
+
+The problem in a nutshell is that when an application opens up multiple
+channels over a single session, those are all using the same socket. If the
+application is then using select() to wait for traffic (like any sensible app
+does) and wants to act on the data when select() tells there is something to
+for example read, what does an application do?
+
+With our current API, you have to loop over all the channels and read from
+them to see if they have data. This effectively makes blocking reads
+impossible. If the app has many channels in a setup like this, it even becomes
+slow. (The original API had the libssh2_poll_channel_read() and libssh2_poll()
+to somewhat overcome this hurdle, but they too have pretty much the same
+problems plus a few others.)
+
+Traffic in the other direction is similarly limited: the app has to try
+sending to all channels, even though some of them may very well not accept any
+data at that point.
+
+A SOLUTION
+
+I suggest we introduce two new helper functions:
+
+ libssh2_transport_read()
+
+ - Read "a bunch" of data from the given socket and returns information to the
+   app about what channels that are now readable (ie they will not block when
+   read from). The function can be called over and over and it will repeatedly
+   return info about what channels that are readable at that moment.
+
+ libssh2_transport_write()
+
+ - Returns information about what channels that are writable, in the sense
+   that they have windows set from the remote side that allows data to get
+   sent. Writing to one of those channels will not block. Of course, the
+   underlying socket may only accept a certain amount of data, so at the first
+   short return, nothing more should be attempted to get sent until select()
+   (or equivalent) has been used on the master socket again.
+
+I haven't yet figured out a sensible API for how these functions should return
+that info, but if we agree on the general principles I guess we can work that
+out.
+
+VOLUNTARY
+
+  I wanted to mention that these two helper functions would not be mandatory
+  in any way. They would just be there for those who want them, and existing
+  programs can remain using the old functions only if they prefer to.
+
+New SFTP API
+============
+
+PURPOSE
+
+ Provide API functions that explicitly tells at once that a (full) SFTP file
+ transfer is wanted, to allow libssh2 to leverage on that knowledge to speed
+ up things internally. It can for example do read ahead, buffer writes (merge
+ small writes into larger chunks), better tune the SSH window and more. This
+ sort of API is already provided for SCP transfers.
+
+API
+
+ New functions:
+
+    LIBSSH2_SFTP_HANDLE *libssh2_sftp_send(SFTP_SESSION *sftp,
+                                           uint64_t filesize,
+                                           char *remote_path,
+                                           size_t remote_path_len,
+                                           long mode);
+
+ Tell libssh2 that a local file with a given size is about to get sent to
+ the SFTP server.
+
+    LIBSSH2_SFTP_HANDLE *libssh2_sftp_recv();
+
+ Tell libssh2 that a remote file is requested to get downloaded from the SFTP
+ server.
+
+ Only the setup of the file transfer is different from an application's point
+ of view. Depending on direction of the transfer(s), the following already
+ existing functions should then be used until the transfer is complete:
+
+ libssh2_sftp_read()
+ libssh2_sftp_write()
+
+HOW TO USE
+
+ 1. Setup the transfer using one of the two new functions.
+
+ 2. Loop through the reading or writing of data.
+
+ 3. Cleanup the transfer

buildconf

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

configure.ac

@@ -16,7 +16,7 @@ fi
 
 dnl figure out the libssh2 version
 VERSION=`$SED -ne 's/^#define LIBSSH2_VERSION *"\(.*\)"/\1/p' ${srcdir}/include/libssh2.h`
-AM_INIT_AUTOMAKE(libssh2,$VERSION)
+AM_INIT_AUTOMAKE
 AC_MSG_CHECKING([libssh2 version])
 AC_MSG_RESULT($VERSION)
 
@@ -41,6 +41,9 @@ case "$host" in
 	;;
     *hpux*)
     ;;
+    *osf*)
+    CFLAGS="$CFLAGS -D_POSIX_PII_SOCKET"
+    ;;
     *)
     ;;
 esac
@@ -108,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>])
@@ -144,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"
 
@@ -159,6 +170,7 @@ AC_HELP_STRING([--disable-debug],[Disable debug options]),
        ;;
   esac
  ],
+       enable_debug=no
        AC_MSG_RESULT(no)
 )
 
@@ -217,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
@@ -256,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,66 @@ 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_get_exit_signal.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.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 +80,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 +109,56 @@ 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_seek64.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.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_get_exit_signal.3

@@ -0,0 +1,36 @@
+.\" $Id$
+.\"
+.TH libssh2_channel_get_exit_signal 3 "4 Oct 2010" "libssh2 1.2.8" "libssh2 manual"
+.SH NAME
+libssh2_channel_get_exit_signal - get the remote exit signal
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int 
+libssh2_channel_get_exit_signal(LIBSSH2_CHANNEL *channel, char **exitsignal, size_t *exitsignal_len, char **errmsg, size_t *errmsg_len, char **langtag, size_t *langtag_len);
+
+.SH DESCRIPTION
+\fIchannel\fP - Closed channel stream to retrieve exit signal from.
+
+\fIexitsignal\fP - If not NULL, is populated by reference with the exit signal
+(without leading "SIG"). Note that the string is stored in a newly allocated
+buffer. If the remote program exited cleanly, the referenced string pointer
+will be set to NULL. 
+
+\fIexitsignal_len\fP - If not NULL, is populated by reference with the length
+of exitsignal. 
+
+\fIerrmsg\fP - If not NULL, is populated by reference with the error message
+(if provided by remote server, if not it will be set to NULL). Note that the
+string is stored in a newly allocated buffer.
+
+\fIerrmsg_len\fP - If not NULL, is populated by reference with the length of errmsg.
+
+\fIlangtag\fP - If not NULL, is populated by reference with the language tag 
+(if provided by remote server, if not it will be set to NULL). Note that the
+string is stored in a newly allocated buffer.
+
+\fIlangtag_len\fP - If not NULL, is populated by reference with the length of langtag.
+
+.SH RETURN VALUE
+Numeric error code corresponding to the the Error Code constants.

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
-libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel, 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);
+ssize_t libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel,
+                                 int stream_id, 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_free.3

@@ -0,0 +1,19 @@
+.TH libssh2_exit 3 "13 Oct 2010" "libssh2 1.2.8" "libssh2 manual"
+.SH NAME
+libssh2_free - deallocate libssh2 memory
+.SH SYNOPSIS
+#include <libssh2.h>
+
+void
+libssh2_free(LIBSSH2_SESSION *session, void *ptr);
+.SH DESCRIPTION
+Deallocate memory allocated by earlier call to libssh2 functions.  It
+uses the memory allocation callbacks provided by the application, if
+any.  Otherwise, this will just call free().
+
+This function is mostly useful under Windows when libssh2 is linked to
+one run-time library and the application to another.
+.SH AVAILABILITY
+Added in libssh2 1.2.8
+.SH SEE ALSO
+.BR libssh2_session_init_ex(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_readfile.3

@@ -1,5 +1,5 @@
 .\"
-.\" Copyright (c) 2009 by Daniel Stenberg
+.\" Copyright (c) 2009-2011 by Daniel Stenberg
 .\"
 .TH libssh2_knownhost_readfile 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
 .SH NAME
@@ -19,8 +19,8 @@ collection of known hosts.
 \fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported
 format. This file is normally found named ~/.ssh/known_hosts
 .SH RETURN VALUE
-Returns a regular libssh2 error code, where negative values are error codes
-and 0 indicates success.
+Returns a negative value, a regular libssh2 error code for errors, or a
+positive number as number of parsed known hosts in the file.
 .SH AVAILABILITY
 Added in libssh2 1.2
 .SH SEE ALSO

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 *
-libssh2_session_callback_set(LIBSSH2_SESSION *session, int cbtype, void *callback);
-
+void *libssh2_session_callback_set(LIBSSH2_SESSION *session,
+                                   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,20 @@ 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.
-
-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.
-
+.SH CALLBACK TYPES
+.IP LIBSSH2_CALLBACK_IGNORE
+Called when a SSH_MSG_IGNORE message is received
+.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. If the
+function returns 0, the packet will be accepted nonetheless.
+.IP LIBSSH2_CALLBACK_X11
+Called when an X11 connection has been accepted
 .SH RETURN VALUE
-Pointer to previous callback handler. Returns NULL if no 
-prior callback handler was set.
-
+Pointer to previous callback handler. Returns NULL if no prior callback
+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_flag.3

@@ -5,11 +5,21 @@
 libssh2_session_flag - TODO
 .SH SYNOPSIS
 int
-libssh2_session_flag(LIBSSH2_SESSION * session, int flag, int value);
+libssh2_session_flag(LIBSSH2_SESSION *session, int flag, int value);
 .SH DESCRIPTION
-This function has no purpose and no documented flags can be set nor read.
+Set options for the created session. \fIflag\fP is the option to set, while
+\fIvalue\fP is typically set to 1 or 0 to enable or disable the option.
+.SH FLAGS
+.IP LIBSSH2_FLAG_SIGPIPE
+If set, libssh2 will not attempt to block SIGPIPEs but will let them trigger
+from the underlying socket layer.
+.IP LIBSSH2_FLAG_COMPRESS
+If set - before the connection negotiation is performed - libssh2 will try to
+negotiate compression enabling for this connection. By default libssh2 will
+not attempt to use compression.
 .SH RETURN VALUE
-0
-.SH ERRORS
-Its mere existence is an error
+Returns regular libssh2 error code.
+.SH AVAILABILITY
+This function has existed since the age of dawn. LIBSSH2_FLAG_COMPRESS was
+added in version 1.2.8.
 .SH SEE ALSO

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_handshake.3

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

docs/libssh2_session_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_session_methods.3

@@ -13,17 +13,17 @@ libssh2_session_methods(LIBSSH2_SESSION *session, int method_type);
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
 
-\fImethod_type\fP - One of the Method Type constants.
-
-Return the actual method negotiated for a particular transport parameter.
+\fImethod_type\fP - one of the method type constants: LIBSSH2_METHOD_KEX,
+LIBSSH2_METHOD_HOSTKEY, LIBSSH2_METHOD_CRYPT_CS, LIBSSH2_METHOD_CRYPT_SC,
+LIBSSH2_METHOD_MAC_CS, LIBSSH2_METHOD_MAC_SC, LIBSSH2_METHOD_COMP_CS,
+LIBSSH2_METHOD_COMP_SC, LIBSSH2_METHOD_LANG_CS, LIBSSH2_METHOD_LANG_SC.
 
+Returns the actual method negotiated for a particular transport parameter.
 .SH RETURN VALUE
 Negotiated method or NULL if the session has not yet been started.
-
 .SH ERRORS
 \fILIBSSH2_ERROR_INVAL\fP - The requested method type was invalid.
 
-\fILIBSSH2_ERROR_METHOD_NONE\fP - 
-
+\fILIBSSH2_ERROR_METHOD_NONE\fP - no method has been set
 .SH SEE ALSO
 .BR libssh2_session_init_ex(3)

docs/libssh2_session_startup.3

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

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)
-
-int 
-libssh2_sftp_fstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs)
-
-int 
-libssh2_sftp_fsetstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs)
+libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle,
+                      LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat)
 
+#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 
-from or into depending on the value of setstat.
+\fIattrs\fP - Pointer to an LIBSSH2_SFTP_ATTRIBUTES structure to set file
+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_open_ex.3

@@ -4,31 +4,45 @@
 .SH NAME
 libssh2_sftp_open - open filehandle for file on SFTP.
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
 LIBSSH2_SFTP_HANDLE *
-libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, const char *filename, unsigned int filename_len, unsigned long flags, long mode, int open_type);
-
-LIBSSH2_SFTP_HANDLE *
-libssh2_sftp_open(LIBSSH2_SFTP *sftp, const char *filename, unsigned long flags, long mode);
-
-LIBSSH2_SFTP_HANDLE *
-libssh2_sftp_opendir(LIBSSH2_SFTP *sftp, const char *path);
-
+libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, const char *filename,
+                     unsigned int filename_len, unsigned long flags,
+                     long mode, int open_type);
 .SH DESCRIPTION
-\fIsftp\fP - SFTP instance as returned by 
-.BR libssh2_sftp_init(3)
+\fIsftp\fP - SFTP instance as returned by \fIlibssh2_sftp_init(3)\fP
 
 \fIfilename\fP - Remote file/directory resource to open 
 
 \fIfilename_len\fP - Length of filename 
 
-\fIflags\fP - Any (reasonable) combination of the LIBSSH2_FXF_* constants
-corresponding fopen modes.
+\fIflags\fP - Any reasonable combination of the LIBSSH2_FXF_* constants:
+.RS
+.IP LIBSSH2_FXF_READ
+Open the file for reading.
+.IP LIBSSH2_FXF_WRITE
+Open the file for writing.  If both this and LIBSSH2_FXF_READ are specified,
+the file is opened for both reading and writing.
+.IP LIBSSH2_FXF_APPEND
+Force all writes to append data at the end of the file.
+.IP LIBSSH2_FXF_CREAT,
+If this flag is specified, then a new file will be created if one does not
+already exist (if LIBSSH2_FXF_TRUNC is specified, the new file will be
+truncated to zero length if it previously exists)
+.IP LIBSSH2_FXF_TRUNC
+Forces an existing file with the same name to be truncated to zero length when
+creating a file by specifying LIBSSH2_FXF_CREAT. LIBSSH2_FXF_CREAT MUST also
+be specified if this flag is used.
+.IP LIBSSH2_FXF_EXCL
+Causes the request to fail if the named file already exists.
+LIBSSH2_FXF_CREAT MUST also be specified if this flag is used.
 
+.RE
 \fImode\fP - POSIX file permissions to assign if the file is being newly
-created.
+created. See the LIBSSH2_SFTP_S_* convenience defines in <libssh2_sftp.h>
 
 \fIopen_type\fP - Either of LIBSSH2_SFTP_OPENFILE (to open a file) or
 LIBSSH2_SFTP_OPENDIR (to open a directory).

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,19 @@
 .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);
-
-int 
-libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
-
+libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle,
+                        char *buffer, size_t buffer_maxlen,
+                        char *longentry, size_t longentry_maxlen,
+                        LIBSSH2_SFTP_ATTRIBUTES *attrs);
 .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 +28,26 @@ 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 
-of the full directory entry is longer than the space provided by 
-longentry_maxlen it will be truncated to fit.
+\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length of
+the full directory entry is longer than the space provided by
+\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
-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.
+Number of bytes actually populated into buffer (not counting 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 BUG
+Passing in a too small buffer for 'buffer' or 'longentry' when receiving data
+only results in libssh2 1.2.7 or earlier to not copy the entire data amount,
+and it is not possible for the application to tell when it happens!
 .SH ERRORS
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
 
@@ -54,6 +58,10 @@ 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.
+
+From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if any of the
+given 'buffer' or 'longentry' buffers are too small to fit the requested
+object name.
 .SH SEE ALSO
 .BR libssh2_sftp_open_ex(3),
 .BR libssh2_sftp_close_handle(3)

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 
-libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len);
-
-int 
-libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path);
-
+int libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path,
+                          unsigned int path_len);
 .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. 
-
-Remove a directory from the remote file system.
-
+\fIsourcefile_len\fP - Length of the full path of the existing directory to
+remove.
 .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_seek.3

@@ -4,16 +4,14 @@
 .SH NAME
 libssh2_sftp_seek - set the read/write position indicator within a file
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
-void 
-libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset);
-
-void 
-libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle, libssh2_uint64_t offset);
-
+void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset);
 .SH DESCRIPTION
+Deprecated function. Use \fIlibssh2_sftp_seek64(3)\fP instead!
+
 \fIhandle\fP - SFTP File Handle as returned by 
 .BR libssh2_sftp_open_ex(3)
 
@@ -24,7 +22,6 @@ Note that libssh2 implements file pointers as a localized concept to make
 file access appear more POSIX like. No packets are exchanged with the server 
 during a seek operation. The localized file pointer is simply used as a 
 convenience offset during read/write operations.
-.SH AVAILABILITY
-libssh2_sftp_seek64(3) was added in 1.0
 .SH SEE ALSO
-.BR libssh2_sftp_open_ex(3)
+.BR libssh2_sftp_open_ex(3),
+.BR libssh2_sftp_seek64(3)

docs/libssh2_sftp_seek64.3

@@ -0,0 +1,31 @@
+.\" $Id: libssh2_sftp_seek.3,v 1.5 2009/03/17 10:34:27 bagder Exp $
+.\"
+.TH libssh2_sftp_seek64 3 "22 Dec 2008" "libssh2 1.0" "libssh2 manual"
+.SH NAME
+libssh2_sftp_seek64 - set the read/write position within a file
+.SH SYNOPSIS
+.nf
+#include <libssh2.h>
+#include <libssh2_sftp.h>
+
+void libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle,
+                         libssh2_uint64_t offset);
+.SH DESCRIPTION
+\fIhandle\fP - SFTP File Handle as returned by 
+.BR libssh2_sftp_open_ex(3)
+
+\fIoffset\fP - Number of bytes from the beginning of file to seek to.
+
+Move the file handle's internal pointer to an arbitrary location. libssh2
+implements file pointers as a localized concept to make file access appear
+more POSIX like. No packets are exchanged with the server during a seek
+operation. The localized file pointer is simply used as a convenience offset
+during read/write operations.
+
+You MUST NOT seek during writing or reading a file with SFTP, as the internals
+use outstanding packets and changing the "file position" during transit will
+results in badness.
+.SH AVAILABILITY
+Added in 1.0
+.SH SEE ALSO
+.BR libssh2_sftp_open_ex(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

@@ -4,49 +4,64 @@
 .SH NAME
 libssh2_sftp_stat_ex - get status about an SFTP file
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
-int 
-libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len, int stat_type, LIBSSH2_SFTP_ATTRIBUTES *attrs);
-
-int 
-libssh2_sftp_stat(LIBSSH2_SFTP *sftp, const char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs);
-
-int 
-libssh2_sftp_lstat(LIBSSH2_SFTP *sftp, const char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs);
-
-int 
-libssh2_sftp_setstat(LIBSSH2_SFTP *sftp, const char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs);
-
+int libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, const char *path,
+                         unsigned int path_len, int stat_type,
+                         LIBSSH2_SFTP_ATTRIBUTES *attrs);
 .SH DESCRIPTION
 \fIsftp\fP - SFTP instance as returned by 
 .BR libssh2_sftp_init(3)
 
 \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 
-stat operation to perform.
+stat operation to perform:
 
-\fIattrs\fP - Pointer to attribute structure to set file metadata 
-from or into depending on the value of stat_type.
+.br
+\fBLIBSSH2_SFTP_STAT\fP: performs stat(2) operation
+.br
+\fBLIBSSH2_SFTP_LSTAT\fP: performs lstat(2) operation
+.br
+\fBLIBSSH2_SFTP_SETSTAT\fP: performs operation to set stat info on file
 
-Get or Set statbuf type data on a remote filesystem object. When 
-getting statbuf data, 
+\fIattrs\fP - Pointer to a \fBLIBSSH2_SFTP_ATTRIBUTES\fP structure to set file
+metadata from or into depending on the value of stat_type.
+
+Get or Set statbuf type data on a remote filesystem object. When getting
+statbuf data,
 .BR libssh2_sftp_stat(3)
 will follow all symlinks, while 
 .BR libssh2_sftp_lstat(3)
 will return data about the object encountered, even if that object 
 happens to be a symlink.
 
-.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.
+The LIBSSH2_SFTP_ATTRIBUTES struct looks like this:
 
+.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;
+
+    libssh2_uint64_t filesize;
+    unsigned long uid;
+    unsigned long gid;
+    unsigned long permissions;
+    unsigned long atime;
+    unsigned long mtime;
+};
+.fi
+.SH RETURN VALUE
+Returns 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.
 
@@ -57,6 +72,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_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,17 @@
 .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);
-
-int 
-libssh2_sftp_symlink(LIBSSH2_SFTP *sftp, const char *path, char *target);
-
-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);
-
+libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path,
+                        unsigned int path_len, char *target,
+                        unsigned int target_len, int link_type);
 .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 +23,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 +49,23 @@ 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
-LIBSSH2_ERROR_EAGAIN when it would otherwise block. While
+When using LIBSSH2_SFTP_SYMLINK, this funtion returns 0 on success or negative
+on failure.
+
+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.
 
+From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if the given 'target'
+buffer is too small to fit the requested object name.
+.SH BUG
+Passing in a too small buffer when receiving data only results in libssh2
+1.2.7 or earlier to not copy the entire data amount, and it is not possible
+for the application to tell when it happens!
 .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,51 @@
 .SH NAME
 libssh2_sftp_write - write SFTP data
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
-ssize_t 
-libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, const char *buffer, size_t count);
-
+ssize_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle,
+                           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
-method is modeled after the POSIX write() function and uses the same calling
-semantics.
+\fIlibssh2_sftp_handle(3)\fP will use as much as possible of the buffer and
+put it into a single SFTP 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 WRITE AHEAD
+Starting in libssh2 version 1.2.8, the default behavior of libssh2 is to
+create several smaller outgoing packets for all data you pass to this function
+and it will return a positive number as soon as the first packet is
+acknowledged from the server.
+
+This has the effect that sometimes more data has been sent off but isn't acked
+yet when this function returns, and when this function is subsequently called
+again to write more data, libssh2 will immediately figure out that the data is
+already received remotely.
+
+In most normal situation this should not cause any problems, but it should be
+noted that if you've once called libssh2_sftp_write() with data and it returns
+short, you MUST still assume that the rest of the data might've been cached so
+you need to make sure you don't alter that data and think that the version you
+have in your next function invoke will be detected or used.
+
+The reason for this funny behavior is that SFTP can only send 32K data in each
+packet and it gets all packets acked individually. This means we cannot use a
+simple serial approach if we want to reach high performance even on high
+latency connections. And we want that.
 .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_list.3

@@ -2,42 +2,40 @@
 .\"
 .TH libssh2_userauth_list 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual"
 .SH NAME
-libssh2_userauth_list - list the authentication methods supported by a server
+libssh2_userauth_list - list supported authentication methods
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 
 char *
-libssh2_userauth_list(LIBSSH2_SESSION *session, const char *username, unsigned int username_len);
-
+libssh2_userauth_list(LIBSSH2_SESSION *session, const char *username,
+                      unsigned int username_len);
 .SH DESCRIPTION
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
 
-\fIusername\fP - Username which will be used while authenticating. Note 
-that most server implementations do not permit attempting authentication 
-with different usernames between requests. Therefore this must be the 
-same username you will use on later userauth calls.
+\fIusername\fP - Username which will be used while authenticating. Note that
+most server implementations do not permit attempting authentication with
+different usernames between requests. Therefore this must be the same username
+you will use on later userauth calls.
 
 \fIusername_len\fP - Length of username parameter.
 
-Send a \fBSSH_USERAUTH_NONE\fP request to the remote host. Unless the 
-remote host is configured to accept none as a viable authentication 
-scheme (unlikely), it will return \fBSSH_USERAUTH_FAILURE\fB along with a 
-listing of what authentication schemes it does support. In the unlikely 
-event that none authentication succeeds, this method with return NULL. This 
-case may be distinguished from faily by examining 
-.BR libssh2_userauth_authenticated(3)
-
+Send a \fBSSH_USERAUTH_NONE\fP request to the remote host. Unless the remote
+host is configured to accept none as a viable authentication scheme
+(unlikely), it will return \fBSSH_USERAUTH_FAILURE\fP along with a listing of
+what authentication schemes it does support. In the unlikely event that none
+authentication succeeds, this method with return NULL. This case may be
+distinguished from a failing case by examining
+\fIlibssh2_userauth_authenticated(3)\fP.
 .SH RETURN VALUE
-On success a comma delimited list of supported authentication schemes.  This list is 
-internally managed by libssh2.  On failure ruturns NULL.
-
+On success a comma delimited list of supported authentication schemes.  This
+list is internally managed by libssh2.  On failure ruturns NULL.
 .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_EAGAIN\fP - Marked for non-blocking I/O but the call
-
 .SH SEE ALSO
 .BR libssh2_session_init_ex(3)

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
-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
-libssh2_userauth_password(LIBSSH2_SESSION *session, const char *username, const char *password);
-
+#define libssh2_userauth_password(session, username, password) \\
+ libssh2_userauth_password_ex((session), (username), \\
+                              strlen(username), \\
+                              (password), strlen(password), NULL)
 .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.3

@@ -0,0 +1,29 @@
+.\" $Id: template.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_userauth_publickey 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual"
+.SH NAME
+libssh2_userauth_publickey - authenticate using a callback function
+.SH SYNOPSIS
+#include <libssh2.h>
+
+.NF
+int libssh2_userauth_publickey(LIBSSH2_SESSION *session,
+                               const char *user,
+                               const unsigned char *pubkeydata,
+                               size_t pubkeydata_len,
+                               sign_callback,
+                               void **abstract);
+.SH DESCRIPTION
+Authenticate with the \fIsign_callback\fP callback that matches the prototype
+below
+.SH CALLBACK
+.nf
+int name(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len,
+         const unsigned char *data, size_t data_len, void **abstract);
+.fi
+
+This function gets called...
+.SH RETURN VALUE
+Return 0 on success or negative on failure.
+.SH SEE ALSO
+.BR libssh2_userauth_publickey_fromfile_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

docs/libssh2_userauth_publickey_fromfile_ex.3

@@ -6,12 +6,12 @@ libssh2_userauth_publickey_fromfile - authenticate a session with a public key,
 .SH SYNOPSIS
 #include <libssh2.h>
 
-int
-libssh2_userauth_publickey_fromfile_ex(LIBSSH2_SESSION *session, const char *username, unsigned int username_len, const char *publickey, const char *privatekey, const char *passphrase);
-
-int
-libssh2_userauth_publickey_fromfile_ex(LIBSSH2_SESSION *session, const char *username, const char *publickey, const char *privatekey, const char *passphrase);
-
+.nf
+int libssh2_userauth_publickey_fromfile_ex(LIBSSH2_SESSION *session,
+                                           const char *username,
+                                           const char *publickey,
+                                           const char *privatekey,
+                                           const char *passphrase);
 .SH DESCRIPTION
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)

example/Makefile.am

@@ -3,14 +3,10 @@ AUTOMAKE_OPTIONS = foreign nostdinc
 EXTRA_DIST = libssh2_config.h.in
 
 # samples
-noinst_PROGRAMS = direct_tcpip ssh2 \
-		scp scp_nonblock \
-		scp_write scp_write_nonblock \
-		sftp sftp_nonblock \
-		sftp_write sftp_write_nonblock \
-		sftp_mkdir sftp_mkdir_nonblock \
-		sftp_RW_nonblock \
-		sftpdir sftpdir_nonblock ssh2_exec ssh2_agent
+noinst_PROGRAMS = direct_tcpip ssh2 scp scp_nonblock scp_write		\
+ scp_write_nonblock sftp sftp_nonblock sftp_write sftp_write_nonblock	\
+ sftp_mkdir sftp_mkdir_nonblock sftp_RW_nonblock sftpdir		\
+ sftpdir_nonblock ssh2_exec ssh2_agent ssh2_echo sftp_append
 
 AM_CPPFLAGS = -I$(top_srcdir)/include -I$(top_builddir)/example
 LDADD = $(top_builddir)/src/libssh2.la

example/direct_tcpip.c

@@ -1,3 +1,4 @@
+#include "libssh2_config.h"
 #include <libssh2.h>
 
 #ifdef WIN32
@@ -18,6 +19,14 @@
 #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
+
 const char *keyfile1 = "/home/username/.ssh/id_rsa.pub";
 const char *keyfile2 = "/home/username/.ssh/id_rsa";
 const char *username = "username";
@@ -77,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;
@@ -140,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;
         }
@@ -187,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, "(Note that this can be a problem at the server! Please review the server logs.)\n");
+        fprintf(stderr, "Could not open the direct-tcpip channel!\n"
+                "(Note that this can be a problem at the server!"
+                " Please review the server logs.)\n");
         goto shutdown;
     }
 
@@ -267,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
@@ -131,7 +137,8 @@ int main(int argc, char *argv[])
     channel = libssh2_scp_recv(session, scppath, &fileinfo);
 
     if (!channel) {
-        fprintf(stderr, "Unable to open a session\n");
+        fprintf(stderr, "Unable to open a session: %d\n",
+                libssh2_session_last_errno(session));
         goto shutdown;
     }
 
@@ -145,10 +152,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 +176,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);
-        goto shutdown;
+        fprintf(stderr, "Can't open local file %s\n", loclfile);
+        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 {
-                /* rc indicates how many bytes were written this time */
-                sent += rc;
+                break;
             }
-        } while (rc > 0 && sent < nread);
-        ptr += sent;
-        nread -= sent;
+            else {
+                /* rc indicates how many bytes were written this time */
+                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");
-    libssh2_session_free(session);
-
+    if(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,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[])
 {
@@ -39,7 +70,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 +81,14 @@ int main(int argc, char *argv[])
 #if defined(HAVE_IOCTLSOCKET)
     long flag = 1;
 #endif
-    char mem[1024];
-    size_t nread, sent;
+    char mem[1024*100];
+    size_t nread;
     char *ptr;
     struct stat fileinfo;
+    time_t start;
+    long total = 0;
+    int duration;
+    size_t prev;
 
 #ifdef WIN32
     WSADATA wsadata;
@@ -79,10 +114,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 +210,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,23 +218,37 @@ int main(int argc, char *argv[])
             break;
         }
         ptr = mem;
-        sent = 0;
 
+        total += nread;
+
+        prev = 0;
         do {
-            /* write the same data over and over, until error or completion */
-            rc = libssh2_channel_write(channel, ptr, nread);
-            if (LIBSSH2_ERROR_EAGAIN == rc) { /* must loop around */
-                continue;
-            } else if (rc < 0) {
-                fprintf(stderr, "ERROR %d\n", rc);
-            } else {
-                /* rc indicates how many bytes were written this time */
-                sent += rc;
+            while ((rc = libssh2_channel_write(channel, ptr, nread)) ==
+                   LIBSSH2_ERROR_EAGAIN) {
+                waitsocket(sock, session);
+                prev = 0;
             }
-        } while (rc > 0 && sent < nread);
-        ptr += sent;
-        nread -= sent;
-    } while (1);
+            if (rc < 0) {
+                fprintf(stderr, "ERROR %d total %ld / %d prev %d\n", rc,
+                        total, (int)nread, (int)prev);
+                break;
+            }
+            else {
+                prev = nread;
+                if(rc > nread) {
+                    fprintf(stderr, "MOO %d > %d\n", (int)rc, (int)nread);
+                }
+                /* rc indicates how many bytes were written this time */
+                nread -= rc;
+                ptr += rc;
+            }
+        } while (nread);
+    } while (!nread); /* only continue if nread was drained */
+
+    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 +264,9 @@ 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
@@ -218,5 +275,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;
-    (void)name_len;
-    (void)instruction;
-    (void)instruction_len;
-    if (num_prompts == 1) {
-        responses[0].text = strdup(password);
-        responses[0].length = strlen(password);
-    }
-    (void)prompts;
+    int i;
+    size_t n;
+    char buf[1024];
     (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
@@ -210,7 +245,8 @@ int main(int argc, char *argv[])
         libssh2_sftp_open(sftp_session, sftppath, LIBSSH2_FXF_READ, 0);
 
     if (!sftp_handle) {
-        fprintf(stderr, "Unable to open file with SFTP\n");
+        fprintf(stderr, "Unable to open file with SFTP: %ld\n",
+                libssh2_sftp_last_error(sftp_session));
         goto shutdown;
     }
     fprintf(stderr, "libssh2_sftp_open() is done, now receive data!\n");
@@ -241,5 +277,8 @@ int main(int argc, char *argv[])
     close(sock);
 #endif
     fprintf(stderr, "all done\n");
+
+    libssh2_exit();
+
     return 0;
 }