DF(SVAS)

Shore Programmer's Manual - 2 August 96

NAME

df \- Shore disk usage and free space report

SYNOPSIS

df [-a | -s | -p | -b | -e]

DESCRIPTION

Df is a command given to the Shore server's Tcl shell, and it prints voluminous information about disk space utilization.

ARGUMENTS

-a causes all statistics to be printed.

-s causes only summary information to be printed.

-p reports statistics in units of pages.

-b reports statistics in units of bytes.

-e reports statistics about extents and files.

All statistics are computed and reported for one volume at a time.

EXTENT and FILE STATISTICS

An extent is a unit of allocation; 8 pages make an extent, and one extent is allocated to a Shore Storage Manager (SSM) file, B-tree, R-tree or RD-tree at a time. In some cases, the server creates small B-trees, which are handled specially, and they are assigned one page rather than a full extent. These B-trees are converted, if necessary, to "normal" B-trees when they grow.

R-trees and RD-trees cannot be created by the Shore applications, but the statistics are reported by the SSM and printed by the Shore server.

When a Shore file system is created on a volume, the Shore server creates one file for storing registered objects. It also creates one file for each pool created by an application.

The statistics reported for files and extents are:

Files: The number of files created on the volume.
1-page B-trees: The number of small B-trees on the volume.
B-trees: The number of full-sized B-trees on the volume.
R-trees: The number of full-sized R-trees on the volume.
RD-trees: The number of full-sized RD-trees on the volume.
Pages per extent: The size of an extent in pages (a compile-time constant).
Extents in volume: The number of extents in the formatted volume (determined when the volume is formatted).
vol hdr, bitmap ext: The number of extents assigned for use as bit-map pages and the volume header.
free extents: The number of unallocated extents.
allocated extents: The number extents allocated for user data.

PAGE STATISTICS

A page is normally 8 kilobytes, although a system can be rebuilt to use pages of a different size.

The statistics reported for pages are:

Total pages in volume: The total number of pages in all the volume's extents. Following this is a long list of the various kinds of pages that have been allocated on the volume. The kinds are as follows:
small obj: pages containing small objects -- objects that are small enough that they can fit in their entirety on one page, along with the various page headers and alignment taken into account.
large data: pages containing the data of large objects
large data: pages used for the data structure that links together large data pages.
xxxx lf pgs: leaf pages of a tree of type xxxx.
xxxx intern pgs: internal pages of a tree of type xxxx.
1pbtree: one-page B-tree
btree: a B-tree created by an application program
rtree, rdtree: always zero
store-dir: a B-tree used by the SSM for maintenance of volume data structures.
root-idx: a B-tree used by the SSM for maintenance of volume data structures, and used by the Shore server for locating the root directory, and for storing information about persistent mounts.
lid-map: a B-tree used by the SSM to map logical OIDs to physical IDs.
lidR-map: a B-tree used by the SSM for a reverse mapping for remote IDs.
used alloc pgs: The total number of pages that have been allocated. This number is the sum of preceding list of allocated pages broken down by kind.
unused alloc pgs: The number of unused pages in allocated extents.
Pages in alloc extents: The total number of pages in extents that have been allocated.
Pages in unalloc exts: The total number of pages in free extents.
Pages in hdr, bmap ext: The number of pages in the extent allocated for the volume header and for the free-space bit-map.

BYTE STATISTICS

The statistics reported in units of bytes might be daunting at first, but they can be interpreted rather easily, with the following information:

The intent is to give as much detail as possible about where the bytes fall on every kind of page that a volume has:

used: any statistic so marked refers to bytes that are in use, whether for an application's data, or for overhead of some sort, such as headers or alignment.
unused, allocated: bytes that are on allocated pages (pages in allocated extents) but that are unused, either because the entire page is unused, or because the bytes are unused (depending on the statistic). Pages are assigned a purpose when their containing extent is allocated, even though the entire page is not in use; thus, unused pages can be designated "unused small obj pages", etc.
unallocated: bytes in pages that are in unallocated extents.

Many statistics are reported as summary statistics, followed by a report of more specific statistics, with percentages. The intent is to indicate the distribution of the items being reported in detail, in terms of percentages of the summary statistic. For example,

In pages used                      :                          2400256

is the summary, and

In object pages                    :    2023424  (  84.300% of    2400256)
In SM indexes                      :     319488  (  13.311% of    2400256)
In user indexes                    :      32768  (   1.365% of    2400256)

give more detail about the pages in use. Furthermore, the "object pages" is reported in more and more detail:

     user data in records          :    1627726  (  80.444% of    2023424)
         small object data         :    1194450  (  73.382% of    1627726)
         large object data         :     433276  (  26.618% of    1627726)

     record headers                :     122552  (   6.057% of    2023424)

     unused in allocated pages     :     159236  (   7.870% of    2023424)
         in small object pages     :     154032  (  96.732% of     159236)
         in large object leaf pgs  :       5204  (   3.268% of     159236)
         in large obj interior pgs :          0  (   0.000% of     159236)

     bytes lost in alignment       :       1694  (   0.084% of    2023424)
         for sysprops (headers)    :         16  (   0.945% of       1694)
         for user data             :       1678  (  99.055% of       1694)

     SM page headers               :      18556  (   0.917% of    2023424)
         for small obj pgs         :      14668  (  79.047% of      18556)
         for lg obj data pgs       :       3888  (  20.953% of      18556)

     other SM overhead             :      93660  (   4.629% of    2023424)
         for rec tags              :      73408  (  78.377% of      93660)
         for slots                 :      20212  (  21.580% of      93660)
             slots used            :      18352  (  90.798% of      20212)
             slots unused          :       1860  (   9.202% of      20212)
         for large object overhead :         40  (   0.043% of      93660)
             chunks                :         40  ( 100.000% of         40)
             indirect              :          0  (   0.000% of         40)
             index pg              :          0  (   0.000% of         40)

DEFINITIONS for BYTE STATISTICS

record: A record is the SSM portion of a small-object page that contains a Shore object. A record is further split into a record tag, record header and a record body. The record header contains the system properties, or sysprops.
sysprops: The Shore system properties associated with a Shore object, including the owner, permission bits, last-modified timestamp, etc.
rec tag: A tiny header attached to each record for SSM purposes.
lost in alignment: Each portion of a record is 8-byte aligned, so some bytes are lost in alignment. A Shore object containing 1 byte of application data, for example, loses 7 bytes in alignment of the record body.
object pages: pages used for small objects and large objects.
page headers: Each page has a small header containing information about the page and its status for recovery purposes.
slot: Each small-object page contains a slot array that is used to locate the records on the page.
small obj: pages containing small objects -- objects that are small enough that they can fit in their entirety on one page, along with the various page headers and alignment taken into account.
lg obj data: pages containing the data of large objects
interior: pages used for the data structures (trees) links together other pages, whether for B-trees or for large objects

SUMMARY STATISTICS

The summary statistics report selected information that is reported in each of other categories.

BUGS

Df leaves you sitting in the directory that is the root of the last volume for which it computed the statistics.

VERSION

This manual page applies to Version 1.0 of theShore software.

SPONSORSHIP

The Shore project is sponsored by the Advanced Research Project Agency, ARPA order number 018 (formerly 8230), monitored by the U.S. Army Research Laboratory under contract DAAB07-92-C-Q508.