Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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.