3 fs storebehind - Enables asynchronous writes to the file server
7 fs storebehind [B<-kbytes> I<asynchrony for specified names>]
8 [B<-files> I<specific pathnames> [I<specific pathnames> ...]]
9 [B<-allfiles> I<new default (KB)>] [B<-verbose>] [B<-help>]
11 fs st [B<-k> I<asynchrony for specified names>] [B<-f> I<specific pathnames> [I<specific pathnames> ...]]
12 [B<-a> I<new default (KB)>] [B<-v>] [B<-h>]
16 The C<fs storebehind> command enables the Cache Manager to perform a
17 delayed asynchronous write to the File Server when an application
18 closes a file. By default, the Cache Manager writes all data to the
19 File Server immediately and synchronously when an application program
20 closes a file--that is, the B<close> system call does not return until
21 the Cache Manager has actually transferred the final chunk of the file
22 to the File Server. This command specifies the number of kilobytes of
23 a file that can still remain to be written to the File Server when the
24 Cache Manager returns control to the application. It is useful if
25 users working on the machine commonly work with very large files, but
26 also introduces the complications discussed in the L</"CAVEATS"> section.
28 Set either or both of the following in a single command:
34 To set a value that applies to all AFS files manipulated by
35 applications running on the machine, use the B<-allfiles> argument.
36 This value is termed the I<default store asynchrony> for the machine,
37 and persists until the machine reboots. If it is not set, the
38 default value is zero, indicating that the Cache Manager performs
41 As an example, the following setting means that when an
42 application closes a file, the Cache Manager can return control to
43 the application as soon as no more than 10 kilobytes of the file
44 remain to be written to the File Server.
50 To set a value that applies to one or more individual files, and
51 overrides the value of the B<-allfiles> argument for them, combine
52 the B<-kbytes> and B<-files> arguments. The setting persists as long as
53 there is an entry for the file in the kernel table that the Cache
54 Manager uses to track certain information about files. In general,
55 such an entry persists at least until an application closes the
56 file or exits, but the Cache Manager is free to recycle the entry
57 if the file is inactive and it needs to free up slots in the
58 table. To increase the certainty that there is an entry for the
59 file in the table, issue the C<fs storebehind> command shortly before
62 As an example, the following setting means that when an
63 application closes either of the files B<bigfile> and B<biggerfile>, the
64 Cache Manager can return control to the application as soon as no
65 more than a megabyte of the file remains to be written to the File
68 -kbytes 1024 -files bigfile biggerfile
70 Note that once an explicit value has been set for a file, the only
71 way to make it subject to the default store asynchrony once again
72 is to set B<-kbytes> to that value. In other words, there is no
73 combination of arguments that automatically makes a file subject
74 to the default store asynchrony once another value has been set
79 To display the settings that currently apply to individual files or to
80 all files, provide the command's arguments in certain combinations as
81 specified in the L</"OUTPUT"> section of this reference page.
87 =item B<-kbytes> I<asynchrony for specified names>
89 Specifies the number of kilobytes of data from each file named
90 by the B<-files> argument that can remain to be written to the
91 file server when the Cache Manager returns control to an
92 application program that closed the file. The B<-files> argument
93 is required along with this argument. Provide an integer from
94 the range B<0> (which reinstates the Cache Manager's default
95 behavior or writing synchronously) to the maximum AFS file
98 =item B<-files> I<specific pathnames> [I<specific pathnames> ...]
100 Names each file to which the value set with the B<-kbytes>
101 argument applies. The setting persists as long as there is an
102 entry for the file in the kernel table that the Cache Manager
103 uses to track certain information about files. Because closing
104 a file generally erases the entry, when reopening a file the
105 only way to guarantee that the setting still applies is to
106 reissue the command. If this argument is provided without the
107 B<-kbytes> argument, the command reports the current setting for
108 the specified files, and the default store asynchrony.
110 =item B<-allfiles> I<new default (KB)>
112 Sets the default store asynchrony for the local machine, which
113 is the number of kilobytes of data that can remain to be
114 written to the file server when the Cache Manager returns
115 control to the application program that closed a file. The
116 value applies to all AFS files manipulated by applications
117 running on the machine, except those for which settings have
118 been made with the B<-kbytes> and B<-files> arguments. Provide an
119 integer from the range B<0> (which indicates the default of
120 synchronous writes) to the maximum AFS file size.
124 Produces output confirming the settings made with the
125 accompanying B<-kbytes> and B<-files> arguments, the B<-allfiles>
126 argument, or all three. If provided by itself, reports the
127 current default store asynchrony.
131 Prints the online help for this command. All other valid
138 If none of the command's options are included, or if only the B<-verbose>
139 flag is included, the following message reports the default store
140 asynchrony (the setting that applies to all files manipulated by
141 applications running on the local machine and for which not more
142 specific asynchrony is set).
144 Default store asynchrony is x kbytes.
146 A value of C<0> (zero) indicates synchronous writes and is the default if
147 no one has included the B<-allfiles> argument on this command since the
148 machine last rebooted.
150 If the B<-files> argument is provided without the B<-kbytes> argument, the
151 output reports the value that applies to each specified file along
152 with the default store asynchrony. If a particular value has
153 previously been set for a file, the following message reports it:
155 Will store up to y kbytes of file asynchronously.
156 Default store asynchrony is x kbytes.
158 If the default store asynchrony applies to a file because no explicit
159 B<-kbytes> value has been set for it, the message is instead as follows:
161 Will store file according to default.
162 Default store asynchrony is x kbytes.
164 If the B<-verbose> flag is combined with arguments that set values
165 (B<-files> and B<-kbytes>, or B<-allfiles>, or all three), there is a message
166 that confirms immediately that the setting has taken effect. When
167 included without other arguments or flags, the B<-verbose> flag reports
168 the default store asynchrony only.
172 The following command enables the Cache Manager to return control to
173 the application program that closed the file B<test.data> when 100
174 kilobytes still remain to be written to the File Server. The B<-verbose>
175 flag produces output that confirms the new setting, and that the
176 default store asynchrony is zero.
178 fs storebehind -kbytes 100 -files test.data -verbose
179 Will store up to 100 kbytes of test.data asynchronously.
180 Default store asynchrony is 0 kbytes.
182 =head1 PRIVILEGE REQUIRED
184 To include the B<-allfiles> argument, the issuer must be logged in as the
185 local superuser B<root>.
187 To include the B<-kbytes> and B<-files> arguments, the issuer must either be
188 logged in as the local superuser B<root> or have the B<w> (B<write>) permission
189 on the ACL of each file's directory.
191 To view the current settings (by including no arguments, the B<-file>
192 argument alone, or the B<-verbose> argument alone), no privilege is
197 For the following reasons, use of this command is not recommended in
200 In normal circumstances, an asynchronous setting results in the Cache
201 Manager returning control to applications earlier than it otherwise
202 does, but this is not guaranteed.
204 If a delayed write fails, there is no way to notify the application,
205 since the B<close> system call has already returned with a code
208 Writing asynchronously increases the possibility that the user will
209 not notice if a write operation makes the volume that houses the file
210 exceed its quota. As always, the portion of the file that exceeds the
211 volume's quota is lost, which prompts a message such as the following:
213 C<No space left on device>
215 To avoid losing data, it is advisable to verify that the volume
216 housing the file has space available for the amount of data
217 anticipated to be written.
221 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
223 Converted from html to pod by Alf Wachsmann <alfw@slac.stanford.edu>, 2003,
224 and Elizabeth Cassell <e_a_c@mailsnare.net>, 2004,
225 Stanford Linear Accelerator Center, a department of Stanford University.