diff options
Diffstat (limited to 'lib/tftp/doc/src')
| -rw-r--r-- | lib/tftp/doc/src/Makefile | 154 | ||||
| -rw-r--r-- | lib/tftp/doc/src/book.xml | 49 | ||||
| -rw-r--r-- | lib/tftp/doc/src/getting_started.xml | 81 | ||||
| -rw-r--r-- | lib/tftp/doc/src/introduction.xml | 62 | ||||
| -rw-r--r-- | lib/tftp/doc/src/notes.xml | 53 | ||||
| -rw-r--r-- | lib/tftp/doc/src/ref_man.xml | 36 | ||||
| -rw-r--r-- | lib/tftp/doc/src/tftp.xml | 599 | ||||
| -rw-r--r-- | lib/tftp/doc/src/usersguide.xml | 37 |
8 files changed, 1071 insertions, 0 deletions
diff --git a/lib/tftp/doc/src/Makefile b/lib/tftp/doc/src/Makefile new file mode 100644 index 0000000000..a2fdcf6325 --- /dev/null +++ b/lib/tftp/doc/src/Makefile @@ -0,0 +1,154 @@ +# +# %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 \ + getting_started.xml \ + notes.xml + +XML_REF3_FILES = \ + tftp.xml + +XML_PART_FILES = \ + usersguide.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..c0b551d517 --- /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="usersguide.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/getting_started.xml b/lib/tftp/doc/src/getting_started.xml new file mode 100644 index 0000000000..9bce52dbe0 --- /dev/null +++ b/lib/tftp/doc/src/getting_started.xml @@ -0,0 +1,81 @@ +<?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> + 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>Getting Started</title> + <prepared></prepared> + <docno></docno> + <approved></approved> + <date></date> + <rev></rev> + <file>getting_started.xml</file> + </header> + + <section> + <title>General Information</title> + <p>The <seealso marker="tftp#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="tftp#read_file/3">read_file/3</seealso> + and <seealso marker="tftp#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="tftp#read_file/3">read_file/3</seealso> and + <seealso marker="tftp#write_file/3">write_file/3</seealso> for details. + You can also implement your own callback modules, see + <seealso marker="tftp#tftp_callback">CALLBACK FUNCTIONS</seealso>. + A callback module provided by + the user is registered using option <c>callback</c>, see + <seealso marker="tftp#options">DATA TYPES</seealso>.</p> + </section> + + <section> + <title>Using the TFTP client and server</title> + <p>This is a simple example of starting the TFTP server and reading the content + of a sample file using the TFTP client.</p> + + <p><em>Step 1.</em> Create a sample file to be used for the transfer:</p> + <code> + $ echo "Erlang/OTP 21" > file.txt + </code> + + <p><em>Step 2.</em> Start the TFTP server:</p> + <code type="erl" > + 1> {ok, Pid} = tftp:start([{port, 19999}]). + <![CDATA[{ok,<0.65.0>}]]> + </code> + + <p><em>Step 3.</em> Start the TFTP client (in another shell):</p> + <code type="erl" > + 1> tftp:read_file("file.txt", binary, [{port, 19999}]). + <![CDATA[{ok,<<"Erlang/OTP 21\n">>}]]> + </code> + </section> + +</chapter> diff --git a/lib/tftp/doc/src/introduction.xml b/lib/tftp/doc/src/introduction.xml new file mode 100644 index 0000000000..70761db0dc --- /dev/null +++ b/lib/tftp/doc/src/introduction.xml @@ -0,0 +1,62 @@ +<?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>The Trivial File Transfer Protocol or TFTP is a very simple protocol + used to transfer files.</p> + <p>It has been implemented on top of the User Datagram protocol (UDP) so + it may be used to move files between machines on different networks + implementing UDP. It is designed to be small and easy to implement. + Therefore, it lacks most of the features of a regular FTP. The only + thing it can do is read and write files (or mail) from/to a remote server. + It cannot list directories, and currently has no provisions for user + authentication.</p> + <p>The <c>tftp</c> application implements 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 <c>netascii</c> transfer mode.</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..3a4d97a008 --- /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</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/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..481e5446ad --- /dev/null +++ b/lib/tftp/doc/src/tftp.xml @@ -0,0 +1,599 @@ +<?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>Interface module for the <c>tftp</c> application.</p> + </description> + + <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> Mode = read | write</c> <br></br> +<c> 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> | badop | eexist | baduser | badopt</v> + <v> | 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> Key = Value = string()</v> + <v>State = InitialState | term()</v> + <v> InitialState = [] | [{root_dir, string()}]</v> + <v>NewState = term()</v> + <v>Code = undef | enoent | eacces | enospc</v> + <v> | badop | eexist | baduser | badopt</v> + <v> | 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> Key = Value = string()</v> + <v>InitialState = [] | [{root_dir, string()}]</v> + <v>NewState = term()</v> + <v>Code = undef | enoent | eacces | enospc</v> + <v> | badop | eexist | baduser | badopt</v> + <v> | 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> | badop | eexist | baduser | badopt</v> + <v> | 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> | badop | eexist | baduser | badopt</v> + <v> | 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> + + diff --git a/lib/tftp/doc/src/usersguide.xml b/lib/tftp/doc/src/usersguide.xml new file mode 100644 index 0000000000..eb7f7d17c3 --- /dev/null +++ b/lib/tftp/doc/src/usersguide.xml @@ -0,0 +1,37 @@ +<?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"/> + <xi:include href="getting_started.xml"/> +</part> |