3 fs storebehind - Enables asynchronous writes to the file server
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>]
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>]
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>.
29 Set either or both of the following in a single command:
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.
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
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.
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.
66 -kbytes 1024 -files bigfile biggerfile
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.
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>.
82 For the following reasons, use of this command is not recommended in most
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.
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
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:
98 No space left on device
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
108 =item B<-kbytes> <I<asynchrony for specified names>>
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
118 =item B<-files> <I<specific pathnames>>+
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.
129 =item B<-allfiles> <I<new default (KB)>>
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.
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
149 Prints the online help for this command. All other valid options are
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
162 Default store asynchrony is <x> kbytes.
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.
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:
173 Will store up to <y> kbytes of <file> asynchronously.
174 Default store asynchrony is <x> kbytes.
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:
179 Will store <file> according to default.
180 Default store asynchrony is <x> kbytes.
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.
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
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.
200 =head1 PRIVILEGE REQUIRED
202 To include the B<-allfiles> argument, the issuer must be logged in as the
203 local superuser C<root>.
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.
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
219 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
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.