inets,tftp: Break out TFTP from inets

- Create directory structure
- Move code, tests, documentation from inets
- Add inets_tftp_wrapper
- Add tftp app to run-dialyzer script

Change-Id: I6a142ae66cecb9a1821cbf9ea6a45f66a836763d

11 files changed, 1016 insertions, 0 deletions

diff --git a/lib/tftp/doc/html/.gitignore b/lib/tftp/doc/html/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/tftp/doc/html/.gitignore
diff --git a/lib/tftp/doc/man3/.gitignore b/lib/tftp/doc/man3/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/tftp/doc/man3/.gitignore
diff --git a/lib/tftp/doc/man6/.gitignore b/lib/tftp/doc/man6/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/tftp/doc/man6/.gitignore
diff --git a/lib/tftp/doc/pdf/.gitignore b/lib/tftp/doc/pdf/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/tftp/doc/pdf/.gitignore
diff --git a/lib/tftp/doc/src/Makefile b/lib/tftp/doc/src/Makefile
new file mode 100644
index 0000000000..cd97bdf7ff
--- /dev/null
+++ b/lib/tftp/doc/src/Makefile
@@ -0,0 +1,153 @@
+#
+# %CopyrightBegin%
+#
+# Copyright Ericsson AB 1997-2018. All Rights Reserved.
+#
+# 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.
+#
+# %CopyrightEnd%
+#
+#
+include $(ERL_TOP)/make/target.mk
+include $(ERL_TOP)/make/$(TARGET)/otp.mk
+
+# ----------------------------------------------------
+# Application version
+# ----------------------------------------------------
+include ../../vsn.mk
+VSN=$(TFTP_VSN)
+
+# ----------------------------------------------------
+# Release directory specification
+# ----------------------------------------------------
+RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
+
+
+# ----------------------------------------------------
+# Target Specs
+# ----------------------------------------------------
+XML_APPLICATION_FILES = ref_man.xml
+
+XML_CHAPTER_FILES = \
+	introduction.xml \
+	notes.xml
+
+XML_REF3_FILES = \
+	tftp.xml
+
+XML_PART_FILES = \
+	part.xml
+
+BOOK_FILES = book.xml
+
+XML_FILES = \
+	$(BOOK_FILES)        \
+	$(XML_CHAPTER_FILES) \
+	$(XML_PART_FILES)    \
+	$(XML_REF6_FILES)    \
+	$(XML_REF3_FILES)    \
+	$(XML_APPLICATION_FILES)
+
+# GIF_FILES = tftp.gif
+
+
+# ----------------------------------------------------
+
+HTML_FILES = \
+	$(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \
+	$(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html)
+
+INFO_FILE = ../../info
+EXTRA_FILES = \
+	$(XML_REF3_FILES:%.xml=$(HTMLDIR)/%.html) \
+	$(XML_REF6_FILES:%.xml=$(HTMLDIR)/%.html) \
+	$(XML_CHAPTER_FILES:%.xml=$(HTMLDIR)/%.html)
+
+MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
+
+HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
+
+TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+
+# ----------------------------------------------------
+# FLAGS
+# ----------------------------------------------------
+XML_FLAGS +=
+DVIPS_FLAGS +=
+
+# ----------------------------------------------------
+# Targets
+# ----------------------------------------------------
+$(HTMLDIR)/%.gif: %.gif
+	$(INSTALL_DATA) $< $@
+
+docs: pdf html man
+
+ldocs: local_docs
+
+$(TOP_PDF_FILE): $(XML_FILES)
+
+pdf: $(TOP_PDF_FILE)
+
+html: gifs $(HTML_REF_MAN_FILE)
+
+clean clean_docs: clean_html clean_man clean_pdf
+	rm -f errs core *~
+
+man: $(MAN3_FILES)
+
+gifs: $(GIF_FILES:%=$(HTMLDIR)/%)
+
+debug opt:
+
+clean_pdf:
+	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+
+clean_html:
+	rm -rf $(TOP_HTML_FILES) $(HTMLDIR)/*
+
+clean_man:
+	rm -f $(MAN3_FILES)
+
+
+# ----------------------------------------------------
+# Release Target
+# ----------------------------------------------------
+include $(ERL_TOP)/make/otp_release_targets.mk
+
+release_docs_spec: docs
+	$(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf"
+	$(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf"
+	$(INSTALL_DIR) "$(RELSYSDIR)/doc/html"
+	$(INSTALL_DATA) $(HTMLDIR)/* "$(RELSYSDIR)/doc/html"
+	$(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)"
+	$(INSTALL_DIR) "$(RELEASE_PATH)/man/man3"
+	$(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3"
+
+release_spec:
+
+info:
+	@echo "GIF_FILES:\n$(GIF_FILES)"
+	@echo ""
+	@echo "EXTRA_FILES:\n$(EXTRA_FILES)"
+	@echo ""
+	@echo "HTML_FILES:\n$(HTML_FILES)"
+	@echo ""
+	@echo "TOP_HTML_FILES:\n$(TOP_HTML_FILES)"
+	@echo ""
+	@echo "XML_REF3_FILES:\n$(XML_REF3_FILES)"
+	@echo ""
+	@echo "XML_REF6_FILES:\n$(XML_REF6_FILES)"
+	@echo ""
+	@echo "XML_CHAPTER_FILES:\n$(XML_CHAPTER_FILES)"
+	@echo ""
diff --git a/lib/tftp/doc/src/book.xml b/lib/tftp/doc/src/book.xml
new file mode 100644
index 0000000000..cf8032a4e9
--- /dev/null
+++ b/lib/tftp/doc/src/book.xml
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE book SYSTEM "book.dtd">
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header titlestyle="normal">
+    <copyright>
+      <year>1997</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>Péter Dimitrov</prepared>
+    <docno></docno>
+    <date>2018-03-22</date>
+    <rev>1.0</rev>
+    <file>book.sgml</file>
+  </header>
+  <insidecover>
+  </insidecover>
+  <pagetext>TFTP</pagetext>
+  <preamble>
+    <contents level="2"></contents>
+  </preamble>
+  <parts lift="no">
+    <xi:include href="part.xml"/>
+  </parts>
+  <applications>
+    <xi:include href="ref_man.xml"/>
+  </applications>
+  <releasenotes>
+    <xi:include href="notes.xml"/>
+  </releasenotes>
+  <listofterms></listofterms>
+  <index></index>
+</book>
diff --git a/lib/tftp/doc/src/introduction.xml b/lib/tftp/doc/src/introduction.xml
new file mode 100644
index 0000000000..949438ae92
--- /dev/null
+++ b/lib/tftp/doc/src/introduction.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</year><year>2018</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>Introduction</title>
+    <prepared>Péter Dimitrov</prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>2018-03-22</date>
+    <rev>A</rev>
+    <file>introduction.xml</file>
+  </header>
+
+  <section>
+    <title>Purpose</title>
+    <p>A <c>TFTP</c> client and server.</p>
+  </section>
+
+  <section>
+    <title>Prerequisites</title>
+    <p>It is assumed that the reader is familiar with the Erlang
+      programming language, concepts of OTP, and has a basic
+      understanding of the TFTP protocol.</p>
+  </section>
+</chapter>
diff --git a/lib/tftp/doc/src/notes.xml b/lib/tftp/doc/src/notes.xml
new file mode 100644
index 0000000000..f7525c8f3e
--- /dev/null
+++ b/lib/tftp/doc/src/notes.xml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>2002</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 Release Notes</title>
+    <prepared></prepared>
+    <responsible></responsible>
+    <docno></docno>
+    <approved></approved>
+    <checked></checked>
+    <date>2018-03-22</date>
+    <rev>A</rev>
+    <file>notes.xml</file>
+  </header>
+  
+  <section><title>TFTP 1.0.0</title>
+
+    <section><title>First released version</title>
+      <list>
+        <item>
+          <p>
+	    Inets application was split into multiple smaller protocol specific applications.
+	    The TFTP application is a standalone TFTP client and server with the same functionality as
+	    TFTP in Inets.</p>
+          <p>
+	    Own Id: OTP-14113</p>
+        </item>
+      </list>
+    </section>
+
+</section>
+
+</chapter>
diff --git a/lib/tftp/doc/src/part.xml b/lib/tftp/doc/src/part.xml
new file mode 100644
index 0000000000..abbe0edcbf
--- /dev/null
+++ b/lib/tftp/doc/src/part.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header>
+    <copyright>
+      <year>2004</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 User's Guide</title>
+    <prepared>Péter Dimitrov</prepared>
+    <docno></docno>
+    <date>2018-03-22</date>
+    <rev>A</rev>
+    <file>part.sgml</file>
+  </header>
+  <description>
+    <p>The <c>TFTP</c> application provides a TFTP client and server.</p>
+  </description>
+  <xi:include href="introduction.xml"/>
+</part>
diff --git a/lib/tftp/doc/src/ref_man.xml b/lib/tftp/doc/src/ref_man.xml
new file mode 100644
index 0000000000..41a6cc6d52
--- /dev/null
+++ b/lib/tftp/doc/src/ref_man.xml
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+
+<application xmlns:xi="http://www.w3.org/2001/XInclude">
+  <header>
+    <copyright>
+      <year>1997</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 Reference Manual</title>
+    <prepared>Péter Dimitrov</prepared>
+    <docno></docno>
+    <date>2018-03-22</date>
+    <rev>1.0</rev>
+    <file>ref_man.xml</file>
+  </header>
+  <description>
+    <p>The <c>TFTP</c> application.</p>
+  </description>
+  <xi:include href="tftp.xml"/>
+</application>
diff --git a/lib/tftp/doc/src/tftp.xml b/lib/tftp/doc/src/tftp.xml
new file mode 100644
index 0000000000..c4d6a4e6d0
--- /dev/null
+++ b/lib/tftp/doc/src/tftp.xml
@@ -0,0 +1,643 @@
+<?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>This is a complete implementation of the following IETF standards:</p>
+    <list type="bulleted">
+      <item>RFC 1350, The TFTP Protocol (revision 2)</item>
+      <item>RFC 2347, TFTP Option Extension</item>
+      <item>RFC 2348, TFTP Blocksize Option</item>
+      <item>RFC 2349, TFTP Timeout Interval and Transfer Size Options</item>
+    </list>
+    <p>The only feature that not is implemented is
+      the "netascii" transfer mode.</p>
+    <p>The <seealso marker="#start/1">start/1</seealso> function 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 transfer.</p>
+    <p>On the client side,
+      function <seealso marker="#read_file/3">read_file/3</seealso>
+      and <seealso marker="#write_file/3">write_file/3</seealso>
+      spawn a temporary client process establishing
+      contact with a TFTP daemon and perform the file transfer.</p>
+    <p><c>tftp</c> uses a callback module to handle the file
+      transfer. Two such callback modules are provided,
+      <c>tftp_binary</c> and <c>tftp_file</c>. See
+      <seealso marker="#read_file/3">read_file/3</seealso> and
+      <seealso marker="#write_file/3">write_file/3</seealso> for details.
+      You can also implement your own callback modules, see 
+      <seealso marker="#tftp_callback">CALLBACK FUNCTIONS</seealso>. 
+      A callback module provided by
+      the user is registered using option <c>callback</c>, see
+      <seealso marker="#options">DATA TYPES</seealso>.</p>
+  </description>
+  
+ <section>
+    <title>TFTP SERVER SERVICE START/STOP</title>
+    
+    <p>A TFTP server can be started dynamically
+      (when <c>tftp</c> is already started) by calling the <c>tftp</c> application 
+      API <c>tftp:start(ServiceConfig)</c>.
+      The <c>ServiceConfig</c> for TFTP is described in
+      the <seealso marker="#options">DATA TYPES</seealso>
+      section.</p>
+    
+    <p>The TFTP server can be stopped using <c>tftp:stop_service(Pid)</c>.</p>
+
+    <p>The TPFT client is of such a temporary nature that it is not
+      handled as a service in the <c>tftp</c> service framework.</p>
+    
+  </section>
+  
+  <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>
+
+