libssh2_sftp_seek64: new man page

Split off libssh2_sftp_seek64 from the libssh2_sftp_seek man page, and
mentioned that we consider the latter deprecated. Also added a mention
about the dangers of doing seek during writing or reading.

docs/Makefile.am

@@ -135,6 +135,7 @@ dist_man_MANS = \
 	libssh2_sftp_rmdir.3 \
 	libssh2_sftp_rmdir_ex.3 \
 	libssh2_sftp_seek.3 \
+	libssh2_sftp_seek64.3 \
 	libssh2_sftp_setstat.3 \
 	libssh2_sftp_shutdown.3 \
 	libssh2_sftp_stat.3 \

docs/libssh2_sftp_seek.3

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

docs/libssh2_sftp_seek64.3

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