path: root/lib/tftp/doc/src/tftp.xml

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2006</year><year>2018</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      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>

    <title>tftp</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
  </header>
  <module>tftp</module>
  <modulesummary>Trivial FTP.</modulesummary>
  <description>
    <p>Interface module for the <c>tftp</c> application.</p>
  </description>

  <section>
    <marker id="options"></marker>
    <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. 
      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. 
	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>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. 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 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 <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></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>
      </item>
      <tag><c>{use_tsize, Bool}</c></tag>
      <item>
        <p><c>Bool = bool()</c></p>
        <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 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
          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 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>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>&nbsp;Mode = read | write</c>          <br></br>
<c>&nbsp;TftpKey = string()</c></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>
        <p>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
          <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, see
          <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso>.</p>
      </item>

   <tag><c>{logger, Module}</c></tag>
      <item>
        <p><c>Module = module()</c></p>

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

      <tag><c>{max_retries, MaxRetries}</c></tag>
      <item>
        <p><c>MaxRetries = int()</c></p>

        <p>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.</p>
      </item>
    </taglist>
  </section>

  <funcs>
    <func>
      <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>Changes configuration for all TFTP daemon processes. </p>
      </desc>
    </func>

    <func>
      <name>change_config(servers, Options) -> [{Pid, Result}]</name>
      <fsummary>Changes configuration for all servers.
      </fsummary>
      <type>
        <v>Options = [option()]</v>
        <v>Pid = pid()</v>
        <v>Result = ok | {error, Reason}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Changes configuration for all TFTP server processes.</p>
      </desc>
    </func>

    <func>
      <name>change_config(Pid, Options) -> Result</name>
      <fsummary>Changes configuration for a TFTP daemon, server, 
      or client process.</fsummary>
      <type>
        <v>Pid = pid()</v>
        <v>Options = [option()]</v>
        <v>Result = ok | {error, Reason}</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Changes configuration for a TFTP daemon, server, or client process.</p>
      </desc>
    </func>
    
    <func>
      <name>info(daemons) -> [{Pid, Options}]</name>
      <fsummary>Returns information about all daemons.</fsummary>
      <type>
        <v>Pid = [pid()]</v>
        <v>Options = [option()]</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Returns information about all TFTP daemon processes.</p>
      </desc>
    </func>

    <func>
      <name>info(servers) -> [{Pid, Options}]</name>
      <fsummary>Returns information about all servers.</fsummary>
      <type>
        <v>Pid = [pid()]</v>
        <v>Options = [option()]</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Returns information about all TFTP server processes. </p>
      </desc>
    </func>

    <func>
      <name>info(Pid) -> {ok, Options} | {error, Reason}</name>
      <fsummary>Returns information about a daemon, server, or client process.</fsummary>
      <type>
        <v>Options = [option()]</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <p>Returns information about a TFTP daemon, server, or client process.</p>
      </desc>
    </func>
       
    <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>LastCallbackState = term()</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>	
    </func>
    
    <func>
       <name>start(Options) -> {ok, Pid} | {error, Reason}</name>
      <fsummary>Starts a daemon process.</fsummary>
      <type>
        <v>Options = [option()]</v>
        <v>Pid = pid()</v>
        <v>Reason = term()</v>
      </type>
      <desc>
        <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>
      </desc>
    </func>

    <func>
      <name>write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallbackState} | {error, Reason}</name>
      <fsummary>Writes a (virtual) file to a TFTP server.</fsummary>
      <type>
        <v>RemoteFilename = string()</v>
        <v>LocalFilename = binary() | string()</v>
        <v>Options = [option()]</v>
        <v>LastCallbackState = term()</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>
      </desc>
    </func>
  </funcs>

  <section>
    <marker id="tftp_callback"></marker>
    <title>CALLBACK FUNCTIONS</title>
    <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
      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 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
      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 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 <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
      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 (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.</p>

    <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
    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.</p>
    
    <marker id="prepare"></marker>
  </section>

  <funcs>
     <func>
      <name>Module:abort(Code, Text, State) -> ok</name>
      <fsummary>Aborts the file transfer.</fsummary>
      <type>
        <v>Code = undef | enoent | eacces | enospc</v>
        <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
        <v>&nbsp;&nbsp;| 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>
        <v>PeerHost = ip_address()</v>
        <v>PeerPort = integer()</v>
        <v>Access = read | write</v>
        <v>Filename = string()</v>
        <v>Mode = string()</v>
        <v>SuggestedOptions = AcceptedOptions = [{Key, Value}]</v>
        <v>&nbsp;Key = Value = string()</v>
        <v>State = InitialState | term()</v>
        <v>&nbsp;InitialState = [] | [{root_dir, string()}]</v>
        <v>NewState = term()</v>
        <v>Code = undef | enoent | eacces | enospc</v>
        <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
        <v>&nbsp;&nbsp;| int()</v>
        <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 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="read"></marker>
      </desc>
    </func>
    
    <func>
      <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>
        <v>PeerHost = ip_address()</v>
        <v>PeerPort = integer()</v>
        <v>Access = read | write</v>
        <v>Filename = string()</v>
        <v>Mode = string()</v>
        <v>SuggestedOptions = AcceptedOptions = [{Key, Value}]</v>
        <v>&nbsp;Key = Value = string()</v>
        <v>InitialState = [] | [{root_dir, string()}]</v>
        <v>NewState = term()</v>
        <v>Code = undef | enoent | eacces | enospc</v>
        <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
        <v>&nbsp;&nbsp;| int()</v>
        <v>Text = string()</v>
      </type>
      <desc>
	<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="open"></marker>
      </desc>
    </func>

    <func>
      <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>
        <v>FileSize = int()</v>
        <v>Code = undef | enoent | eacces | enospc</v>
        <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
        <v>&nbsp;&nbsp;| int()</v>
        <v>Text = string()</v>
      </type>
      <desc>
        <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,
	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.</p>
    
	<marker id="write"></marker>
      </desc>
    </func>

    <func>
      <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>
        <v>FileSize = int()</v>
        <v>Code = undef | enoent | eacces | enospc</v>
        <v>&nbsp;&nbsp;| badop | eexist | baduser | badopt</v>
        <v>&nbsp;&nbsp;| int()</v>
        <v>Text = string()</v>
      </type>
      <desc>
        <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,
	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.</p>
    
	<marker id="abort"></marker>
      </desc>
    </func>
  </funcs>
  
  <section>
    <marker id="tftp_logger"></marker>
    <title>LOGGER FUNCTIONS</title>
    
    <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>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>Logs an error message. 
	See <c>error_logger:error_msg/2</c> for details.</p>
	
	<marker id="warning_msg"></marker>
      </desc>
    </func>

    <func>
      <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>Logs an info message. 
	See <c>error_logger:info_msg/2</c>  for details.</p>
      </desc>
    </func>
    
    <func>
      <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>Logs a warning message. 
	See <c>error_logger:warning_msg/2</c> for details.</p>
	
	<marker id="info_msg"></marker>
      </desc>
    </func>
  </funcs>
</erlref>