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