The only feature that not is implemented is
the "netascii" transfer mode.

The start/1 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.

On the client side,
function read_file/3
and write_file/3
spawn a temporary client process establishing
contact with a TFTP daemon and perform the file transfer.

tftp uses a callback module to handle the file
transfer. Two such callback modules are provided,
tftp_binary and tftp_file. See
read_file/3 and
write_file/3 for details.
You can also implement your own callback modules, see
CALLBACK FUNCTIONS.
A callback module provided by
the user is registered using option callback, see
DATA TYPES.

TFTP SERVER SERVICE START/STOP

A TFTP server can be configured to start statically when starting
the Inets application. Alternatively, it can be started dynamically
(when Inets is already started) by calling the Inets application
API inets:start(tftpd, ServiceConfig) or
inets:start(tftpd, ServiceConfig, How),
see inets(3) for details.
The ServiceConfig for TFTP is described in
the DATA TYPES
section.

The TFTP server can be stopped using inets:stop(tftpd, Pid),
see inets(3) for details.

The TPFT client is of such a temporary nature that it is not
handled as a service in the Inets service framework.

DATA TYPES

ServiceConfig = Options

Options = [option()]

Most of the options are common for both the client and the server
side, but some of them differs a little.
The available option()s are as follows:

The name or IP address of the host where the TFTP daemon
resides. This option is only used by the client.

{port, Port}

Port = int()

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 info/1).

If a socket is connected already, option
{udp, [{fd, integer()}]} can be used to pass the
open file descriptor to gen_udp. 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
setuid_socket_wrap, 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}]} is automatically added.
See init:get_argument/ about command-line arguments and
gen_udp:open/2 about UDP options.

{port_policy, Policy}

Policy = random | Port | {range, MinPort, MaxPort}

Port = MinPort = MaxPort = int()

Policy for the selection of the temporary port that is used
by the server/client during the file transfer. Default is
random, 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.

Flag for automated use of option tsize. With
this set to true, the write_file/3 client
determines the filesize and sends it to the server as
the standardized tsize option. A read_file/3
client acquires only a filesize from the server by sending
a zero tsize.

{max_tsize, MaxTsize}

MaxTsize = int() | infinity

Threshold for the maximal filesize in bytes. The transfer
is aborted if the limit is exceeded.
Default is infinity.

{max_conn, MaxConn}

MaxConn = int() | infinity

Threshold for the maximal number of active connections.
The daemon rejects the setup of new connections if
the limit is exceeded. Default is infinity.

{TftpKey, TftpVal}

TftpKey = string()TftpVal = string()

Name and value of a TFTP option.

{reject, Feature}

Feature = Mode | TftpKey Mode = read | write TftpKey = string()

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.

{callback, {RegExp, Module, State}}

RegExp = string()Module = atom()State = term()

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
read_file/3 and
write_file/3.

If LocalFilename is the atom binary,
tftp_binary is used as callback module. It concatenates
all transferred blocks and returns them as one single binary
in LastCallbackState.

If LocalFilename is a string and there are no
registered callback modules, tftp_file is used as
callback module. It writes each transferred block to the file
named LocalFilename and returns the number of
transferred bytes in LastCallbackState.

If LocalFilename is a string and there are registered
callback modules, LocalFilename 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.

start(Options) -> {ok, Pid} | {error, Reason}

Options = [option()]

Pid = pid()

Reason = term()

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.

If LocalFilename is a binary, tftp_binary is
used as callback module. The binary is transferred block by
block and the number of transferred bytes is returned in
LastCallbackState.

If LocalFilename is a string and there are no
registered callback modules, tftp_file is used as
callback module. It reads the file named LocalFilename
block by block and returns the number of transferred bytes
in LastCallbackState.

If LocalFilename is a string and there are registered
callback modules, LocalFilename 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.

CALLBACK FUNCTIONS

A tftp callback module is to be implemented as a
tftp behavior and export the functions listed
in the following.

On the server side, the callback interaction starts with a call to
open/5 with the registered initial callback state.
open/5 is expected to open the (virtual) file. Then either
function read/1 or write/2 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 read/1 or
write/2 is expected to close the (virtual) file
and return its last state. Function abort/3 is only
used in error situations. Function prepare/5 is not used on
the server side.

On the client side, the callback interaction is the same, but it
starts and ends a bit differently. It starts with a call to
prepare/5 with the same arguments as open/5 takes.
prepare/5 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 open/5
on the client side. On the client side, function open/5
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
read/1 or write/2, the returned state is forwarded to
the user and returned from read_file/3 or
write_file/3.

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.

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.

Module:abort(Code, Text, State) -> ok

Code = undef | enoent | eacces | enospc

| badop | eexist | baduser | badopt

| int()

Text = string()

State = term()

Invoked when the file transfer is aborted.

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).

No new options can be added, but those present in
SuggestedOptions can be omitted or replaced with new
values in AcceptedOptions.

This is followed by a call to open/4 before any
read/write access is performed. AcceptedOptions is
sent to the server, which replies with the options that it
accepts. These are then forwarded to open/4 as
SuggestedOptions.

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.

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.

LOGGER FUNCTIONS

A tftp_logger callback module is to be implemented as a
tftp_logger behavior and export the following functions: