From 5e08fcceb9f40d4d8213ae4794b5366088b62550 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Tue, 27 Mar 2018 16:42:55 +0200 Subject: tftp: Improve documentation Change-Id: Ie23a40e7159fe632cf5514ac617de17c5d5b5ce2 --- lib/tftp/doc/src/Makefile | 3 +- lib/tftp/doc/src/book.xml | 2 +- lib/tftp/doc/src/getting_started.xml | 81 ++++++++++++++++++++++++++++++++++++ lib/tftp/doc/src/introduction.xml | 18 +++++++- lib/tftp/doc/src/part.xml | 36 ---------------- lib/tftp/doc/src/tftp.xml | 46 +------------------- lib/tftp/doc/src/usersguide.xml | 37 ++++++++++++++++ 7 files changed, 139 insertions(+), 84 deletions(-) create mode 100644 lib/tftp/doc/src/getting_started.xml delete mode 100644 lib/tftp/doc/src/part.xml create mode 100644 lib/tftp/doc/src/usersguide.xml 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 @@ - + 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 @@ + + + + +
+ + 1997 + 2018 + Ericsson AB. 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. + + + + Getting Started + + + + + + getting_started.xml +
+ +
+ General Information +

The start/1 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.

+

On the client side, + function read_file/3 + and write_file/3 + spawn a temporary client process establishing + contact with a TFTP daemon and perform the file transfer.

+

tftp uses a callback module to handle the file + transfer. Two such callback modules are provided, + tftp_binary and tftp_file. See + read_file/3 and + write_file/3 for details. + You can also implement your own callback modules, see + CALLBACK FUNCTIONS. + A callback module provided by + the user is registered using option callback, see + DATA TYPES.

+
+ +
+ Using the TFTP client and server +

This is a simple example of starting the TFTP server and reading the content + of a sample file using the TFTP client.

+ +

Step 1. Create a sample file to be used for the transfer:

+ + $ echo "Erlang/OTP 21" > file.txt + + +

Step 2. Start the TFTP server:

+ + 1> {ok, Pid} = tftp:start([{port, 19999}]). + }]]> + + +

Step 3. Start the TFTP client (in another shell):

+ + 1> tftp:read_file("file.txt", binary, [{port, 19999}]). + >}]]> + +
+ + 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 @@
Purpose -

A TFTP client and server.

+

The Trivial File Transfer Protocol or TFTP is a very simple protocol + used to transfer files.

+

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.

+

The tftp application implements the following IETF standards:

+ + RFC 1350, The TFTP Protocol (revision 2) + RFC 2347, TFTP Option Extension + RFC 2348, TFTP Blocksize Option + RFC 2349, TFTP Timeout Interval and Transfer Size Options + +

The only feature that not is implemented is the netascii transfer mode.

diff --git a/lib/tftp/doc/src/part.xml b/lib/tftp/doc/src/part.xml deleted file mode 100644 index abbe0edcbf..0000000000 --- a/lib/tftp/doc/src/part.xml +++ /dev/null @@ -1,36 +0,0 @@ - - - - -
- - 20042018 - Ericsson AB. 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. - - - - TFTP User's Guide - Péter Dimitrov - - 2018-03-22 - A - part.sgml -
- -

The TFTP application provides a TFTP client and server.

- - - 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 @@ tftp Trivial FTP. -

This is a complete implementation of the following IETF standards:

- - RFC 1350, The TFTP Protocol (revision 2) - RFC 2347, TFTP Option Extension - RFC 2348, TFTP Blocksize Option - RFC 2349, TFTP Timeout Interval and Transfer Size Options - -

The only feature that not is implemented is - the "netascii" transfer mode.

-

The start/1 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.

-

On the client side, - function read_file/3 - and write_file/3 - spawn a temporary client process establishing - contact with a TFTP daemon and perform the file transfer.

-

tftp uses a callback module to handle the file - transfer. Two such callback modules are provided, - tftp_binary and tftp_file. See - read_file/3 and - write_file/3 for details. - You can also implement your own callback modules, see - CALLBACK FUNCTIONS. - A callback module provided by - the user is registered using option callback, see - DATA TYPES.

+

Interface module for the tftp application.

 - -
- TFTP SERVER SERVICE START/STOP - -

A TFTP server can be started dynamically - (when tftp is already started) by calling the tftp application - API tftp:start(ServiceConfig). - The ServiceConfig for TFTP is described in - the DATA TYPES - section.

- -

The TFTP server can be stopped using tftp:stop_service(Pid).

-

The TPFT client is of such a temporary nature that it is not - handled as a service in the tftp service framework.

- -
-
DATA TYPES 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 @@ + + + + +
+ + 20042018 + Ericsson AB. 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. + + + + TFTP User's Guide + Péter Dimitrov + + 2018-03-22 + A + part.sgml +
+ +

The TFTP application provides a TFTP client and server.

+ + + + -- cgit v1.2.3