From owner-freebsd-doc@FreeBSD.ORG Sun Aug 28 21:59:25 2005 Return-Path: X-Original-To: freebsd-doc@FreeBSD.org Delivered-To: freebsd-doc@FreeBSD.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id BAA6216A41F; Sun, 28 Aug 2005 21:59:25 +0000 (GMT) (envelope-from garys@opusnet.com) Received: from opusnet.com (mail.opusnet.com [209.210.200.6]) by mx1.FreeBSD.org (Postfix) with ESMTP id 64A9E43D45; Sun, 28 Aug 2005 21:59:25 +0000 (GMT) (envelope-from garys@opusnet.com) Received: from localhost.localhost [70.98.246.232] by opusnet.com with ESMTP (SMTPD32-8.05) id A3B997A30038; Sun, 28 Aug 2005 14:59:21 -0700 Received: from localhost.localhost (localhost.localhost [127.0.0.1]) by localhost.localhost (8.13.3/8.13.3) with ESMTP id j7SM0Ffa048400; Sun, 28 Aug 2005 15:00:15 -0700 (PDT) (envelope-from garys@opusnet.com) Received: (from jojo@localhost) by localhost.localhost (8.13.3/8.13.3/Submit) id j7SM09qG048399; Sun, 28 Aug 2005 15:00:09 -0700 (PDT) (envelope-from garys@opusnet.com) To: Giorgos Keramidas From: garys@opusnet.com (Gary W. Swearingen) Date: Sun, 28 Aug 2005 15:00:09 -0700 Message-ID: User-Agent: Gnus/5.1007 (Gnus v5.10.7) XEmacs/21.4.17 (Jumbo Shrimp, berkeley-unix) MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Cc: freebsd-doc@FreeBSD.org Subject: Re: docs/84765: [patch] ls(1) manpage doesn't describe block handling well X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 28 Aug 2005 21:59:25 -0000 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.