bin/47167: Errors in, and enhancements for, ls(1) and its man page [patch included]

To: gnats-admin%netbsd.org@localhost,netbsd-bugs%netbsd.org@localhost
Subject: bin/47167: Errors in, and enhancements for, ls(1) and its man page [patch included]
From: Bug Hunting <bughunting%xs4all.nl@localhost>
Date: Wed, 7 Nov 2012 19:05:01 +0000 (UTC)
>Number:         47167
>Category:       bin
>Synopsis:       Errors in, and enhancements for, ls(1) and its man page [patch 
>included]
>Confidential:   no
>Severity:       non-critical
>Priority:       medium
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Wed Nov 07 19:05:00 +0000 2012
>Originator:     Bug Hunting
>Release:        NetBSD 6.99.15
>Description:

The ls(1) man page contains errors, and could use additional
enhancements as well.

The ls.c source file contains a minor error, and could use a small
comment enhancement.



>How-To-Repeat:

"man -s 1 ls"

and

calling ls(1) with options which' descriptions are changed in the
patch, or calling it with a non-existent option (to show the `usage'
message).



>Fix:

Apply the patch attached.  Its top lines provide a list of changes,
which may be included as-is in the commit message(s).

Some additional explanation / notes about the patch' changes, given
the following excerpt from it:

-       /* If -l or -s, figure out block size. */
+       /* If -i, -l, or -s, figure out block size. */
        if (f_inode || f_longform || f_size) {
                if (!kflag)
                        (void)getbsize(NULL, &blocksize);

`f_inode' (on the third line here) was included here in r1.45 of
ls.c, to overcome a bug introduced with r1.44; thus, the comment
change in the patch could be augmented more in a way to let it
explicitly note that the block size isn't figured out for `-i' for
functional reasons, but to overcome a bug.  (This is also the reason
why `-i' doesn't need to be added to the `BLOCKSIZE' text block in
the man page, as the patch does for `-l', there.)

The patch excerpt above also shows why `-h' is incorrectly mentioned
in the man page's `BLOCKSIZE' text block, an issue which is fixed
by the patch as well: only `-k' makes this environment variable
get ignored.

--SLDf9lqlvOQaIe6s
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="ls.1_1.71_ls.c_1.69.patch"

Full list of changes:

ls.1:
- Sort options in `SYNOPSIS', the option list, and texts within
  the man page;
- improve wording;
- improve macro usage;
- use more consistency regarding (locations for) information about
  which options override which;
- cross-reference `-d' and `-R';
- simplify description of `-k', removing redundant and unneeded
  information;
- sort entry type list (but leave `-a' and `-A' as they are, given
  their meaning);
- correct / augment description of `BLOCKSIZE' environment variable
  in `ENVIRONMENT' section;
- bump date.

ls.c:
- Sort options in `usage';
- augment comment about when to figure out block size.

---

Index: src/bin/ls/ls.1
===================================================================
RCS file: /cvsroot/src/bin/ls/ls.1,v
retrieving revision 1.71
diff -u -r1.71 ls.1
--- src/bin/ls/ls.1     21 Oct 2012 08:18:27 -0000      1.71
+++ src/bin/ls/ls.1     7 Nov 2012 11:27:00 -0000
@@ -32,7 +32,7 @@
 .\"
 .\"     @(#)ls.1       8.7 (Berkeley) 7/29/94
 .\"
-.Dd April 2, 2011
+.Dd November 7, 2012
 .Dt LS 1
 .Os
 .Sh NAME
@@ -40,19 +40,19 @@
 .Nd list directory contents
 .Sh SYNOPSIS
 .Nm
-.Op Fl AaBbCcdFfghikLlMmnopqRrSsTtuWwx1
+.Op Fl 1AaBbCcdFfghikLlMmnopqRrSsTtuWwx
 .Op Ar
 .Sh DESCRIPTION
-For each operand that names a
+For each
 .Ar file
-of a type other than
+operand that names a file of a type other than
 directory,
 .Nm
 displays its name as well as any requested,
 associated information.
-For each operand that names a
+For each
 .Ar file
-of type directory,
+operand that names a file of type directory,
 .Nm
 displays the names of files contained
 within that directory, as well as any requested, associated
@@ -67,6 +67,11 @@
 .Pp
 The following options are available:
 .Bl -tag -width indent
+.It Fl \&1
+(The numeric digit
+.Dq one ) .
+Force output to be one entry per line.
+This is the default when output is not to a terminal.
 .It Fl A
 List all entries except for
 .Ql \&.
@@ -88,13 +93,18 @@
 Force multi-column output; this is the default when output is to a terminal.
 .It Fl c
 Use time when file status was last changed,
-instead of time of last modification of the file for sorting
-.Pq Fl t
-or printing
-.Pq Fl l .
+instead of time of last modification of the file for printing
+.Pq Fl l
+or sorting
+.Pq Fl t .
+Overrides
+.Fl u .
 .It Fl d
 Directories are listed as plain files (not searched recursively) and
 symbolic links in the argument list are not followed.
+Turns off
+.Fl R
+if also given.
 .It Fl F
 Display a slash
 .Pq Sq \&/
@@ -123,9 +133,9 @@
 except that the owner is not printed.
 .It Fl h
 Modifies the
-.Fl s
-and
 .Fl l
+and
+.Fl s
 options, causing the sizes to be reported in bytes displayed in a human
 readable format.
 Overrides
@@ -138,15 +148,8 @@
 Modifies the
 .Fl s
 option, causing the sizes to be reported in kilobytes.
-The rightmost of the
-.Fl k
-and
-.Fl h
-flags overrides the previous flag.
-See also
-.Fl h
-and
-.Fl M .
+Overrides
+.Fl h .
 .It Fl L
 For each file, if it's a link, evaluate file information and file type
 of the referenced file and not the link itself; however still print
@@ -169,8 +172,8 @@
 commas (or a locale appropriate separator) resulting in a more readable
 output.
 Overrides
-.Fl h .
-Does not override
+.Fl h ;
+does not override
 .Fl k .
 .It Fl m
 Stream output format; list files across the page, separated by commas.
@@ -201,6 +204,8 @@
 this is the default when output is to a terminal.
 .It Fl R
 Recursively list subdirectories encountered.
+See also
+.Fl d .
 .It Fl r
 Reverse the order of the sort to get reverse
 lexicographical order or the smallest or oldest entries first.
@@ -230,10 +235,12 @@
 .It Fl u
 Use time of last access,
 instead of last modification
-of the file for sorting
-.Pq Fl t
-or printing
-.Pq Fl l .
+of the file for printing
+.Pq Fl l
+or sorting
+.Pq Fl t .
+Overrides
+.Fl c .
 .It Fl W
 Display whiteouts when scanning directories.
 .It Fl w
@@ -241,19 +248,14 @@
 This is the default when output is not to a terminal.
 .It Fl x
 Multi-column output sorted across the page rather than down the page.
-.It Fl \&1
-(The numeric digit
-.Dq one ) .
-Force output to be one entry per line.
-This is the default when output is not to a terminal.
 .El
 .Pp
 The
 .Fl B ,
 .Fl b ,
-.Fl w ,
+.Fl q ,
 and
-.Fl q
+.Fl w
 options all override each other; the last one specified determines
 the format used for non-printable characters.
 .Pp
@@ -278,13 +280,6 @@
 .Fl g
 was specified last.
 .Pp
-The
-.Fl c
-and
-.Fl u
-options override each other; the last one specified determines
-the file time used.
-.Pp
 By default,
 .Nm
 lists one entry per line to standard
@@ -296,11 +291,11 @@
 .Pp
 File information is displayed with one or more
 .Aq blank
-separating the information associated with the
+characters separating the information associated with the
 .Fl i ,
-.Fl s ,
+.Fl l ,
 and
-.Fl l
+.Fl s
 options.
 .Ss The Long Format
 If the
@@ -333,7 +328,7 @@
 .El
 .Pp
 In addition, for each directory whose contents are displayed, the total
-number of blocks in units of 512 bytes or
+number of file system blocks in units of 512 bytes or
 .Ev BLOCKSIZE
 (see
 .Sx ENVIRONMENT )
@@ -361,6 +356,8 @@
 follows:
 .Pp
 .Bl -tag -width 4n -offset indent -compact
+.It Sy \-
+Regular file.
 .It Sy a
 Archive state 1.
 .It Sy A
@@ -373,14 +370,12 @@
 Directory.
 .It Sy l
 Symbolic link.
-.It Sy s
-Socket link.
 .It Sy p
 FIFO.
+.It Sy s
+Socket link.
 .It Sy w
 Whiteout.
-.It Sy \-
-Regular file.
 .El
 .Pp
 The next three fields
@@ -460,11 +455,11 @@
 If the environment variable
 .Ev BLOCKSIZE
 is set, and the
-.Fl h
-and
 .Fl k
-options are not specified, the block counts
+option is not specified, the block counts
 (see
+.Fl l
+and
 .Fl s )
 will be displayed in units of that size block.
 .It Ev COLUMNS
Index: src/bin/ls/ls.c
===================================================================
RCS file: /cvsroot/src/bin/ls/ls.c,v
retrieving revision 1.69
diff -u -r1.69 ls.c
--- src/bin/ls/ls.c     29 Aug 2011 14:44:21 -0000      1.69
+++ src/bin/ls/ls.c     7 Nov 2012 11:27:01 -0000
@@ -117,7 +117,7 @@
 {
 
        (void)fprintf(stderr,
-           "usage: %s [-AaBbCcdFfghikLlMmnopqRrSsTtuWwx1] [file ...]\n",
+           "usage: %s [-1AaBbCcdFfghikLlMmnopqRrSsTtuWwx] [file ...]\n",
            getprogname());
        exit(EXIT_FAILURE);
        /* NOTREACHED */
@@ -331,7 +331,7 @@
                fts_options |= FTS_WHITEOUT;
 #endif
 
-       /* If -l or -s, figure out block size. */
+       /* If -i, -l, or -s, figure out block size. */
        if (f_inode || f_longform || f_size) {
                if (!kflag)
                        (void)getbsize(NULL, &blocksize);

--SLDf9lqlvOQaIe6s--

>Unformatted:
 --SLDf9lqlvOQaIe6s
 Content-Type: text/plain; charset=us-ascii
 Content-Disposition: inline
Prev by Date: Re: port-arm/47139 (multiple definition of __umodsi3 on arm)
Next by Date: NetBSD Nightly Trouble Ticket Report
Previous by Thread: Re: port-arm/47139 (multiple definition of __umodsi3 on arm)
Next by Thread: kern/47169: itesio_isa: Add support for ITE8720F
Indexes:
Home | Main Index | Thread Index | Old Index