diff options
Diffstat (limited to 'lib/inets/doc/src')
| -rw-r--r-- | lib/inets/doc/src/Makefile | 3 | ||||
| -rw-r--r-- | lib/inets/doc/src/ftp.xml | 948 | ||||
| -rw-r--r-- | lib/inets/doc/src/ftp_client.xml | 86 | ||||
| -rw-r--r-- | lib/inets/doc/src/httpc.xml | 13 | ||||
| -rw-r--r-- | lib/inets/doc/src/inets.xml | 7 | ||||
| -rw-r--r-- | lib/inets/doc/src/introduction.xml | 10 | ||||
| -rw-r--r-- | lib/inets/doc/src/notes.xml | 14 | ||||
| -rw-r--r-- | lib/inets/doc/src/part.xml | 9 | ||||
| -rw-r--r-- | lib/inets/doc/src/ref_man.xml | 12 | ||||
| -rw-r--r-- | lib/inets/doc/src/tftp.xml | 647 |
10 files changed, 23 insertions, 1726 deletions
diff --git a/lib/inets/doc/src/Makefile b/lib/inets/doc/src/Makefile index cbfa5c9e30..90c1258d4a 100644 --- a/lib/inets/doc/src/Makefile +++ b/lib/inets/doc/src/Makefile @@ -43,13 +43,10 @@ XML_CHAPTER_FILES = \ inets_services.xml \ http_client.xml \ http_server.xml \ - ftp_client.xml \ notes.xml XML_REF3_FILES = \ inets.xml \ - ftp.xml \ - tftp.xml \ http_uri.xml\ httpc.xml\ httpd.xml \ diff --git a/lib/inets/doc/src/ftp.xml b/lib/inets/doc/src/ftp.xml deleted file mode 100644 index 42bece4d38..0000000000 --- a/lib/inets/doc/src/ftp.xml +++ /dev/null @@ -1,948 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>1997</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>ftp</title> - <prepared>Peter Högfeldt</prepared> - <docno></docno> - <date>1997-11-05</date> - <rev>B</rev> - <file>ftp.xml</file> - </header> - <module>ftp</module> - <modulesummary>A File Transfer Protocol client.</modulesummary> - - <description> - - <p>This module implements a client for file transfer - according to a subset of the File Transfer Protocol (FTP), see - <url href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</url>.</p> - - <p>As from <c>Inets</c> 4.4.1, the FTP - client always tries to use passive FTP mode and only resort - to active FTP mode if this fails. This default behavior can be - changed by start option <seealso marker="#mode">mode</seealso>.</p> - - <marker id="two_start"></marker> - - <p>An FTP client can be started in two ways. One is using the - <seealso marker="#service_start">Inets service framework</seealso>, - the other is to start it directly as a standalone process - using function <seealso marker="#open">open</seealso>.</p> - - <p>For a simple example of an FTP session, see - <seealso marker="ftp_client">Inets User's Guide</seealso>.</p> - - <p>In addition to the ordinary functions for receiving and sending - files (see <c>recv/2</c>, <c>recv/3</c>, <c>send/2</c>, and - <c>send/3</c>) there are functions for receiving remote files as - binaries (see <c>recv_bin/2</c>) and for sending binaries to be - stored as remote files (see <c>send_bin/3</c>).</p> - - <p>A set of functions is provvided for sending and receiving - contiguous parts of a file to be stored in a remote file. For send, - see <c>send_chunk_start/2</c>, <c>send_chunk/2</c>, and - <c>send_chunk_end/1</c>. For receive, see - <c>recv_chunk_start/2</c> and <c>recv_chunk/</c>).</p> - - <p>The return values of the following functions depend - much on the implementation of the FTP server at the remote - host. In particular, the results from <c>ls</c> and <c>nlist</c> - varies. Often real errors are not reported as errors by <c>ls</c>, - even if, for example, a file or directory does not - exist. <c>nlist</c> is usually more strict, but some - implementations have the peculiar behaviour of responding with an - error if the request is a listing of the contents of a directory - that exists but is empty.</p> - - <marker id="service_start"></marker> - </description> - - <section> - <title>FTP CLIENT SERVICE START/STOP</title> - - <p>The FTP client can be started and stopped dynamically in runtime by - calling the <c>Inets</c> application API - <c>inets:start(ftpc, ServiceConfig)</c>, - or <c>inets:start(ftpc, ServiceConfig, How)</c>, and - <c>inets:stop(ftpc, Pid)</c>. - For details, see <seealso marker="inets">inets(3)</seealso>.</p> - - <p>The available configuration options are as follows:</p> - - <taglist> - <tag>{host, Host}</tag> - <item> - <marker id="host"></marker> - <p>Host = <c>string() | ip_address()</c></p> - </item> - - <tag>{port, Port}</tag> - <item> - <marker id="port"></marker> - <p>Port = <c>integer() > 0</c></p> - <p>Default is <c>21</c>.</p> - </item> - - <tag>{mode, Mode}</tag> - <item> - <marker id="mode"></marker> - <p>Mode = <c>active | passive</c></p> - <p>Default is <c>passive</c>.</p> - </item> - - <tag>{verbose, Verbose}</tag> - <item> - <marker id="verbose"></marker> - <p>Verbose = <c>boolean()</c> </p> - <p>Determines if the FTP communication is to be - verbose or not.</p> - <p>Default is <c>false</c>.</p> - </item> - - <tag>{debug, Debug}</tag> - <item> - <marker id="debug"></marker> - <p>Debug = <c>trace | debug | disable</c> </p> - <p>Debugging using the dbg toolkit. </p> - <p>Default is <c>disable</c>.</p> - </item> - - <tag>{ipfamily, IpFamily}</tag> - <item> - <marker id="ipfamily"></marker> - <p>IpFamily = <c>inet | inet6 | inet6fb4</c> </p> - <p>With <c>inet6fb4</c> the client behaves as before, that is, - tries to use IPv6, and only if that does not work it - uses IPv4).</p> - <p>Default is <c>inet</c> (IPv4).</p> - </item> - - <tag>{timeout, Timeout}</tag> - <item> - <marker id="timeout"></marker> - <p>Timeout = <c>non_neg_integer()</c></p> - <p>Connection time-out.</p> - <p>Default is <c>60000</c> (milliseconds).</p> - </item> - - <tag>{dtimeout, DTimeout}</tag> - <item> - <marker id="dtimeout"></marker> - <p>DTimeout = <c>non_neg_integer() | infinity</c> </p> - <p>Data connect time-out. - The time the client waits for the server to connect to the - data socket.</p> - <p>Default is <c>infinity</c>. </p> - </item> - - <tag>{progress, Progress}</tag> - <item> - <marker id="progress"></marker> - <p>Progress = <c>ignore | {CBModule, CBFunction, InitProgress}</c></p> - <p><c>CBModule = atom()</c>, <c>CBFunction = atom()</c></p> - <p><c>InitProgress = term()</c></p> - <p>Default is <c>ignore</c>.</p> - </item> - - </taglist> - - <p>Option <c>progress</c> is intended to be used by applications that - want to create some type of progress report, such as a progress bar in - a GUI. Default for the progress option is <c>ignore</c>, - that is, the option is not used. When the progress option is - specified, the following happens when <c>ftp:send/[3,4]</c> or - <c>ftp:recv/[3,4]</c> are called:</p> - - <list type="bulleted"> - <item> - <p>Before a file is transferred, the following call is - made to indicate the start of the file transfer and how large - the file is. The return value of the callback function - is to be a new value for the <c>UserProgressTerm</c> that will - be used as input the next time the callback function is - called.</p> - <p><c> - CBModule:CBFunction(InitProgress, File, {file_size, FileSize}) - </c></p> - </item> - - <item> - <p>Every time a chunk of bytes is transferred the - following call is made:</p> - <p><c> - CBModule:CBFunction(UserProgressTerm, File, {transfer_size, TransferSize}) - </c></p> - </item> - - <item> - <p>At the end of the file the following call is - made to indicate the end of the transfer:</p> - <p><c> - CBModule:CBFunction(UserProgressTerm, File, {transfer_size, 0}) - </c></p> - </item> - </list> - - <p>The callback function is to be defined as follows:</p> - - <p><c> - CBModule:CBFunction(UserProgressTerm, File, Size) -> UserProgressTerm - </c></p> - - <p><c> - CBModule = CBFunction = atom() - </c></p> - - <p><c> - UserProgressTerm = term() - </c></p> - - <p><c> - File = string() - </c></p> - - <p><c> - Size = {transfer_size, integer()} | {file_size, integer()} | {file_size, unknown} - </c></p> - - <p>For remote files, <c>ftp</c> cannot determine the - file size in a platform independent way. In this case the size - becomes <c>unknown</c> and it is left to the application to - determine the size.</p> - - <note> - <p>The callback is made by a middleman process, hence the - file transfer is not affected by the code in the progress - callback function. If the callback crashes, this is - detected by the FTP connection process, which then prints an - info-report and goes on as if the progress option was set - to <c>ignore</c>.</p> - </note> - - <p>The file transfer type is set to the default of the FTP server - when the session is opened. This is usually ASCCI mode. - </p> - - <p>The current local working directory (compare <c>lpwd/1</c>) is set - to the value reported by <c>file:get_cwd/1</c>, the wanted - local directory. - </p> - - <p>The return value <c>Pid</c> is used as a reference to the - newly created FTP client in all other functions, and they are to - be called by the process that created the connection. The FTP - client process monitors the process that created it and - terminates if that process terminates.</p> - </section> - - <section> - <title>DATA TYPES</title> - <p>The following type definitions are used by more than one - function in the FTP client API:</p> - <p><c>pid()</c> = identifier of an FTP connection</p> - <p><c>string()</c> = list of ASCII characters</p> - <p><c>shortage_reason()</c> = <c>etnospc | epnospc</c></p> - <p><c>restriction_reason()</c> = <c>epath | efnamena | elogin | enotbinary</c> - - all restrictions are not always relevant to all functions - </p> - <p><c>common_reason()</c> = <c>econn | eclosed | term()</c> - - some explanation of what went wrong</p> - - <marker id="account"></marker> - </section> - - <funcs> - <func> - <name>account(Pid, Account) -> ok | {error, Reason}</name> - <fsummary>Specifies which account to use.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Account = string()</v> - <v>Reason = eacct | common_reason()</v> - </type> - <desc> - <p>Sets the account for an operation, if needed.</p> - - <marker id="append"></marker> - <marker id="append2"></marker> - <marker id="append3"></marker> - </desc> - </func> - - <func> - <name>append(Pid, LocalFile) -> </name> - <name>append(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}</name> - <fsummary>Transfers a file to remote server, and appends it to - <c>Remotefile</c>.</fsummary> - <type> - <v>Pid = pid()</v> - <v>LocalFile = RemoteFile = string()</v> - <v>Reason = epath | elogin | etnospc | epnospc | efnamena | common_reason</v> - </type> - <desc> - <p>Transfers the file <c>LocalFile</c> to the remote server. If - <c>RemoteFile</c> is specified, the name of the remote file that the - file is appended to is set to <c>RemoteFile</c>, otherwise - to <c>LocalFile</c>. If the file does not exists, - it is created.</p> - - <marker id="append_bin"></marker> - </desc> - </func> - - <func> - <name>append_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}</name> - <fsummary>Transfers a binary into a remote file.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Bin = binary()()</v> - <v>RemoteFile = string()</v> - <v>Reason = restriction_reason()| shortage_reason() | common_reason()</v> - </type> - <desc> - <p>Transfers the binary <c>Bin</c> to the remote server and appends - it to the file <c>RemoteFile</c>. If the file does not exist, it - is created.</p> - - <marker id="append_chunk"></marker> - </desc> - </func> - - <func> - <name>append_chunk(Pid, Bin) -> ok | {error, Reason}</name> - <fsummary>Appends a chunk to the remote file.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Bin = binary()</v> - <v>Reason = echunk | restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Transfers the chunk <c>Bin</c> to the remote server, which - appends it to the file specified in the call to - <c>append_chunk_start/2</c>.</p> - <p>For some errors, for example, file system full, it is - necessary to call <c>append_chunk_end</c> to get the - proper reason.</p> - - <marker id="append_chunk_start"></marker> - </desc> - </func> - - <func> - <name>append_chunk_start(Pid, File) -> ok | {error, Reason}</name> - <fsummary>Starts transfer of file chunks for appending to <c>File</c>.</fsummary> - <type> - <v>Pid = pid()</v> - <v>File = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Starts the transfer of chunks for appending to the file - <c>File</c> at the remote server. If the file does not exist, - it is created.</p> - - <marker id="append_chunk_end"></marker> - </desc> - </func> - - <func> - <name>append_chunk_end(Pid) -> ok | {error, Reason}</name> - <fsummary>Stops transfer of chunks for appending.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Reason = echunk | restriction_reason() | shortage_reason() </v> - </type> - <desc> - <p>Stops transfer of chunks for appending to the remote server. - The file at the remote server, specified in the call to - <c>append_chunk_start/2</c>, is closed by the server.</p> - - <marker id="cd"></marker> - </desc> - </func> - - <func> - <name>cd(Pid, Dir) -> ok | {error, Reason}</name> - <fsummary>Changes remote working directory.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Dir = string()</v> - <v>Reason = restriction_reason() | common_reason() </v> - </type> - <desc> - <p>Changes the working directory at the remote server to - <c>Dir</c>.</p> - - <marker id="close"></marker> - </desc> - </func> - - <func> - <name>close(Pid) -> ok</name> - <fsummary>Ends the FTP session.</fsummary> - <type> - <v>Pid = pid()</v> - </type> - <desc> - <p>Ends an FTP session, created using function - <seealso marker="#open">open</seealso>.</p> - - <marker id="delete"></marker> - </desc> - </func> - - <func> - <name>delete(Pid, File) -> ok | {error, Reason}</name> - <fsummary>Deletes a file at the remote server.</fsummary> - <type> - <v>Pid = pid()</v> - <v>File = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Deletes the file <c>File</c> at the remote server.</p> - - <marker id="append"></marker> - </desc> - </func> - - <func> - <name>formaterror(Tag) -> string()</name> - <fsummary>Returns error diagnostics.</fsummary> - <type> - <v>Tag = {error, atom()} | atom()</v> - </type> - <desc> - <p>Given an error return value <c>{error, AtomReason}</c>, - this function returns a readable string describing the error.</p> - - <marker id="lcd"></marker> - </desc> - </func> - - <func> - <name>lcd(Pid, Dir) -> ok | {error, Reason}</name> - <fsummary>Changes local working directory.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Dir = string()</v> - <v>Reason = restriction_reason()</v> - </type> - <desc> - <p>Changes the working directory to <c>Dir</c> for the local client.</p> - - <marker id="lpwd"></marker> - </desc> - </func> - - <func> - <name>lpwd(Pid) -> {ok, Dir}</name> - <fsummary>Gets local current working directory.</fsummary> - <type> - <v>Pid = pid()</v> - </type> - <desc> - <p>Returns the current working directory at the local client.</p> - - <marker id="ls"></marker> - <marker id="ls1"></marker> - <marker id="ls2"></marker> - </desc> - </func> - - <func> - <name>ls(Pid) -> </name> - <name>ls(Pid, Pathname) -> {ok, Listing} | {error, Reason}</name> - <fsummary>List of files.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Pathname = string()</v> - <v>Listing = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Returns a list of files in long format.</p> - <p><c>Pathname</c> can be a directory, a group of files, or - a file. The <c>Pathname</c> string can contain wildcards.</p> - <p><c>ls/1</c> implies the current remote directory of the user.</p> - <p>The format of <c>Listing</c> depends on the operating system. - On UNIX, it is typically produced from the output of the - <c>ls -l</c> shell command.</p> - - <marker id="mkdir"></marker> - </desc> - </func> - - <func> - <name>mkdir(Pid, Dir) -> ok | {error, Reason}</name> - <fsummary>Creates a remote directory.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Dir = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Creates the directory <c>Dir</c> at the remote server.</p> - - <marker id="nlist"></marker> - <marker id="nlist1"></marker> - <marker id="nlist2"></marker> - </desc> - </func> - - <func> - <name>nlist(Pid) -> </name> - <name>nlist(Pid, Pathname) -> {ok, Listing} | {error, Reason}</name> - <fsummary>List of files.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Pathname = string()</v> - <v>Listing = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Returns a list of files in short format.</p> - <p><c>Pathname</c> can be a directory, a group of files, or - a file. The <c>Pathname</c> string can contain wildcards.</p> - <p><c>nlist/1</c> implies the current remote directory of the user.</p> - <p>The format of <c>Listing</c> is a stream of - filenames where each filename is separated by <CRLF> or - <NL>. Contrary to function <c>ls</c>, the purpose of - <c>nlist</c> is to enable a program to - process filename information automatically.</p> - - <marker id="open"></marker> - </desc> - </func> - - <func> - <name>open(Host) -> {ok, Pid} | {error, Reason}</name> - <name>open(Host, Opts) -> {ok, Pid} | {error, Reason}</name> - <fsummary>Starts a standalone FTP client.</fsummary> - <type> - <v>Host = string() | ip_address()</v> - <v>Opts = options()</v> - <v>options() = [option()]</v> - <v>option() = start_option() | open_option()</v> - <v>start_option() = {verbose, verbose()} | {debug, debug()}</v> - <v>verbose() = boolean() (default is false)</v> - <v>debug() = disable | debug | trace (default is disable)</v> - <v>open_option() = {ipfamily, ipfamily()} | {port, port()} | {mode, mode()} | {tls, tls_options()} | {timeout, timeout()} | {dtimeout, dtimeout()} | {progress, progress()}</v> - <v>ipfamily() = inet | inet6 | inet6fb4 (default is inet)</v> - <v>port() = integer() > 0 (default is 21)</v> - <v>mode() = active | passive (default is passive)</v> - <v>tls_options() = [<seealso marker="ssl:ssl#type-ssloption">ssl:ssloption()</seealso>]</v> - <v>timeout() = integer() > 0 (default is 60000 milliseconds)</v> - <v>dtimeout() = integer() > 0 | infinity (default is infinity)</v> - <v>pogress() = ignore | {module(), function(), initial_data()} (default is ignore)</v> - <v>module() = atom()</v> - <v>function() = atom()</v> - <v>initial_data() = term()</v> - <v>Reason = ehost | term()</v> - </type> - - <desc> - <p>Starts a standalone FTP client process - (without the <c>Inets</c> service framework) and - opens a session with the FTP server at <c>Host</c>. </p> - - <p>If option <c>{tls, tls_options()}</c> is present, the FTP session - is transported over <c>tls</c> (<c>ftps</c>, see - <url href="http://www.ietf.org/rfc/rfc4217.txt">RFC 4217</url>). - The list <c>tls_options()</c> can be empty. The function - <seealso marker="ssl:ssl#connect/3"><c>ssl:connect/3</c></seealso> - is used for securing both the control connection and the data sessions. - </p> - - <p>A session opened in this way is closed using function - <seealso marker="#close">close</seealso>.</p> - - <marker id="pwd"></marker> - </desc> - </func> - - <func> - <name>pwd(Pid) -> {ok, Dir} | {error, Reason}</name> - <fsummary>Gets the remote current working directory.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Returns the current working directory at the remote server.</p> - - <marker id="recv"></marker> - <marker id="recv2"></marker> - <marker id="recv3"></marker> - </desc> - </func> - - <func> - <name>recv(Pid, RemoteFile) -> </name> - <name>recv(Pid, RemoteFile, LocalFile) -> ok | {error, Reason}</name> - <fsummary>Transfers a file from remote server.</fsummary> - <type> - <v>Pid = pid()</v> - <v>RemoteFile = LocalFile = string()</v> - <v>Reason = restriction_reason() | common_reason() | file_write_error_reason() </v> - <v>file_write_error_reason() = see file:write/2</v> - </type> - <desc> - <p>Transfers the file <c>RemoteFile</c> from the remote server - to the file system of the local client. If - <c>LocalFile</c> is specified, the local file will be - <c>LocalFile</c>, otherwise - <c>RemoteFile</c>.</p> - <p>If the file write fails (for example, <c>enospc</c>), the command is - aborted and <c>{error, file_write_error_reason()}</c> is returned. - However, the file is <em>not</em> removed.</p> - - <marker id="recv_bin"></marker> - </desc> - </func> - - <func> - <name>recv_bin(Pid, RemoteFile) -> {ok, Bin} | {error, Reason}</name> - <fsummary>Transfers a file from remote server as a binary.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Bin = binary()</v> - <v>RemoteFile = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Transfers the file <c>RemoteFile</c> from the remote server and - receives it as a binary.</p> - - <marker id="recv_chunk_start"></marker> - </desc> - </func> - - <func> - <name>recv_chunk_start(Pid, RemoteFile) -> ok | {error, Reason}</name> - <fsummary>Starts chunk-reading of the remote file.</fsummary> - <type> - <v>Pid = pid()</v> - <v>RemoteFile = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Starts transfer of the file <c>RemoteFile</c> from the - remote server.</p> - - <marker id="recv_chunk"></marker> - </desc> - </func> - - <func> - <name>recv_chunk(Pid) -> ok | {ok, Bin} | {error, Reason}</name> - <fsummary>Receives a chunk of the remote file.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Bin = binary()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Receives a chunk of the remote file (<c>RemoteFile</c> of - <c>recv_chunk_start</c>). The return values have the following - meaning:</p> - <list type="bulleted"> - <item><c>ok</c> = the transfer is complete.</item> - <item><c>{ok, Bin}</c> = just another chunk of the file.</item> - <item><c>{error, Reason}</c> = transfer failed.</item> - </list> - - <marker id="rename"></marker> - </desc> - </func> - - <func> - <name>rename(Pid, Old, New) -> ok | {error, Reason}</name> - <fsummary>Renames a file at the remote server.</fsummary> - <type> - <v>Pid = pid()</v> - <v>CurrFile = NewFile = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Renames <c>Old</c> to <c>New</c> at the remote server.</p> - - <marker id="rmdir"></marker> - </desc> - </func> - - <func> - <name>rmdir(Pid, Dir) -> ok | {error, Reason}</name> - <fsummary>Removes a remote directory.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Dir = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Removes directory <c>Dir</c> at the remote server.</p> - - <marker id="send"></marker> - <marker id="send2"></marker> - <marker id="send3"></marker> - </desc> - </func> - - <func> - <name>send(Pid, LocalFile) -></name> - <name>send(Pid, LocalFile, RemoteFile) -> ok | {error, Reason}</name> - <fsummary>Transfers a file to the remote server.</fsummary> - <type> - <v>Pid = pid()</v> - <v>LocalFile = RemoteFile = string()</v> - <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v> - </type> - <desc> - <p>Transfers the file <c>LocalFile</c> to the remote server. If - <c>RemoteFile</c> is specified, the name of the remote file is set - to <c>RemoteFile</c>, otherwise to <c>LocalFile</c>.</p> - - <marker id="send_bin"></marker> - </desc> - </func> - - <func> - <name>send_bin(Pid, Bin, RemoteFile) -> ok | {error, Reason}</name> - <fsummary>Transfers a binary into a remote file.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Bin = binary()()</v> - <v>RemoteFile = string()</v> - <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v> - </type> - <desc> - <p>Transfers the binary <c>Bin</c> into the file <c>RemoteFile</c> - at the remote server.</p> - - <marker id="send_chunk"></marker> - </desc> - </func> - - <func> - <name>send_chunk(Pid, Bin) -> ok | {error, Reason}</name> - <fsummary>Writes a chunk to the remote file.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Bin = binary()</v> - <v>Reason = echunk | restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Transfers the chunk <c>Bin</c> to the remote server, which - writes it into the file specified in the call to - <c>send_chunk_start/2</c>.</p> - <p>For some errors, for example, file system full, it is - necessary to to call <c>send_chunk_end</c> to get the - proper reason.</p> - - <marker id="send_chunk_start"></marker> - </desc> - </func> - - <func> - <name>send_chunk_start(Pid, File) -> ok | {error, Reason}</name> - <fsummary>Starts transfer of file chunks.</fsummary> - <type> - <v>Pid = pid()</v> - <v>File = string()</v> - <v>Reason = restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Starts transfer of chunks into the file <c>File</c> at the - remote server.</p> - - <marker id="send_chunk_end"></marker> - </desc> - </func> - - <func> - <name>send_chunk_end(Pid) -> ok | {error, Reason}</name> - <fsummary>Stops transfer of chunks.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Reason = restriction_reason() | common_reason() | shortage_reason()</v> - </type> - <desc> - <p>Stops transfer of chunks to the remote server. The file at the - remote server, specified in the call to <c>send_chunk_start/2</c> - is closed by the server.</p> - - <marker id="type"></marker> - </desc> - </func> - - <func> - <name>type(Pid, Type) -> ok | {error, Reason}</name> - <fsummary>Sets transfer type to <c>ascii</c>or <c>binary</c>.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Type = ascii | binary</v> - <v>Reason = etype | restriction_reason() | common_reason()</v> - </type> - <desc> - <p>Sets the file transfer type to <c>ascii</c> or <c>binary</c>. When - an FTP session is opened, the default transfer type of the - server is used, most often <c>ascii</c>, which is default - according to <url href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</url>.</p> - <marker id="user3"></marker> - </desc> - </func> - - <func> - <name>user(Pid, User, Password) -> ok | {error, Reason}</name> - <fsummary>User login.</fsummary> - <type> - <v>Pid = pid()</v> - <v>User = Password = string()</v> - <v>Reason = euser | common_reason()</v> - </type> - <desc> - <p>Performs login of <c>User</c> with <c>Password</c>.</p> - - <marker id="user4"></marker> - </desc> - </func> - - <func> - <name>user(Pid, User, Password, Account) -> ok | {error, Reason}</name> - <fsummary>User login.</fsummary> - <type> - <v>Pid = pid()</v> - <v>User = Password = string()</v> - <v>Reason = euser | common_reason() </v> - </type> - <desc> - <p>Performs login of <c>User</c> with <c>Password</c> to the account - specified by <c>Account</c>.</p> - - <marker id="quote"></marker> - </desc> - </func> - - <func> - <name>quote(Pid, Command) -> [FTPLine]</name> - <fsummary>Sends an arbitrary FTP command.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Command = string()</v> - <v>FTPLine = string(</v> - </type> - <desc><note><p>The telnet end of line characters, from the FTP - protocol definition, CRLF, for example, "\\r\\n" has been removed.</p></note> - <p>Sends an arbitrary FTP command and returns verbatim a list - of the lines sent back by the FTP server. This function is - intended to give application accesses to FTP commands - that are server-specific or that cannot be provided by - this FTP client.</p> - <note> - <p>FTP commands requiring a data connection cannot be - successfully issued with this function.</p> - </note> - </desc> - </func> - </funcs> - - <section> - <title>ERRORS</title> - <p>The possible error reasons and the corresponding diagnostic strings - returned by <c>formaterror/1</c> are as follows: - </p> - <taglist> - <tag><c>echunk</c></tag> - <item> - <p>Synchronization error during chunk sending according to one - of the following: - </p><list type="bulleted"> - <item>A call is made to <c>send_chunk/2</c> or <c>send_chunk_end/1</c> - before a call to <c>send_chunk_start/2</c>.</item> - <item>A call has been made to another transfer function during chunk - sending, that is, before a call to <c>send_chunk_end/1</c>.</item> - </list> - </item> - <tag><c>eclosed</c></tag> - <item> - <p>The session is closed.</p> - </item> - <tag><c>econn</c></tag> - <item> - <p>Connection to the remote server is prematurely closed.</p> - </item> - <tag><c>ehost</c></tag> - <item> - <p>Host is not found, FTP server is not found, or connection is rejected - by FTP server.</p> - </item> - <tag><c>elogin</c></tag> - <item> - <p>User is not logged in.</p> - </item> - <tag><c>enotbinary</c></tag> - <item> - <p>Term is not a binary.</p> - </item> - <tag><c>epath</c></tag> - <item> - <p>No such file or directory, or directory already exists, or - permission denied.</p> - </item> - <tag><c>etype</c></tag> - <item> - <p>No such type.</p> - </item> - <tag><c>euser</c></tag> - <item> - <p>Invalid username or password.</p> - </item> - <tag><c>etnospc</c></tag> - <item> - <p>Insufficient storage space in system [452].</p> - </item> - <tag><c>epnospc</c></tag> - <item> - <p>Exceeded storage allocation (for current directory or - dataset) [552].</p> - </item> - <tag><c>efnamena</c></tag> - <item> - <p>Filename not allowed [553].</p> - </item> - </taglist> - </section> - - <section> - <title>SEE ALSO</title> - <p><seealso marker="kernel:file">file(3)</seealso> - <seealso marker="stdlib:filename">filename(3)</seealso> - and J. Postel and J. Reynolds: File Transfer Protocol - (<url href="http://www.ietf.org/rfc/rfc959.txt">RFC 959</url>). - </p> - </section> - -</erlref> - - diff --git a/lib/inets/doc/src/ftp_client.xml b/lib/inets/doc/src/ftp_client.xml deleted file mode 100644 index 990dd68604..0000000000 --- a/lib/inets/doc/src/ftp_client.xml +++ /dev/null @@ -1,86 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE chapter SYSTEM "chapter.dtd"> - -<chapter> - <header> - <copyright> - <year>2004</year><year>2016</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>FTP Client</title> - <prepared>Ingela Anderton Andin</prepared> - <responsible></responsible> - <docno></docno> - <approved></approved> - <checked></checked> - <date></date> - <rev></rev> - <file>ftp_client.xml</file> - </header> - - <section> - <title>Getting Started</title> - - <p>FTP clients are considered to be rather temporary. Thus, - they are only started and stopped during runtime and cannot - be started at application startup. - The FTP client API is designed to allow some functions to - return intermediate results. This implies that only the process - that started the FTP client can access it with - preserved sane semantics. - If the process that started the FTP session - dies, the FTP client process terminates.</p> - - <p>The client supports IPv6 as long as the underlying mechanisms - also do so.</p> - - <p>The following is a simple example of an FTP session, where - the user <c>guest</c> with password <c>password</c> logs on to - the remote host <c>erlang.org</c>:</p> - <code type="erl"><![CDATA[ - 1> inets:start(). - ok - 2> {ok, Pid} = inets:start(ftpc, [{host, "erlang.org"}]). - {ok,<0.22.0>} - 3> ftp:user(Pid, "guest", "password"). - ok - 4> ftp:pwd(Pid). - {ok, "/home/guest"} - 5> ftp:cd(Pid, "appl/examples"). - ok - 6> ftp:lpwd(Pid). - {ok, "/home/fred"}. - 7> ftp:lcd(Pid, "/home/eproj/examples"). - ok - 8> ftp:recv(Pid, "appl.erl"). - ok - 9> inets:stop(ftpc, Pid). - ok - ]]></code> - <p> The file - <c>appl.erl</c> is transferred from the remote to the local - host. When the session is opened, the current directory at - the remote host is <c>/home/guest</c>, and <c>/home/fred</c> - at the local host. Before transferring the file, the current - local directory is changed to <c>/home/eproj/examples</c>, and - the remote directory is set to - <c>/home/guest/appl/examples</c>.</p> - </section> -</chapter> - - diff --git a/lib/inets/doc/src/httpc.xml b/lib/inets/doc/src/httpc.xml index 1ef93de301..521ad6a015 100644 --- a/lib/inets/doc/src/httpc.xml +++ b/lib/inets/doc/src/httpc.xml @@ -288,8 +288,7 @@ {autoredirect, boolean()} | {proxy_auth, {userstring(), passwordstring()}} | {version, http_version()} | - {relaxed, boolean()} | - {url_encode, boolean()}</v> + {relaxed, boolean()}</v> <v>timeout() = integer() >= 0 | infinity</v> <v>Options = options()</v> <v>options() = [option()]</v> @@ -313,8 +312,7 @@ <v>Body = string() | binary()</v> <v>Profile = profile() | pid()</v> <d>When started <c>stand_alone</c> only the pid can be used.</d> - <v>Reason = {connect_failed, term()} | - {send_failed, term()} | term()</v> + <v>Reason = term()</v> </type> <desc> @@ -380,13 +378,6 @@ from the HTTP-standard are enabled.</p> <p>Default is <c>false</c>.</p> </item> - - <tag><c><![CDATA[url_encode]]></c></tag> - <item> - <p>Applies Percent-encoding, also known as URL encoding on the - URL.</p> - <p>Default is <c>false</c>.</p> - </item> </taglist> <p>Option (<c>option()</c>) details:</p> diff --git a/lib/inets/doc/src/inets.xml b/lib/inets/doc/src/inets.xml index 137381cbe9..eb4e51584f 100644 --- a/lib/inets/doc/src/inets.xml +++ b/lib/inets/doc/src/inets.xml @@ -188,10 +188,9 @@ <section> <title>SEE ALSO</title> - <p><seealso marker="ftp">ftp(3)</seealso>, - <seealso marker="httpc">httpc(3)</seealso>, - <seealso marker="httpd">httpd(3)</seealso>, - <seealso marker="tftp">tftp(3)</seealso></p> + <p><seealso marker="httpc">httpc(3)</seealso>, + <seealso marker="httpd">httpd(3)</seealso> + </p> </section> </erlref> diff --git a/lib/inets/doc/src/introduction.xml b/lib/inets/doc/src/introduction.xml index 1af2ef5dae..faf911f188 100644 --- a/lib/inets/doc/src/introduction.xml +++ b/lib/inets/doc/src/introduction.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1997</year><year>2016</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -22,12 +22,12 @@ </legalnotice> <title>Introduction</title> - <prepared>Ingela Anderton Andin</prepared> + <prepared>Péter Dimitrov</prepared> <responsible></responsible> <docno></docno> <approved></approved> <checked></checked> - <date>2004-09-28</date> + <date>2018-02-28</date> <rev>A</rev> <file>introduction.xml</file> </header> @@ -37,8 +37,6 @@ <p><c>Inets</c> is a container for Internet clients and servers including the following:</p> <list type="bulleted"> - <item>An FTP client</item> - <item>A TFTP client and server</item> <item>An <term id="HTTP"></term> client and server</item> </list> <p>The HTTP client and server are HTTP 1.1 compliant as @@ -50,7 +48,7 @@ <title>Prerequisites</title> <p>It is assumed that the reader is familiar with the Erlang programming language, concepts of OTP, and has a basic - understanding of the FTP, TFTP, and HTTP protocols.</p> + understanding of and HTTP protocol.</p> </section> </chapter> diff --git a/lib/inets/doc/src/notes.xml b/lib/inets/doc/src/notes.xml index 672ef49c0c..10dd26322c 100644 --- a/lib/inets/doc/src/notes.xml +++ b/lib/inets/doc/src/notes.xml @@ -1781,7 +1781,7 @@ <list> <item> <p>[ftpc] Add a config option to specify a - <seealso marker="ftp#dtimeout">data connect timeout</seealso>. + <seealso marker="ftp:ftp#dtimeout">data connect timeout</seealso>. That is how long the ftp client will wait for the server to connect to the data socket. If this timeout occurs, an error will be returned to the caller and the ftp client process will be @@ -2664,10 +2664,10 @@ <item> <p>It is now also possible to start a standalone FTP client process using the re-introduced - <seealso marker="ftp#open">ftp:open</seealso> + <seealso marker="ftp:ftp#open">ftp:open</seealso> function. </p> <p>This is an alternative to starting the client using the - <seealso marker="ftp#service_start">inets service framework</seealso>. </p> + <seealso marker="ftp:ftp#service_start">inets service framework</seealso>. </p> <p>The old <c>ftp:open/1</c>, undocumented, function, caused the client to be hooken into the inets service supervision framework. This is <em>no</em> longer the @@ -2680,10 +2680,10 @@ flag), and only used IPv4 if this did not work. This has now been <em>changed</em>. </p> <p>A new option, - <seealso marker="ftp#ipfamily">ipfamily</seealso>, + <seealso marker="ftp:ftp#ipfamily">ipfamily</seealso>, has been introduced, with the default value <c>inet</c> (IPv4). </p> - <p>See <seealso marker="ftp#open">ftp:open</seealso> + <p>See <seealso marker="ftp:ftp#open">ftp:open</seealso> for more info.</p> <p>*** POTENTIAL INCOMPATIBILITY ***</p> </item> @@ -2717,9 +2717,9 @@ <item> <p>[ftpc] - The - <seealso marker="ftp#ls2">ls/2</seealso> function (LIST command) + <seealso marker="ftp:ftp#ls2">ls/2</seealso> function (LIST command) and the - <seealso marker="ftp#nlist2">nlist/2</seealso> function + <seealso marker="ftp:ftp#nlist2">nlist/2</seealso> function (NLST command) with wildcards did not work properly. </p> diff --git a/lib/inets/doc/src/part.xml b/lib/inets/doc/src/part.xml index f777481b5c..b9c8ed674c 100644 --- a/lib/inets/doc/src/part.xml +++ b/lib/inets/doc/src/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>2004</year><year>2016</year> + <year>2004</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -23,9 +23,9 @@ </legalnotice> <title>Inets User's Guide</title> - <prepared>Ingela Anderton Andin</prepared> + <prepared>Péter Dimitrov</prepared> <docno></docno> - <date>2002-09-17</date> + <date>2018-02-28</date> <rev>A</rev> <file>part.sgml</file> </header> @@ -33,8 +33,6 @@ <p>The <c>Inets</c> application provides a set of Internet-related services as follows:</p> <list type="bulleted"> - <item>An FTP client</item> - <item>A TFTP client and server</item> <item>An <term id="HTTP"></term> client and server</item> </list> <p>The HTTP client and server are HTTP 1.1 compliant as @@ -43,7 +41,6 @@ </description> <xi:include href="introduction.xml"/> <xi:include href="inets_services.xml"/> - <xi:include href="ftp_client.xml"/> <xi:include href="http_client.xml"/> <xi:include href="http_server.xml"/> </part> diff --git a/lib/inets/doc/src/ref_man.xml b/lib/inets/doc/src/ref_man.xml index 27021ea09a..58c1a651f9 100644 --- a/lib/inets/doc/src/ref_man.xml +++ b/lib/inets/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1997</year><year>2015</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -23,20 +23,16 @@ </legalnotice> <title>Inets Reference Manual</title> - <prepared>Joakim Grebenö</prepared> + <prepared>Péter Dimitrov</prepared> <docno></docno> - <date>1997-07-16</date> + <date>2018-02-28</date> <rev>2.1</rev> <file>ref_man.xml</file> </header> <description> - <p><c>Inets</c> is a container for Internet clients and - servers. An FTP client, an HTTP client and server, and - a TFTP client and server are incorporated in <c>Inets</c>.</p> + <p><c>Inets</c> is a container for an HTTP client and server.</p> </description> <xi:include href="inets.xml"/> - <xi:include href="ftp.xml"/> - <xi:include href="tftp.xml"/> <xi:include href="httpc.xml"/> <xi:include href="httpd.xml"/> <xi:include href="httpd_custom_api.xml"/> diff --git a/lib/inets/doc/src/tftp.xml b/lib/inets/doc/src/tftp.xml deleted file mode 100644 index 10398f5088..0000000000 --- a/lib/inets/doc/src/tftp.xml +++ /dev/null @@ -1,647 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>2006</year><year>2015</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. - - </legalnotice> - - <title>tftp</title> - <prepared></prepared> - <docno></docno> - <date></date> - <rev></rev> - </header> - <module>tftp</module> - <modulesummary>Trivial FTP.</modulesummary> - <description> - <p>This is a complete implementation of the following IETF standards:</p> - <list type="bulleted"> - <item>RFC 1350, The TFTP Protocol (revision 2)</item> - <item>RFC 2347, TFTP Option Extension</item> - <item>RFC 2348, TFTP Blocksize Option</item> - <item>RFC 2349, TFTP Timeout Interval and Transfer Size Options</item> - </list> - <p>The only feature that not is implemented is - the "netascii" transfer mode.</p> - <p>The <seealso marker="#start/1">start/1</seealso> function starts - a daemon process listening for UDP packets on a port. When it - receives a request for read or write, it spawns a temporary server - process handling the transfer.</p> - <p>On the client side, - function <seealso marker="#read_file/3">read_file/3</seealso> - and <seealso marker="#write_file/3">write_file/3</seealso> - spawn a temporary client process establishing - contact with a TFTP daemon and perform the file transfer.</p> - <p><c>tftp</c> uses a callback module to handle the file - transfer. Two such callback modules are provided, - <c>tftp_binary</c> and <c>tftp_file</c>. See - <seealso marker="#read_file/3">read_file/3</seealso> and - <seealso marker="#write_file/3">write_file/3</seealso> for details. - You can also implement your own callback modules, see - <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso>. - A callback module provided by - the user is registered using option <c>callback</c>, see - <seealso marker="#options">DATA TYPES</seealso>.</p> - </description> - - <section> - <title>TFTP SERVER SERVICE START/STOP</title> - - <p>A TFTP server can be configured to start statically when starting - the <c>Inets</c> application. Alternatively, it can be started dynamically - (when <c>Inets</c> is already started) by calling the <c>Inets</c> application - API <c>inets:start(tftpd, ServiceConfig)</c> or - <c>inets:start(tftpd, ServiceConfig, How)</c>, - see <seealso marker="inets">inets(3)</seealso> for details. - The <c>ServiceConfig</c> for TFTP is described in - the <seealso marker="#options">DATA TYPES</seealso> - section.</p> - - <p>The TFTP server can be stopped using <c>inets:stop(tftpd, Pid)</c>, - see <seealso marker="inets">inets(3)</seealso> for details.</p> - - <p>The TPFT client is of such a temporary nature that it is not - handled as a service in the <c>Inets</c> service framework.</p> - - </section> - - <section> - <marker id="options"></marker> - <title>DATA TYPES</title> - <p><c>ServiceConfig = Options</c></p> - <p><c>Options = [option()]</c></p> - <p>Most of the options are common for both the client and the server - side, but some of them differs a little. - The available <c>option()</c>s are as follows:</p> - <taglist> - <tag><c>{debug, Level}</c></tag> - <item> - <p><c>Level = none | error | warning | brief | normal | verbose | all</c></p> - <p>Controls the level of debug printouts. - Default is <c>none</c>.</p> - </item> - <tag><c>{host, Host}</c></tag> - <item> - <p><c>Host = hostname()</c>, see - <seealso marker="kernel:inet">inet(3)</seealso>.</p> - <p>The name or IP address of the host where the TFTP daemon - resides. This option is only used by the client.</p> - </item> - <tag><c>{port, Port}</c></tag> - <item> - <p><c>Port = int()</c></p> - <p>The TFTP port where the daemon listens. Defaults is - the standardized number 69. On the server side, it can - sometimes make sense to set it to 0, meaning that - the daemon just picks a free port (which one is - returned by function <c>info/1</c>).</p> - <p>If a socket is connected already, option - <c>{udp, [{fd, integer()}]}</c> can be used to pass the - open file descriptor to <c>gen_udp</c>. This can be automated - by using a command-line argument stating the - prebound file descriptor number. For example, if the - port is 69 and file descriptor 22 is opened by - <c>setuid_socket_wrap</c>, the command-line argument - "-tftpd_69 22" triggers the prebound file - descriptor 22 to be used instead of opening port 69. - The UDP option <c>{udp, [{fd, 22}]}</c> is automatically added. - See <c>init:get_argument/</c> about command-line arguments and - <c>gen_udp:open/2</c> about UDP options.</p> - </item> - <tag><c>{port_policy, Policy}</c></tag> - <item> - <p><c>Policy = random | Port | {range, MinPort, MaxPort}</c></p> - <p><c>Port = MinPort = MaxPort = int()</c></p> - <p>Policy for the selection of the temporary port that is used - by the server/client during the file transfer. Default is - <c>random</c>, which is the standardized policy. With this - policy a randomized free port is used. A single port or a range - of ports can be useful if the protocol passes through a - firewall.</p> - </item> - <tag><c>{udp, Options}</c></tag> - <item> - <p><c>Options = [Opt]</c>, see - <seealso marker="kernel:gen_udp#open/1">gen_udp:open/2</seealso>.</p> - </item> - <tag><c>{use_tsize, Bool}</c></tag> - <item> - <p><c>Bool = bool()</c></p> - <p>Flag for automated use of option <c>tsize</c>. With - this set to <c>true</c>, the <c>write_file/3</c> client - determines the filesize and sends it to the server as - the standardized <c>tsize</c> option. A <c>read_file/3</c> - client acquires only a filesize from the server by sending - a zero <c>tsize</c>.</p> - </item> - <tag><c>{max_tsize, MaxTsize}</c></tag> - <item> - <p><c>MaxTsize = int() | infinity</c></p> - <p>Threshold for the maximal filesize in bytes. The transfer - is aborted if the limit is exceeded. - Default is <c>infinity</c>.</p> - </item> - <tag><c>{max_conn, MaxConn}</c></tag> - <item> - <p><c>MaxConn = int() | infinity</c></p> - <p>Threshold for the maximal number of active connections. - The daemon rejects the setup of new connections if - the limit is exceeded. Default is <c>infinity</c>.</p> - </item> - <tag><c>{TftpKey, TftpVal}</c></tag> - <item> - <p><c>TftpKey = string()</c> <br></br> -<c>TftpVal = string()</c></p> - <p>Name and value of a TFTP option.</p> - </item> - <tag><c>{reject, Feature}</c></tag> - <item> - <p><c>Feature = Mode | TftpKey</c> <br></br> -<c> Mode = read | write</c> <br></br> -<c> TftpKey = string()</c></p> - <p>Controls which features to reject. This is - mostly useful for the server as it can restrict the use - of certain TFTP options or read/write access.</p> - </item> - <tag><c>{callback, {RegExp, Module, State}}</c></tag> - <item> - <p><c>RegExp = string()</c> <br></br> -<c>Module = atom()</c> <br></br> -<c>State = term()</c></p> - <p>Registration of a callback module. When a file is to be - transferred, its local filename is matched to the regular - expressions of the registered callbacks. The first matching - callback is used during the transfer. See - <seealso marker="#read_file/3">read_file/3</seealso> and - <seealso marker="#write_file/3">write_file/3</seealso>. - </p> - <p>The callback module must implement the <c>tftp</c> behavior, see - <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso>.</p> - </item> - - <tag><c>{logger, Module}</c></tag> - <item> - <p><c>Module = module()()</c></p> - - <p>Callback module for customized logging of errors, warnings, and - info messages. The callback module must implement the - <c>tftp_logger</c> behavior, see - <seealso marker="#tftp_logger">LOGGER FUNCTIONS</seealso>. - The default module is <c>tftp_logger</c>.</p> - </item> - - <tag><c>{max_retries, MaxRetries}</c></tag> - <item> - <p><c>MaxRetries = int()</c></p> - - <p>Threshold for the maximal number of retries. By default - the server/client tries to resend a message up to - five times when the time-out expires.</p> - </item> - </taglist> - </section> - - <funcs> - <func> - <name>change_config(daemons, Options) -> [{Pid, Result}]</name> - <fsummary>Changes configuration for all daemons. - </fsummary> - <type> - <v>Options = [option()]</v> - <v>Pid = pid()</v> - <v>Result = ok | {error, Reason}</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Changes configuration for all TFTP daemon processes. </p> - </desc> - </func> - - <func> - <name>change_config(servers, Options) -> [{Pid, Result}]</name> - <fsummary>Changes configuration for all servers. - </fsummary> - <type> - <v>Options = [option()]</v> - <v>Pid = pid()</v> - <v>Result = ok | {error, Reason}</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Changes configuration for all TFTP server processes.</p> - </desc> - </func> - - <func> - <name>change_config(Pid, Options) -> Result</name> - <fsummary>Changes configuration for a TFTP daemon, server, - or client process.</fsummary> - <type> - <v>Pid = pid()</v> - <v>Options = [option()]</v> - <v>Result = ok | {error, Reason}</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Changes configuration for a TFTP daemon, server, or client process.</p> - </desc> - </func> - - <func> - <name>info(daemons) -> [{Pid, Options}]</name> - <fsummary>Returns information about all daemons.</fsummary> - <type> - <v>Pid = [pid()()]</v> - <v>Options = [option()]</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Returns information about all TFTP daemon processes.</p> - </desc> - </func> - - <func> - <name>info(servers) -> [{Pid, Options}]</name> - <fsummary>Returns information about all servers.</fsummary> - <type> - <v>Pid = [pid()()]</v> - <v>Options = [option()]</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Returns information about all TFTP server processes. </p> - </desc> - </func> - - <func> - <name>info(Pid) -> {ok, Options} | {error, Reason}</name> - <fsummary>Returns information about a daemon, server, or client process.</fsummary> - <type> - <v>Options = [option()]</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Returns information about a TFTP daemon, server, or client process.</p> - </desc> - </func> - - <func> - <name>read_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name> - <fsummary>Reads a (virtual) file from a TFTP server.</fsummary> - <type> - <v>RemoteFilename = string()</v> - <v>LocalFilename = binary | string()</v> - <v>Options = [option()]</v> - <v>LastCallbackState = term()</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Reads a (virtual) file <c>RemoteFilename</c> from a TFTP - server.</p> - <p>If <c>LocalFilename</c> is the atom <c>binary</c>, - <c>tftp_binary</c> is used as callback module. It concatenates - all transferred blocks and returns them as one single binary - in <c>LastCallbackState</c>.</p> - <p>If <c>LocalFilename</c> is a string and there are no - registered callback modules, <c>tftp_file</c> is used as - callback module. It writes each transferred block to the file - named <c>LocalFilename</c> and returns the number of - transferred bytes in <c>LastCallbackState</c>.</p> - <p>If <c>LocalFilename</c> is a string and there are registered - callback modules, <c>LocalFilename</c> is tested against - the regexps of these and the callback module corresponding to - the first match is used, or an error tuple is returned if no - matching regexp is found.</p> - </desc> - </func> - - <func> - <name>start(Options) -> {ok, Pid} | {error, Reason}</name> - <fsummary>Starts a daemon process.</fsummary> - <type> - <v>Options = [option()]</v> - <v>Pid = pid()</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Starts a daemon process listening for UDP packets on a - port. When it receives a request for read or write, it spawns - a temporary server process handling the actual transfer - of the (virtual) file.</p> - </desc> - </func> - - <func> - <name>write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name> - <fsummary>Writes a (virtual) file to a TFTP server.</fsummary> - <type> - <v>RemoteFilename = string()</v> - <v>LocalFilename = binary() | string()</v> - <v>Options = [option()]</v> - <v>LastCallbackState = term()</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Writes a (virtual) file <c>RemoteFilename</c> to a TFTP - server.</p> - <p>If <c>LocalFilename</c> is a binary, <c>tftp_binary</c> is - used as callback module. The binary is transferred block by - block and the number of transferred bytes is returned in - <c>LastCallbackState</c>.</p> - <p>If <c>LocalFilename</c> is a string and there are no - registered callback modules, <c>tftp_file</c> is used as - callback module. It reads the file named <c>LocalFilename</c> - block by block and returns the number of transferred bytes - in <c>LastCallbackState</c>.</p> - <p>If <c>LocalFilename</c> is a string and there are registered - callback modules, <c>LocalFilename</c> is tested against - the regexps of these and the callback module corresponding to - the first match is used, or an error tuple is returned if no - matching regexp is found.</p> - </desc> - </func> - </funcs> - - <section> - <marker id="tftp_callback"></marker> - <title>CALLBACK FUNCTIONS</title> - <p>A <c>tftp</c> callback module is to be implemented as a - <c>tftp</c> behavior and export the functions listed - in the following.</p> - <p>On the server side, the callback interaction starts with a call to - <c>open/5</c> with the registered initial callback state. - <c>open/5</c> is expected to open the (virtual) file. Then either - function <c>read/1</c> or <c>write/2</c> is invoked - repeatedly, once per transferred block. At each function call, - the state returned from the previous call is obtained. When - the last block is encountered, function <c>read/1</c> or - <c>write/2</c> is expected to close the (virtual) file - and return its last state. Function <c>abort/3</c> is only - used in error situations. Function <c>prepare/5</c> is not used on - the server side.</p> - <p>On the client side, the callback interaction is the same, but it - starts and ends a bit differently. It starts with a call to - <c>prepare/5</c> with the same arguments as <c>open/5</c> takes. - <c>prepare/5</c> is expected to validate the TFTP options - suggested by the user and to return the subset of them that it - accepts. Then the options are sent to the server, which performs - the same TFTP option negotiation procedure. The options that are - accepted by the server are forwarded to function <c>open/5</c> - on the client side. On the client side, function <c>open/5</c> - must accept all option as-is or reject the transfer. Then - the callback interaction follows the same pattern as described - for the server side. When the last block is encountered in - <c>read/1</c> or <c>write/2</c>, the returned state is forwarded to - the user and returned from <c>read_file</c>/3 or - <c>write_file/3</c>.</p> - - <p> If a callback (performing the file access - in the TFTP server) takes too long time (more than - the double TFTP time-out), the server aborts the - connection and sends an error reply to the client. - This implies that the server releases resources - attached to the connection faster than before. The - server simply assumes that the client has given - up.</p> - - <p>If the TFTP server receives yet another request from - the same client (same host and port) while it - already has an active connection to the client, it - ignores the new request if the request is - equal to the first one (same filename and options). - This implies that the (new) client will be served - by the already ongoing connection on the server - side. By not setting up yet another connection, in - parallel with the ongoing one, the server - consumes less resources.</p> - - <marker id="prepare"></marker> - </section> - - <funcs> - <func> - <name>Module:abort(Code, Text, State) -> ok</name> - <fsummary>Aborts the file transfer.</fsummary> - <type> - <v>Code = undef | enoent | eacces | enospc</v> - <v> | badop | eexist | baduser | badopt</v> - <v> | int()</v> - <v>Text = string()</v> - <v>State = term()</v> - </type> - <desc> - <p>Invoked when the file transfer is aborted.</p> - <p>The callback function is expected to clean - up its used resources after the aborted file - transfer, such as closing open file - descriptors and so on. The function is not - invoked if any of the other callback - functions returns an error, as it is - expected that they already have cleaned up - the necessary resources. However, it is - invoked if the functions fail (crash).</p> - </desc> - </func> - - <func> - <name>Module:open(Peer, Access, Filename, Mode, SuggestedOptions, State) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</name> - <fsummary>Opens a file for read or write access.</fsummary> - <type> - <v>Peer = {PeerType, PeerHost, PeerPort}</v> - <v>PeerType = inet | inet6</v> - <v>PeerHost = ip_address()</v> - <v>PeerPort = integer()</v> - <v>Access = read | write</v> - <v>Filename = string()</v> - <v>Mode = string()</v> - <v>SuggestedOptions = AcceptedOptions = [{Key, Value}]</v> - <v> Key = Value = string()</v> - <v>State = InitialState | term()</v> - <v> InitialState = [] | [{root_dir, string()}]</v> - <v>NewState = term()</v> - <v>Code = undef | enoent | eacces | enospc</v> - <v> | badop | eexist | baduser | badopt</v> - <v> | int()</v> - <v>Text = string()</v> - </type> - <desc> - <p>Opens a file for read or write access.</p> - <p>On the client side, where the <c>open/5</c> call has been - preceded by a call to <c>prepare/5</c>, all options must be - accepted or rejected.</p> - <p>On the server side, where there is no preceding - <c>prepare/5</c> call, no new options can be added, but - those present in <c>SuggestedOptions</c> can be - omitted or replaced with new values in <c>AcceptedOptions</c>.</p> - - <marker id="read"></marker> - </desc> - </func> - - <func> - <name>Module:prepare(Peer, Access, Filename, Mode, SuggestedOptions, InitialState) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</name> - <fsummary>Prepares to open a file on the client side.</fsummary> - <type> - <v>Peer = {PeerType, PeerHost, PeerPort}</v> - <v>PeerType = inet | inet6</v> - <v>PeerHost = ip_address()</v> - <v>PeerPort = integer()</v> - <v>Access = read | write</v> - <v>Filename = string()</v> - <v>Mode = string()</v> - <v>SuggestedOptions = AcceptedOptions = [{Key, Value}]</v> - <v> Key = Value = string()</v> - <v>InitialState = [] | [{root_dir, string()}]</v> - <v>NewState = term()</v> - <v>Code = undef | enoent | eacces | enospc</v> - <v> | badop | eexist | baduser | badopt</v> - <v> | int()</v> - <v>Text = string()</v> - </type> - <desc> - <p>Prepares to open a file on the client side.</p> - <p>No new options can be added, but those present in - <c>SuggestedOptions</c> can be omitted or replaced with new - values in <c>AcceptedOptions</c>.</p> - <p>This is followed by a call to <c>open/4</c> before any - read/write access is performed. <c>AcceptedOptions</c> is - sent to the server, which replies with the options that it - accepts. These are then forwarded to <c>open/4</c> as - <c>SuggestedOptions</c>.</p> - - <marker id="open"></marker> - </desc> - </func> - - <func> - <name>Module:read(State) -> {more, Bin, NewState} | {last, Bin, FileSize} | {error, {Code, Text}}</name> - <fsummary>Reads a chunk from the file.</fsummary> - <type> - <v>State = NewState = term()</v> - <v>Bin = binary()</v> - <v>FileSize = int()</v> - <v>Code = undef | enoent | eacces | enospc</v> - <v> | badop | eexist | baduser | badopt</v> - <v> | int()</v> - <v>Text = string()</v> - </type> - <desc> - <p>Reads a chunk from the file.</p> - <p>The callback function is expected to close - the file when the last file chunk is - encountered. When an error is encountered, - the callback function is expected to clean - up after the aborted file transfer, such as - closing open file descriptors, and so on. In both - cases there will be no more calls to any of - the callback functions.</p> - - <marker id="write"></marker> - </desc> - </func> - - <func> - <name>Module:write(Bin, State) -> {more, NewState} | {last, FileSize} | {error, {Code, Text}}</name> - <fsummary>Writes a chunk to the file.</fsummary> - <type> - <v>Bin = binary()</v> - <v>State = NewState = term()</v> - <v>FileSize = int()</v> - <v>Code = undef | enoent | eacces | enospc</v> - <v> | badop | eexist | baduser | badopt</v> - <v> | int()</v> - <v>Text = string()</v> - </type> - <desc> - <p>Writes a chunk to the file.</p> - <p>The callback function is expected to close - the file when the last file chunk is - encountered. When an error is encountered, - the callback function is expected to clean - up after the aborted file transfer, such as - closing open file descriptors, and so on. In both - cases there will be no more calls to any of - the callback functions.</p> - - <marker id="abort"></marker> - </desc> - </func> - </funcs> - - <section> - <marker id="tftp_logger"></marker> - <title>LOGGER FUNCTIONS</title> - - <p>A <c>tftp_logger</c> callback module is to be implemented as a - <c>tftp_logger</c> behavior and export the following functions:</p> - - <marker id="error_msg"></marker> - </section> - - <funcs> - <func> - <name>Logger:error_msg(Format, Data) -> ok | exit(Reason)</name> - <fsummary>Logs an error message.</fsummary> - <type> - <v>Format = string()</v> - <v>Data = [term()]</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Logs an error message. - See <c>error_logger:error_msg/2</c> for details.</p> - - <marker id="warning_msg"></marker> - </desc> - </func> - - <func> - <name>Logger:info_msg(Format, Data) -> ok | exit(Reason)</name> - <fsummary>Logs an info message.</fsummary> - <type> - <v>Format = string()</v> - <v>Data = [term()]</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Logs an info message. - See <c>error_logger:info_msg/2</c> for details.</p> - </desc> - </func> - - <func> - <name>Logger:warning_msg(Format, Data) -> ok | exit(Reason)</name> - <fsummary>Logs a warning message.</fsummary> - <type> - <v>Format = string()</v> - <v>Data = [term()]</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Logs a warning message. - See <c>error_logger:warning_msg/2</c> for details.</p> - - <marker id="info_msg"></marker> - </desc> - </func> - </funcs> -</erlref> - - |