Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
tftp(3)			   Erlang Module Definition		       tftp(3)

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(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. 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.1			       tftp(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | CALLBACK FUNCTIONS | EXPORTS | LOGGER FUNCTIONS | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tftp&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help