NAME

       afs_cache - Format of data stored in an AFS client disk cache

DESCRIPTION

       The disk cache on a client machine is composed of multiple Vn files that contain the data,
       a CacheItems file that records index information for all of the Vn files, and a
       VolumeItems file that records the mapping between volume name and mount point for volumes.

       When it initializes, the Cache Manager creates the cache files in the configured cache
       location.  The standard directory name is /usr/vice/cache, but it is acceptable to use a
       directory on a partition with more available space. To designate a different directory,
       change the value in the second field of the /etc/openafs/cacheinfo file before issuing the
       afsd command, or include the -cachedir argument to the afsd command.

   CacheItems
       The CacheItems file records information about each file in the disk cache on a client
       machine (each Vn file). The information includes the file ID number and associated volume
       version number of the AFS file currently stored in the Vn file, which enables the Cache
       Manager to determine which Vn file contains the AFS data it needs to present to an
       application.

       As it initializes, the Cache Manager creates the binary-format CacheItems file in the same
       local disk cache directory as the Vn files that the CacheItems file describes, and it must
       always remain there.

   VolumeItems
       The VolumeItems file records the mapping between volume name and mount point for each
       volume that the Cache Manager has accessed since it initialized on a client machine using
       a disk cache. The Cache Manager uses the mappings to respond correctly to queries about
       the current working directory, which can come from the operating system or commands such
       as the UNIX pwd command.

       As it initializes, the Cache Manager creates the binary-format VolumeItems file in the
       local disk cache directory, and it must always remain there.

   Vn
       A Vn file can store a chunk of cached AFS data on a client machine that is using a disk
       cache. As the Cache Manager initializes, it verifies that the local disk cache directory
       houses a number of Vn files equal to the largest of the following:

       •   100

       •   One and a half times the result of dividing the cache size by the chunk size
           (cachesize/chunksize * 1.5).

       •   The result of dividing the cache size by 10 MB (10,240).

       The Cache Manager determines the cache size from the -blocks argument to the afsd command,
       or if the argument is not included, from the third field of the /etc/openafs/cacheinfo
       file.  The default chunk size is 64 KB; use the -chunksize argument to the afsd command to
       override it. To override the default number of chunks resulting from the calculation,
       include the -files argument to the afsd command. afsd(8) describes the restrictions on
       acceptable values for each of the arguments.

       If the disk cache directory houses fewer Vn files than necessary, the Cache Manager
       creates new ones, assigning each a unique integer n that distinguishes it from the other
       files; the integers start with 1 and increment by one for each Vn file created. The Cache
       Manager removes files if there are more than necessary. The Cache Manager also adds and
       removes Vn files in response to the fs setcachesize command, which can be used to alter
       the cache size between reboots.

       Vn files expand and contract to accommodate the size of the AFS directory listing or file
       they temporarily house. As mentioned, by default each Vn file holds up to 64 KB (65,536
       bytes) of a cached AFS element. AFS elements larger than 64 KB are divided among multiple
       Vn files. If an element is smaller than 64 KB, the Vn file expands only to the required
       size. A Vn file accommodates only a single element, so if there many small cached
       elements, it is possible to exhaust the available Vn files without reaching the maximum
       cache size.

CAUTIONS

       Editing or removing the CacheItems or VolumeItems files or a Vn file can cause a kernel
       panic. If the contents of Vn files seem out of date, clear the files by using the fs flush
       or fs flushvolume command. If any of the cache files are accidentally modified or deleted,
       rebooting the machine usually restores normal performance.

       To alter cache size (and thus the number of Vn files) between reboots, use the fs
       setcachesize command. Alternatively, alter the value of the -blocks, -files or -chunksize
       arguments to the afsd command invoked in the machine's AFS initialization file, and
       reboot. To refresh the contents of one or more Vn files, use the fs flush or fs
       flushvolume command.

SEE ALSO

       cacheinfo(5), afsd(8), fs_checkvolumes(1), fs_flush(1), fs_flushvolume(1),
       fs_setcachesize(1)

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.