From inwap@shell3.ba.best.com  Fri Dec 10 14:12:39 1999
Return-Path: <inwap@shell3.ba.best.com>
Received: from shell3.ba.best.com (shell3.ba.best.com [206.184.139.134])
	by hub.freebsd.org (Postfix) with ESMTP id 3F7BF15162
	for <FreeBSD-gnats-submit@freebsd.org>; Fri, 10 Dec 1999 14:12:38 -0800 (PST)
	(envelope-from inwap@shell3.ba.best.com)
Received: (from inwap@localhost)
	by shell3.ba.best.com (8.9.3/8.9.2/best.sh) id OAA18185;
	Fri, 10 Dec 1999 14:12:17 -0800 (PST)
Message-Id: <199912102212.OAA18185@shell3.ba.best.com>
Date: Fri, 10 Dec 1999 14:12:17 -0800 (PST)
From: Joe Smith <inwap@best.com>
Sender: inwap@shell3.ba.best.com
Reply-To: inwap@best.com
To: FreeBSD-gnats-submit@freebsd.org
Subject: Description of ls and nlist wrong in man page for ftp
X-Send-Pr-Version: 3.2

>Number:         15408
>Category:       docs
>Synopsis:       Description of ls and nlist wrong in man page for ftp
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    ben
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Fri Dec 10 14:20:01 PST 1999
>Closed-Date:    Wed Jul 19 20:02:09 BST 2000
>Last-Modified:  Wed Jul 19 20:03:11 BST 2000
>Originator:     Joe Smith
>Release:        FreeBSD 2.2.8-STABLE i386
>Organization:
Chez Inwap
>Environment:
>Description:

	There is an undocumented change in the behavior of the 'ls' command
inside the ftp client program.  With older versions of ftp (such as the ones
use by Sun), the difference between 'ls' and 'dir' is that the former
sends the NLST command to get a list of names only and the latter sends
LIST to get a full directory listing (often done by executing `ls -l` on
the server).  The man page for ftp states that 'nlist' is an alias for
'ls' and that 'ls' will "print a list of the files in a directory on the
remote machine".

	The docs need to be changed to say that 'ls' is a synonym for 'dir'
and that 'nlist' has to be used to get a list of just the file names.

>How-To-Repeat:

ftp> debug
ftp> dir .cshrc
ftp> ls .cshrc
ftp> nlist .cshrc

Note from the response that 'ls' acts like 'dir' and not 'nlist'.

>Fix:
	
1) Change the program back so that 'ls' is synonymous with 'nlist'.
	or
2) Change the docs to show that 'ls' is different from 'nlist'.

	Update the man page, so that the paragraph on 'dir' includes
a statement how 'dir' differs from 'nlist'.  Replace the paragraph on
'ls' with "ls [remote-directory [local-file]]\nA synonym for dir."
Move the old description of 'ls' to 'nlist'.  Make it clear that,
according to the RFC, this command returns a list of files on the
remote machine, explictly excluding the names of any subdirectories
in the remote directory.  (The wu-ftpd-2.6.0 server enforces this.)


>Release-Note:
>Audit-Trail:

From: Ben Smithurst <ben@FreeBSD.org>
To: freebsd-gnats-submit@FreeBSD.org
Cc: inwap@best.com
Subject: Re: docs/15408: Description of ls and nlist wrong in man page for ftp
Date: Tue, 11 Jul 2000 01:58:21 +0100

 >      2) Change the docs to show that 'ls' is different from 'nlist'.
 > 
 >              Update the man page, so that the paragraph on 'dir' includes
 >      a statement how 'dir' differs from 'nlist'.
 
 I'd rather the other way around, but I don't feel strongly either way.
 It already explains that 'dir' returns system-dependent information.
 How about adding something like this to the 'nlist' description:
 
 	Note that this command only returns the filenames in the remote
 	directory.  If you wish to see more information about the files
 	(often size, modification time, and so on) use the dir command
 	instead.
 
 Perhaps something could be added to the 'dir' description too:
 
 	If you want a plain list of files, with no extra information, use
 	the nlist command instead.
 
 ok?
 
 >      Replace the paragraph on
 >      'ls' with "ls [remote-directory [local-file]]\nA synonym for dir."
 >      Move the old description of 'ls' to 'nlist'.
 
 That's easy...
 
 >      Make it clear that, according to the RFC, this command returns
 >      a list of files on the remote machine, explictly excluding the
 >      names of any subdirectories in the remote directory.  (The
 >      wu-ftpd-2.6.0 server enforces this.)
 
 What do you mean by "this command"?  The "nlist" client command?  The NLST
 server command?  Either way, I don't see subdirectories excluded:
 
 ftp> ls
 ---> PORT 192,168,91,33,192,13
 200 PORT command successful.
 ---> LIST
 150 Opening ASCII mode data connection for /bin/ls.
 total 12
 d--x--x--x   2 root  wheel   512 Apr  5 19:14 bin
 d--x--x--x   2 root  wheel   512 Apr  5 19:18 etc
 drwxrwx-wt   2 root  wheel   512 Apr  5 19:13 incoming
 drwxr-xr-x   4 root  wheel   512 Aug 11  1999 local
 drwxr-xr-x  39 root  bin    1024 Jul 10 01:34 packages
 drwxr-xr-x   5 root  wheel   512 Jul  1 20:38 pub
 226 Transfer complete.
 ftp> dir
 ---> PORT 192,168,91,33,192,14
 200 PORT command successful.
 ---> LIST
 150 Opening ASCII mode data connection for /bin/ls.
 total 12
 d--x--x--x   2 root  wheel   512 Apr  5 19:14 bin
 d--x--x--x   2 root  wheel   512 Apr  5 19:18 etc
 drwxrwx-wt   2 root  wheel   512 Apr  5 19:13 incoming
 drwxr-xr-x   4 root  wheel   512 Aug 11  1999 local
 drwxr-xr-x  39 root  bin    1024 Jul 10 01:34 packages
 drwxr-xr-x   5 root  wheel   512 Jul  1 20:38 pub
 226 Transfer complete.
 ftp> nlist
 ---> PORT 192,168,91,33,192,15
 200 PORT command successful.
 ---> NLST
 150 Opening ASCII mode data connection for file list.
 bin
 etc
 incoming
 local
 packages
 pub
 226 Transfer complete.
 
 Am I misunderstanding something?  The server in question is running
 wu-ftpd-2.6.0.  Could you explain what should be happening a bit better?
 
 thanks,
 
 -- 
 Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
 
