release: updated to hold 1.2.7 info

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

.cvsusers

@@ -1,11 +0,0 @@
-jas4711:Simon Josefsson <simon@josefsson.org>
-bagder:Daniel Stenberg
-sarag:Sara Golemon <pollita@libssh2.org>
-gusarov:Mikhail Gusarov <dottedmag@dottedmag.net>
-wez:Wez Furlong
-edink:Edink Kadribasic
-jehousley: James Housley
-gknauf: Guenter Knauf
-dfandrich: Dan Fandrich
-yangtse: Yang Tse
-thomaspu: Paul Thomas

.gitattribute

@@ -0,0 +1,2 @@
+win32/msvcproj.head -crlf
+win32/msvcproj.foot -crlf

.gitignore

@@ -26,3 +26,10 @@ ssh2_sample
 libssh2-*.tar.gz
 INSTALL
 install-sh
+*.o
+*.lo
+*.la
+mkinstalldirs
+tags
+libssh2.pc
+TAGS

AUTHORS

@@ -1,15 +1,47 @@
-* Sara Golemon: Author / Project Manager
+ libssh2 is the result of many friendly people. This list is an attempt to
+ mention all contributors. If we've missed anyone, tell us!
 
-* Daniel Stenberg: Co-maintainer
+ This list of names is a-z sorted.
 
-* James Housleys: Nonblocking conversion
-
-* Simon Josefsson: libgcrypt support
-
-* Mikhail Gusarov: Keyboard Interactive Authentication
-
-* Wez Furlong & Edink Kadribasic: Windows Port
-
-* Dan Fandrich: bug fixes, cleanups
-
-* Guenter Knauf: win32 work and more
+Adam Gobiowski
+Alexander Holyapin
+Alexander Lamaison
+Ben Kibbey
+Bjorn Stenborg
+Carlo Bramini
+Dan Casey
+Dan Fandrich
+Daniel Stenberg
+David J Sullivan
+David Robins
+Edink Kadribasic
+Erik Brossler
+Francois Dupoux
+Guenter Knauf
+Heiner Steven
+James Housleys
+Jean-Louis Charton
+Jussi Mononen
+Mark McPherson
+Markus Moeller
+Mike Protts
+Mikhail Gusarov
+Neil Gierman
+Olivier Hervieu
+Paul Veldkamp
+Peter O'Gorman
+Peter Stuge
+Romain Bondue
+Sara Golemon
+Satish Mittal
+Sean Peterson
+Selcuk Gueney
+Simon Hart
+Simon Josefsson
+Steven Ayre
+Steven Van Ingelgem
+Tor Arntsen
+Vincent Jaulin
+Vlad Grachov
+Wez Furlong
+Yang Tse

COPYING

