👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for tftp (linux section 3erl)

tftp(3erl)			     Erlang Module Definition			       tftp(3erl)

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 infor-
       mation  about  these. The user can also implement own callback modules, see CALLBACK FUNC-
       TIONS 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, Service-
       Config, 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 dae-
	   mon 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 dur-
	   ing 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 use-
	   ful 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  file-
	   name 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 call-
	   back 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  Last-
	      CallbackState .

	      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 LastCallback-
	      State .

	      If LocalFilename is a string and there are registered callback modules,  LocalFile-
	      name  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 Last-
	      CallbackState .

	      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,  LocalFile-
	      name  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  regis-
       tered  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  (vir-
       tual)  file  and  return its last state. The abort/3 function is only used in error situa-
       tions. 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 dif-
       ferently. It starts with a call to prepare/5 with the same arguments as open/5 takes. pre-
       pare/5 is expected to validate the TFTP options, suggested by the user and return the sub-
       set 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 func-
       tion 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, AcceptedOp-
       tions, 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, New-
       State} | {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.

Ericsson AB				   inets 5.5.2				       tftp(3erl)


All times are GMT -4. The time now is 01:33 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password