aboutsummaryrefslogtreecommitdiffstats
path: root/lib
diff options
context:
space:
mode:
authorPéter Dimitrov <[email protected]>2018-03-27 16:42:55 +0200
committerPéter Dimitrov <[email protected]>2018-03-28 10:19:38 +0200
commit5e08fcceb9f40d4d8213ae4794b5366088b62550 (patch)
tree8620eaf6d5f2b035ccd780d84ec7e4506b7555f1 /lib
parent6fc2b7bf5eb331fdc1c0fb93758dad5a741da4fa (diff)
downloadotp-5e08fcceb9f40d4d8213ae4794b5366088b62550.tar.gz
otp-5e08fcceb9f40d4d8213ae4794b5366088b62550.tar.bz2
otp-5e08fcceb9f40d4d8213ae4794b5366088b62550.zip
tftp: Improve documentation
Change-Id: Ie23a40e7159fe632cf5514ac617de17c5d5b5ce2
Diffstat (limited to 'lib')
-rw-r--r--lib/tftp/doc/src/Makefile3
-rw-r--r--lib/tftp/doc/src/book.xml2
-rw-r--r--lib/tftp/doc/src/getting_started.xml81
-rw-r--r--lib/tftp/doc/src/introduction.xml18
-rw-r--r--lib/tftp/doc/src/tftp.xml46
-rw-r--r--lib/tftp/doc/src/usersguide.xml (renamed from lib/tftp/doc/src/part.xml)1
6 files changed, 103 insertions, 48 deletions
diff --git a/lib/tftp/doc/src/Makefile b/lib/tftp/doc/src/Makefile
index cd97bdf7ff..a2fdcf6325 100644
--- a/lib/tftp/doc/src/Makefile
+++ b/lib/tftp/doc/src/Makefile
@@ -40,13 +40,14 @@ XML_APPLICATION_FILES = ref_man.xml
XML_CHAPTER_FILES = \
introduction.xml \
+ getting_started.xml \
notes.xml
XML_REF3_FILES = \
tftp.xml
XML_PART_FILES = \
- part.xml
+ usersguide.xml
BOOK_FILES = book.xml
diff --git a/lib/tftp/doc/src/book.xml b/lib/tftp/doc/src/book.xml
index cf8032a4e9..c0b551d517 100644
--- a/lib/tftp/doc/src/book.xml
+++ b/lib/tftp/doc/src/book.xml
@@ -36,7 +36,7 @@
<contents level="2"></contents>
</preamble>
<parts lift="no">
- <xi:include href="part.xml"/>
+ <xi:include href="usersguide.xml"/>
</parts>
<applications>
<xi:include href="ref_man.xml"/>
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
index 949438ae92..70761db0dc 100644
--- a/lib/tftp/doc/src/introduction.xml
+++ b/lib/tftp/doc/src/introduction.xml
@@ -34,7 +34,23 @@
<section>
<title>Purpose</title>
- <p>A <c>TFTP</c> client and server.</p>
+ <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>
diff --git a/lib/tftp/doc/src/tftp.xml b/lib/tftp/doc/src/tftp.xml
index c4d6a4e6d0..481e5446ad 100644
--- a/lib/tftp/doc/src/tftp.xml
+++ b/lib/tftp/doc/src/tftp.xml
@@ -31,53 +31,9 @@
<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>
+ <p>Interface module for the <c>tftp</c> application.</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>
diff --git a/lib/tftp/doc/src/part.xml b/lib/tftp/doc/src/usersguide.xml
index abbe0edcbf..eb7f7d17c3 100644
--- a/lib/tftp/doc/src/part.xml
+++ b/lib/tftp/doc/src/usersguide.xml
@@ -33,4 +33,5 @@
<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>