summaryrefslogtreecommitdiffstats
path: root/bin
diff options
context:
space:
mode:
authorgarys <garys@FreeBSD.org>2005-08-31 17:58:38 +0000
committergarys <garys@FreeBSD.org>2005-08-31 17:58:38 +0000
commita10ff72c1747d7baabe93388931a6b70bc86fb9e (patch)
treee5d58127589ff7e8ff29cce37d2a602107977203 /bin
parent2f4cafe2dd265939df7235ef901ee7912ac064e4 (diff)
downloadFreeBSD-src-a10ff72c1747d7baabe93388931a6b70bc86fb9e.zip
FreeBSD-src-a10ff72c1747d7baabe93388931a6b70bc86fb9e.tar.gz
Improved descriptions of block size handling.
PR: docs/84765 Submitted by: garys Approved by: keramida MFC after: 3 days
Diffstat (limited to 'bin')
-rw-r--r--bin/ls/ls.185
1 files changed, 48 insertions, 37 deletions
diff --git a/bin/ls/ls.1 b/bin/ls/ls.1
index bb73dda..9339667 100644
--- a/bin/ls/ls.1
+++ b/bin/ls/ls.1
@@ -180,29 +180,17 @@ using base 2 for sizes.
.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
@@ -226,13 +214,12 @@ this is the default when output is to a terminal.
.It Fl r
Reverse the order of the sort.
.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 in lexicographical
@@ -318,10 +305,6 @@ number of bytes in the file, abbreviated
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
@@ -340,6 +323,24 @@ If the file is a symbolic link the pathname of the
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
@@ -446,12 +447,15 @@ The following environment variables affect the execution of
.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
@@ -663,3 +667,10 @@ command appeared in
.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.
OpenPOWER on IntegriCloud