Responsible-Changed-From-To: freebsd-doc->ben 
Responsible-Changed-By: ben 
Responsible-Changed-When: Tue Jul 11 10:57:36 PDT 2000 
Responsible-Changed-Why:  
I'm looking at this. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=15408 
State-Changed-From-To: open->feedback 
State-Changed-By: ben 
State-Changed-When: Wed Jul 12 01:54:10 BST 2000 
State-Changed-Why:  
I'm waiting for a reply from the submitter to clarify one issue regarding 
this PR. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=15408 

From: Ben Smithurst <ben@FreeBSD.org>
To: freebsd-gnats-submit@FreeBSD.org
Cc: inwap@best.com
Subject: Re: docs/15408: Description of ls and nlist wrong in man page for ftp
Date: Wed, 12 Jul 2000 17:01:53 +0100

 >>      Make it clear that, according to the RFC, this command returns
 >>      a list of files on the remote machine, explictly excluding the
 >>      names of any subdirectories in the remote directory.  (The
 >>      wu-ftpd-2.6.0 server enforces this.)
 
 Unless I get a clarification of this point, I'll be committing this
 patch shortly which addresses the main problem (that ls is not the same
 as nlist, but is the same as dir).
 
 Index: ftp.1
 ===================================================================
 RCS file: /usr/cvs/src/usr.bin/ftp/ftp.1,v
 retrieving revision 1.16
 diff -u -r1.16 ftp.1
 --- ftp.1	2000/06/12 18:30:15	1.16
 +++ ftp.1	2000/07/11 01:03:01
 @@ -297,6 +297,11 @@
  is
  .Sq Fl ,
  the output is sent to the terminal.
 +.Pp
 +As this command provides extra information which is system-dependent,
 +you should use the
 +.Ic nlist
 +command instead if you only want a plain list of files.
  .It Ic disconnect
  A synonym for
  .Ic close .
 @@ -419,22 +424,8 @@
  .It Ic lpwd
  Print the working directory on the local machine.
  .It Ic \&ls Op Ar remote-directory Op Ar local-file
 -Print a list of the files in a
 -directory on the remote machine.
 -If
 -.Ar remote-directory
 -is left unspecified, the current working directory is used.
 -If interactive prompting is on,
 -.Nm
 -will prompt the user to verify that the last argument is indeed the
 -target local file for receiving
 -.Ic ls
 -output.
 -If no local file is specified, or if
 -.Ar local-file
 -is
 -.Fl  ,
 -the output is sent to the terminal.
 +A synonym for
 +.Ic dir .
  .It Ic macdef Ar macro-name
  Define a macro.
  Subsequent lines are stored as the macro
 @@ -543,8 +534,29 @@
  Otherwise, this command is identical to
  .Ar get .
  .It Ic nlist Op Ar remote-directory Op Ar local-file
 -A synonym for
 -.Ic ls .
 +Print a list of the files in a
 +directory on the remote machine.
 +If
 +.Ar remote-directory
 +is left unspecified, the current working directory is used.
 +If interactive prompting is on,
 +.Nm
 +will prompt the user to verify that the last argument is indeed the
 +target local file for receiving
 +.Ic ls
 +output.
 +If no local file is specified, or if
 +.Ar local-file
 +is
 +.Fl  ,
 +the output is sent to the terminal.
 +.Pp
 +Note that this command only returns the filenames in the remote
 +directory.  If you wish to see more information about the files (often
 +size, modification time, and so on),
 +you should use the
 +.Ic dir
 +command instead.
  .It Ic nmap Op Ar inpattern outpattern
  Set or unset the filename mapping mechanism.
  If no arguments are specified, the filename mapping mechanism is unset.
 
 -- 
 Ben Smithurst / ben@FreeBSD.org / PGP: 0x99392F7D
 
State-Changed-From-To: feedback->closed 
State-Changed-By: ben 
State-Changed-When: Wed Jul 19 20:02:09 BST 2000 
State-Changed-Why:  
Turns out the submitter was mistaken about the point I wanted to clarify. 
The other changed have been committed. 

http://www.freebsd.org/cgi/query-pr.cgi?pr=15408 
>Unformatted:
 
