File: tftp.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (624 lines) | stat: -rw-r--r-- 19,155 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>tftp</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>tftp</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
tftp
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Trivial FTP
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>This is a complete implementation of the following IETF standards:

<P>
<UL>

<LI>
RFC 1350, The TFTP Protocol (revision 2).
</LI>


<LI>
RFC 2347, TFTP Option Extension.
</LI>


<LI>
RFC 2348, TFTP Blocksize Option.
</LI>


<LI>
RFC 2349, TFTP Timeout Interval and Transfer Size Options.

</LI>


</UL>

<P>The only feature that not is implemented in this release is
the &#34;netascii&#34; transfer mode.
<P>The <A HREF="#start/1">start/1</A> 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.
<P>On the client side
the <A HREF="#read_file/3">read_file/3</A>
and <A HREF="#write_file/3">write_file/3</A>
functions spawns a temporary client process which establishes
contact with a TFTP daemon and performs the actual transfer of
the file.
<P><CODE>tftp</CODE> uses a callback module to handle the actual file
transfer. Two such callback modules are provided,
<CODE>tftp_binary</CODE> and <CODE>tftp_file</CODE>. See
<A HREF="#read_file/3">read_file/3</A> and
<A HREF="#write_file/3">write_file/3</A> for
more information about these. The user can also implement own
callback modules, see <A HREF="#behavior">CALLBACK
        FUNCTIONS</A> below. A callback module provided by
the user is registered using the <CODE>callback</CODE> option, see
<A HREF="#options">DATA TYPES</A> below.
</DIV>
<A NAME="options"><!-- Empty --></A>
<H3>DATA TYPES</H3>
<DIV CLASS=REFBODY>

<PRE>
      option() -- see below
    
</PRE>

<P>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:
<P>
<DL>

<DT>
<CODE>{debug, Level}</CODE>
</DT>

<DD>
        <CODE>Level = none | brief | normal | verbose | all</CODE><BR>


        Controls the level of debug printouts. The default is
         <CODE>none</CODE>.<BR>


</DD>

<DT>
<CODE>{host, Host}</CODE>
</DT>

<DD>
        <CODE>Host = hostname()</CODE> see
         <A HREF="javascript:erlhref('../../../../', 'kernel', 'inet.html');">inet(3)</A><BR>


        The name or IP address of the host where the TFTP daemon
         resides. This option is only used by the client.<BR>


</DD>

<DT>
<CODE>{port, Port}</CODE>
</DT>

<DD>
        <CODE>Port = int()</CODE><BR>


        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 <CODE>info/1</CODE> function).<BR>


</DD>

<DT>
<CODE>{port_policy, Policy}</CODE>
</DT>

<DD>
                 <CODE>Policy = random | Port | {range, MinPort, MaxPort}</CODE><BR>

         <CODE>Port = MinPort = MaxPort = int()</CODE><BR>


        Policy for the selection of the temporary port which is used
         by the server/client during the file transfer. It defaults to
         <CODE>random</CODE> 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.<BR>

        
</DD>

<DT>
<CODE>{udp, Options}</CODE>
</DT>

<DD>
        <CODE>Options = [Opt]</CODE> see
         <A HREF="javascript:erlhref('../../../../', 'kernel', 'gen_udp.html#open/1');">gen_udp:open/2</A><BR>


</DD>

<DT>
<CODE>{use_tsize, Bool}</CODE>
</DT>

<DD>
        <CODE>Bool = bool()</CODE><BR>


        Flag for automated usage of the <CODE>tsize</CODE> option. With
         this set to true, the <CODE>write_file/3</CODE> client will
         determine the filesize and send it to the server as
         the standardized <CODE>tsize</CODE> option. A <CODE>read_file/3</CODE>
         client will just acquire filesize from the server by sending
         a zero <CODE>tsize</CODE>.<BR>


</DD>

<DT>
<CODE>{max_tsize, MaxTsize}</CODE>
</DT>

<DD>
        <CODE>MaxTsize = int() | infinity</CODE><BR>


        Threshold for the maximal filesize in bytes. The transfer
         will be aborted if the limit is exceeded. It defaults to
         <CODE>infinity</CODE>.<BR>


</DD>

<DT>
<CODE>{max_conn, MaxConn}</CODE>
</DT>

<DD>
        <CODE>MaxConn = int() | infinity</CODE><BR>


        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 <CODE>infinity</CODE>.<BR>


</DD>

<DT>
<CODE>{TftpKey, TftpVal}</CODE>
</DT>

<DD>
                 <CODE>TftpKey = string()</CODE><BR>

         <CODE>TftpVal = string()</CODE><BR>


        The name and value of a TFTP option.<BR>


</DD>

<DT>
<CODE>{reject, Feature}</CODE>
</DT>

<DD>
                 <CODE>Feature = Mode | TftpKey</CODE><BR>

         <CODE>Mode = read | write</CODE><BR>

         <CODE>TftpKey = string()</CODE><BR>


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

        
</DD>

