diff options
Diffstat (limited to 'lib/libftp/doc/libftp.tex')
| -rw-r--r-- | lib/libftp/doc/libftp.tex | 571 |
1 files changed, 571 insertions, 0 deletions
diff --git a/lib/libftp/doc/libftp.tex b/lib/libftp/doc/libftp.tex new file mode 100644 index 0000000..f7d14e8 --- /dev/null +++ b/lib/libftp/doc/libftp.tex @@ -0,0 +1,571 @@ +\documentstyle[cxx,fancyheadings,twoside,epsf,indentfirst]{article} +% Vertical sizes +%\vsize=20cm +%\voffset=-2.3cm +%\topmargin=0cm +%\headheight=0.9cm +%\footskip=1cm +%\footheight=0.9cm +%\textheight=16cm +%\headrulewidth 0.01cm +%\footrulewidth 0.0cm +% 0 sizes +%\hsize=30cm +%\hoffset=-4.3cm +%\hoffset=-2.3cm +%\textwidth=13cm +% Modes +% \special{landscape} +\pagestyle{empty} +\pagestyle{fancyplain} +\newcommand{\tit}[1]{#1} +\rhead[\fancyplain{}{\tit{\leftmark}}]{\fancyplain{}{\tit{\rightmark}}} +\lhead[\fancyplain{}{\tit{\rightmark}}]{\fancyplain{}{\tit{\leftmark}}} +\chead{\hfill} +\lfoot[\fancyplain{}{\tit{\thepage}}]{\fancyplain{}{\hfill}} +\rfoot[\fancyplain{}{\hfill}]{\fancyplain{}{\tit{\thepage}}} +\cfoot{\hfill} +\renewcommand{\sectionmark}[1]{\markboth{#1}{\ }} +\renewcommand{\subsectionmark}[1]{\markright{\ }} +\newcommand{\look}[1]{(Chapter~\ref{#1}, page~\pageref{#1})} +\newcommand{\toindex}[1]{\underline{\bf#1}\index{#1}} +\newcommand{\add}[1]{\symbol{64}} +\newcommand{\ps}[1]{\symbol{37}s} +\newcommand{\twcol}[4]{ +\noindent\parbox[t]{#1\textwidth}{#3} \hfill \parbox[t]{#2\textwidth}{#4\hfill}\\ +} +\newcommand{\tc}[2]{\twcol{0.49}{0.49}{#1}{#2}} +\newcommand{\tcc}[2]{\twcol{0.49}{0.49}{\toindex{#1}}{#2}} +\newcommand{\ttt}[2]{\bigskip + +{\bf#1} + +#2} +\newcommand{\ts}[1]{{\underline{\bf#1}}} +\newcommand{\dl}[2]{\parbox[t]{0.4\textwidth}{#1\hfill}\hfill + \parbox[t]{0.4\textwidth}{#2\hfill}} +\makeindex +\begin{document} +\title{\bf\it{LIBFTP User's guide}} +\author{Oleg Orel} +\date{\today} +\newpage +\maketitle + +\section*{License} + +This library is designed for free, non-commercial software creation. +It is changeable and can be improved. The author would greatly appreciate +any advises, new components and patches of the existing programs. +Commercial usage is also possible with participation of it's author. + +\section*{Introduction} + +The basic orientation of this library is making user's programs which transport +files via TCP/IP network. It contains set of functions, +starting from primitive, such as opening FTP connection to the server, +and finishing by high-level functions, such as functions which retrieve files + via network, making and closing channels to the server. All functions have +prototypes in common header file named \toindex{FtpLibrary.h}, +which must be +available in standard headers directory +\footnote{for example ``/usr/include''}. +Those prototypes almost fully +describe orientation and arguments of all functions, +but common ideology and library components should be mentioned. + +This library is a client and uses standard FTPD from the other side. + +There are problems of errors processing in many operating systems including input/output errors. +The mutual mechanism of value returning of all functions is used in this library. +(EXIT macros, defined in file FtpLibrary.h). This mechanism allows, + after the definition of the error processing functions, write programs, +considering the conditions to be ideal. +Data transfer functions have possibility to preset data stream +expectation timeout. +When the set time expires, previously set function will be called. + +\section{Variables and definitions} + +\subsection{Some definitions in libftp's header file (FtpLibrary.h)} + +\ttt{\toindex{EXIT}}{Main macro for return value from library's functions with +calling handlers if it's need} + +\ttt{\toindex{MAX\_ANSWERS}}{Number of possible answers from FTPD for one request} + +\ttt{\toindex{NFDS}}{Maximum numbers of one-time opened files in your system, if this +value higher than need isn't important. } + +\ttt{\toindex{FTPBUFSIZE}}{Size of block for transmit data via network. By default equivalence \toindex{BUSIZ}} + +\ttt{\toindex{LQUIT}}{Error status of local functions. If you give this status from libftp's function you must use perror for expand diagnostic.} + +\ttt{\toindex{QUIT}}{Error status of network operation. Use perror.} + +\ttt{\toindex{Ctrl}(char)}{Return control character code} + +\ttt{\toindex{FREE}(data)}{Full data by zero} + +\ttt{\toindex{FtpError}(libftp's call)}{Special macro for diagnostic bad conditions} + +\ttt{\toindex{FtpAssert}(libftp's call}{Special macro for automatically return from +this function if status is bad} + +\subsection{Libftp's file specification} + +All files wich must be interprets as local interprets as libftp's files. +Libftp responds to three types of files such + as local file, ftp files and program +pipes. All files can be described as next syntax: + +\ttt{$\mid$string}{interprets string as shell command, which must be + executed with appropriate input/output for file. It depends where + this file is specified.} + +\ttt{hostname:filename}{interprets as file, which must be taken + using ftp protocol with anonymous access} + +\ttt{user@hostname:filename\\ +user/pass@hostname:filename +}{interprets as file accesses via ftp + with password yourname@your\_host.your\_domain} + + +\ttt{*STDIN*, *STDOUT*, *STDERR* or char '-'}{opened standard streams} + +\ttt{anything else}{local file} + + + + +\subsection{The FTP data structure} + +\subsubsection{The members of FTP structure} + +\tc{FILE *\toindex{sock}\footnote{You can use macro FTPCMD(ftp) for extract +this members, using this macro for making your program more compatibility +with next versions of this library}} +{--- command channel to the server;} + +\tc{FILE *\toindex{data}\footnote{You can use macro FTPDATA(ftp) for extract +this members, using this macro for making your program more compatibility +with next versions of this library}} +{--- pointer to data structure, which describes data channel to the server;} + +\tc{int \toindex{errno}}{ --- last returned value. When value is lower than 1, an error occurred;} + +\tc{char \toindex{mode}}{--- type of transfer (valid values: 'A' 'I' ....);} + +\tc{int \toindex{ch}}{--- help variable. Is used to convert ASCII files, user of library for cleaning your problems must forget about this member;} + +\tc{STATUS (*\toindex{error})()}{--- pointer to an error handler. It is called + when status from the server is bad;} +\tc{STATUS (*\toindex{debug})()}{--- pointer to a debug handler. Is called from + functions of sending/receiving messages to/from server;} + +\tc{STATUS (*\toindex{IO})()}{--- pointer to Input/Output error handler. Is called when channel to server is broken.} + +\tc{STATUS (*\toindex{hash})()}{--- pointer to function, which must compute +summary traffic. This function can take one argument which describe + how many bytes +now received of sended to/from server. If the argument is equivalence +to zero, then counter must be reset to zero. But of course user can use +this handler for another properties of herself program, for example for +perriodicaly called anything else for checking other conditions, because +the transfer procedure can take large time from user's program.} + +\tc{int \toindex{seek}}{--- the first byte in file for transfer. This option +can use for retransfer file again after connection is broken} + +\tc{int \toindex{flags}}{--- the option list for transfer procedures such as: +\\ +\begin{itemize} +\item[FTP\_REST] Turn on retransfer file using method of compare size of files +in both sides. +\item[FTP\_NOEXIT] Don't exit from standard error and IO handlers +\end{itemize}} + +\tc{struct timeval \toindex{timeout}}{--- Timeout for send/receive procedures} + +\tc{int \toindex{port}}{--- Port for making command connection} + +\tc{String \toindex{title}}{--- Connection identification} + +\tc{unsigned long \toindex{counter}}{--- counter of already transferred bytes} + +\subsubsection{Initialization of FTP structure} + +This library have two special objects: procedure FtpCreateObject and external +static structure FtpInit. The procedure FtpCreateObject called from +FtpConnect. The structure FtpInit can be modified by hand or by using special +macros such as \toindex{FtpSetFlag}, \toindex{FtpClearFlag}, \toindex{FtpSetPort}, \toindex{FtpSetTimeout}, \toindex{FtpSetErrorHandler}, \toindex{FtpSetDebugHandler}, \toindex{FtpSetIOHandler}, \\ +\toindex{FtpSetHashHandler}. + +\subsection{The \toindex{ARCHIE} data structure} + +The \ts{ARCHIE} data structure using only with function FtpArchie for extract +result of works one. This structure have four members such as: + +\tc{struct tm \toindex{createtime}}{Time of file creation.} + +\tc{unsigned long \toindex{size}}{size of file.} + +\tc{String \toindex{host}}{Host which file is located} + +\tc{String \toindex{file}}{Full path in pointed host of this file} + + +\section{Library's routines} + +\subsection{Connection/Disconnection with server} + +\ttt{STATUS \toindex{FtpConnect}(FTP~**, char~*hostname +\footnote{The name of the host may be symbolic (for example \ts{dxcern.cern.ch}) or numeric (for example \ts{128.141.201.96})} +)} +{ + Makes channel to the server, at the ``hostname'' machine. + Creates FTP data structure and returns pointer to it. If the procedure \toindex{FtplibDebug}(1) +was previously called, \ts{FtpConnect} calls automatically \ts{FtpDebug} for the \ts{debug mode} to be turned on. + \look{debug}. +} +\ttt{STATUS \toindex{FtpUser}(FTP~*, char~*user)} +{ + Sends the name of the user to the server. The connection must be done before it. +} + +\ttt{STATUS \toindex{FtpPassword}(FTP~*, char~*password)} +{ + Sends \ts{password} to the server. The function \ts{FtpUser} must be called before it. +} + +\ttt{STATUS \toindex{FtpAccount}(FTP~*, char~*account)} +{ + Sends a name of the account to the server. The name of the account is not standard + attribute for many systems, so this function is used very seldom. + The function \ts{FtpPassword} must be called before it. +} + +\ttt{ +STATUS \toindex{FtpLogin}(FTP~**, char~*hostname, char~*user, char~*password, char~*account)} +{ + Executes functions \ts{FtpConnect}, \ts{FtpUser}, \ts{FtpPassword}, + \ts{FtpAccount} (if necessary) consistently. If the name of the account is absent, + replaces it with the \ts{NULL} value. +} + +\ttt{STATUS \toindex{FtpBye}(FTP~*)} +{ Finishes work with the server and closes all channels. +\footnote{You can see from the description of connect/disconnect functions, that you can create +more than one connection to servers simultaneously.} +} + +\ttt{STATUS \toindex{FtpQuickBye}(FTP~*)} +{ Fast close data and command connection to server without delays for waiting +server's confirmation and destroying the FTP object. +} + +\ttt{STATUS \toindex{FtpAbort}(FTP~*)} +{ Abort last command passed to server} + + +\subsection{The debugging} \label{debug} + +There is a possibility to predefine few functions, +such as:~\footnote{If the \ts{NULL} value is transferred as a parameter \ts{``function''} to the functions, described below, +the handling will be turned off.} + +\ttt{\toindex{FtpSetDebugHandler}(FTP *,function)} +{ Predefines function of protocol debugging. + After the function is predefined, it is called with every + sending/receiving messages from the server. + The function, defined as a debug handler must do returns to the calling +functions (\ts{FtpSendMessage}/\ts{FtpGetMessage}), but can also abort the program. + +} + +\ttt{\toindex{FtpSetErrorHandler}(FTP *,function)} +{ + Predefines error handler. If the server's answer means, that the operation is not finished + correctly, this function will be called. + The result code is negative, if an error is occurs. +} +\ttt{\toindex{FtpSetIOHandler}(FTP *,function)} +{ + Predefines handler of Input/Output processing. This function is called, when a connection to the + server is broken. For example, when the network or the remote host is down. This handler also is + called after the \toindex{timeout} of one character waiting expires. +} + +\ttt{\toindex{FtpDebug}(FTP *)} +{ +Turns on all standard debugging functions. + +\tc{\toindex{FtpDebugError}}{--- prints a string, taken from the server, and aborts the program;} +\tc{\toindex{FtpDebugDebug}}{--- prints a string, taken from the server;} +\tc{\toindex{FtpDebugIO}}{--- prints string \ts{strerror(errno)} and aborts the program.} +} + +\ttt{\toindex{FtpSetHashHandler}(FTP *,function)} +{ + Predefines handler of function which must compute traffic size. This +function have only one argument which describe number of transferred bytes. +If this argument is zero counter must be reset to zero. +} + + +All function for debugging have three arguments:\\ +1. Pointer to FTP data structure;\\ +2. Last returned value from the server. When errors occur, the value is less than 1;\\ +3. Diagnostic string.(char *) + +\ttt{\toindex{FtplibDebug}(yes|no)} +{ Turns on/off autostart debug mode, when connection is established. +} + +\ttt{\toindex{FtpLog}(char *name\_of\_log, char *message)} +{ Print message to user's screen in libftp's standard format, + name\_of\_log must be your program name (if this function called +from standard handlers then this string is title from FTP structure) and +message with diagnostic string from anywhere.} + + +\subsection{Data transfer procedures} + +\ttt{STATUS \toindex{FtpRetr}(FTP~*, char~*command, char~*inp, char~*out)} +{ + This is basically and single procedure in the library with transfer + file from the server. One check many option with customizing its style + of working. This options basically is members of FTP structure such + as timeout, all handlers, mode, seek. If in continue of working this + function happen timeout or network broked then this function + automatically called I/O handler which can restart this function + again or broken procedure. If handler is not set then FtpRetr return + status QUIT or LQUIT as signal of type of error (LQUIT is specify + error happen with local filesystem). \\ + {\bf Warring!} All receive function described bellow working by + called this procedure and described rules is right for them. +} + +\ttt{\toindex{FtpGet}(FTP~*, char~*in, char~*out)} +{ + Calls \ts{FtpRetr} with adaptation arguments to transfer file +} + +\ttt{\toindex{FtpDirectory}(FTP~*, char~*pat\footnote{This is the first argument for \ts{``ls''} command}, char~*out)} +{ + Transfers files listing from the server, described by \ts{pat}, to the local file \ts{out}. +} + +\ttt{\toindex{FtpDir}(FTP~*, char~*out)} +{ + Transfers files listing of the current directory from the server to the local file \ts{out}. +} + +\ttt{\toindex{FtpStor}(FTP~*, char~*command, char~*inp, char*~out)} +{ + Store file to the server. Works like FtpRetr. +} + +\ttt{\toindex{FtpPut}(FTP~*, char~*in, char~*out)} +{ + Calls \ts{FtpStor} adaptation arguments to transfer file +} + +\ttt{\toindex{FtpCopy}(FTP~*ftp\_from, FTP~*ftp\_to, char~*in, char~*out)} +{ + Transfer file between two server without connection to client's host +} + +\ttt{\toindex{FtpPassiveTransfer}(FTP~*ftp\_from, FTP~*ftp\_to, char~*in, char~*out)} +{ + Transfer file between two server via client's cache. +} + +\subsection{Server's files read/write procedures} + +This library contains special functions for remote files reading and +writing, without precopying them to local files. The functions, +which are described below, do it. After the data channel +to a remote file is created, it becomes possible to read and write + characters using standard Input/Output functions +or using special functions \ts{FtpRead}/\ts{FtpWrite} and/or +\ts{FtpGetc}/\ts{FtpPutc}, which reorganize stream for standard text file, +under condition that the \ts{ASCII} mode is set. +\footnote{Of course, such functions as \ts{seek}, \ts{ioctl}, .... +can not be used.} + +\ttt{\toindex{FtpData}(FTP~*, char~*command, char~*param, char~*mode)} +{ Makes data transfer channel, with presending command composed from \ts{command} and \ts{param}. +The mode must be \ts{``r''} or \ts{``w''}} + +\ttt{\toindex{FtpOpenRead}(FTP~*,char~*filename)} +{ Opens file named \ts{filename} for reading on server} + +\ttt{\toindex{FtpOpenWrite}(FTP~*,char~*filename)} +{ Creats and opens file named \ts{filename} for writing on server} + +\ttt{\toindex{FtpOpenAppend}(FTP~*,char~*filename)} +{ Creats and opens file named \ts{filename} for appending on server} + +\ttt{\toindex{FtpOpenDir}(FTP~*, char~*files)} +{ + Creats channel for directory list reading, described by argument \ts{files}. +} + +\ttt{STATUS \toindex{FtpRead}(FTP~*)}{ +Reads character from data stream. If \ts{ASCII} mode is set\footnote{By default} converts new line markers. +When the end of file is detected or channel is broken, returns \toindex{EOF}} + +\ttt{\toindex{FtpWrite}(FTP~*, char~c)}{ +Writes single character to stream, if \ts{ASCII} mode is set converts new line markers. +When channel is broken, returns \toindex{EOF}} + +\ttt{int \toindex{FtpGetc}(FTP~*,FILE~*fp)}{ +Reads character from data stream specified by fp. Using macros FTPDATA and FTPCMD you can specify stream need for reading. \footnote{Functions FtpGetc and FtpPutc ignories data stream mode, works as binary always} +} + +\ttt{STATUS \toindex{FtpPutc}(FTP~*,FILE~*fp, char c)}{ +Writes character to data stream specified by fp. Using macros FTPDATA and +FTPCMD you can specify stream need for reading. \footnote{Functions +FtpGetc and FtpPutc ignores data stream mode, works as binary always} +} + + +\ttt{\toindex{FtpClose}(FTP~*)} +{Closes opened channel to server} + +\subsection{Other commands for server} + +\ttt{\toindex{FtpCommand}(FTP~*, char~*command, char~*param, int~ok1, ok2, ok3, ..., okN, EOF)} +{ Sends a command, composed from \ts{command} and \ts{param} using \ts{sprintf} function. +Reads an answer from the server. +When return code from the server is not included to \ts{ok-list}(\ts{ok1},\ts{ok2}...) the sign of code +will be inverted.} + + +\ttt{\toindex{FtpType}(FTP~*,char~mode)} +{Sets transfer mode, such as \ts{'A'},\ts{'I'},\ts{'S'},etc...} + +\ttt{\toindex{FtpBinary}(FTP~*)} +{Sets binary mode} + +\ttt{\toindex{FtpAscii}(FTP~*)} +{Sets \ts{ASCII} mode} + + +\ttt{\toindex{FtpMkdir}(FTP~*,char *dirname)} +{Makes directory on server} + +\ttt{\toindex{FtpChdir}(FTP~*,char *dirname)} +{Changes working directory on server} + +\ttt{\toindex{FtpRm}(FTP~*,char *filename)} +{Removes file on server} + +\ttt{char~*\toindex{FtpPwd}(FTP~*)} +{Returns the name of working directory on server} + +\ttt{int \toindex{FtpSize}(FTP~*,char *filename)} +{Returned size (in bytes) of description's file.} + +\ttt{\toindex{FtpMove}(FTP~*,char *oldfilename, char *newfilename)} +{Renames file from \ts{oldfilename} to \ts{newfilename}} + +\ttt{\toindex{FtpPort}(FTP~*, int~a, int~b, int~c, int~d, int~e, int~f) +\footnote{Recommended in non-trivial situations} +} +{ A command for the server for making a new data channel. \ts{a.b.c.d} is an IP address of a client(i.e. your IP address), +\ts{e*256+f} is a port number} + + +\ttt{struct hostent *\toindex{FtpGetHost}(char *hostname) +\footnote{Extension of standard function ``gethostbyname''} +} +{Returned pointer to structure \ts{hostent} creating using string +\ts{hostname}, which contains name of the computer or its IP +address~\footnote{For example''dxunk8.oea.ihep.su'' or ``192.102.229.71''} +} + + +\subsection{Functions for sending/receiving control messages to/from server} + +\ttt{\toindex{FtpSendMessage}(FTP~*, char~*message)} +{Sends a message to the server} + +\ttt{int \toindex{FtpGetMessage}(FTP~*)} +{Receives a message from the server.} + +\ttt{\toindex{FtpMessage}(int Number)} +{Gets a message by code.} + +\ttt{\toindex{FtpNumber}(char *Message)} +{Extract message's number from string.} + +\subsection{High-level functions} + +\ttt{FILE *\toindex{FtpFullOpen}(char *filename,char *mode)} +{ +Parses string \ts{filename}, which must contain a string in format or \\ +\ts{host/user/password:filename} or \ts{filename}, +what corresponds to remote or local file. The second argument is the type of opening, divided into two characters: +first --- the mode of opening \ts{``r''}, \ts{``w''} or \ts{``a''}, second is the transfer type , if contains character \ts{``b''}, + then the mode is binary. +} + +\ttt{STATUS \toindex{FtpFullSyntax}(String source,String host,String user,String password,String file)} +{Make out string ``source'' for next four parameters.} + +\ttt{FILE *\toindex{Ftpfopen}(char *file, char *mode)} +{ + Open file specified in libftp's file specification. Works like + \ts{fopen}. See description of libftp's file specification in the + top of paper. +} + +\ttt{STATUS \toindex{Ftpfclose}(FILE *fp)} +{ + Close file which opened using Ftpfopen. Works like fclose. +} + +\ttt{STATUS \toindex{FtpArchie}(char *what, ARCHIE *result, int number)}{ +Find \ts{number} entrys in archie's database enrolls described by \ts{what} +argument. \ts{result} must be pointer to array of ARCHIE's structures number +of which must be equivalence or higher than \ts{number}. This call return +number of entrys which found in database. If FtpArchie return value lower +than zero then pointed target not found or archie isn't works} + + +\section{Example of using libftp} + +Next example demonstrate very simple using library calls only Ftpfopen +and Ftpfclose functions which discriminate libftp's file specification: + +\input example + +For tests works this program you can try run one as: + +\bigskip + +\% example username/password@hostname:filename myfile.out + +\% example myfile.input username/password@hostname:filename.out + + +\newpage +\input libftp.ind +\newpage +\tableofcontents +\end{document} + + + + + + + + + + + + |
