Date: Wed, 10 Aug 2005 08:39:35 -0700 From: "Gary W. Swearingen" <garys@opusnet.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/84765: [patch] ls(1) manpage doesn't describe block handling well Message-ID: <45br45iyx4.r45@mail.opusnet.com> Resent-Message-ID: <200508101540.j7AFeI4K034319@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 84765 >Category: docs >Synopsis: [patch] ls(1) manpage doesn't describe block handling well >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Wed Aug 10 15:40:18 GMT 2005 >Closed-Date: >Last-Modified: >Originator: Gary W. Swearingen >Release: FreeBSD 5.4-RELEASE i386 >Organization: none >Environment: n/a >Description: The ls(1) manpage doesn't describe block handling well. Pieces of the block size discussion are scattered around. The "total blocks" sometimes output by the -l and -s options is not described completely. >How-To-Repeat: n/a >Fix: I put the main discussion of both issues in the "The Long Format" section, and made the -l, -s, and BLOCKSIZE descriptions reference the main discussion, mostly. --- ls..orig.1 Sun Aug 7 12:24:22 2005 +++ ls.1 Sun Aug 7 16:58:50 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 the 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,11 @@ 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 file system blocks used by each file. +Block sizes and directory totals are handled as decribed in +.Sx The Long Format +subsection below, except (for unknown reasons) the directory totals +are only output with multi-column outputs. .It Fl t Sort by time modified (most recently modified first) before sorting the operands by lexicographical @@ -315,10 +301,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 +319,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 file system blocks used by the files +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. +It may be set with the +.Fl k +option or the +.Ev BLOCKSIZE +environment variable. +Output numbers of blocks will have been rounded up so the number of bytes +is at least as many as is 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 +462,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 +680,7 @@ .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 is probably a bug. >Release-Note: >Audit-Trail: >Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?45br45iyx4.r45>