<DT>
<CODE>{callback, {RegExp, Module, State}}</CODE>
</DT>

<DD>
                 <CODE>RegExp = string()</CODE><BR>

         <CODE>Module = atom()</CODE><BR>

         <CODE>State = term()</CODE><BR>


        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
         <A HREF="#read_file/3">read_file/3</A> and
         <A HREF="#write_file/3">write_file/3</A>.

        <BR>
The callback module must implement the <CODE>tftp</CODE> behavior,
         <A HREF="#behavior">CALLBACK FUNCTIONS</A>.<BR>


</DD>

</DL>

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="start/1"><STRONG><CODE>start(Options) -&#62; {ok, Pid} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Options = [option()]</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>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.
</DIV>

<P><A NAME="read_file/3"><STRONG><CODE>read_file(RemoteFilename, LocalFilename, Options) -&#62;
        {ok, LastCallbackState} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>RemoteFilename = string()</CODE></STRONG><BR>
<STRONG><CODE>LocalFilename = binary | string()</CODE></STRONG><BR>
<STRONG><CODE>Options = [option()]</CODE></STRONG><BR>
<STRONG><CODE>LastCallbackState = term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Reads a (virtual) file <CODE>RemoteFilename</CODE> from a TFTP
         server.
<P>If <CODE>LocalFilename</CODE> is the atom <CODE>binary</CODE>,
         <CODE>tftp_binary</CODE> is used as callback module. It concatenates
         all transferred blocks and returns them as one single binary
         in <CODE>LastCallbackState</CODE>.
<P>If <CODE>LocalFilename</CODE> is a string and there are no
         registered callback modules, <CODE>tftp_file</CODE> is used as
         callback module. It writes each transferred block to the file
         named <CODE>LocalFilename</CODE> and returns the number of
         transferred bytes in <CODE>LastCallbackState</CODE>.
<P>If <CODE>LocalFilename</CODE> is a string and there are registered
         callback modules, <CODE>LocalFilename</CODE> 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.
</DIV>

<P><A NAME="write_file/3"><STRONG><CODE>write_file(RemoteFilename, LocalFilename, Options) -&#62;
        {ok, LastCallbackState} | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>RemoteFilename = string()</CODE></STRONG><BR>
<STRONG><CODE>LocalFilename = binary() | string()</CODE></STRONG><BR>
<STRONG><CODE>Options = [option()]</CODE></STRONG><BR>
<STRONG><CODE>LastCallbackState = term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Writes a (virtual) file <CODE>RemoteFilename</CODE> to a TFTP
         server.
<P>If <CODE>LocalFilename</CODE> is a binary, <CODE>tftp_binary</CODE> is
         used as callback module. The binary is transferred block by
         block and the number of transferred bytes is returned in
         <CODE>LastCallbackState</CODE>.
<P>If <CODE>LocalFilename</CODE> is a string and there are no
         registered callback modules, <CODE>tftp_file</CODE> is used as
         callback module. It reads the file named <CODE>LocalFilename</CODE>
         block by block and returns the number of transferred bytes
         in <CODE>LastCallbackState</CODE>.
<P>If <CODE>LocalFilename</CODE> is a string and there are registered
         callback modules, <CODE>LocalFilename</CODE> 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.
</DIV>

<P><A NAME="info/1"><STRONG><CODE>info(Pid) -&#62; undefined | Options</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Options = [option()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns info about a TFTP daemon, server or client process.
        
</DIV>

<P><A NAME="start/0"><STRONG><CODE>start() -&#62; ok | {error, Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Starts the Inets application.
</DIV>
<A NAME="behavior"><!-- Empty --></A>
<H3>CALLBACK FUNCTIONS</H3>
<DIV CLASS=REFBODY>

