>Number:         14291
>Category:       bin
>Synopsis:       ls(1) doesn't explain what file size of a directory means
>Confidential:   no
>Severity:       non-critical
>Priority:       low
>Responsible:    bin-bug-people
>State:          open
>Class:          doc-bug
>Submitter-Id:   net
>Arrival-Date:   Thu Oct 18 12:38:00 PDT 2001
>Closed-Date:
>Last-Modified:
>Originator:     Jeremy C. Reed
>Release:        not current
>Organization:
http://bsd.reedmedia.net/
>Environment:
	
System: NetBSD rainier 1.5.1_BETA NetBSD 1.5.1_BETA (JCR-1.5-20010407) #0: Sat Apr 7 01:44:35 PDT 2001 reed@rainier:/usr/src/sys/arch/i386/compile/JCR-1.5-20010407 i386


>Description:
ls -l showing subdirectories size is unclear from ls(1) manual page.
For example, an empty directory shows size 512. And there doesn't seem
to be any consistent correlation to this size compared to actual size
of the directories contents.

To the novice, it is unclear that this represents the file contain the
dirent records.

This should be documented in ls(1) and stat(2).
>How-To-Repeat:
man ls
>Fix:
Two patches follow (made against netbsd-1-5):

--- /usr/src/bin/ls/ls.1        Sun Aug 27 21:25:45 2000
+++ ls.1        Thu Oct 18 12:27:37 2001
@@ -339,6 +339,12 @@
 .Xr sticky 8 . )
 .El
 .El
+.Pp
+The number of bytes displayed for a directory represents the size
+of a special directory file (which records the inode
+numbers and filenames of the entries for that directory).
+(See
+.Xr dirent 5 . )
 .Sh RETURN VALUES
 The
 .Nm
@@ -382,6 +388,9 @@
 .Sh SEE ALSO
 .Xr chflags 1 ,
 .Xr chmod 1 ,
+.Xr stat 2 ,
+.Xr getbsize 3,
+.Xr dir 5 ,
 .Xr symlink 7 ,
 .Xr sticky 8
 .Sh STANDARDS


--- /usr/src/lib/libc/sys/stat.2        Thu Jun 29 16:57:39 2000
+++ stat.2      Thu Oct 18 12:27:07 2001
@@ -147,6 +147,11 @@
 .Fa struct stat
 are as follows:
 .Bl -tag -width XXXst_blksize
+.It st_size
+The size of the file in bytes. (If the
+.Fa path
+is a directory, then it provides the size of this directory file; see
+.Xr dir 5 . )
 .It st_blksize
 The optimal I/O block size for the file.
 .It st_blocks
@@ -265,6 +270,7 @@
 .Xr chmod 2 ,
 .Xr chown 2 ,
 .Xr utimes 2 ,
+.Xr dir 5 ,
 .Xr symlink 7
 .Sh BUGS
 Applying

>Release-Note:
>Audit-Trail:
>Unformatted: