diff options
Diffstat (limited to 'lib/inets/doc/src/tftp.xml')
| -rw-r--r-- | lib/inets/doc/src/tftp.xml | 576 |
1 files changed, 281 insertions, 295 deletions
diff --git a/lib/inets/doc/src/tftp.xml b/lib/inets/doc/src/tftp.xml index 42a65ed0c5..00d9d53376 100644 --- a/lib/inets/doc/src/tftp.xml +++ b/lib/inets/doc/src/tftp.xml @@ -8,16 +8,17 @@ <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + 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> @@ -28,173 +29,170 @@ <rev></rev> </header> <module>tftp</module> - <modulesummary>Trivial FTP</modulesummary> + <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> + <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 in this release is + <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 which listens for UDP packets on a port. When it - receives a request for read or write it spawns a temporary server - process which handles the actual transfer of the file.</p> - <p>On the client side - the <seealso marker="#read_file/3">read_file/3</seealso> + 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> - functions spawns a temporary client process which establishes - contact with a TFTP daemon and performs the actual transfer of - the file.</p> - <p><c>tftp</c> uses a callback module to handle the actual file + 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 - more information about these. The user can also implement own - callback modules, see <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso> below. A callback module provided by - the user is registered using the <c>callback</c> option, see - <seealso marker="#options">DATA TYPES</seealso> below.</p> + <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> + <title>TFTP SERVER SERVICE START/STOP</title> <p>A TFTP server can be configured to start statically when starting - the Inets application. Alternatively it can be started dynamically - (when Inets already is started) by calling the Inets application API - <c>inets:start(tftpd, ServiceConfig)</c>, or + 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 below in - the <seealso marker="#options">COMMON DATA TYPES</seealso> + 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 Inets service framework.</p> + handled as a service in the <c>Inets</c> service framework.</p> </section> <section> <marker id="options"></marker> - <title>COMMON DATA TYPES</title> - <pre> - ServiceConfig = Options - Options = [option()] - option() -- see below - </pre> + <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. Here are the available - options:</p> + 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. The default is - <c>none</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><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. It defaults to - the standardized number 69. On the server side it may - sometimes make sense to set it to 0, which means that - the daemon just will pick a free port (which one is - returned by the <c>info/1</c> function).</p> - <p>If a socket has somehow already has been connected, the - {udp, [{fd, integer()}]} option can be used to pass the - open file descriptor to gen_udp. This can be automated - a bit by using a command line argument stating the + <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 the file descriptor 22 has been opened by - setuid_socket_wrap. Then the command line argument - "-tftpd_69 22" will trigger the prebound file + 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 {udp, [{fd, 22}]} automatically be added. - See init:get_argument/ about command line arguments and - gen_udp:open/2 about UDP options.</p> + 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> <br></br> -<c>Port = MinPort = MaxPort = int()</c></p> - <p>Policy for the selection of the temporary port which is used - by the server/client during the file transfer. It defaults to - <c>random</c> which is the standardized policy. With this - policy a randomized free port used. A single port or a range - of ports can be useful if the protocol should pass through a + <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> + <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 usage of the <c>tsize</c> option. With - this set to true, the <c>write_file/3</c> client will - determine the filesize and send it to the server as + <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 will just acquire filesize from the server by sending + 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 - will be aborted if the limit is exceeded. It defaults to - <c>infinity</c>.</p> + 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 will reject the setup of new connections if - the limit is exceeded. It defaults to <c>infinity</c>.</p> + 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>The name and value of a TFTP option.</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>Control which features that should be rejected. This is - mostly useful for the server as it may restrict usage of - certain TFTP options or read/write access.</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> +<c>State = term()</c></p> <p>Registration of a callback module. When a file is to be - transferred, its local filename will be matched to the regular + transferred, its local filename is matched to the regular expressions of the registered callbacks. The first matching - callback will be used the during the transfer. See + 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, + <p>The callback module must implement the <c>tftp</c> behavior, see <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso>.</p> </item> @@ -202,9 +200,9 @@ <item> <p><c>Module = module()()</c></p> - <p>Callback module for customized logging of error, warning and - info messages. >The callback module must implement the - <c>tftp_logger</c> behavior, + <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> @@ -214,8 +212,8 @@ <p><c>MaxRetries = int()</c></p> <p>Threshold for the maximal number of retries. By default - the server/client will try to resend a message up to - <c>5</c> times when the timeout expires.</p> + the server/client tries to resend a message up to + five times when the time-out expires.</p> </item> </taglist> @@ -223,98 +221,67 @@ </section> <funcs> + <marker id="change_config_daemons"></marker> <func> - <name>start(Options) -> {ok, Pid} | {error, Reason}</name> - <fsummary>Start a daemon process</fsummary> + <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>Starts a daemon process which listens for udp packets on a - port. When it receives a request for read or write it spawns - a temporary server process which handles the actual transfer - of the (virtual) file.</p> + <p>Changes configuration for all TFTP daemon processes. </p> - <marker id="read_file"></marker> + <marker id="change_config_servers"></marker> </desc> </func> <func> - <name>read_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name> - <fsummary>Read a (virtual) file from a TFTP server</fsummary> + <name>change_config(servers, Options) -> [{Pid, Result}]</name> + <fsummary>Changes configuration for all servers. + </fsummary> <type> - <v>RemoteFilename = string()</v> - <v>LocalFilename = binary | string()</v> <v>Options = [option()]</v> - <v>LastCallbackState = term()</v> + <v>Pid = pid()</v> + <v>Result = ok | {error, Reason}</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> + <p>Changes configuration for all TFTP server processes.</p> - <marker id="write_file"></marker> + <marker id="change_config_pid"></marker> + </desc> </func> <func> - <name>write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name> - <fsummary>Write a (virtual) file to a TFTP server</fsummary> + <name>change_config(Pid, Options) -> Result</name> + <fsummary>Changes configuration for a TFTP daemon, server, + or client process.</fsummary> <type> - <v>RemoteFilename = string()</v> - <v>LocalFilename = binary() | string()</v> + <v>Pid = pid()</v> <v>Options = [option()]</v> - <v>LastCallbackState = term()</v> + <v>Result = ok | {error, Reason}</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> - + <p>Changes configuration for a TFTP daemon, server, or client process.</p> <marker id="info_daemons"></marker> </desc> </func> - + <func> <name>info(daemons) -> [{Pid, Options}]</name> - <fsummary>Return information about all daemons</fsummary> + <fsummary>Returns information about all daemons.</fsummary> <type> <v>Pid = [pid()()]</v> <v>Options = [option()]</v> <v>Reason = term()</v> </type> <desc> - <p>Returns info about all TFTP daemon processes. </p> + <p>Returns information about all TFTP daemon processes.</p> <marker id="info_servers"></marker> </desc> @@ -322,14 +289,14 @@ <func> <name>info(servers) -> [{Pid, Options}]</name> - <fsummary>Return information about all servers</fsummary> + <fsummary>Returns information about all servers.</fsummary> <type> <v>Pid = [pid()()]</v> <v>Options = [option()]</v> <v>Reason = term()</v> </type> <desc> - <p>Returns info about all TFTP server processes. </p> + <p>Returns information about all TFTP server processes. </p> <marker id="info_pid"></marker> </desc> @@ -337,117 +304,136 @@ <func> <name>info(Pid) -> {ok, Options} | {error, Reason}</name> - <fsummary>Return information about a daemon, server or client process</fsummary> + <fsummary>Returns information about a daemon, server, or client process.</fsummary> <type> <v>Options = [option()]</v> <v>Reason = term()</v> </type> <desc> - <p>Returns info about a TFTP daemon, server or client process.</p> - - <marker id="change_config_daemons"></marker> + <p>Returns information about a TFTP daemon, server, or client process.</p> </desc> </func> - - <func> - <name>change_config(daemons, Options) -> [{Pid, Result}]</name> - <fsummary>Changes config for all daemons - </fsummary> + + <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>Pid = pid()</v> - <v>Result = ok | {error, Reason}</v> + <v>LastCallbackState = term()</v> <v>Reason = term()</v> </type> <desc> - <p>Changes config for all TFTP daemon processes. </p> - - <marker id="change_config_servers"></marker> + <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> + + <marker id="write_file"></marker> </func> - + <func> - <name>change_config(servers, Options) -> [{Pid, Result}]</name> - <fsummary>Changes config for all servers - </fsummary> + <name>start(Options) -> {ok, Pid} | {error, Reason}</name> + <fsummary>Starts a daemon process.</fsummary> <type> <v>Options = [option()]</v> <v>Pid = pid()</v> - <v>Result = ok | {error, Reason}</v> <v>Reason = term()</v> </type> <desc> - <p>Changes config for all TFTP server processes. </p> + <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> - <marker id="change_config_pid"></marker> + <marker id="read_file"></marker> </desc> </func> <func> - <name>change_config(Pid, Options) -> Result</name> - <fsummary>Changes config for a TFTP daemon, server or client process</fsummary> + <name>write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name> + <fsummary>Writes a (virtual) file to a TFTP server.</fsummary> <type> - <v>Pid = pid()</v> + <v>RemoteFilename = string()</v> + <v>LocalFilename = binary() | string()</v> <v>Options = [option()]</v> - <v>Result = ok | {error, Reason}</v> - <v>Reason = term()</v> - </type> - <desc> - <p>Changes config for a TFTP daemon, server or client process</p> - - <marker id="start2"></marker> - </desc> - </func> - - <func> - <name>start() -> ok | {error, Reason}</name> - <fsummary>Start the Inets application</fsummary> - <type> + <v>LastCallbackState = term()</v> <v>Reason = term()</v> </type> <desc> - <p>Starts the Inets application.</p> + <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 should be implemented as a - <c>tftp</c> behavior and export the functions listed below.</p> - <p>On the server side the callback interaction starts with a call to + <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 - the <c>read/1</c> or <c>write/2</c> functions are invoked - repeatedly, once per transferred block. At each function call + 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 has been encountered the <c>read/1</c> or - <c>write/2</c> functions is expected to close the (virtual) file - and return its last state. The <c>abort/3</c> function is only - used in error situations. <c>prepare/5</c> is not used on + 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 + <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 return the subset of them that it - accepts. Then the options is sent to the server which will perform + <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 the <c>open/5</c> function - on the client side. On the client side the <c>open/5</c> function - must accept all option as is or reject the transfer. Then + 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 - above 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 + 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 (which performs the file access + <p> If a callback (performing the file access in the TFTP server) takes too long time (more than - the double TFTP timeout), the server will abort the - connection and send an error reply to the client. - This implies that the server will release resources + 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> @@ -455,21 +441,45 @@ <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 - will simply ignore the new request if the request is - equal with the first one (same filename and options). + 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 will - consumer lesser resources. </p> + parallel with the ongoing one, the server + consumes less resources.</p> <marker id="prepare"></marker> </section> <funcs> - <func> - <name>prepare(Peer, Access, Filename, Mode, SuggestedOptions, InitialState) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</name> - <fsummary>Prepare to open a file on the client side</fsummary> + <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> @@ -480,7 +490,8 @@ <v>Mode = string()</v> <v>SuggestedOptions = AcceptedOptions = [{Key, Value}]</v> <v> Key = Value = string()</v> - <v>InitialState = [] | [{root_dir, 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> @@ -488,23 +499,22 @@ <v>Text = string()</v> </type> <desc> - <p>Prepares to open a file on the client side.</p> - <p>No new options may be added, but the ones that are present in - <c>SuggestedOptions</c> may be omitted or replaced with new - values in <c>AcceptedOptions</c>.</p> - <p>Will be 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 those options that it - accepts. These will be forwarded to <c>open/4</c> as - <c>SuggestedOptions</c>.</p> + <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="open"></marker> + <marker id="read"></marker> </desc> </func> - + <func> - <name>open(Peer, Access, Filename, Mode, SuggestedOptions, State) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</name> - <fsummary>Open a file for read or write access</fsummary> + <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> @@ -515,8 +525,7 @@ <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>InitialState = [] | [{root_dir, string()}]</v> <v>NewState = term()</v> <v>Code = undef | enoent | eacces | enospc</v> <v> | badop | eexist | baduser | badopt</v> @@ -524,22 +533,23 @@ <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 may be added, but - the ones that are present in <c>SuggestedOptions</c> may be - omitted or replaced with new values in <c>AcceptedOptions</c>.</p> + <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="read"></marker> + <marker id="open"></marker> </desc> </func> <func> - <name>read(State) -> {more, Bin, NewState} | {last, Bin, FileSize} | {error, {Code, Text}}</name> - <fsummary>Read a chunk from the file</fsummary> + <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> @@ -550,13 +560,13 @@ <v>Text = string()</v> </type> <desc> - <p>Read a chunk from the file.</p> + <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 + 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 etc. In both + closing open file descriptors, and so on. In both cases there will be no more calls to any of the callback functions.</p> @@ -565,8 +575,8 @@ </func> <func> - <name>write(Bin, State) -> {more, NewState} | {last, FileSize} | {error, {Code, Text}}</name> - <fsummary>Write a chunk to the file</fsummary> + <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> @@ -577,99 +587,75 @@ <v>Text = string()</v> </type> <desc> - <p>Write a chunk to the file.</p> + <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 + 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 etc. In both + 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> - - <func> - <name>abort(Code, Text, State) -> ok</name> - <fsummary>Abort 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 etc. The function will not be - invoked if any of the other callback - functions returns an error, as it is - expected that they already have cleaned up - the necessary resources. It will however be - invoked if the functions fails (crashes).</p> - </desc> - </func> </funcs> <section> <marker id="tftp_logger"></marker> <title>LOGGER FUNCTIONS</title> - <p>A <c>tftp_logger</c> callback module should be implemented as a - <c>tftp_logger</c> behavior and export the functions listed below.</p> + <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>error_msg(Format, Data) -> ok | exit(Reason)</name> - <fsummary>Log an error message</fsummary> + <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>Log an error message. - See <c>error_logger:error_msg/2 for details.</c> </p> + <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>warning_msg(Format, Data) -> ok | exit(Reason)</name> - <fsummary>Log an error message</fsummary> + <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>Log a warning message. - See <c>error_logger:warning_msg/2 for details.</c> </p> - - <marker id="info_msg"></marker> + <p>Logs an info message. + See <c>error_logger:info_msg/2</c> for details.</p> </desc> </func> - + <func> - <name>info_msg(Format, Data) -> ok | exit(Reason)</name> - <fsummary>Log an error message</fsummary> + <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>Log an info message. - See <c>error_logger:info_msg/2 for details.</c> </p> + <p>Logs a warning message. + See <c>error_logger:warning_msg/2</c> for details.</p> + + <marker id="info_msg"></marker> </desc> </func> </funcs> |