<P>A <CODE>tftp</CODE> callback module should be implemented as a
<CODE>tftp</CODE> behavior and export the functions listed below.
<P>On the server side the callback interaction starts with a call to
<CODE>open/5</CODE> with the registered initial callback state.
<CODE>open/5</CODE> is expected to open the (virtual) file. Then either
the <CODE>read/1</CODE> or <CODE>write/2</CODE> 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 <CODE>read/1</CODE> or
<CODE>write/2</CODE> functions is expected to close the (virtual) file
and return its last state. The <CODE>abort/3</CODE> function is only
used in error situations. <CODE>prepare/5</CODE> is not used on
the server side.
<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
<CODE>prepare/5</CODE> with the same arguments as <CODE>open/5</CODE> takes.
<CODE>prepare/5</CODE> 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 <CODE>open/5</CODE> function
on the client side. On the client side the <CODE>open/5</CODE> 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
<CODE>read/1</CODE> or <CODE>write/2</CODE> the returned state is forwarded to
the user and returned from <CODE>read_file</CODE>/3 or
<CODE>write_file/3</CODE>.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="prepare/5"><STRONG><CODE>prepare(Access, Filename, Mode, SuggestedOptions,
        InitialState) -&#62;
        {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Access = read | write</CODE></STRONG><BR>
<STRONG><CODE>Filename = string()</CODE></STRONG><BR>
<STRONG><CODE>Mode = string()</CODE></STRONG><BR>
<STRONG><CODE>SuggestedOptions = AcceptedOptions = [{Key, Value}]</CODE></STRONG><BR>
<STRONG><CODE>Key = Value = string()</CODE></STRONG><BR>
<STRONG><CODE>InitialState = [] | [{root_dir, string()}]</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Code = undef | enoent | eacces | enospc</CODE></STRONG><BR>
<STRONG><CODE>| badop | eexist | baduser | badopt</CODE></STRONG><BR>
<STRONG><CODE>| int()</CODE></STRONG><BR>
<STRONG><CODE>Text = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Prepares to open a file on the client side.
<P>No new options may be added, but the ones that are present in
         <CODE>SuggestedOptions</CODE> may be omitted or replaced with new
         values in <CODE>AcceptedOptions</CODE>.
<P>Will be followed by a call to <CODE>open/4</CODE> before any
         read/write access is performed. <CODE>AcceptedOptions</CODE> is
         sent to the server which replies with those options that it
         accepts. These will be forwarded to <CODE>open/4</CODE> as
         <CODE>SuggestedOptions</CODE>.
</DIV>

<P><A NAME="open/5"><STRONG><CODE>open(Access, Filename, Mode, SuggestedOptions, State) -&#62;
        {ok, AcceptedOptions, NewState} | {error, {Code, Text}}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Access = read | write</CODE></STRONG><BR>
<STRONG><CODE>Filename = string()</CODE></STRONG><BR>
<STRONG><CODE>Mode = string()</CODE></STRONG><BR>
<STRONG><CODE>SuggestedOptions = AcceptedOptions = [{Key, Value}]</CODE></STRONG><BR>
<STRONG><CODE>Key = Value = string()</CODE></STRONG><BR>
<STRONG><CODE>State = InitialState | term()</CODE></STRONG><BR>
<STRONG><CODE>InitialState = [] | [{root_dir, string()}]</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Code = undef | enoent | eacces | enospc</CODE></STRONG><BR>
<STRONG><CODE>| badop | eexist | baduser | badopt</CODE></STRONG><BR>
<STRONG><CODE>| int()</CODE></STRONG><BR>
<STRONG><CODE>Text = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Opens a file for read or write access.
<P>On the client side where the <CODE>open/5</CODE> call has been
         preceeded by a call to <CODE>prepare/5</CODE>, all options must be
         accepted or rejected.
<P>On the server side, where there is no preceeding
         <CODE>prepare/5</CODE> call, no new options may be added, but
         the ones that are present in <CODE>SuggestedOptions</CODE> may be
         omitted or replaced with new values in <CODE>AcceptedOptions</CODE>.
        
</DIV>

<P><A NAME="read/1"><STRONG><CODE>read(State) -&#62; {more, Bin, NewState} | {last, Bin, FileSize}
        | {error, {Code, Text}}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>State = NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Bin = binary()</CODE></STRONG><BR>
<STRONG><CODE>FileSize = int()</CODE></STRONG><BR>
<STRONG><CODE>Code = undef | enoent | eacces | enospc</CODE></STRONG><BR>
<STRONG><CODE>| badop | eexist | baduser | badopt</CODE></STRONG><BR>
<STRONG><CODE>| int()</CODE></STRONG><BR>
<STRONG><CODE>Text = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Read a chunk from the file.
<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 etc. In both
cases there will be no more calls to any of
the callback functions.
        
</DIV>

<P><A NAME="write/2"><STRONG><CODE>write(Bin, State) -&#62; {more, NewState} | {last, FileSize}
        | {error, {Code, Text}}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Bin = binary()</CODE></STRONG><BR>
<STRONG><CODE>State = NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>FileSize = int()</CODE></STRONG><BR>
<STRONG><CODE>Code = undef | enoent | eacces | enospc</CODE></STRONG><BR>
<STRONG><CODE>| badop | eexist | baduser | badopt</CODE></STRONG><BR>
<STRONG><CODE>| int()</CODE></STRONG><BR>
<STRONG><CODE>Text = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Write a chunk to the file.
<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 etc. In both
cases there will be no more calls to any of
the callback functions.
</DIV>

<P><A NAME="abort/3"><STRONG><CODE>abort(Code, Text, State) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Code = undef | enoent | eacces | enospc</CODE></STRONG><BR>
<STRONG><CODE>| badop | eexist | baduser | badopt</CODE></STRONG><BR>
<STRONG><CODE>| int()</CODE></STRONG><BR>
<STRONG><CODE>Text = string()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Invoked when the file transfer is aborted.
<P>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).
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Hkan Mattsson - support@erlang.ericsson.se<BR>
Gunilla Arendt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>inets 4.7.6<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>