Bug 36459

Summary:	tftp(1) manual's "get" syntax/description is confusing
Product:	Documentation	Reporter:	Gary W. Swearingen <swear>
Component:	Books & Articles	Assignee:	Simon L. B. Nielsen <simon>
Status:	Closed FIXED
Severity:	Affects Only Me
Priority:	Normal
Version:	Latest
Hardware:	Any
OS:	Any

Description Gary W. Swearingen 2002-03-29 04:20:01 UTC

The tftp(1) manual's "get" command syntax/description is very confusing.

-- The first two syntax lines seem redundant, given the third, except
that the second form seems to have a special behavior of renaming the
file, but it's unclear how that's different from just requesting two
files from the remote system.

-- The description refers to "source" (underlined) which isn't
mentioned in the syntax statements.  And the things mentioned
in the systax statements aren't mentioned in the description.

-- Similarly for the "put" command.

================

Fix: 

Determine how to specify a "get" of two files and how to specify
a "get" of one file to be renamed locally and rewrite the whole
thing.  Similarly for "put".
How-To-Repeat: n/a
================

Comment 1 Jim Brown 2003-05-06 16:45:50 UTC

Hi,

Here is a patch for docs/36459 to clear up
the different command forms for 'get' and 'put'.

Best Regards,
jpb
===


root@jpb-wks:/usr2/tmp/src/usr.bin/tftp#cvs diff -u tftp.1
Index: tftp.1
===================================================================
RCS file: /home/ncvs/src/usr.bin/tftp/tftp.1,v
retrieving revision 1.14
diff -u -r1.14 tftp.1
--- tftp.1      2002/11/26 17:33:36     1.14
+++ tftp.1      2003/05/06 15:43:27
@@ -101,15 +101,33 @@
 .It Cm get Ar remotename localname
 .It Cm get Ar file1 file2 ...  fileN
 Get a file or set of files from the specified
-.Ar sources .
-.Ar Source
-can be in one of two forms:
+.Ar source .
+If the first command form is used, the file
+is transferred from the remote host
+to the local host retaining the same name.
+If the second form is used, the file is
+transferred from the remote host to the
+local host and renamed as
+.Ar localname .
+If the third form is
+used, the last hostname specified becomes the default for
+future transfers.
+.Pp
+A
+.Ar source
+can be in one of two forms-
 a filename on the remote host, if the host has already been specified,
 or a string of the form
-.Ar hosts Ns : Ns Ar filename
+.Ar host Ns : Ns Ar filename
 to specify both a host and filename at the same time.
 If the latter form is used,
 the last hostname specified becomes the default for future transfers.
+To specify an IPv6 numeric address for a
+.Ar host ,
+wrap it using square brackets
+like [3ffe:2900:e00c:ffee::1234]:foo
+to disambiguate the colons used in the IPv6 address
+from the colon separating the host from the filename.
 .Pp
 .It Cm mode Ar transfer-mode
 Set the mode for transfers;
@@ -126,23 +144,18 @@
 .It Cm put Ar file1 file2 ... fileN remote-directory
 Put a file or set of files to the specified
 remote file or directory.
-The destination
-can be in one of two forms:
-a filename on the remote host, if the host has already been specified,
-or a string of the form
-.Ar hosts Ns : Ns Ar filename
-to specify both a host and filename at the same time.
-If the latter form is used,
-the hostname specified becomes the default for future transfers.
+The three command forms have similar meaning
+to those of the
+.Ar get
+command above.
 If the remote-directory form is used, the remote host is
 assumed to be a
 .Ux
 machine.
-To specify IPv6 numeric addresses with
-.Ar hosts ,
-wrap them using square brackets like
-.Bo Ar hosts Bc Ns : Ns Ar filename ,
-to disambiguate the colon.
+To specify an IPv6 numeric address for a
+.Ar host ,
+see the example above under
+.Ar get .
 .Pp
 .It Cm quit
 Exit

Comment 2 simon 2003-05-13 01:26:46 UTC

Hello

I din't feel that Jim Brown's patch completely covered the problems raised
in this PR so I have expanded his patch.

I played a bit around with tftp and read parts of the source code so I'm
rather certain that the way described in the patch is actually the way
tftp works.

Btw. I also fixed a bad Ar reference in the connect section.

