Date: Sun, 28 Aug 2005 15:00:09 -0700 From: garys@opusnet.com (Gary W. Swearingen) To: Giorgos Keramidas <keramida@FreeBSD.org> Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/84765: [patch] ls(1) manpage doesn't describe block handling well Message-ID: <j1acj1wwly.cj1@mail.opusnet.com>
next in thread | raw e-mail | index | archive | help
Well, I've done a little with gnats. I hanged several times while editing in vi. I switched to emacs and I hanged once when exiting, but the PR looked OK. Here's an new-and-improved patch for your approval (or anyone's comment): --- ls..orig.1 Sun Aug 7 12:24:22 2005 +++ ls.1 Sun Aug 28 14:50:54 2005 @@ -176,29 +176,17 @@ .It Fl i For each file, print the file's file serial number (inode number). .It Fl k -If the -.Fl s -option is specified, print the file size allocation in kilobytes, -not blocks. -This option overrides the environment variable -.Ev BLOCKSIZE . -Note that -.Fl k -is mutually exclusive to -.Fl h , -and later -.Fl k -will nullify earlier -.Fl h . +This has the same effect as setting environment variable +.Ev BLOCKSIZE +to 1024, except that it also nullifies any +.Fl h +options to its left. .It Fl l (The lowercase letter .Dq ell . ) -List in long format. -(See below.) -A total sum (in blocks, see the -.Fl s -option for the block size unit) for all the file -sizes is output on a line before the long listing. +List files in the long format, as described in the +.Sx The Long Format +subsection below. .It Fl m Stream output format; list files across the page, separated by commas. .It Fl n @@ -223,13 +211,12 @@ Reverse the order of the sort to get reverse lexicographical order or the oldest entries first. .It Fl s -Display the number of file system blocks actually used by each file, in units -of 512 bytes, where partial units are rounded up to the next integer value. -A total sum for all the file -sizes is output on a line before the listing. -The environment variable -.Ev BLOCKSIZE -overrides the unit size of 512 bytes. +Display the number of blocks used in the file system by each file. +Block sizes and directory totals are handled as decribed in +.Sx The Long Format +subsection below, except (if the long format is not also requested) +the directory totals are not output when the output is in a +single column, even if multi-column output is requested. .It Fl t Sort by time modified (most recently modified first) before sorting the operands by lexicographical @@ -315,10 +302,6 @@ month, day-of-month file was last modified, hour file last modified, minute file last modified, and the pathname. -In addition, for each directory whose contents are displayed, the total -number of 512-byte blocks used by the files in the directory is displayed -on a line by itself immediately before the information for the files in the -directory. .Pp If the modification time of the file is more than 6 months in the past or future, then the year of the last modification @@ -337,6 +320,26 @@ linked-to file is preceded by .Dq Li -> . .Pp +If a file is a directory (and +.Fl d +is not used), the listing of the directory's contents is preceeded +by a labeled total number of blocks used in the file system by the files +which are listed as the directory's contents +(which may or may not include +.Pa \&. +and +.Pa .. +and other files which start with a dot, depending on other options). +.Pp +The default block size is 512 bytes. +The block size may be set with option +.Fl k +or environment variable +.Ev BLOCKSIZE . +Numbers of blocks in the output will have been rounded up so the +numbers of bytes is at least as many as used by the corresponding +file system blocks (which might have a different size). +.Pp The file mode printed under the .Fl l option consists of the @@ -460,12 +463,15 @@ .Nm : .Bl -tag -width ".Ev CLICOLOR_FORCE" .It Ev BLOCKSIZE -If the environment variable -.Ev BLOCKSIZE -is set, the block counts -(see -.Fl s ) -will be displayed in units of that size block. +If this is set, its value, rounded up to 512 or down to a +multiple of 512, will be used as the block size in bytes by the +.Fl l +and +.Fl s +options. +See +.Sx The Long Format +subsection for more information. .It Ev CLICOLOR Use .Tn ANSI @@ -675,3 +681,10 @@ .Sh BUGS To maintain backward compatibility, the relationships between the many options are quite complex. +.Pp +The exception mentioned in the +.Fl s +option description might be a feature that was +based on the fact that single-column output +usually goes to something other than a terminal. +It is debatable whether this is a design bug.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?j1acj1wwly.cj1>