doc/man-pages/pod1/fs_storebehind.pod

   1 =head1 NAME
   2
   3 fs_storebehind - Enables asynchronous writes to the file server
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<fs storebehind> S<<< [B<-kbytes> <I<asynchrony for specified names>>] >>>
  11     S<<< [B<-files> <I<specific pathnames>>+] >>>
  12     S<<< [B<-allfiles> <I<new default (KB)>>] >>> [B<-verbose>] [B<-help>]
  13
  14 B<fs st> S<<< [B<-k> <I<asynchrony for specified names>>] >>>
  15     S<<< [B<-f> <I<specific pathnames>>+] >>>
  16     S<<< [B<-a> <I<new default (KB)>>] >>> [B<-v>] [B<-h>]
  17
  18 =for html
  19 </div>
  20
  21 =head1 DESCRIPTION
  22
  23 The B<fs storebehind> command enables the Cache Manager to perform a
  24 delayed asynchronous write to the File Server when an application closes a
  25 file. By default, the Cache Manager writes all data to the File Server
  26 immediately and synchronously when an application program closes a file --
  27 that is, the close() system call does not return until the Cache Manager
  28 has actually transferred the final chunk of the file to the File
  29 Server. This command specifies the number of kilobytes of a file that can
  30 still remain to be written to the File Server when the Cache Manager
  31 returns control to the application. It is useful if users working on the
  32 machine commonly work with very large files, but also introduces the
  33 complications discussed in the L</CAUTIONS>.
  34
  35 Set either or both of the following in a single command:
  36
  37 =over 4
  38
  39 =item *
  40
  41 To set a value that applies to all AFS files manipulated by applications
  42 running on the machine, use the B<-allfiles> argument. This value is
  43 termed the I<default store asynchrony> for the machine, and persists until
  44 the machine reboots. If it is not set, the default value is zero,
  45 indicating that the Cache Manager performs synchronous writes.
  46
  47 As an example, the following setting means that when an application closes
  48 a file, the Cache Manager can return control to the application as soon as
  49 no more than 10 kilobytes of the file remain to be written to the File
  50 Server.
  51
  52    -allfiles 10
  53
  54 =item *
  55
  56 To set a value that applies to one or more individual files, and overrides
  57 the value of the B<-allfiles> argument for them, combine the B<-kbytes>
  58 and B<-files> arguments. The setting persists as long as there is an entry
  59 for the file in the kernel table that the Cache Manager uses to track
  60 certain information about files. In general, such an entry persists at
  61 least until an application closes the file or exits, but the Cache Manager
  62 is free to recycle the entry if the file is inactive and it needs to free
  63 up slots in the table. To increase the certainty that there is an entry
  64 for the file in the table, issue the B<fs storebehind> command shortly
  65 before closing the file.
  66
  67 As an example, the following setting means that when an application closes
  68 either of the files B<bigfile> and B<biggerfile>, the Cache Manager can
  69 return control to the application as soon as no more than a megabyte of
  70 the file remains to be written to the File Server.
  71
  72    -kbytes 1024 -files bigfile biggerfile
  73
  74 Note that once an explicit value has been set for a file, the only way to
  75 make it subject to the default store asynchrony once again is to set
  76 B<-kbytes> to that value. In other words, there is no combination of
  77 arguments that automatically makes a file subject to the default store
  78 asynchrony once another value has been set for the file.
  79
  80 =back
  81
  82 To display the settings that currently apply to individual files or to all
  83 files, provide the command's arguments in certain combinations as
  84 specified in L</OUTPUT>.
  85
  86 =head1 CAUTIONS
  87
  88 For the following reasons, use of this command is not recommended in most
  89 cases.
  90
  91 In normal circumstances, an asynchronous setting results in the Cache
  92 Manager returning control to applications earlier than it otherwise does,
  93 but this is not guaranteed.
  94
  95 If a delayed write fails, there is no way to notify the application, since
  96 the close() system call has already returned with a code indicating
  97 success.
  98
  99 Writing asynchronously increases the possibility that the user will not
 100 notice if a write operation makes the volume that houses the file exceed
 101 its quota. As always, the portion of the file that exceeds the volume's
 102 quota is lost, which prompts a message such as the following:
 103
 104    No space left on device
 105
 106 To avoid losing data, it is advisable to verify that the volume housing
 107 the file has space available for the amount of data anticipated to be
 108 written.
 109
 110 =head1 OPTIONS
 111
 112 =over 4
 113
 114 =item B<-kbytes> <I<asynchrony for specified names>>
 115
 116 Specifies the number of kilobytes of data from each file named by the
 117 B<-files> argument that can remain to be written to the file server when
 118 the Cache Manager returns control to an application program that closed
 119 the file. The B<-files> argument is required along with this
 120 argument. Provide an integer from the range C<0> (which reinstates the
 121 Cache Manager's default behavior or writing synchronously) to the maximum
 122 AFS file size.
 123
 124 =item B<-files> <I<specific pathnames>>+
 125
 126 Names each file to which the value set with the B<-kbytes> argument
 127 applies. The setting persists as long as there is an entry for the file in
 128 the kernel table that the Cache Manager uses to track certain information
 129 about files. Because closing a file generally erases the entry, when
 130 reopening a file the only way to guarantee that the setting still applies
 131 is to reissue the command. If this argument is provided without the
 132 B<-kbytes> argument, the command reports the current setting for the
 133 specified files, and the default store asynchrony.
 134
 135 =item B<-allfiles> <I<new default (KB)>>
 136
 137 Sets the default store asynchrony for the local machine, which is the
 138 number of kilobytes of data that can remain to be written to the file
 139 server when the Cache Manager returns control to the application program
 140 that closed a file. The value applies to all AFS files manipulated by
 141 applications running on the machine, except those for which settings have
 142 been made with the B<-kbytes> and B<-files> arguments. Provide an integer
 143 from the range C<0> (which indicates the default of synchronous writes) to
 144 the maximum AFS file size.
 145
 146 =item B<-verbose>
 147
 148 Produces output confirming the settings made with the accompanying
 149 B<-kbytes> and B<-files> arguments, the B<-allfiles> argument, or all
 150 three. If provided by itself, reports the current default store
 151 asynchrony.
 152
 153 =item B<-help>
 154
 155 Prints the online help for this command. All other valid options are
 156 ignored.
 157
 158 =back
 159
 160 =head1 OUTPUT
 161
 162 If none of the command's options are included, or if only the B<-verbose>
 163 flag is included, the following message reports the default store
 164 asynchrony (the setting that applies to all files manipulated by
 165 applications running on the local machine and for which not more specific
 166 asynchrony is set).
 167
 168    Default store asynchrony is <x> kbytes.
 169
 170 A value of C<0> (zero) indicates synchronous writes and is the default if
 171 no one has included the B<-allfiles> argument on this command since the
 172 machine last rebooted.
 173
 174 If the B<-files> argument is provided without the B<-kbytes> argument, the
 175 output reports the value that applies to each specified file along with
 176 the default store asynchrony. If a particular value has previously been
 177 set for a file, the following message reports it:
 178
 179    Will store up to <y> kbytes of <file> asynchronously.
 180    Default store asynchrony is <x> kbytes.
 181
 182 If the default store asynchrony applies to a file because no explicit
 183 B<-kbytes> value has been set for it, the message is instead as follows:
 184
 185    Will store <file> according to default.
 186    Default store asynchrony is <x> kbytes.
 187
 188 If the B<-verbose> flag is combined with arguments that set values
 189 (B<-files> and B<-kbytes>, or B<-allfiles>, or all three), there is a
 190 message that confirms immediately that the setting has taken effect. When
 191 included without other arguments or flags, the B<-verbose> flag reports
 192 the default store asynchrony only.
 193
 194 =head1 EXAMPLES
 195
 196 The following command enables the Cache Manager to return control to the
 197 application program that closed the file F<test.data> when 100 kilobytes
 198 still remain to be written to the File Server. The B<-verbose> flag
 199 produces output that confirms the new setting, and that the default store
 200 asynchrony is zero.
 201
 202    % fs storebehind -kbytes 100 -files test.data -verbose
 203    Will store up to 100 kbytes of test.data asynchronously.
 204    Default store asynchrony is 0 kbytes.
 205
 206 =head1 PRIVILEGE REQUIRED
 207
 208 To include the B<-allfiles> argument, the issuer must be logged in as the
 209 local superuser C<root>.
 210
 211 To include the B<-kbytes> and B<-files> arguments, the issuer must either
 212 be logged in as the local superuser C<root> or have the C<w> (write)
 213 permission on the ACL of each file's directory.
 214
 215 To view the current settings (by including no arguments, the B<-file>
 216 argument alone, or the B<-verbose> argument alone), no privilege is
 217 required.
 218
 219 =head1 SEE ALSO
 220
 221 L<afsd(8)>
 222
 223 =head1 COPYRIGHT
 224
 225 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 226
 227 This documentation is covered by the IBM Public License Version 1.0.  It was
 228 converted from HTML to POD by software written by Chas Williams and Russ
 229 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.