diff options
author | jkh <jkh@FreeBSD.org> | 1996-06-17 12:26:06 +0000 |
---|---|---|
committer | jkh <jkh@FreeBSD.org> | 1996-06-17 12:26:06 +0000 |
commit | 880dd9d3c6fae1c0252b9a7ad8b0a3acd985acb6 (patch) | |
tree | 8f5d310b7f8f5268b7d1524b01546840e5a9b6f1 /lib/libftpio/ftpio.3 | |
parent | d296466eaa9e2d412ac79232f8f0308f0488b67d (diff) | |
download | FreeBSD-src-880dd9d3c6fae1c0252b9a7ad8b0a3acd985acb6.zip FreeBSD-src-880dd9d3c6fae1c0252b9a7ad8b0a3acd985acb6.tar.gz |
Bring in a new library `libftpio', so named to avoid clashes with older
packages and also sort of give the (correct) impression that this basically
sits on top of stdio and deals with stream pointers (FILE*).
Diffstat (limited to 'lib/libftpio/ftpio.3')
-rw-r--r-- | lib/libftpio/ftpio.3 | 185 |
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. |