d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
227d42bebc
freebsd-dev/lib/libftpio/ftpio.3

213 lines
6.4 KiB
Groff
Raw Normal View History

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*).
1996-06-17 12:26:06 +00:00
.\" 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.
.\"
.Sh AUTHOR -> .Sh AUTHORS. Use .An/.Aq
1998-03-19 07:34:22 +00:00
.\" $Id: ftpio.3,v 1.16 1998/02/10 07:01:51 jkh Exp $
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*).
1996-06-17 12:26:06 +00:00
.\"
.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 ,
Implement an ftpVerbose() hook. Submitted by: jmz
1996-07-04 00:55:21 +00:00
.Nm ftpVerbose ,
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*).
1996-06-17 12:26:06 +00:00
.Nm ftpGetURL ,
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
.Nm ftpPutURL
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*).
1996-06-17 12:26:06 +00:00
.Nd FTPIO User library
.Sh SYNOPSIS
.Fd #include <ftpio.h>
.Ft FILE *
For functions ftpGetURL, ftpPutURL, ftpLogin it was impossible to know FTP error return code because 1) They return NULL, it means that ftpErrno can't be used because it takes file pointer 2) They don't have FILE-type argument as f.e. ftpGet/ftpPut to use it for ftpErrno instead. For that functions I add yet one int* type argument to store FTP error return code. It is impossible to add some global variable for that reason, because user can have multiply FTP connections opened at the same time. So, interface changed, major number bumped. Userland changes will follows. Minor bugfixes, the code: Forget to close file in few places, when failure occurse Forget to NULL cached host name, multiply free is possible
1996-11-14 06:59:41 +00:00
.Fn ftpLogin "char *host" "char *user" "char *passwd" "int ftp_port" "int verbose" "int *retcode"
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*).
1996-06-17 12:26:06 +00:00
.Ft int
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
.Fn ftpChdir "FILE *stream, char *dirname"
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*).
1996-06-17 12:26:06 +00:00
.Ft int
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
.Fn ftpErrno "FILE *stream"
Add an ftpErrString() function for returning human readable failure codes. Submitted-By: Archie Cobbs <archie@whistle.com>
1996-08-21 01:12:11 +00:00
.Ft const char *
.Fn ftpErrString "int errno"
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*).
1996-06-17 12:26:06 +00:00
.Ft time_t
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
.Fn ftpGetModtime "FILE *stream, char *file"
Fixed #include and/or prototype bugs in synopsis.
1997-04-19 15:57:20 +00:00
.Ft off_t
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
.Fn ftpGetSize "FILE *stream, char *file"
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*).
1996-06-17 12:26:06 +00:00
.Ft FILE *
Fixed #include and/or prototype bugs in synopsis.
1997-04-19 15:57:20 +00:00
.Fn ftpGet "FILE *stream, char *file, off_t *seekto"
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*).
1996-06-17 12:26:06 +00:00
.Ft FILE *
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
.Fn ftpPut "FILE *stream, char *file"
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*).
1996-06-17 12:26:06 +00:00
.Ft int
Adjust docs to match reality.
1996-06-24 02:22:15 +00:00
.Fn ftpAscii "FILE *stream"
.Ft int
.Fn ftpBinary "FILE *stream"
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*).
1996-06-17 12:26:06 +00:00
.Ft int
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
.Fn ftpPassive "FILE *stream, int status"
Implement an ftpVerbose() hook. Submitted by: jmz
1996-07-04 00:55:21 +00:00
.Ft void
.Fn ftpVerbose "FILE *stream, int status"
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*).
1996-06-17 12:26:06 +00:00
.Ft FILE *
For functions ftpGetURL, ftpPutURL, ftpLogin it was impossible to know FTP error return code because 1) They return NULL, it means that ftpErrno can't be used because it takes file pointer 2) They don't have FILE-type argument as f.e. ftpGet/ftpPut to use it for ftpErrno instead. For that functions I add yet one int* type argument to store FTP error return code. It is impossible to add some global variable for that reason, because user can have multiply FTP connections opened at the same time. So, interface changed, major number bumped. Userland changes will follows. Minor bugfixes, the code: Forget to close file in few places, when failure occurse Forget to NULL cached host name, multiply free is possible
1996-11-14 06:59:41 +00:00
.Fn ftpGetURL "char *url, char *user, char *passwd, int *retcode"
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*).
1996-06-17 12:26:06 +00:00
.Ft FILE *
For functions ftpGetURL, ftpPutURL, ftpLogin it was impossible to know FTP error return code because 1) They return NULL, it means that ftpErrno can't be used because it takes file pointer 2) They don't have FILE-type argument as f.e. ftpGet/ftpPut to use it for ftpErrno instead. For that functions I add yet one int* type argument to store FTP error return code. It is impossible to add some global variable for that reason, because user can have multiply FTP connections opened at the same time. So, interface changed, major number bumped. Userland changes will follows. Minor bugfixes, the code: Forget to close file in few places, when failure occurse Forget to NULL cached host name, multiply free is possible
1996-11-14 06:59:41 +00:00
.Fn ftpPutURL "char *url, char *user, char *passwd, int *retcode"
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*).
1996-06-17 12:26:06 +00:00
.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 ,
1. Add verbose flag to ftp_login() 2. Remove pkg_* support - tcl7.5's channel interface has rendered this almost entirely unsupportable (at least in the way it currently stands). Submitted-By: jmz & jkh
1996-08-03 11:58:54 +00:00
.Fa passwd,
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*).
1996-06-17 12:26:06 +00:00
.Fa ftp_port
1. Add verbose flag to ftp_login() 2. Remove pkg_* support - tcl7.5's channel interface has rendered this almost entirely unsupportable (at least in the way it currently stands). Submitted-By: jmz & jkh
1996-08-03 11:58:54 +00:00
(if passed as 0,
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*).
1996-06-17 12:26:06 +00:00
.Fa ftp_port
1. Add verbose flag to ftp_login() 2. Remove pkg_* support - tcl7.5's channel interface has rendered this almost entirely unsupportable (at least in the way it currently stands). Submitted-By: jmz & jkh
1996-08-03 11:58:54 +00:00
defaults to the standard ftp port of 21) and
.Fa verbose
fields. If it is successful, a
Rethink and reimpliment the way RESTARTS are handled. The method I inheirited from jmz was a hopeless kludge (sorry Jean-Marc :) and handled the problem in the wrong way. ftpRestart() has now gone away and ftpGet() has grown a new parameter.
1996-06-17 15:28:08 +00:00
standard stream descriptor is returned which should be passed to
subsequent FTP operations. On failure, NULL is returned and
For functions ftpGetURL, ftpPutURL, ftpLogin it was impossible to know FTP error return code because 1) They return NULL, it means that ftpErrno can't be used because it takes file pointer 2) They don't have FILE-type argument as f.e. ftpGet/ftpPut to use it for ftpErrno instead. For that functions I add yet one int* type argument to store FTP error return code. It is impossible to add some global variable for that reason, because user can have multiply FTP connections opened at the same time. So, interface changed, major number bumped. Userland changes will follows. Minor bugfixes, the code: Forget to close file in few places, when failure occurse Forget to NULL cached host name, multiply free is possible
1996-11-14 06:59:41 +00:00
.Fa retcode
will have the error code returned by the foreign server.
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*).
1996-06-17 12:26:06 +00:00
.Pp
.Fn ftpChdir
delete doubled words, e.g.: "the the" -> "the"
1996-10-05 22:27:30 +00:00
attempts to issue a server CD command to the directory named in
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*).
1996-06-17 12:26:06 +00:00
.Fa dir.
Stamp out a potential memory leak. Make ftpChdir return the server status again - it was more convenient.
1996-06-17 20:36:57 +00:00
On success, zero is returned. On failure, the error code from the server.
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*).
1996-06-17 12:26:06 +00:00
.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).
Add an ftpErrString() function for returning human readable failure codes. Submitted-By: Archie Cobbs <archie@whistle.com>
1996-08-21 01:12:11 +00:00
.Fn ftpErrString
returns a human readable version of the supplied server failure code.
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*).
1996-06-17 12:26:06 +00:00
.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 )
Make certain small things more consistent with the other stdio man pages.
1996-06-20 15:49:54 +00:00
and returns a new FILE* pointer for the file or NULL on failure. If
Rethink and reimpliment the way RESTARTS are handled. The method I inheirited from jmz was a hopeless kludge (sorry Jean-Marc :) and handled the problem in the wrong way. ftpRestart() has now gone away and ftpGet() has grown a new parameter.
1996-06-17 15:28:08 +00:00
.Fa seekto
is non-NULL, the contents of the integer it points to will be used
as a restart point for the file, that is to say that the stream
returned will point
.Fa *seekto
bytes into the file gotten (this is handy for restarting failed
Implement a change suggested by Archie Cobbs - the seekto argument should be zero'd only if the operation *fails*, indicating that the file starting offset is effectively zero. This makes more sense.
1996-08-21 01:23:33 +00:00
transfers efficiently). If the seek operation fails, the value
Rethink and reimpliment the way RESTARTS are handled. The method I inheirited from jmz was a hopeless kludge (sorry Jean-Marc :) and handled the problem in the wrong way. ftpRestart() has now gone away and ftpGet() has grown a new parameter.
1996-06-17 15:28:08 +00:00
of
.Fa *seekto
will be zero'd.
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*).
1996-06-17 12:26:06 +00:00
.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
Adjust docs to match reality.
1996-06-24 02:22:15 +00:00
.Fn ftpAscii
sets ascii mode for the current server connection named by
.Fa stream .
.Pp
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*).
1996-06-17 12:26:06 +00:00
.Fn ftpBinary
sets binary mode for the current server connection named by
Adjust docs to match reality.
1996-06-24 02:22:15 +00:00
.Fa stream .
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*).
1996-06-17 12:26:06 +00:00
.Pp
.Fn ftpPassive
sets passive mode (for firewalls) for the current server connection named by
.Fa stream
to boolean value
.Fa status .
.Pp
Implement an ftpVerbose() hook. Submitted by: jmz
1996-07-04 00:55:21 +00:00
.Fn ftpVerbose
sets the verbosity mode for the current server connection named by
.Fa stream
to boolean value
.Fa status .
.Pp
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*).
1996-06-17 12:26:06 +00:00
.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
Rethink and reimpliment the way RESTARTS are handled. The method I inheirited from jmz was a hopeless kludge (sorry Jean-Marc :) and handled the problem in the wrong way. ftpRestart() has now gone away and ftpGet() has grown a new parameter.
1996-06-17 15:28:08 +00:00
operations except that no server 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.
environment variables missing from ftpio(3) man page PR: 5691 Submitted by: archie@whistle.com
1998-02-10 07:01:51 +00:00
.Sh ENVIRONMENT
.Bl -tag -width FTP_PASSIVE_MODE -offset 123
.It Ev FTP_TIMEOUT
Maximum time, in seconds, to wait for a response
from the peer before aborting an
.Tn FTP
connection.
.It Ev FTP_PASSIVE_MODE
Force the use of passive mode
.Tn FTP .
.El
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*).
1996-06-17 12:26:06 +00:00
.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
Add an ftpErrString() function for returning human readable failure codes. Submitted-By: Archie Cobbs <archie@whistle.com>
1996-08-21 01:12:11 +00:00
extension of stdio by Jordan Hubbard. Also incorporates some ideas and
extensions from Jean-Marc Zucconi.
Whoops, give the authors all proper credit.
1996-06-17 12:28:50 +00:00
.Sh AUTHORS
.Sh AUTHOR -> .Sh AUTHORS. Use .An/.Aq
1998-03-19 07:34:22 +00:00
.An Jordan Hubbard ,
.An Poul-Henning Kamp
and
.An Jean-Marc Zucconi
Reference in New Issue Copy Permalink