Bug 84765
| Summary: | [patch] ls(1) manpage doesn't describe block handling well | ||||||
|---|---|---|---|---|---|---|---|
| Product: | Documentation | Reporter: | Gary W. Swearingen <garys> | ||||
| Component: | Books & Articles | Assignee: | Gary W. Swearingen <garys> | ||||
| Status: | Closed FIXED | ||||||
| Severity: | Affects Only Me | ||||||
| Priority: | Normal | ||||||
| Version: | Latest | ||||||
| Hardware: | Any | ||||||
| OS: | Any | ||||||
| Attachments: |
|
||||||
|
Description
Gary W. Swearingen
2005-08-10 16:40:18 UTC
State Changed From-To: open->analyzed PR came with my patch. Responsible Changed From-To: freebsd-doc->garys I'll handle PR, with mentor. On 2005-08-28 15:00, "Gary W. Swearingen" <garys@opusnet.com> wrote: > 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): Just a minor comment below. > --- ls..orig.1 Sun Aug 7 12:24:22 2005 > +++ ls.1 Sun Aug 28 14:50:54 2005 > @@ -337,6 +320,26 @@ > linked-to file is preceded by > .Dq Li -> . > .Pp > +If a file is a directory (and "a file is a directory" sounds a bit confusing. I'm not sure how we can write this in a way that avoids confusion and still retains the original spirit of BSD UNIX that "directories are just special files". Perhaps something like this? If one of the listed directory entries is a directory itself ... Giorgos Keramidas <keramida@freebsd.org> writes: >> +If a file is a directory (and > > "a file is a directory" sounds a bit confusing. I'm not sure how we can > write this in a way that avoids confusion and still retains the original > spirit of BSD UNIX that "directories are just special files". Perhaps > something like this? > > If one of the listed directory entries is a directory itself ... Yeah, I worried about that one too. The next (pre-existing) para talks about the type of file being Directory, FIFO, etc. Your alternative is a bit long. I think the meaning remains if I simply rm the nastiness and repair grammar. From: If a file is a directory (and .Fl d is not used), the listing of the directory's contents is preceeded to: The listing of a directory's contents is preceeded. OK? Here is part of my private PR file that my CVS tool works from. Let me know which parts of this you want to see in the future. I can omit any of: the XMLish lines; the repo; the branch; the commit_msg, if you'd like. <----------------------------------------------provisional_repository> src </---------------------------------------------provisional_repository> <---------------------------------------------provisional_repo_branch> HEAD </--------------------------------------------provisional_repo_branch> <----------------------------------------------provisional_commit_msg> Improved descriptions of block size handling. PR: docs/84765 Submitted by: garys Approved by: keramida MFC after: 3 days </---------------------------------------------provisional_commit_msg> <-----------------------------------------------provisional_file_list> src/bin/ls/ls.1 </----------------------------------------------provisional_file_list> <----------------------------------------------provisional_file_patch> --- ls..orig.1 Sun Aug 7 12:24:22 2005 +++ ls.1 Tue Aug 30 08:19:31 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,24 @@ linked-to file is preceded by .Dq Li -> . .Pp +The listing of a 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 +461,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 +679,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. </---------------------------------------------provisional_file_patch> State Changed From-To: analyzed->patched Committed to HEAD only. State Changed From-To: patched->closed Patched in HEAD, RELENG_6, RELENG_5. |
