Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
tftp - Trivial FTP
DESCRIPTION
This is a complete implementation of the following IETF standards:
* RFC 1350, The TFTP Protocol (revision 2).
* RFC 2347, TFTP Option Extension.
* RFC 2348, TFTP Blocksize Option.
* RFC 2349, TFTP Timeout Interval and Transfer Size Options.
The only feature that not is implemented in this release is the "netascii" transfer mode.
The start/1 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.
On the client side the read_file/3 and write_file/3 functions spawns a temporary client
process which establishes contact with a TFTP daemon and performs the actual transfer of
the file.
tftp uses a callback module to handle the actual file transfer. Two such callback modules
are provided, tftp_binary and tftp_file. See read_file/3 and write_file/3 for more
information about these. The user can also implement own callback modules, see CALLBACK
FUNCTIONS below. A callback module provided by the user is registered using the callback
option, see DATA TYPES below.
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 already is started) by calling the
Inets application API inets:start(tftpd, ServiceConfig), or inets:start(tftpd,
ServiceConfig, How), see inets(3erl) for details. The ServiceConfig for TFTP is described
below in the COMMON DATA TYPES section.
The TFTP server can be stopped using inets:stop(tftpd, Pid), see inets(3erl) for details.
The TPFT client is of such a temporary nature that it is not handled as a service in the
Inets service framework.
COMMON DATA TYPES
ServiceConfig = Options
Options = [option()]
option() -- see below
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:
{debug, Level}:
Level = none | error | warning | brief | normal | verbose | all
Controls the level of debug printouts. The default is none.
{host, Host}:
Host = hostname() see inet(3erl)
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. 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 info/1 function).
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 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 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.
{port_policy, Policy}:
Policy = random | Port | {range, MinPort, MaxPort}
Port = MinPort = MaxPort = int()
Policy for the selection of the temporary port which is used by the server/client
during the file transfer. It defaults to random 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 firewall.
{udp, Options}:
Options = [Opt] see gen_udp:open/2
{use_tsize, Bool}:
Bool = bool()
Flag for automated usage of the tsize option. With this set to true, the write_file/3
client will determine the filesize and send it to the server as the standardized tsize
option. A read_file/3 client will just acquire filesize from the server by sending a
zero tsize.
{max_tsize, MaxTsize}:
MaxTsize = int() | infinity
Threshold for the maximal filesize in bytes. The transfer will be aborted if the limit
is exceeded. It defaults to infinity.
{max_conn, MaxConn}:
MaxConn = int() | infinity
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 infinity.
{TftpKey, TftpVal}:
TftpKey = string()
TftpVal = string()
The name and value of a TFTP option.
{reject, Feature}:
Feature = Mode | TftpKey
Mode = read | write
TftpKey = string()
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.
{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 will be matched to the regular expressions of the registered callbacks. The
first matching callback will be used the during the transfer. See read_file/3 and
write_file/3.
The callback module must implement the tftp behavior, CALLBACK FUNCTIONS.
{logger, Module}:
Module = module()()
Callback module for customized logging of error, warning and info messages. >The
callback module must implement the tftp_logger behavior, LOGGER FUNCTIONS. The default
module is tftp_logger.
{max_retries, MaxRetries}:
MaxRetries = int()
Threshold for the maximal number of retries. By default the server/client will try to
resend a message up to 5 times when the timeout expires.
EXPORTS
start(Options) -> {ok, Pid} | {error, Reason}
Types:
Options = [option()]
Pid = pid()
Reason = term()
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.
read_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error,
Reason}
Types:
RemoteFilename = string()
LocalFilename = binary | string()
Options = [option()]
LastCallbackState = term()
Reason = term()
Reads a (virtual) file RemoteFilename from a TFTP server.
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.
write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error,
Reason}
Types:
RemoteFilename = string()
LocalFilename = binary() | string()
Options = [option()]
LastCallbackState = term()
Reason = term()
Writes a (virtual) file RemoteFilename to a TFTP server.
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.
info(daemons) -> [{Pid, Options}]
Types:
Pid = [pid()()]
Options = [option()]
Reason = term()
Returns info about all TFTP daemon processes.
info(servers) -> [{Pid, Options}]
Types:
Pid = [pid()()]
Options = [option()]
Reason = term()
Returns info about all TFTP server processes.
info(Pid) -> {ok, Options} | {error, Reason}
Types:
Options = [option()]
Reason = term()
Returns info about a TFTP daemon, server or client process.
change_config(daemons, Options) -> [{Pid, Result}]
Types:
Options = [option()]
Pid = pid()
Result = ok | {error, Reason}
Reason = term()
Changes config for all TFTP daemon processes.
change_config(servers, Options) -> [{Pid, Result}]
Types:
Options = [option()]
Pid = pid()
Result = ok | {error, Reason}
Reason = term()
Changes config for all TFTP server processes.
change_config(Pid, Options) -> Result
Types:
Pid = pid()
Options = [option()]
Result = ok | {error, Reason}
Reason = term()
Changes config for a TFTP daemon, server or client process
start() -> ok | {error, Reason}
Types:
Reason = term()
Starts the Inets application.
CALLBACK FUNCTIONS
A tftp callback module should be implemented as a tftp behavior and export the functions
listed below.
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 the read/1 or write/2 functions are 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 read/1 or write/2 functions is expected to close the
(virtual) file and return its last state. The abort/3 function is only used in error
situations. 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 return the
subset of them that it accepts. Then the options is sent to the server which will perform
the same TFTP option negotiation procedure. The options that are accepted by the server
are forwarded to the open/5 function on the client side. On the client side the open/5
function 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 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 (which performs 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 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 will simply ignore the new
request if the request is equal with 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.
EXPORTS
prepare(Peer, Access, Filename, Mode, SuggestedOptions, InitialState) -> {ok,
AcceptedOptions, NewState} | {error, {Code, Text}}
Types:
Peer = {PeerType, PeerHost, PeerPort}
PeerType = inet | inet6
PeerHost = ip_address()
PeerPort = integer()
Access = read | write
Filename = string()
Mode = string()
SuggestedOptions = AcceptedOptions = [{Key, Value}]
Key = Value = string()
InitialState = [] | [{root_dir, string()}]
NewState = term()
Code = undef | enoent | eacces | enospc
| badop | eexist | baduser | badopt
| int()
Text = string()
Prepares to open a file on the client side.
No new options may be added, but the ones that are present in SuggestedOptions may
be omitted or replaced with new values in AcceptedOptions.
Will be followed by a call to open/4 before any read/write access is performed.
AcceptedOptions is sent to the server which replies with those options that it
accepts. These will be forwarded to open/4 as SuggestedOptions.
open(Peer, Access, Filename, Mode, SuggestedOptions, State) -> {ok, AcceptedOptions,
NewState} | {error, {Code, Text}}
Types:
Peer = {PeerType, PeerHost, PeerPort}
PeerType = inet | inet6
PeerHost = ip_address()
PeerPort = integer()
Access = read | write
Filename = string()
Mode = string()
SuggestedOptions = AcceptedOptions = [{Key, Value}]
Key = Value = string()
State = InitialState | term()
InitialState = [] | [{root_dir, string()}]
NewState = term()
Code = undef | enoent | eacces | enospc
| badop | eexist | baduser | badopt
| int()
Text = string()
Opens a file for read or write access.
On the client side where the open/5 call has been preceded by a call to prepare/5,
all options must be accepted or rejected.
On the server side, where there is no preceding prepare/5 call, no new options may
be added, but the ones that are present in SuggestedOptions may be omitted or
replaced with new values in AcceptedOptions.
read(State) -> {more, Bin, NewState} | {last, Bin, FileSize} | {error, {Code, Text}}
Types:
State = NewState = term()
Bin = binary()
FileSize = int()
Code = undef | enoent | eacces | enospc
| badop | eexist | baduser | badopt
| int()
Text = string()
Read a chunk from the file.
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
etc. In both cases there will be no more calls to any of the callback functions.
write(Bin, State) -> {more, NewState} | {last, FileSize} | {error, {Code, Text}}
Types:
Bin = binary()
State = NewState = term()
FileSize = int()
Code = undef | enoent | eacces | enospc
| badop | eexist | baduser | badopt
| int()
Text = string()
Write a chunk to the file.
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
etc. In both cases there will be no more calls to any of the callback functions.
abort(Code, Text, State) -> ok
Types:
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 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).
LOGGER FUNCTIONS
A tftp_logger callback module should be implemented as a tftp_logger behavior and export
the functions listed below.
EXPORTS
error_msg(Format, Data) -> ok | exit(Reason)
Types:
Format = string()
Data = [term()]
Reason = term()
Log an error message. See error_logger:error_msg/2 for details.
warning_msg(Format, Data) -> ok | exit(Reason)
Types:
Format = string()
Data = [term()]
Reason = term()
Log a warning message. See error_logger:warning_msg/2 for details.
info_msg(Format, Data) -> ok | exit(Reason)
Types:
Format = string()
Data = [term()]
Reason = term()
Log an info message. See error_logger:info_msg/2 for details.