@@ -1,5 +1,9 @@
 /* Copyright (c) 2004-2007 Sara Golemon <sarag@libssh2.org>
- * Copyright (C) 2006-2007 The Written Word, Inc.
+ * 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.
  *
  * Redistribution and use in source and binary forms,

HACKING

@@ -9,24 +9,5 @@ libssh2 source code style guide:
          go_nuts();
      }
 
- - write both braces on the else line:
-
-     if (banana) {
-         go_nuts();
-     } else {
-         stay_calm();
-     }
-
- - use braces even for single-statement blocks
- 
  - keep source lines shorter than 80 columns
-
-------------
-
- Older libssh2 code that still hasn't quite transitioned to the above
- mentioned style, used a different style:
-
- - indented with tabs (only)
-
- - no line length limits
-
+ - See libssh2-style.el for how to achieve this within Emacs

Makefile.am

@@ -1,5 +1,10 @@
+AUTOMAKE_OPTIONS = foreign nostdinc
+
 SUBDIRS = src example tests docs
 
+pkgconfigdir = $(libdir)/pkgconfig
+pkgconfig_DATA = libssh2.pc
+
 include_HEADERS =			\
 	include/libssh2.h		\
 	include/libssh2_publickey.h	\
@@ -11,20 +16,30 @@ NETWAREFILES =  nw/keepscreen.c \
  nw/nwlib.c \
  nw/test/Makefile.netware
 
-WIN32FILES = win32/libssh2_dll.dsp win32/libssh2.dsw win32/Makefile.win32      \
-win32/config.mk win32/Makefile win32/test/Makefile.win32 win32/libssh2_lib.dsp \
-win32/libssh2_config.h win32/tests.dsp win32/rules.mk
+DSP = win32/libssh2.dsp
+VCPROJ = win32/libssh2.vcproj
+
+DISTCLEANFILES = $(DSP)
+
+VMSFILES = vms/libssh2_make_example.dcl vms/libssh2_make_help.dcl	\
+vms/libssh2_make_kit.dcl vms/libssh2_make_lib.dcl vms/man2help.c	\
+vms/readme.vms vms/libssh2_config.h
+
+
+WIN32FILES = win32/Makefile.win32 win32/libssh2.dsw     \
+win32/config.mk win32/Makefile win32/test/Makefile.win32 \
+win32/libssh2_config.h win32/tests.dsp win32/rules.mk $(DSP) \
+win32/msvcproj.head win32/msvcproj.foot
 
 EXTRA_DIST = $(WIN32FILES) buildconf $(NETWAREFILES) get_ver.awk HACKING \
- maketgz NMakefile TODO
+ maketgz NMakefile TODO RELEASE-NOTES libssh2.pc.in $(VMSFILES)
 
 ACLOCAL_AMFLAGS = -I m4
 
 .PHONY: ChangeLog
 ChangeLog:
-	if test -f .cvsusers; then \
-	  cvs2cl --utc --fsf --FSF --usermap .cvsusers -I ChangeLog -I .cvs; \
-	fi
+	echo "see NEWS" > ./ChangeLog
+DISTCLEANFILES += ChangeLog
 
 dist-hook:
 	rm -rf $(top_builddir)/tests/log
@@ -57,3 +72,62 @@ gen-coverage:
 		--title "$(PACKAGE_NAME)"
 
 coverage: init-coverage build-coverage gen-coverage
+
+# DSP/VCPROJ generation adapted from libcurl
+# Makefile.inc provides the CSOURCES and HHEADERS defines
+include Makefile.inc
+
+WIN32SOURCES = $(CSOURCES)
+WIN32HEADERS = $(HHEADERS) libssh2_config.h
+
+$(DSP): win32/msvcproj.head win32/msvcproj.foot Makefile.am
+	echo "creating $(DSP)"
+	@( (cat $(srcdir)/win32/msvcproj.head; \
+	echo "# Begin Group \"Source Files\""; \
+	echo ""; \
+	echo "# PROP Default_Filter \"cpp;c;cxx\""; \
+	win32_srcs='$(WIN32SOURCES)'; \
+	sorted_srcs=`for file in $$win32_srcs; do echo $$file; done | sort`; \
+	for file in $$sorted_srcs; do \
+		echo "# Begin Source File"; \
+		echo ""; \
+		echo "SOURCE=..\\src\\"$$file; \
+		echo "# End Source File"; \
+	done; \
+	echo "# End Group"; \
+	echo "# Begin Group \"Header Files\""; \
+	echo ""; \
+	echo "# PROP Default_Filter \"h;hpp;hxx\""; \
+	win32_hdrs='$(WIN32HEADERS)'; \
+	sorted_hdrs=`for file in $$win32_hdrs; do echo $$file; done | sort`; \
+	for file in $$sorted_hdrs; do \
+		echo "# Begin Source File"; \
+		echo ""; \
+		if [ "$$file" == "libssh2_config.h" ]; \
+		then \
+			echo "SOURCE=.\\"$$file; \
+		else \
+			echo "SOURCE=..\\src\\"$$file; \
+		fi; \
+		echo "# End Source File"; \
+	done; \
+	echo "# End Group"; \
+	cat $(srcdir)/win32/msvcproj.foot) | \
+	awk '{printf("%s\r\n", gensub("\r", "", "g"))}' > $@ )
+
+$(VCPROJ): win32/vc8proj.head win32/vc8proj.foot Makefile.am
+	echo "creating $(VCPROJ)"
+	@( (cat $(srcdir)/vc8proj.head; \
+	win32_srcs='$(WIN32SOURCES)'; \
+	sorted_srcs=`for file in $$win32_srcs; do echo $$file; done | sort`; \
+	for file in $$sorted_srcs; do \
+		echo "<File RelativePath=\""..\src\$$file"\"></File>"; \
+	done; \
+	echo "</Filter><Filter	Name=\"Header Files\">"; \
+	win32_hdrs='$(WIN32HEADERS)'; \
+	sorted_hdrs=`for file in $$win32_hdrs; do echo $$file; done | sort`; \
+	for file in $$sorted_hdrs; do \
+		echo "<File RelativePath=\""..\src\$$file"\"></File>"; \
+	done; \
+	cat $(srcdir)/vc8proj.foot) | \
+	awk '{printf("%s\r\n", gensub("\r", "", "g"))}' > $@ )

Makefile.inc

@@ -0,0 +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 keepalive.c \
+ global.c
+
+HHEADERS = libssh2_priv.h openssl.h libgcrypt.h transport.h channel.h \
+ comp.h mac.h misc.h packet.h userauth.h session.h

NEWS

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

NMakefile

@@ -1,6 +1,6 @@
 !include "win32/config.mk"
 
-# SUBDIRS=src example\simple
+# SUBDIRS=src example
 SUBDIRS=src
 
 all-sub:

README

@@ -6,7 +6,7 @@ the revised BSD license.
 
 Web site: http://www.libssh2.org/
 
-Mailing list: https://lists.sourceforge.net/lists/listinfo/libssh2-devel
+Mailing list: http://cool.haxx.se/mailman/listinfo/libssh2-devel
 
 Generic installation instructions are in INSTALL.  Some ./configure
 options deserve additional comments:

RELEASE-NOTES

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

TODO

@@ -1,19 +1,15 @@
 Things TODO
 ===========
 
-* Add one of the missing man pages:
+* make sure the windowing code adapts better to slow situations so that it
+  doesn't then use as much memory as today. Possibly by an app-controllable
+  "Window mode"?
 
-  libssh2_channel_receive_window_adjust
-  libssh2_channel_request_pty_size_ex
-  libssh2_channel_window_read_ex
-  libssh2_channel_window_write_ex
-  libssh2_publickey_add_ex
-  libssh2_publickey_init
-  libssh2_publickey_list_fetch
-  libssh2_publickey_list_free
-  libssh2_publickey_remove_ex
-  libssh2_publickey_shutdown
-  libssh2_userauth_hostbased_fromfile_ex
+* 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.
 
@@ -21,8 +17,9 @@ Things TODO
 
 * Extend the test suite to actually test lots of aspects of libssh2
 
-* libssh2_channel_receive_window_adjust() can return EAGAIN while documented
-  to return the window as an "unsigned long".
+* Fix all compiler warnings (some can't be done without API changes)
+
+* Expose error messages sent by the server
 
 At next SONAME bump
 ===================
@@ -30,9 +27,34 @@ At next SONAME bump
 * stop using #defined macros as part of the official API. The macros should
   either be turned into real functions or discarded from the API.
 
+* fix the parts of the API where object pointers and function pointers are
+  mixed like libssh2_session_callback_set()
+
 * remove the following functions from the API/ABI
 
   libssh2_base64_decode()
   libssh2_session_flag()
   libssh2_channel_handle_extended_data()
   libssh2_channel_receive_window_adjust()
+  libssh2_poll()
+  libssh2_poll_channel_read()
+
+* Rename a few function:
+
+  libssh2_hostkey_hash => libssh2_session_hostkey_hash
+  libssh2_banner_set => libssh2_session_banner_set
+
+* change 'int' to 'libssh2_socket_t' in the public API for sockets.
+
+* Use 'size_t' for string lengths in all functions.
+
+* Add a comment field to struct libssh2_knownhost.
+
+* remove the existing libssh2_knownhost_add() function and rename
+  libssh2_knownhost_addc to become the new libssh2_knownhost_add instead
+
+* remove the existing libssh2_scp_send_ex() function and rename
+  libssh2_scp_send64 to become the new libssh2_scp_send instead.
+
+* remove the existing libssh2_knownhost_check() functin and rename
+  libssh2_knownhost_checkp() to become the new libssh2_knownhost_check instead

acinclude.m4

@@ -288,3 +288,97 @@ dnl end of non-blocking try-compile test
     AC_MSG_WARN([non-block sockets disabled])
   fi
 ])
+
+dnl CURL_CHECK_NEED_REENTRANT_SYSTEM
+dnl -------------------------------------------------
+dnl Checks if the preprocessor _REENTRANT definition
+dnl must be unconditionally done for this platform.
+dnl Internal macro for CURL_CONFIGURE_REENTRANT.
+
+AC_DEFUN([CURL_CHECK_NEED_REENTRANT_SYSTEM], [
+  case $host in
+    *-*-solaris* | *-*-hpux*)
+      tmp_need_reentrant="yes"
+      ;;
+    *)
+      tmp_need_reentrant="no"
+      ;;
+  esac
+])
+
+
+dnl CURL_CONFIGURE_FROM_NOW_ON_WITH_REENTRANT
+dnl -------------------------------------------------
+dnl This macro ensures that configuration tests done
+dnl after this will execute with preprocessor symbol
+dnl _REENTRANT defined. This macro also ensures that
+dnl the generated config file defines NEED_REENTRANT
+dnl and that in turn setup.h will define _REENTRANT.
+dnl Internal macro for CURL_CONFIGURE_REENTRANT.
+
+AC_DEFUN([CURL_CONFIGURE_FROM_NOW_ON_WITH_REENTRANT], [
+AC_DEFINE(NEED_REENTRANT, 1,
+  [Define to 1 if _REENTRANT preprocessor symbol must be defined.])
+cat >>confdefs.h <<_EOF
+#ifndef _REENTRANT
+#  define _REENTRANT
+#endif
+_EOF
+])
+
+
+dnl CURL_CONFIGURE_REENTRANT
+dnl -------------------------------------------------
+dnl This first checks if the preprocessor _REENTRANT
+dnl symbol is already defined. If it isn't currently
+dnl defined a set of checks are performed to verify
+dnl if its definition is required to make visible to
+dnl the compiler a set of *_r functions. Finally, if
+dnl _REENTRANT is already defined or needed it takes
+dnl care of making adjustments necessary to ensure
+dnl that it is defined equally for further configure
+dnl tests and generated config file.
+
+AC_DEFUN([CURL_CONFIGURE_REENTRANT], [
+  AC_PREREQ([2.50])dnl
+  #
+  AC_MSG_CHECKING([if _REENTRANT is already defined])
+  AC_COMPILE_IFELSE([
+    AC_LANG_PROGRAM([[
+    ]],[[
+#ifdef _REENTRANT
+      int dummy=1;
+#else
+      force compilation error
+#endif
+    ]])
+  ],[
+    AC_MSG_RESULT([yes])
+    tmp_reentrant_initially_defined="yes"
+  ],[
+    AC_MSG_RESULT([no])
+    tmp_reentrant_initially_defined="no"
+  ])
+  #
+  if test "$tmp_reentrant_initially_defined" = "no"; then
+    AC_MSG_CHECKING([if _REENTRANT is actually needed])
+    CURL_CHECK_NEED_REENTRANT_SYSTEM
+
+    if test "$tmp_need_reentrant" = "yes"; then
+      AC_MSG_RESULT([yes])
+    else
+      AC_MSG_RESULT([no])
+    fi
+  fi
+  #
+  AC_MSG_CHECKING([if _REENTRANT is onwards defined])
+  if test "$tmp_reentrant_initially_defined" = "yes" ||
+    test "$tmp_need_reentrant" = "yes"; then
+    CURL_CONFIGURE_FROM_NOW_ON_WITH_REENTRANT
+    AC_MSG_RESULT([yes])
+  else
+    AC_MSG_RESULT([no])
+  fi
+  #
+])
+

buildconf

@@ -1,11 +1,22 @@
 #!/bin/sh
 
-${LIBTOOLIZE:-libtoolize} --copy --automake --force
+LIBTOOLIZE="libtoolize"
+
+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
+fi
+
+${LIBTOOLIZE} --copy --automake --force
 ${ACLOCAL:-aclocal} -I m4 $ACLOCAL_FLAGS
 ${AUTOHEADER:-autoheader}
 # copy the private libssh2_config.h.in to the examples dir so that
 # it can be included without pointing the include path to the private
 # source dir
-cp src/libssh2_config.h.in example/simple/config.h.in
+cp src/libssh2_config.h.in example/libssh2_config.h.in
 ${AUTOCONF:-autoconf}
 ${AUTOMAKE:-automake} --add-missing --copy

configure.ac

@@ -1,8 +1,8 @@
 # AC_PREREQ(2.57)
-AC_INIT(libssh2, [-], libssh2-devel@lists.sourceforge.net)
+AC_INIT(libssh2, [-], libssh2-devel@cool.haxx.se)
 AC_CONFIG_MACRO_DIR([m4])
 AC_CONFIG_SRCDIR([src])
-AC_CONFIG_HEADER([src/libssh2_config.h])
+AM_CONFIG_HEADER([src/libssh2_config.h example/libssh2_config.h])
 AM_MAINTAINER_MODE
 
 dnl SED is needed by some of the tools
@@ -41,6 +41,9 @@ case "$host" in
 	;;
     *hpux*)
     ;;
+    *osf*)
+    CFLAGS="$CFLAGS -D_POSIX_PII_SOCKET"
+    ;;
     *)
     ;;
 esac
@@ -50,6 +53,10 @@ AC_CHECK_TYPE(long long,
       [Define to 1 if the compiler supports the 'long long' data type.])]
    longlong="yes"
 )
+
+dnl Our configure and build reentrant settings
+CURL_CONFIGURE_REENTRANT
+
 # Some systems (Solaris?) have socket() in -lsocket.
 AC_SEARCH_LIBS(socket, socket)
 
@@ -104,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>])
@@ -140,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"
 
@@ -155,6 +170,46 @@ AC_HELP_STRING([--disable-debug],[Disable debug options]),
        ;;
   esac
  ],
+       enable_debug=no
+       AC_MSG_RESULT(no)
+)
+
+dnl ************************************************************
+dnl Enable hiding of internal symbols in library to reduce its size and
+dnl speed dynamic linking of applications.  This currently is only supported
+dnl on gcc >= 4.0 and SunPro C.
+dnl
+AC_MSG_CHECKING([whether to enable hidden symbols in the library])
+AC_ARG_ENABLE(hidden-symbols,
+AC_HELP_STRING([--enable-hidden-symbols],[Hide internal symbols in library])
+AC_HELP_STRING([--disable-hidden-symbols],[Leave all symbols with default visibility in library]),
+[ case "$enableval" in
+  no)
+       AC_MSG_RESULT(no)
+       ;;
+  *)
+       AC_MSG_CHECKING([whether $CC supports it])
+       if test "$GCC" = yes ; then
+         if $CC --help --verbose 2>&1 | grep fvisibility= > /dev/null ; then
+           AC_MSG_RESULT(yes)
+           AC_DEFINE(LIBSSH2_API, [__attribute__ ((visibility ("default")))], [to make a symbol visible])
+           CFLAGS="$CFLAGS -fvisibility=hidden"
+         else
+            AC_MSG_RESULT(no)
+          fi
+
+       else
+         dnl Test for SunPro cc
+         if $CC 2>&1 | grep flags >/dev/null && $CC -flags | grep xldscope= >/dev/null ; then
+           AC_MSG_RESULT(yes)
+           AC_DEFINE(LIBSSH2_API, [__global], [to make a symbol visible])
+           CFLAGS="$CFLAGS -xldscope=hidden"
+         else
+           AC_MSG_RESULT(no)
+         fi
+       fi
+       ;;
+  esac ],
        AC_MSG_RESULT(no)
 )
 
@@ -163,6 +218,7 @@ AC_HELP_STRING([--disable-debug],[Disable debug options]),
 AC_CHECK_HEADERS([errno.h fcntl.h stdio.h stdlib.h unistd.h sys/uio.h])
 AC_CHECK_HEADERS([sys/select.h sys/socket.h sys/ioctl.h sys/time.h])
 AC_CHECK_HEADERS([arpa/inet.h netinet/in.h])
+AC_CHECK_HEADERS([sys/un.h])
 
 case $host in
   *-*-cygwin* | *-*-cegcc*)
@@ -173,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
@@ -209,6 +283,20 @@ AC_CONFIG_FILES([Makefile
                  src/Makefile
                  tests/Makefile
                  example/Makefile
-                 example/simple/Makefile
-                 docs/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

@@ -3,41 +3,103 @@
 EXTRA_DIST = template.3
 
 dist_man_MANS = \
+	libssh2_agent_connect.3 \
+	libssh2_agent_disconnect.3 \
+	libssh2_agent_free.3 \
+	libssh2_agent_get_identity.3 \
+	libssh2_agent_init.3 \
+	libssh2_agent_list_identities.3 \
+	libssh2_agent_userauth.3 \
 	libssh2_banner_set.3 \
+	libssh2_base64_decode.3 \
 	libssh2_channel_close.3 \
+	libssh2_channel_direct_tcpip.3 \
 	libssh2_channel_direct_tcpip_ex.3 \
 	libssh2_channel_eof.3 \
+	libssh2_channel_exec.3 \
+	libssh2_channel_flush.3 \
 	libssh2_channel_flush_ex.3 \
+	libssh2_channel_flush_stderr.3 \
 	libssh2_channel_forward_accept.3 \
 	libssh2_channel_forward_cancel.3 \
+	libssh2_channel_forward_listen.3 \
 	libssh2_channel_forward_listen_ex.3 \
 	libssh2_channel_free.3 \
 	libssh2_channel_get_exit_status.3 \
 	libssh2_channel_handle_extended_data.3 \
 	libssh2_channel_handle_extended_data2.3 \
+	libssh2_channel_ignore_extended_data.3 \
 	libssh2_channel_open_ex.3 \
+	libssh2_channel_open_session.3 \
 	libssh2_channel_process_startup.3 \
+	libssh2_channel_read.3 \
 	libssh2_channel_read_ex.3 \
+	libssh2_channel_read_stderr.3 \
 	libssh2_channel_receive_window_adjust.3 \
 	libssh2_channel_receive_window_adjust2.3 \
+	libssh2_channel_request_pty.3 \
 	libssh2_channel_request_pty_ex.3 \
+	libssh2_channel_request_pty_size.3 \
+	libssh2_channel_request_pty_size_ex.3 \
 	libssh2_channel_send_eof.3 \
 	libssh2_channel_set_blocking.3 \
+	libssh2_channel_setenv.3 \
 	libssh2_channel_setenv_ex.3 \
-	libssh2_channel_wait_eof.3 \
+	libssh2_channel_shell.3 \
+	libssh2_channel_subsystem.3 \
 	libssh2_channel_wait_closed.3 \
+	libssh2_channel_wait_eof.3 \
+	libssh2_channel_window_read.3 \
 	libssh2_channel_window_read_ex.3 \
+	libssh2_channel_window_write.3 \
 	libssh2_channel_window_write_ex.3 \
+	libssh2_channel_write.3 \
 	libssh2_channel_write_ex.3 \
+	libssh2_channel_write_stderr.3 \
+	libssh2_channel_x11_req.3 \
 	libssh2_channel_x11_req_ex.3 \
+	libssh2_exit.3 \
+	libssh2_free_host_entry.3 \
+	libssh2_host_entry_match.3 \
 	libssh2_hostkey_hash.3 \
+	libssh2_init.3 \
+	libssh2_knownhost_add.3 \
+	libssh2_knownhost_addc.3 \
+	libssh2_knownhost_check.3 \
+	libssh2_knownhost_checkp.3 \
+	libssh2_knownhost_del.3 \
+	libssh2_knownhost_free.3 \
+	libssh2_knownhost_get.3 \
+	libssh2_knownhost_init.3 \
+	libssh2_knownhost_readfile.3 \
+	libssh2_knownhost_readline.3 \
+	libssh2_knownhost_writefile.3 \
+	libssh2_knownhost_writeline.3 \
+	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_free.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 \
@@ -45,44 +107,54 @@ dist_man_MANS = \
 	libssh2_session_methods.3 \
 	libssh2_session_set_blocking.3 \
 	libssh2_session_startup.3 \
-	libssh2_poll.3 \
-	libssh2_poll_channel_read.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_last_error.3 \
+	libssh2_sftp_fstatvfs.3 \
 	libssh2_sftp_init.3 \
-	libssh2_sftp_open_ex.3 \
+	libssh2_sftp_last_error.3 \
+	libssh2_sftp_lstat.3 \
+	libssh2_sftp_mkdir.3 \
 	libssh2_sftp_mkdir_ex.3 \
+	libssh2_sftp_open.3 \
+	libssh2_sftp_open_ex.3 \
+	libssh2_sftp_opendir.3 \
 	libssh2_sftp_read.3 \
+	libssh2_sftp_readdir.3 \
 	libssh2_sftp_readdir_ex.3 \
+	libssh2_sftp_readlink.3 \
+	libssh2_sftp_realpath.3 \
+	libssh2_sftp_rename.3 \
 	libssh2_sftp_rename_ex.3 \
+	libssh2_sftp_rewind.3 \
+	libssh2_sftp_rmdir.3 \
 	libssh2_sftp_rmdir_ex.3 \
 	libssh2_sftp_seek.3 \
+	libssh2_sftp_setstat.3 \
 	libssh2_sftp_shutdown.3 \
+	libssh2_sftp_stat.3 \
 	libssh2_sftp_stat_ex.3 \
+	libssh2_sftp_statvfs.3 \
+	libssh2_sftp_symlink.3 \
 	libssh2_sftp_symlink_ex.3 \
 	libssh2_sftp_tell.3 \
 	libssh2_sftp_tell64.3 \
+	libssh2_sftp_unlink.3 \
 	libssh2_sftp_unlink_ex.3 \
 	libssh2_sftp_write.3 \
+	libssh2_trace.3 \
+	libssh2_trace_sethandler.3 \
 	libssh2_userauth_authenticated.3 \
+	libssh2_userauth_hostbased_fromfile.3 \
+	libssh2_userauth_hostbased_fromfile_ex.3 \
+	libssh2_userauth_keyboard_interactive.3 \
 	libssh2_userauth_keyboard_interactive_ex.3 \
 	libssh2_userauth_list.3 \
+	libssh2_userauth_password.3 \
 	libssh2_userauth_password_ex.3 \
+	libssh2_userauth_publickey_fromfile.3 \
 	libssh2_userauth_publickey_fromfile_ex.3 \
-	libssh2_base64_decode.3 \
-	libssh2_trace.3 \
 	libssh2_version.3
-	libssh2_channel_request_pty_size_ex.3 \
-	libssh2_free_host_entry.3 \
-	libssh2_host_entry_match.3 \
-	libssh2_new_host_entry.3 \
-	libssh2_publickey_add_ex.3 \
-	libssh2_publickey_init.3 \
-	libssh2_publickey_list_fetch.3 \
-	libssh2_publickey_list_free.3 \
-	libssh2_publickey_remove_ex.3 \
-	libssh2_publickey_shutdown.3 \
-	libssh2_session_flag.3 \
-	libssh2_session_get_blocking.3 \
-	libssh2_userauth_hostbased_fromfile_ex.3

docs/libssh2_agent_connect.3

@@ -0,0 +1,23 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_connect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_connect - connect to an ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_connect(LIBSSH2_AGENT *agent);
+.SH DESCRIPTION
+Connect to an ssh-agent running on the system.
+
+Call \fBlibssh2_agent_disconnect(3)\fP to close the connection after
+you're doing using it.
+.SH RETURN VALUE
+Returns 0 if succeeded, or a negative value for error.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_init(3)
+.BR libssh2_agent_disconnect(3)
+

docs/libssh2_agent_disconnect.3

@@ -0,0 +1,20 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_disconnect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_disconnect - close a connection to an ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_disconnect(LIBSSH2_AGENT *agent);
+.SH DESCRIPTION
+Close a connection to an ssh-agent.
+
+.SH RETURN VALUE
+Returns 0 if succeeded, or a negative value for error.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_connect(3)
+.BR libssh2_agent_free(3)

docs/libssh2_agent_free.3

@@ -0,0 +1,20 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_free 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_free - free an ssh-agent handle
+.SH SYNOPSIS
+#include <libssh2.h>
+
+void libssh2_agent_free(LIBSSH2_AGENT *agent);
+.SH DESCRIPTION
+Free an ssh-agent handle.  This function also frees the internal
+collection of public keys.
+.SH RETURN VALUE
+None.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_init(3)
+.BR libssh2_agent_disconnect(3)

docs/libssh2_agent_get_identity.3

@@ -0,0 +1,34 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_get_identity 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_get_identity - get a public key off the collection of public keys managed by ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_get_identity(LIBSSH2_AGENT *agent,
+                               struct libssh2_agent_publickey **store,
+                               struct libssh2_agent_publickey *prev);
+.SH DESCRIPTION
+\fIlibssh2_agent_get_identity(3)\fP allows an application to iterate
+over all public keys in the collection managed by ssh-agent.
+
+\fIstore\fP should point to a pointer that gets filled in to point to the
+public key data.
+
+\fIprev\fP is a pointer to a previous 'struct libssh2_agent_publickey'
+as returned by a previous invoke of this function, or NULL to get the
+first entry in the internal collection.
+.SH RETURN VALUE
+Returns 0 if everything is fine and information about a host was stored in
+the \fIstore\fP struct.
+
+Returns 1 if it reached the end of public keys.
+
+Returns negative values for error
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_list_identities(3)
+.BR libssh2_agent_userauth(3)

docs/libssh2_agent_init.3

@@ -0,0 +1,26 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_init 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_init - init an ssh-agent handle
+.SH SYNOPSIS
+#include <libssh2.h>
+
+LIBSSH2_AGENT *libssh2_agent_init(LIBSSH2_SESSION *session);
+.SH DESCRIPTION
+Init an ssh-agent handle. Returns the handle to an internal
+representation of an ssh-agent connection.  After the successful
+initialization, an application can call \fBlibssh2_agent_connect(3)\fP
+to connect to a running ssh-agent.
+
+Call \fBlibssh2_agent_free(3)\fP to free the handle again after you're
+doing using it.
+.SH RETURN VALUE
+Returns a handle pointer or NULL if something went wrong. The returned handle
+is used as input to all other ssh-agent related functions libssh2 provides.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_connect(3)
+.BR libssh2_agent_free(3)

docs/libssh2_agent_list_identities.3

@@ -0,0 +1,24 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_list_identities 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_list_identities - request an ssh-agent to list of public keys.
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_list_identities(LIBSSH2_AGENT *agent);
+.SH DESCRIPTION
+Request an ssh-agent to list of public keys, and stores them in the
+internal collection of the handle.  Call
+\fIlibssh2_agent_get_identity(3)\fP to get a public key off the
+collection.
+
+.SH RETURN VALUE
+Returns 0 if succeeded, or a negative value for error.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_connect(3)
+.BR libssh2_agent_get_identity(3)
+

docs/libssh2_agent_userauth.3

@@ -0,0 +1,29 @@
+.\"
+.\" Copyright (c) 2009 by Daiki Ueno
+.\"
+.TH libssh2_agent_userauth 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_agent_userauth - authenticate a session with a public key, with the help of ssh-agent
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_agent_userauth(LIBSSH2_AGENT *agent,
+                           const char *username,
+                           struct libssh2_agent_publickey *identity);
+.SH DESCRIPTION
+\fIagent\fP - ssh-agent handle as returned by 
+.BR libssh2_agent_init(3)
+
+\fIusername\fP - Remote user name to authenticate as.
+
+\fIidentity\fP - Public key to authenticate with, as returned by 
+.BR libssh2_agent_get_identity(3)
+
+Attempt public key authentication with the help of ssh-agent.
+.SH RETURN VALUE
+Returns 0 if succeeded, or a negative value for error.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_agent_init(3)
+.BR libssh2_agent_get_identity(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_direct_tcpip_ex.3

@@ -13,16 +13,16 @@ LIBSSH2_CHANNEL *
 libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session, const char *host, int port);
 
 .SH DESCRIPTION
-/fIsession/fP - Session instance as returned by 
+\fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
 
-/fIhost/fP - Third party host to connect to using the SSH host as a proxy.
+\fIhost\fP - Third party host to connect to using the SSH host as a proxy.
 
-/fIport/fP - Port on third party host to connect to.
+\fIport\fP - Port on third party host to connect to.
 
-/fIshost/fP - Host to tell the SSH server the connection originated on.
+\fIshost\fP - Host to tell the SSH server the connection originated on.
 
-/fIsport/fP - Port to tell the SSH server the connection originated from.
+\fIsport\fP - Port to tell the SSH server the connection originated from.
 
 Tunnel a TCP/IP connection through the SSH transport via the remote host to 
 a third party. Communication from the client to the SSH server remains 

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

@@ -10,7 +10,7 @@ int
 libssh2_channel_forward_cancel(LIBSSH2_LISTENER *listener);
 
 .SH DESCRIPTION
-/fIlistener/fP - Forwarding listener instance as returned by 
+\fIlistener\fP - Forwarding listener instance as returned by 
 .BR libssh2_channel_forward_listen_ex(3)
 
 Instruct the remote host to stop listening for new connections on a previously requested host/port.

docs/libssh2_channel_forward_listen.3

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

docs/libssh2_channel_ignore_extended_data.3

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

docs/libssh2_channel_open_session.3

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

docs/libssh2_channel_read.3

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

docs/libssh2_channel_read_ex.3

@@ -35,6 +35,9 @@ macros.
 Actual number of bytes read 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.
+
+Note that a return value of zero (0) can in fact be a legitimate value and
+only signals that no payload data was read. It is not an error.
 .SH ERRORS
 \fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket.
 

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_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

@@ -0,0 +1,66 @@
+
+.\" 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,
+                          char *host, char *salt,
+                          char *key, size_t keylen,
+                          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.
+
+\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.
+
+\fIsalt\P 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
+
+\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, 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

@@ -0,0 +1,58 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_check 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_check - check a host+key against the list of known hosts
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_check(LIBSSH2_KNOWNHOSTS *hosts,
+                            const char *host,
+                            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.
+
+\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
+.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_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_del.3

@@ -0,0 +1,26 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_del 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_del - delete a known host entry
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_del(LIBSSH2_KNOWNHOSTS *hosts,
+                          struct libssh2_knownhost *entry);
+.SH DESCRIPTION
+Delete a known host entry from the collection of known hosts.
+
+\fIentry\fP is a pointer to a struct that you can extract with
+\fIlibssh2_knownhost_check(3)\fP or \fIlibssh2_knownhost_get(3)\fP.
+.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
+.SH SEE ALSO
+.BR libssh2_knownhost_init(3)
+.BR libssh2_knownhost_free(3)
+.BR libssh2_knownhost_add(3)
+.BR libssh2_knownhost_check(3)

docs/libssh2_knownhost_free.3

@@ -0,0 +1,20 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_free 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_free - free a collection of known hosts
+.SH SYNOPSIS
+#include <libssh2.h>
+
+void libssh2_knownhost_free(LIBSSH2_KNOWNHOSTS *hosts);
+.SH DESCRIPTION
+Free a collection of known hosts.
+.SH RETURN VALUE
+None.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_knownhost_init(3)
+.BR libssh2_knownhost_add(3)
+.BR libssh2_knownhost_check(3)

docs/libssh2_knownhost_get.3

@@ -0,0 +1,35 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_get 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_get - get a known host off the collection of known hosts
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_get(LIBSSH2_KNOWNHOSTS *hosts,
+                          struct libssh2_knownhost **store,
+                          struct libssh2_knownhost *prev):
+.SH DESCRIPTION
+\fIlibssh2_knownhost_get(3)\fP allows an application to iterate over all known
+hosts in the collection.
+
+\fIstore\fP should point to a pointer that gets filled in to point to the
+known host data.
+
+\fIprev\fP is a pointer to a previous 'struct libssh2_knownhost' as returned
+by a previous invoke of this function, or NULL to get the first entry in the
+internal collection.
+.SH RETURN VALUE
+Returns 0 if everything is fine and information about a host was stored in
+the \fIstore\fP struct.
+
+Returns 1 if it reached the end of hosts.
+
+Returns negative values for error
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_knownhost_readfile(3)
+.BR libssh2_knownhost_writefile(3)
+.BR libssh2_knownhost_add(3)

docs/libssh2_knownhost_init.3

@@ -0,0 +1,25 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_init 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_init - init a collection of known hosts
+.SH SYNOPSIS
+#include <libssh2.h>
+
+LIBSSH2_KNOWNHOSTS *libssh2_knownhost_init(LIBSSH2_SESSION *session);
+.SH DESCRIPTION
+Init a collection of known hosts for this session. Returns the handle to an
+internal representation of a known host collection.
+
+Call \fBlibssh2_knownhost_free(3)\fP to free the collection again after you're
+doing using it.
+.SH RETURN VALUE
+Returns a handle pointer or NULL if something went wrong. The returned handle
+is used as input to all other known host related functions libssh2 provides.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_knownhost_free(3)
+.BR libssh2_knownhost_add(3)
+.BR libssh2_knownhost_check(3)

docs/libssh2_knownhost_readfile.3

@@ -0,0 +1,29 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_readfile 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_readfile - parse a file of known hosts
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_readfile(LIBSSH2_KNOWNHOSTS *hosts,
+                               const char *filename, int type);
+.SH DESCRIPTION
+Reads a collection of known hosts from a specified file and adds them to the
+collection of known hosts.
+
+\fIfilename\fP specifies which file to read
+
+\fItype\fP specifies what file type it is, and
+\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.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_knownhost_init(3)
+.BR libssh2_knownhost_free(3)
+.BR libssh2_knownhost_check(3)

docs/libssh2_knownhost_readline.3

@@ -0,0 +1,30 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_readline 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_readline - read a known host line
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_readline(LIBSSH2_KNOWNHOSTS *hosts,
+                               const char *line, size_t len, int type):
+.SH DESCRIPTION
+Tell libssh2 to read a buffer as it if is a line from a known hosts file.
+
+\fIline\fP points to the start of the line
+
+\fIlen\fP is the length of the line in bytes
+
+\fItype\fP specifies what file type it is, and
+\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.
+.SH AVAILABILITY
+Added in libssh2 1.2
+.SH SEE ALSO
+.BR libssh2_knownhost_get(3)
+.BR libssh2_knownhost_writeline(3)
+.BR libssh2_knownhost_readfile(3)

docs/libssh2_knownhost_writefile.3

@@ -0,0 +1,29 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_writefile 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_writefile - write a collection of known hosts to a file
+.SH SYNOPSIS
+#include <libssh2.h>
+
+int libssh2_knownhost_writefile(LIBSSH2_KNOWNHOSTS *hosts,
+                                const char *filename, int type);
+.SH DESCRIPTION
+Writes all the known hosts to the specified file using the specified file
+format.
+
+\fIfilename\fP specifies what filename to create
+
+\fItype\fP specifies what file type it is, and
+\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported
+format.
+.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
+.SH SEE ALSO
+.BR libssh2_knownhost_readfile(3)
+.BR libssh2_knownhost_add(3)
+

docs/libssh2_knownhost_writeline.3

@@ -0,0 +1,46 @@
+.\"
+.\" Copyright (c) 2009 by Daniel Stenberg
+.\"
+.TH libssh2_knownhost_writeline 3 "28 May 2009" "libssh2 1.2" "libssh2 manual"
+.SH NAME
+libssh2_knownhost_writeline - convert a known host to a line for storage
+.SH SYNOPSIS
+#include <libssh2.h>
+
+libssh2_knownhost_writeline(LIBSSH2_KNOWNHOSTS *hosts,
+                            struct libssh2_knownhost *known,
+                            char *buffer, size_t buflen,
+                            size_t *outlen,
+                            int type);
+.SH DESCRIPTION
+Converts a single known host to a single line of output for storage, using
+the 'type' output format.
+
+\fIknown\fP identifies which particular known host
+
+\fIbuffer\fP points to an allocated buffer
+
+\fIbuflen\fP is the size of the \fIbuffer\fP. See RETURN VALUE about the size.
+
+\fIoutlen\fP must be a pointer to a size_t variable that will get the output
+length of the stored data chunk. The number does not included the trailing
+zero!
+
+\fItype\fP specifies what file type it is, and
+\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported
+format.
+.SH RETURN VALUE
+Returns a regular libssh2 error code, where negative values are error codes
+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 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
+.SH SEE ALSO
+.BR libssh2_knownhost_get(3)
+.BR libssh2_knownhost_readline(3)
+.BR libssh2_knownhost_writefile(3)
+

docs/libssh2_poll.3

@@ -1,4 +1,4 @@
-.\" $Id: libssh2_poll.3,v 1.3 2007/06/13 12:51:11 jehousley Exp $
+.\" $Id: libssh2_poll.3,v 1.4 2009/04/14 21:38:36 bagder Exp $
 .\"
 .TH libssh2_poll 3 "14 Dec 2006" "libssh2 0.15" "libssh2 manual"
 .SH NAME
@@ -8,6 +8,10 @@ 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. 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
 \fIpoll(2)\fP however the structure of fds is somewhat more complex in order

docs/libssh2_poll_channel_read.3

@@ -1,4 +1,4 @@
-.\" $Id: libssh2_poll_channel_read.3,v 1.2 2007/06/13 12:51:11 jehousley Exp $
+.\" $Id: libssh2_poll_channel_read.3,v 1.3 2009/04/14 21:38:36 bagder Exp $
 .\"
 .TH libssh2_poll_channel_read 3 "14 Dec 2006" "libssh2 0.15" "libssh2 manual"
 .SH NAME
@@ -8,6 +8,8 @@ libssh2_poll_channel_read - check if data is available
 
 int libssh2_poll_channel_read(LIBSSH2_CHANNEL *channel, int extended);
 .SH DESCRIPTION
+This function is deprecated. Do note use.
+
 \fIlibssh2_poll_channel_read(3)\fP checks to see if data is available in the
 \fIchannel\fP's read buffer. No attempt is made with this method to see if
 packets are available to be processed. For full polling support, use

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

@@ -13,7 +13,8 @@ libssh2_scp_recv(LIBSSH2_SESSION *session, const char *path, struct stat *sb);
 \fIsession\fP - Session instance as returned by 
 .BR libssh2_session_init_ex(3)
 
-\fIpath\fP - Full path and filename of file to transfer
+\fIpath\fP - Full path and filename of file to transfer. That is the remote
+file name.
 
 \fIsb\fP - Populated with remote file's size, mode, mtime, and atime
 

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,15 +4,21 @@
 .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)
 
-\fIpath\fP - Full path and filename of file to transfer
+\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
 
@@ -37,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,19 @@ libssh2_session_callback_set(LIBSSH2_SESSION *session, int cbtype, void *callbac
 
 \fIcallback\fP - Pointer to custom callback function. The prototype for 
 this function must match the associated callback declaration macro.
-
-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
+.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_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_hostkey.3

@@ -0,0 +1,23 @@
+.\" $Id: session_hostkey.3,v 1.4 2007/06/13 16:41:33 jehousley Exp $
+.\"
+.TH libssh2_session_hostkey 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual"
+.SH NAME
+libssh2_session_hostkey - get the remote key
+.SH SYNOPSIS
+#include <libssh2.h>
+
+const char *libssh2_session_hostkey(LIBSSH2_SESSION *session,
+                                    size_t *len, int *type);
+.SH DESCRIPTION
+Returns a pointer to the current host key, the value \fIlen\fP points to will
+get the length of the key.
+
+The value \fItype\fP points to the type of hostkey which is one of:
+LIBSSH2_HOSTKEY_TYPE_RSA, LIBSSH2_HOSTKEY_TYPE_DSS, or
+LIBSSH2_HOSTKEY_TYPE_UNKNOWN.
+
+.SH RETURN VALUE
+A pointer, or NULL if something went wrong.
+.SH SEE ALSO
+.BR libssh2_knownhost_check(3)
+.BR libssh2_knownhost_add(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_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_close_handle.3

@@ -20,14 +20,10 @@ libssh2_sftp_closedir(LIBSSH2_SFTP_HANDLE *handle);
 \fIhandle\fP - SFTP File Handle as returned by \fBlibssh2_sftp_open_ex(3)\fP
 or \fBlibssh2_sftp_opendir(3)\fP (which is a macro).
 
-Close an active LIBSSH2_SFTP_HANDLE. Because files and directories 
-share the same underlying storage mechanism these methods may be used 
-interchangably. It is recommended that 
-.BR libssh2_sftp_closedir()
-be used for files and that 
-.BR libssh2_sftp_closedir()
-be used for directories so that future changes in the library may cause
-minimal disruption. Both are macros for \fBlibssh2_sftp_close_handle\fP.
+Close an active LIBSSH2_SFTP_HANDLE. Because files and directories share the
+same underlying storage mechanism these methods may be used
+interchangably. \fBlibssh2_sftp_close(3)\fP and \fBlibssh2_sftp_closedir(3)\fP
+are macros for \fBlibssh2_sftp_close_handle(3)\fP.
 
 .SH RETURN VALUE
 Return 0 on success or negative on failure.  It returns

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

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

docs/libssh2_sftp_readdir.3

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

docs/libssh2_sftp_readdir_ex.3

@@ -4,16 +4,22 @@
 .SH NAME
 libssh2_sftp_readdir_ex - read directory data from an SFTP handle
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
 int 
-libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, char *longentry, size_t longentry_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs);
-
-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);
 
+#define libssh2_sftp_readdir(h, b, bl, a)      \\
+    libssh2_sftp_readdir_ex((h), (b), (bl), NULL, 0, (a))
 .SH DESCRIPTION
+Reads a block of data from a LIBSSH2_SFTP_HANDLE and returns file entry
+information for the next entry, if any.
+
 \fIhandle\fP - is the SFTP File Handle as returned by 
 .BR libssh2_sftp_open_ex(3)
 
@@ -25,25 +31,22 @@ filename is longer than the space provided by buffer_maxlen it will be
 truncated to fit.
 
 \fIlongentry\fP - is a pointer to a pre-allocated buffer of at least
-\fIlongentry_maxlen\fP bytes to read data into.
+\fIlongentry_maxlen\fP bytes to read data into. The format of the `longname'
+field is unspecified by SFTP protocol. It MUST be suitable for use in the
+output of a directory listing command (in fact, the recommended operation for
+a directory listing command is to simply display this data).
 
-\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length 
-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 ERRORS
 \fILIBSSH2_ERROR_ALLOC\fP -  An internal memory allocation call failed.
 

docs/libssh2_sftp_readlink.3

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

docs/libssh2_sftp_realpath.3

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

docs/libssh2_sftp_rename.3

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

docs/libssh2_sftp_rewind.3

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

docs/libssh2_sftp_rmdir.3

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

docs/libssh2_sftp_rmdir_ex.3

@@ -4,30 +4,26 @@
 .SH NAME
 libssh2_sftp_rmdir_ex - remove an SFTP directory
 .SH SYNOPSIS
+.nf
 #include <libssh2.h>
 #include <libssh2_sftp.h>
 
-int 
-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_setstat.3

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

docs/libssh2_sftp_stat.3

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

docs/libssh2_sftp_stat_ex.3

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

docs/libssh2_sftp_statvfs.3

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