NAME

       fs_storebehind - Enables asynchronous writes to the file server

SYNOPSIS

       fs storebehind [-kbytes <asynchrony for specified names>]
           [-files <specific pathnames>+]
           [-allfiles <new default (KB)>] [-verbose] [-help]

       fs st [-k <asynchrony for specified names>]
           [-f <specific pathnames>+]
           [-a <new default (KB)>] [-v] [-h]

DESCRIPTION

       The fs storebehind command enables the Cache Manager to perform a delayed asynchronous
       write to the File Server when an application closes a file. By default, the Cache Manager
       writes all data to the File Server immediately and synchronously when an application
       program closes a file -- that is, the close() system call does not return until the Cache
       Manager has actually transferred the final chunk of the file to the File Server. This
       command specifies the number of kilobytes of a file that can still remain to be written to
       the File Server when the Cache Manager returns control to the application. It is useful if
       users working on the machine commonly work with very large files, but also introduces the
       complications discussed in the CAUTIONS.

       Set either or both of the following in a single command:

       •   To set a value that applies to all AFS files manipulated by applications running on
           the machine, use the -allfiles argument. This value is termed the default store
           asynchrony for the machine, and persists until the machine reboots. If it is not set,
           the default value is zero, indicating that the Cache Manager performs synchronous
           writes.

           As an example, the following setting means that when an application closes a file, the
           Cache Manager can return control to the application as soon as no more than 10
           kilobytes of the file remain to be written to the File Server.

              -allfiles 10

       •   To set a value that applies to one or more individual files, and overrides the value
           of the -allfiles argument for them, combine the -kbytes and -files arguments. The
           setting persists as long as there is an entry for the file in the kernel table that
           the Cache Manager uses to track certain information about files. In general, such an
           entry persists at least until an application closes the file or exits, but the Cache
           Manager is free to recycle the entry if the file is inactive and it needs to free up
           slots in the table. To increase the certainty that there is an entry for the file in
           the table, issue the fs storebehind command shortly before closing the file.

           As an example, the following setting means that when an application closes either of
           the files bigfile and biggerfile, the Cache Manager can return control to the
           application as soon as no more than a megabyte of the file remains to be written to
           the File Server.

              -kbytes 1024 -files bigfile biggerfile

           Note that once an explicit value has been set for a file, the only way to make it
           subject to the default store asynchrony once again is to set -kbytes to that value. In
           other words, there is no combination of arguments that automatically makes a file
           subject to the default store asynchrony once another value has been set for the file.

       To display the settings that currently apply to individual files or to all files, provide
       the command's arguments in certain combinations as specified in OUTPUT.

CAUTIONS

       For the following reasons, use of this command is not recommended in most cases.

       In normal circumstances, an asynchronous setting results in the Cache Manager returning
       control to applications earlier than it otherwise does, but this is not guaranteed.

       If a delayed write fails, there is no way to notify the application, since the close()
       system call has already returned with a code indicating success.

       Writing asynchronously increases the possibility that the user will not notice if a write
       operation makes the volume that houses the file exceed its quota. As always, the portion
       of the file that exceeds the volume's quota is lost, which prompts a message such as the
       following:

          No space left on device

       To avoid losing data, it is advisable to verify that the volume housing the file has space
       available for the amount of data anticipated to be written.

OPTIONS

       -kbytes <asynchrony for specified names>
           Specifies the number of kilobytes of data from each file named by the -files argument
           that can remain to be written to the file server when the Cache Manager returns
           control to an application program that closed the file. The -files argument is
           required along with this argument. Provide an integer from the range 0 (which
           reinstates the Cache Manager's default behavior or writing synchronously) to the
           maximum AFS file size.

       -files <specific pathnames>+
           Names each file to which the value set with the -kbytes argument applies. The setting
           persists as long as there is an entry for the file in the kernel table that the Cache
           Manager uses to track certain information about files. Because closing a file
           generally erases the entry, when reopening a file the only way to guarantee that the
           setting still applies is to reissue the command. If this argument is provided without
           the -kbytes argument, the command reports the current setting for the specified files,
           and the default store asynchrony.

       -allfiles <new default (KB)>
           Sets the default store asynchrony for the local machine, which is the number of
           kilobytes of data that can remain to be written to the file server when the Cache
           Manager returns control to the application program that closed a file. The value
           applies to all AFS files manipulated by applications running on the machine, except
           those for which settings have been made with the -kbytes and -files arguments. Provide
           an integer from the range 0 (which indicates the default of synchronous writes) to the
           maximum AFS file size.

       -verbose
           Produces output confirming the settings made with the accompanying -kbytes and -files
           arguments, the -allfiles argument, or all three. If provided by itself, reports the
           current default store asynchrony.

       -help
           Prints the online help for this command. All other valid options are ignored.

OUTPUT

       If none of the command's options are included, or if only the -verbose flag is included,
       the following message reports the default store asynchrony (the setting that applies to
       all files manipulated by applications running on the local machine and for which not more
       specific asynchrony is set).

          Default store asynchrony is <x> kbytes.

       A value of 0 (zero) indicates synchronous writes and is the default if no one has included
       the -allfiles argument on this command since the machine last rebooted.

       If the -files argument is provided without the -kbytes argument, the output reports the
       value that applies to each specified file along with the default store asynchrony. If a
       particular value has previously been set for a file, the following message reports it:

          Will store up to <y> kbytes of <file> asynchronously.
          Default store asynchrony is <x> kbytes.

       If the default store asynchrony applies to a file because no explicit -kbytes value has
       been set for it, the message is instead as follows:

          Will store <file> according to default.
          Default store asynchrony is <x> kbytes.

       If the -verbose flag is combined with arguments that set values (-files and -kbytes, or
       -allfiles, or all three), there is a message that confirms immediately that the setting
       has taken effect. When included without other arguments or flags, the -verbose flag
       reports the default store asynchrony only.

EXAMPLES

       The following command enables the Cache Manager to return control to the application
       program that closed the file test.data when 100 kilobytes still remain to be written to
       the File Server. The -verbose flag produces output that confirms the new setting, and that
       the default store asynchrony is zero.

          % fs storebehind -kbytes 100 -files test.data -verbose
          Will store up to 100 kbytes of test.data asynchronously.
          Default store asynchrony is 0 kbytes.

PRIVILEGE REQUIRED

       To include the -allfiles argument, the issuer must be logged in as the local superuser
       "root".

       To include the -kbytes and -files arguments, the issuer must either be logged in as the
       local superuser "root" or have the "w" (write) permission on the ACL of each file's
       directory.

       To view the current settings (by including no arguments, the -file argument alone, or the
       -verbose argument alone), no privilege is required.

SEE ALSO

       afsd(8)

COPYRIGHT

       IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

       This documentation is covered by the IBM Public License Version 1.0.  It was converted
       from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by
       Alf Wachsmann and Elizabeth Cassell.