1 files changed, 185 insertions, 0 deletions
diff --git a/lib/libftpio/ftpio.3 b/lib/libftpio/ftpio.3
new file mode 100644
index 0000000..a53532e
--- /dev/null
+++ b/lib/libftpio/ftpio.3
@@ -0,0 +1,185 @@
+.\" Copyright (c) 1996 Jordan Hubbard (jkh@FreeBSD.org)
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY JORDAN HUBBARD ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\"
+.Dd June 17, 1996
+.Dt ftpio 3
+.Os
+.Sh NAME
+.Nm ftpLogin ,
+.Nm ftpChdir ,
+.Nm ftpErrno ,
+.Nm ftpGetModtime ,
+.Nm ftpGetSize ,
+.Nm ftpGet ,
+.Nm ftpPut ,
+.Nm ftpBinary ,
+.Nm ftpPassive ,
+.Nm ftpRestart ,
+.Nm ftpGetURL ,
+.Nm ftpPutURL ,
+.Nd FTPIO User library
+.Sh SYNOPSIS
+.Fd #include <ftpio.h>
+.Ft FILE *
+.Fn ftpLogin "char *host, char *user, char *passwd, int ftp_port"
+.Ft int
+.Fn ftpChdir "FILE *fp, char *dirname"
+.Ft int
+.Fn ftpErrno "FILE *fp"
+.Ft time_t
+.Fn ftpGetModtime "FILE *fp, char *file"
+.Ft size_t
+.Fn ftpGetSize "FILE *fp, char *file"
+.Ft FILE *
+.Fn ftpGet "FILE *fp, char *file"
+.Ft FILE *
+.Fn ftpPut "FILE *fp, char *file"
+.Ft int
+.Fn ftpBinary "FILE *fp, int status"
+.Ft int
+.Fn ftpPassive "FILE *fp, int status"
+.Ft int
+.Fn ftpRestart "FILE *fp, int where"
+.Ft FILE *
+.Fn ftpGetURL "char *url, char *user, char *passwd"
+.Ft FILE *
+.Fn ftpPutURL "char *url, char *user, char *passwd"
+
+.Sh DESCRIPTION
+These functions implement a high-level library for managing FTP connections.
+.Pp
+.Fn ftpLogin
+attempts to log in using the supplied
+.Fa user ,
+.Fa passwd
+and
+.Fa ftp_port
+fields (if passed as 0,
+.Fa ftp_port
+defaults to the standard ftp port of 21).  If it is successful, a
+standard
+.Fa stream
+descriptor is returned which should be passed to subsequent FTP
+operations. On failure, NULL is returned and
+.Fn ftpErrno
+will return the error code returned by the foreign server.
+.Pp
+.Fn ftpChdir
+attempts to issue a server CD command to the the directory named in
+.Fa dir.
+On success, zero is returned.  On failure, -1.
+.Pp
+.Fn ftpErrno
+returns the server failure code for the last operation (useful for seeing
+more about what happened if you're familiar with FTP error codes).
+.Pp
+.Fn ftpGet
+attempts to retreive the file named by the
+.Fa file
+argument (which is assumed to be relative to the FTP server's current directory,
+see
+.Fn ftpChdir )
+and returns a new
+.Fa stream
+pointer for the file or NULL on failure.
+.Pp
+.Fn ftpGetModtime
+returns the last modification time of the file named by the
+.Fa file
+argument.  If the file could not be opened or stat'd, 0 is returned.
+.Pp
+.Fn ftpGetSize
+returns the size in bytes of the file named by the
+.Fa file
+argument.  If the file could not be opened or stat'd, -1 is returned.
+.Pp
+.Fn ftpPut
+attempts to create a new file named by the
+.Fa file
+argument (which is assumed to be relative to the FTP server's current directory,
+see
+.Fn ftpChdir )
+and returns a new
+.Fa stream
+pointer for the file or NULL on failure.
+.Pp
+.Fn ftpBinary
+sets binary mode for the current server connection named by
+.Fa stream
+to boolean value
+.Fa status .
+.Pp
+.Fn ftpPassive
+sets passive mode (for firewalls) for the current server connection named by
+.Fa stream
+to boolean value
+.Fa status .
+.Pp
+.Fn ftpRestart
+requests that if the remote server supports restart operations, the offset
+in bytes specified in
+.Fa where
+should be used in the next file get operation to resume transferring from
+that location.  This is handy for restarting long get operations which have
+aborted in the middle without re-transferring wasted bytes.  Returns the
+old seek value, if any.
+.Pp
+.Fn ftpGetURL
+attempts to retreive the file named by the supplied
+.Fa URL
+and can be considered equivalent to the combined
+.Fn ftpLogin ,
+.Fn ftpChdir
+and
+.Fn ftpGet
+operations except that no server
+.Fa stream
+is ever returned - the connection to the server closes when
+the file has been completely read.  Use the lower-level routines
+if multiple gets are required as it will be far more efficient.
+.Pp
+.Fn ftpPutURL
+attempts to create the file named by the supplied
+.Fa URL
+and can be considered equivalent to the combined
+.Fn ftpLogin ,
+.Fn ftpChdir
+and
+.Fn ftpPut
+operations except that no server
+.Fa stream
+is ever returned - the connection to the server closes when
+the file has been completely written.  Use the lower-level routines
+if multiple puts are required as it will be far more efficient.
+.Sh BUGS
+I'm sure you can get this thing's internal state machine confused if
+you really work at it, but so far it's proven itself pretty robust in
+all my tests.
+.Sh HISTORY
+Started life as Poul-Henning Kamp's ftp driver for the system installation
+utility, later significantly mutated into a more general form as an
+extension of stdio and given a TCL interface (not enabled by default)
+by Jordan Hubbard.  Also incorporates some ideas and extensions from
+Jean-Marc Zucconi.