doc: fix some broken link specifications
[openafs.git] / 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 =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.