From 33e2bc8785cfc61a18af072305a53fad9879e1c4 Mon Sep 17 00:00:00 2001
From: Daniel Stenberg <daniel@haxx.se>
Date: Sun, 13 Jun 2010 17:00:14 +0200
Subject: [PATCH] libssh2_sftp_write: document buffer size and changed some
 ordering

---
 docs/libssh2_sftp_write.3 | 20 +++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

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