doc/man-pages/pod5/afs_cache.pod

   1 =head1 NAME
   2
   3 afs_cache - Format of data stored in an AFS client disk cache
   4
   5 =head1 DESCRIPTION
   6
   7 The disk cache on a client machine is composed of multiple F<VI<n>> files
   8 that contain the data, a F<CacheItems> file that records index information
   9 for all of the F<VI<n>> files, and a F<VolumeItems> file that records the
  10 mapping between volume name and mount point for volumes.
  11
  12 When it initializes, the Cache Manager creates the cache files in the
  13 configured cache location.  The standard directory name is
  14 F</usr/vice/cache>, but it is acceptable to use a directory on a partition
  15 with more available space. To designate a different directory, change the
  16 value in the second field of the F</usr/vice/etc/cacheinfo> file before
  17 issuing the B<afsd> command, or include the B<-cachedir> argument to the
  18 B<afsd> command.
  19
  20 =head2 F<CacheItems>
  21
  22 The CacheItems file records information about each file in the disk cache
  23 on a client machine (each F<VI<n>> file). The information includes the
  24 file ID number and associated volume version number of the AFS file
  25 currently stored in the B<V>I<n> file, which enables the Cache Manager to
  26 determine which F<VI<n>> file contains the AFS data it needs to present to
  27 an application.
  28
  29 As it initializes, the Cache Manager creates the binary-format
  30 F<CacheItems> file in the same local disk cache directory as the F<VI<n>>
  31 files that the F<CacheItems> file describes, and it must always remain
  32 there.
  33
  34 =head2 F<VolumeItems>
  35
  36 The F<VolumeItems> file records the mapping between volume name and mount
  37 point for each volume that the Cache Manager has accessed since it
  38 initialized on a client machine using a disk cache. The Cache Manager uses
  39 the mappings to respond correctly to queries about the current working
  40 directory, which can come from the operating system or commands such as
  41 the UNIX B<pwd> command.
  42
  43 As it initializes, the Cache Manager creates the binary-format
  44 F<VolumeItems> file in the local disk cache directory, and it must always
  45 remain there.
  46
  47 =head2 F<VI<n>>
  48
  49 A F<VI<n>> file can store a chunk of cached AFS data on a client machine
  50 that is using a disk cache. As the Cache Manager initializes, it verifies
  51 that the local disk cache directory houses a number of F<VI<n>> files
  52 equal to the largest of the following:
  53
  54 =over 4
  55
  56 =item *
  57
  58 100
  59
  60 =item *
  61
  62 One and a half times the result of dividing the cache size by the chunk
  63 size (cachesize/chunksize * 1.5).
  64
  65 =item *
  66
  67 The result of dividing the cache size by 10 MB (10,240).
  68
  69 =back
  70
  71 The Cache Manager determines the cache size from the B<-blocks> argument
  72 to the B<afsd> command, or if the argument is not included, from the third
  73 field of the F</usr/vice/etc/cacheinfo> file.  The default chunk size is
  74 64 KB; use the B<-chunksize> argument to the B<afsd> command to override
  75 it. To override the default number of chunks resulting from the
  76 calculation, include the B<-files> argument to the B<afsd>
  77 command. L<afsd(8)> describes the restrictions on acceptable values for
  78 each of the arguments.
  79
  80 If the disk cache directory houses fewer F<VI<n>> files than necessary,
  81 the Cache Manager creates new ones, assigning each a unique integer I<n>
  82 that distinguishes it from the other files; the integers start with 1 and
  83 increment by one for each F<VI<n>> file created. The Cache Manager removes
  84 files if there are more than necessary. The Cache Manager also adds and
  85 removes F<VI<n>> files in response to the B<fs setcachesize> command,
  86 which can be used to alter the cache size between reboots.
  87
  88 F<VI<n>> files expand and contract to accommodate the size of the AFS
  89 directory listing or file they temporarily house. As mentioned, by default
  90 each F<VI<n>> file holds up to 64 KB (65,536 bytes) of a cached AFS
  91 element. AFS elements larger than 64 KB are divided among multiple
  92 B<V>I<n> files. If an element is smaller than 64 KB, the F<VI<n>> file
  93 expands only to the required size. A F<VI<n>> file accommodates only a
  94 single element, so if there many small cached elements, it is possible to
  95 exhaust the available F<VI<n>> files without reaching the maximum cache
  96 size.
  97
  98 =head1 CAUTIONS
  99
 100 Editing or removing the F<CacheItems> or F<VolumeItems> files or a
 101 F<VI<n>> file can cause a kernel panic. If the contents of F<VI<n>> files
 102 seem out of date, clear the files by using the B<fs flush> or B<fs
 103 flushvolume> command. If any of the cache files are accidentally modified
 104 or deleted, rebooting the machine usually restores normal performance.
 105
 106 To alter cache size (and thus the number of F<VI<n>> files) between
 107 reboots, use the B<fs setcachesize> command. Alternatively, alter the
 108 value of the B<-blocks>, B<-files> or B<-chunksize> arguments to the
 109 B<afsd> command invoked in the machine's AFS initialization file, and
 110 reboot. To refresh the contents of one or more F<VI<n>> files, use the
 111 B<fs flush> or B<fs flushvolume> command.
 112
 113 =head1 SEE ALSO
 114
 115 L<cacheinfo(5)>,
 116 L<afsd(8)>,
 117 L<fs_checkvolumes(1)>,
 118 L<fs_flush(1)>,
 119 L<fs_flushvolume(1)>,
 120 L<fs_setcachesize(1)>
 121
 122 =head1 COPYRIGHT
 123
 124 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 125
 126 This documentation is covered by the IBM Public License Version 1.0.  It was
 127 converted from HTML to POD by software written by Chas Williams and Russ
 128 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.