Commit | Line | Data |
---|---|---|
805e021f CE |
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. |