tftp(3erl) Erlang Module Definition tftp(3erl)
NAME
tftp - Trivial FTP.
DESCRIPTION
Interface module for the tftp application.
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 fol-
lows:
{debug, Level}:
Level = none | error | warning | brief | normal | verbose | all
Controls the level of debug printouts. 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. Defaults is the standard-
ized 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 de-
scriptor 22 is opened by setuid_socket_wrap, the command-line argu-
ment "-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 proto-
col passes through a firewall.
{udp, Options}:
Options = [Opt], see gen_udp:open/2.
{use_tsize, Bool}:
Bool = bool()
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 ac-
quires 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. De-
fault 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 trans-
ferred, its local filename is matched to the regular expressions of
the registered callbacks. The first matching callback is used dur-
ing the transfer. See read_file/3 and write_file/3.
The callback module must implement the tftp behavior, see CALLBACK
FUNCTIONS.
{logger, Module}:
Module = module()
Callback module for customized logging of errors, warnings, and
info messages. The callback module must implement the tftp_logger
behavior, see 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 tries to resend a message up to five times when the
time-out expires.
EXPORTS
change_config(daemons, Options) -> [{Pid, Result}]
Types:
Options = [option()]
Pid = pid()
Result = ok | {error, Reason}
Reason = term()
Changes configuration for all TFTP daemon processes.
change_config(servers, Options) -> [{Pid, Result}]
Types:
Options = [option()]
Pid = pid()
Result = ok | {error, Reason}
Reason = term()
Changes configuration for all TFTP server processes.
change_config(Pid, Options) -> Result
Types:
Pid = pid()
Options = [option()]
Result = ok | {error, Reason}
Reason = term()
Changes configuration for a TFTP daemon, server, or client
process.
info(daemons) -> [{Pid, Options}]
Types:
Pid = [pid()]
Options = [option()]
Reason = term()
Returns information about all TFTP daemon processes.
info(servers) -> [{Pid, Options}]
Types:
Pid = [pid()]
Options = [option()]
Reason = term()
Returns information about all TFTP server processes.
info(Pid) -> {ok, Options} | {error, Reason}
Types:
Options = [option()]
Reason = term()
Returns information about a TFTP daemon, server, or client
process.
read_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallback-
State} | {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 re-
turns them as one single binary in LastCallbackState.
If LocalFilename is a string and there are no registered call-
back modules, tftp_file is used as callback module. It writes
each transferred block to the file named LocalFilename and re-
turns 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}
Types:
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 tempo-
rary server process handling the actual transfer of the (vir-
tual) file.
write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCall-
backState} | {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 call-
back 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 ex-
port 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 per-
forms 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 en-
countered 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.
EXPORTS
Module: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 de-
scriptors 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. How-
ever, it is invoked if the functions fail (crash).
Module: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 can be added, but those present in SuggestedOp-
tions can be omitted or replaced with new values in AcceptedOp-
tions.
Module:prepare(Peer, Access, Filename, Mode, SuggestedOptions, Initial-
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()
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 can be added, but those present in SuggestedOp-
tions can be omitted or replaced with new values in AcceptedOp-
tions.
This is followed by a call to open/4 before any read/write ac-
cess is performed. AcceptedOptions is sent to the server, which
replies with the options that it accepts. These are then for-
warded to open/4 as SuggestedOptions.
Module: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()
Reads 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, and so on.
In both cases there will be no more calls to any of the callback
functions.
Module:write(Bin, State) -> {more, NewState} | {last, FileSize} | {er-
ror, {Code, Text}}
Types:
Bin = binary()
State = NewState = term()
FileSize = int()
Code = undef | enoent | eacces | enospc
| badop | eexist | baduser | badopt
| int()
Text = string()
Writes 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, 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 be-
havior and export the following functions:
EXPORTS
Logger:error_msg(Format, Data) -> ok | exit(Reason)
Types:
Format = string()
Data = [term()]
Reason = term()
Logs an error message. See error_logger:error_msg/2 for details.
Logger:info_msg(Format, Data) -> ok | exit(Reason)
Types:
Format = string()
Data = [term()]
Reason = term()
Logs an info message. See error_logger:info_msg/2 for details.
Logger:warning_msg(Format, Data) -> ok | exit(Reason)
Types:
Format = string()
Data = [term()]
Reason = term()
Logs a warning message. See error_logger:warning_msg/2 for de-
tails.
Ericsson AB tftp 1.0.2 tftp(3erl)