%%%
Index: tftp.1
===================================================================
RCS file: /home/ncvs/src/usr.bin/tftp/tftp.1,v
retrieving revision 1.14
diff -u -d -r1.14 tftp.1
--- tftp.1	26 Nov 2002 17:33:36 -0000	1.14
+++ tftp.1	13 May 2003 02:16:08 -0000
@@ -74,7 +74,7 @@
 .It Cm binary
 Shorthand for "mode binary"
 .Pp
-.It Cm connect Ar host-name Op Ar port
+.It Cm connect Ar host Op Ar port
 Set the
 .Ar host
 (and optionally
@@ -97,19 +97,28 @@
 .Cm put
 commands.
 .Pp
-.It Cm get Ar filename
-.It Cm get Ar remotename localname
-.It Cm get Ar file1 file2 ...  fileN
-Get a file or set of files from the specified
-.Ar sources .
-.Ar Source
-can be in one of two forms:
-a filename on the remote host, if the host has already been specified,
-or a string of the form
-.Ar hosts Ns : Ns Ar filename
-to specify both a host and filename at the same time.
-If the latter form is used,
-the last hostname specified becomes the default for future transfers.
+.It Cm get Bro Ar file | host : Ns Ar file Brc Bq Ar localname
+.It Xo Cm get Bro Ar file1 | host1 : Ns Ar file1 Brc
+.Bro Ar file2 | host2 : Ns Ar file2 Brc ...
+.Bro Ar fileN | hostN : Ns Ar fileN Brc
+.Xc
+Get one or more files from the remote host.  When using the
+.Ar host
+argument the
+.Ar host
+will be used as default host for future transfers.  If
+.Ar localname
+is specified the file is stored locally as
+.Ar localname
+otherwise the original
+.Ar file Ns No name
+is used.  Note that it is not possible to download two files at a
+time, but only one, or three or more files, at a time.
+.Pp
+To specify an IPv6 numeric address for a host, wrap it using square
+brackets like [3ffe:2900:e00c:ffee::1234]:foo to disambiguate the
+colons used in the IPv6 address from the colon separating the host and
+the filename.
 .Pp
 .It Cm mode Ar transfer-mode
 Set the mode for transfers;
@@ -121,28 +130,26 @@
 The default is
 .Em ascii .
 .Pp
-.It Cm put Ar file
-.It Cm put Ar localfile remotefile
-.It Cm put Ar file1 file2 ... fileN remote-directory
-Put a file or set of files to the specified
-remote file or directory.
-The destination
-can be in one of two forms:
-a filename on the remote host, if the host has already been specified,
-or a string of the form
-.Ar hosts Ns : Ns Ar filename
-to specify both a host and filename at the same time.
-If the latter form is used,
-the hostname specified becomes the default for future transfers.
-If the remote-directory form is used, the remote host is
-assumed to be a
+.It Cm put Ar file Bq Ar remotename | Ar host : Ns Ar remotename
+.It Xo Cm put Ar file1 file2 ... fileN
+.Brq Ar remote-directory | Ar host : Ns Ar remote-directory
+.Xc
+Put a file or set of files to the remote host.  When
+.Ar remotename
+is specified the file is stored remotely as
+.Ar remotename
+otherwise the original
+.Ar file Ns No name
+is used.  If the
+.Ar remote-directory
+argument is used, the remote host is assumed to be a
 .Ux
 machine.
-To specify IPv6 numeric addresses with
-.Ar hosts ,
-wrap them using square brackets like
-.Bo Ar hosts Bc Ns : Ns Ar filename ,
-to disambiguate the colon.
+To specify an IPv6 numeric address for a
+.Ar host ,
+see the example under the
+.Cm get
+command.
 .Pp
 .It Cm quit
 Exit
%%%

-- 
Simon L. Nielsen

Comment 3 Simon L. B. Nielsen freebsd_committer

2003-07-25 17:14:44 UTC

Responsible Changed
From-To: freebsd-doc->simon

I already worked on this, so I will handle it.

Comment 4 Simon L. B. Nielsen freebsd_committer

2003-09-14 00:47:10 UTC

State Changed
From-To: open->patched

A patch to address this has been committed to -CURRENT.  I plan to MFC 
sometime after 4.9. 
Thanks for the submission!

Comment 5 Simon L. B. Nielsen freebsd_committer

2003-10-29 23:23:41 UTC

State Changed
From-To: patched->closed

Committed to -STABLE. 
Thanks again for the submission!