# tftp

### MODULE

tftp

### MODULE SUMMARY

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.

### DATA TYPES

          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 | brief | normal | verbose | all`
  Controls the level of debug printouts. The default is `none`.
`{host, Host}`
  `Host = hostname()` see inet(3)
  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).
`{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.

### 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(Pid) -> undefined | Options`

Types:

`Options = [option()]`

Returns info about 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 transfererred 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`.

### EXPORTS

`prepare(Access, Filename, Mode, SuggestedOptions, InitialState) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}`

Types:

`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(Access, Filename, Mode, SuggestedOptions, State) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}`

Types:

`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 preceeded by a call to `prepare/5`, all options must be accepted or rejected.

On the server side, where there is no preceeding `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).

### AUTHORS

Håkan Mattsson - support@erlang.ericsson.se
Gunilla Arendt - support@erlang.ericsson.se

inets 4.7.6
Copyright © 1991-2006 Ericsson AB