| 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. |