doc/xml/AdminReference/sect1/fs_storebehind.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="fs_storebehind1">
   3   <refmeta>
   4     <refentrytitle>fs storebehind</refentrytitle>
   5     <manvolnum>1</manvolnum>
   6   </refmeta>
   7   <refnamediv>
   8     <refname>fs storebehind</refname>
   9     <refpurpose>Enables asynchronous writes to the file server</refpurpose>
  10   </refnamediv>
  11   <refsect1>
  12     <title>Synopsis</title>
  13     <para><emphasis role="bold">fs storebehind</emphasis> [<emphasis role="bold">-kbytes</emphasis> &lt;<emphasis>asynchrony for specified names</emphasis>&gt;]
  14         [<emphasis role="bold">-files</emphasis> &lt;<emphasis>specific pathnames</emphasis>&gt;+]
  15         [<emphasis role="bold">-allfiles</emphasis> &lt;<emphasis>new default (KB)</emphasis>&gt;] [<emphasis role="bold">-verbose</emphasis>] [<emphasis role="bold">-help</emphasis>]</para>
  16
  17     <para><emphasis role="bold">fs st</emphasis> [<emphasis role="bold">-k</emphasis> &lt;<emphasis>asynchrony for specified names</emphasis>&gt;]
  18         [<emphasis role="bold">-f</emphasis> &lt;<emphasis>specific pathnames</emphasis>&gt;+]
  19         [<emphasis role="bold">-a</emphasis> &lt;<emphasis>new default (KB)</emphasis>&gt;] [<emphasis role="bold">-v</emphasis>] [<emphasis role="bold">-h</emphasis>]</para>
  20
  21   </refsect1>
  22   <refsect1>
  23     <title>Description</title>
  24     <para>The <emphasis role="bold">fs storebehind</emphasis> command enables the Cache Manager to perform a
  25     delayed asynchronous write to the File Server when an application closes a
  26     file. By default, the Cache Manager writes all data to the File Server
  27     immediately and synchronously when an application program closes a file --
  28     that is, the close() system call does not return until the Cache Manager
  29     has actually transferred the final chunk of the file to the File
  30     Server. This command specifies the number of kilobytes of a file that can
  31     still remain to be written to the File Server when the Cache Manager
  32     returns control to the application. It is useful if users working on the
  33     machine commonly work with very large files, but also introduces the
  34     complications discussed in the <link linkend="CAUTIONS">CAUTIONS</link>.</para>
  35
  36     <para>Set either or both of the following in a single command:</para>
  37
  38     <itemizedlist>
  39       <listitem>
  40         <para>To set a value that applies to all AFS files manipulated by applications
  41         running on the machine, use the <emphasis role="bold">-allfiles</emphasis> argument. This value is
  42         termed the <emphasis>default store asynchrony</emphasis> for the machine, and persists until
  43         the machine reboots. If it is not set, the default value is zero,
  44         indicating that the Cache Manager performs synchronous writes.</para>
  45
  46         <para>As an example, the following setting means that when an application closes
  47         a file, the Cache Manager can return control to the application as soon as
  48         no more than 10 kilobytes of the file remain to be written to the File
  49         Server.</para>
  50
  51 <programlisting>
  52    -allfiles 10
  53
  54 </programlisting>
  55         </listitem>
  56         <listitem>
  57           <para>To set a value that applies to one or more individual files, and overrides
  58           the value of the <emphasis role="bold">-allfiles</emphasis> argument for them, combine the <emphasis role="bold">-kbytes</emphasis>
  59           and <emphasis role="bold">-files</emphasis> arguments. The setting persists as long as there is an entry
  60           for the file in the kernel table that the Cache Manager uses to track
  61           certain information about files. In general, such an entry persists at
  62           least until an application closes the file or exits, but the Cache Manager
  63           is free to recycle the entry if the file is inactive and it needs to free
  64           up slots in the table. To increase the certainty that there is an entry
  65           for the file in the table, issue the <emphasis role="bold">fs storebehind</emphasis> command shortly
  66           before closing the file.</para>
  67
  68           <para>As an example, the following setting means that when an application closes
  69           either of the files <emphasis role="bold">bigfile</emphasis> and <emphasis role="bold">biggerfile</emphasis>, the Cache Manager can
  70           return control to the application as soon as no more than a megabyte of
  71           the file remains to be written to the File Server.</para>
  72
  73 <programlisting>
  74    -kbytes 1024 -files bigfile biggerfile
  75
  76 </programlisting>
  77             <para>Note that once an explicit value has been set for a file, the only way to
  78             make it subject to the default store asynchrony once again is to set
  79             <emphasis role="bold">-kbytes</emphasis> to that value. In other words, there is no combination of
  80             arguments that automatically makes a file subject to the default store
  81             asynchrony once another value has been set for the file.</para>
  82
  83           </listitem>
  84         </itemizedlist>
  85         <para>To display the settings that currently apply to individual files or to all
  86         files, provide the command's arguments in certain combinations as
  87         specified in <link linkend="OUTPUT">OUTPUT</link>.</para>
  88
  89       </refsect1>
  90       <refsect1>
  91         <title>Cautions</title>
  92         <para>For the following reasons, use of this command is not recommended in most
  93         cases.</para>
  94
  95         <para>In normal circumstances, an asynchronous setting results in the Cache
  96         Manager returning control to applications earlier than it otherwise does,
  97         but this is not guaranteed.</para>
  98
  99         <para>If a delayed write fails, there is no way to notify the application, since
 100         the close() system call has already returned with a code indicating
 101         success.</para>
 102
 103         <para>Writing asynchronously increases the possibility that the user will not
 104         notice if a write operation makes the volume that houses the file exceed
 105         its quota. As always, the portion of the file that exceeds the volume's
 106         quota is lost, which prompts a message such as the following:</para>
 107
 108 <programlisting>
 109    No space left on device
 110
 111 </programlisting>
 112           <para>To avoid losing data, it is advisable to verify that the volume housing
 113           the file has space available for the amount of data anticipated to be
 114           written.</para>
 115
 116         </refsect1>
 117         <refsect1>
 118           <title>Options</title>
 119           <variablelist>
 120             <varlistentry>
 121               <term><emphasis role="bold">-kbytes</emphasis> &lt;<emphasis>asynchrony for specified names</emphasis>&gt;</term>
 122               <listitem>
 123                 <para>Specifies the number of kilobytes of data from each file named by the
 124                 <emphasis role="bold">-files</emphasis> argument that can remain to be written to the file server when
 125                 the Cache Manager returns control to an application program that closed
 126                 the file. The <emphasis role="bold">-files</emphasis> argument is required along with this
 127                 argument. Provide an integer from the range <computeroutput>0</computeroutput> (which reinstates the
 128                 Cache Manager's default behavior or writing synchronously) to the maximum
 129                 AFS file size.</para>
 130
 131               </listitem>
 132             </varlistentry>
 133             <varlistentry>
 134               <term><emphasis role="bold">-files</emphasis> &lt;<emphasis>specific pathnames</emphasis>&gt;+</term>
 135               <listitem>
 136                 <para>Names each file to which the value set with the <emphasis role="bold">-kbytes</emphasis> argument
 137                 applies. The setting persists as long as there is an entry for the file in
 138                 the kernel table that the Cache Manager uses to track certain information
 139                 about files. Because closing a file generally erases the entry, when
 140                 reopening a file the only way to guarantee that the setting still applies
 141                 is to reissue the command. If this argument is provided without the
 142                 <emphasis role="bold">-kbytes</emphasis> argument, the command reports the current setting for the
 143                 specified files, and the default store asynchrony.</para>
 144
 145               </listitem>
 146             </varlistentry>
 147             <varlistentry>
 148               <term><emphasis role="bold">-allfiles</emphasis> &lt;<emphasis>new default (KB)</emphasis>&gt;</term>
 149               <listitem>
 150                 <para>Sets the default store asynchrony for the local machine, which is the
 151                 number of kilobytes of data that can remain to be written to the file
 152                 server when the Cache Manager returns control to the application program
 153                 that closed a file. The value applies to all AFS files manipulated by
 154                 applications running on the machine, except those for which settings have
 155                 been made with the <emphasis role="bold">-kbytes</emphasis> and <emphasis role="bold">-files</emphasis> arguments. Provide an integer
 156                 from the range <computeroutput>0</computeroutput> (which indicates the default of synchronous writes) to
 157                 the maximum AFS file size.</para>
 158
 159               </listitem>
 160             </varlistentry>
 161             <varlistentry>
 162               <term><emphasis role="bold">-verbose</emphasis></term>
 163               <listitem>
 164                 <para>Produces output confirming the settings made with the accompanying
 165                 <emphasis role="bold">-kbytes</emphasis> and <emphasis role="bold">-files</emphasis> arguments, the <emphasis role="bold">-allfiles</emphasis> argument, or all
 166                 three. If provided by itself, reports the current default store
 167                 asynchrony.</para>
 168
 169               </listitem>
 170             </varlistentry>
 171             <varlistentry>
 172               <term><emphasis role="bold">-help</emphasis></term>
 173               <listitem>
 174                 <para>Prints the online help for this command. All other valid options are
 175                 ignored.</para>
 176
 177               </listitem>
 178             </varlistentry>
 179           </variablelist>
 180         </refsect1>
 181         <refsect1>
 182           <title>Output</title>
 183           <para>If none of the command's options are included, or if only the <emphasis role="bold">-verbose</emphasis>
 184           flag is included, the following message reports the default store
 185           asynchrony (the setting that applies to all files manipulated by
 186           applications running on the local machine and for which not more specific
 187           asynchrony is set).</para>
 188
 189 <programlisting>
 190    Default store asynchrony is &amp;lt;x&amp;gt; kbytes.
 191
 192 </programlisting>
 193             <para>A value of <computeroutput>0</computeroutput> (zero) indicates synchronous writes and is the default if
 194             no one has included the <emphasis role="bold">-allfiles</emphasis> argument on this command since the
 195             machine last rebooted.</para>
 196
 197             <para>If the <emphasis role="bold">-files</emphasis> argument is provided without the <emphasis role="bold">-kbytes</emphasis> argument, the
 198             output reports the value that applies to each specified file along with
 199             the default store asynchrony. If a particular value has previously been
 200             set for a file, the following message reports it:</para>
 201
 202 <programlisting>
 203    Will store up to &amp;lt;y&amp;gt; kbytes of &amp;lt;file&amp;gt; asynchronously.
 204    Default store asynchrony is &amp;lt;x&amp;gt; kbytes.
 205
 206 </programlisting>
 207               <para>If the default store asynchrony applies to a file because no explicit
 208               <emphasis role="bold">-kbytes</emphasis> value has been set for it, the message is instead as follows:</para>
 209
 210 <programlisting>
 211    Will store &amp;lt;file&amp;gt; according to default.
 212    Default store asynchrony is &amp;lt;x&amp;gt; kbytes.
 213
 214 </programlisting>
 215                 <para>If the <emphasis role="bold">-verbose</emphasis> flag is combined with arguments that set values
 216                 (<emphasis role="bold">-files</emphasis> and <emphasis role="bold">-kbytes</emphasis>, or <emphasis role="bold">-allfiles</emphasis>, or all three), there is a
 217                 message that confirms immediately that the setting has taken effect. When
 218                 included without other arguments or flags, the <emphasis role="bold">-verbose</emphasis> flag reports
 219                 the default store asynchrony only.</para>
 220
 221               </refsect1>
 222               <refsect1>
 223                 <title>Examples</title>
 224                 <para>The following command enables the Cache Manager to return control to the
 225                 application program that closed the file <replaceable>test.data</replaceable> when 100 kilobytes
 226                 still remain to be written to the File Server. The <emphasis role="bold">-verbose</emphasis> flag
 227                 produces output that confirms the new setting, and that the default store
 228                 asynchrony is zero.</para>
 229
 230 <programlisting>
 231    % fs storebehind -kbytes 100 -files test.data -verbose
 232    Will store up to 100 kbytes of test.data asynchronously.
 233    Default store asynchrony is 0 kbytes.
 234
 235 </programlisting>
 236                 </refsect1>
 237                 <refsect1>
 238                   <title>Privilege Required</title>
 239                   <para>To include the <emphasis role="bold">-allfiles</emphasis> argument, the issuer must be logged in as the
 240                   local superuser <computeroutput>root</computeroutput>.</para>
 241
 242                   <para>To include the <emphasis role="bold">-kbytes</emphasis> and <emphasis role="bold">-files</emphasis> arguments, the issuer must either
 243                   be logged in as the local superuser <computeroutput>root</computeroutput> or have the <computeroutput>w</computeroutput> (write)
 244                   permission on the ACL of each file's directory.</para>
 245
 246                   <para>To view the current settings (by including no arguments, the <emphasis role="bold">-file</emphasis>
 247                   argument alone, or the <emphasis role="bold">-verbose</emphasis> argument alone), no privilege is
 248                   required.</para>
 249
 250                 </refsect1>
 251                 <refsect1>
 252                   <title>See Also</title>
 253                   <para><link linkend="afsd8">afsd(8)</link></para>
 254
 255                 </refsect1>
 256                 <refsect1>
 257                   <title>Copyright</title>
 258                   <para>IBM Corporation 2000. &lt;http://www.ibm.com/&gt; All Rights Reserved.</para>
 259
 260                   <para>This documentation is covered by the IBM Public License Version 1.0.  It was
 261                   converted from HTML to POD by software written by Chas Williams and Russ
 262                   Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.</para>
 263
 264                 </refsect1>
 265               </refentry>