FS_STOREBEHIND

Section: AFS Command Reference (1)
Updated: OpenAFS
Index

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 adelayed asynchronous write to the File Server when an application closes afile. By default, the Cache Manager writes all data to the File Serverimmediately and synchronously when an application program closes a file --that is, the close() system call does not return until the Cache Managerhas actually transferred the final chunk of the file to the FileServer. This command specifies the number of kilobytes of a file that canstill remain to be written to the File Server when the Cache Managerreturns control to the application. It is useful if users working on themachine commonly work with very large files, but also introduces thecomplications discussed in the the CAUTIONS manpage.

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

*

To set a value that applies to all AFS files manipulated by applicationsrunning on the machine, use the -allfiles argument. This value istermed the default store asynchrony for the machine, and persists untilthe 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 closesa file, the Cache Manager can return control to the application as soon asno more than 10 kilobytes of the file remain to be written to the FileServer.

   -allfiles 10

*

To set a value that applies to one or more individual files, and overridesthe value of the -allfiles argument for them, combine the -kbytesand -files arguments. The setting persists as long as there is an entryfor the file in the kernel table that the Cache Manager uses to trackcertain information about files. In general, such an entry persists atleast until an application closes the file or exits, but the Cache Manageris free to recycle the entry if the file is inactive and it needs to freeup slots in the table. To increase the certainty that there is an entryfor the file in the table, issue the fs storebehind command shortlybefore closing the file.

As an example, the following setting means that when an application closeseither of the files bigfile and biggerfile, the Cache Manager canreturn control to the application as soon as no more than a megabyte ofthe 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 tomake it subject to the default store asynchrony once again is to set-kbytes to that value. In other words, there is no combination ofarguments that automatically makes a file subject to the default storeasynchrony once another value has been set for the file.

To display the settings that currently apply to individual files or to allfiles, provide the command's arguments in certain combinations asspecified in the OUTPUT manpage.

CAUTIONS

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

In normal circumstances, an asynchronous setting results in the CacheManager 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, sincethe close() system call has already returned with a code indicatingsuccess.

Writing asynchronously increases the possibility that the user will notnotice if a write operation makes the volume that houses the file exceedits quota. As always, the portion of the file that exceeds the volume'squota 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 housingthe file has space available for the amount of data anticipated to bewritten.

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 whenthe Cache Manager returns control to an application program that closedthe file. The -files argument is required along with thisargument. Provide an integer from the range 0 (which reinstates theCache Manager's default behavior or writing synchronously) to the maximumAFS file size.
-files <specific pathnames>+: Names each file to which the value set with the -kbytes argumentapplies. The setting persists as long as there is an entry for the file inthe kernel table that the Cache Manager uses to track certain informationabout files. Because closing a file generally erases the entry, whenreopening a file the only way to guarantee that the setting still appliesis to reissue the command. If this argument is provided without the-kbytes argument, the command reports the current setting for thespecified files, and the default store asynchrony.
-allfiles <new default (KB)>: Sets the default store asynchrony for the local machine, which is thenumber of kilobytes of data that can remain to be written to the fileserver when the Cache Manager returns control to the application programthat closed a file. The value applies to all AFS files manipulated byapplications running on the machine, except those for which settings havebeen made with the -kbytes and -files arguments. Provide an integerfrom the range 0 (which indicates the default of synchronous writes) tothe maximum AFS file size.
-verbose: Produces output confirming the settings made with the accompanying-kbytes and -files arguments, the -allfiles argument, or allthree. If provided by itself, reports the current default storeasynchrony.
-help: Prints the online help for this command. All other valid options areignored.

OUTPUT

If none of the command's options are included, or if only the -verboseflag is included, the following message reports the default storeasynchrony (the setting that applies to all files manipulated byapplications running on the local machine and for which not more specificasynchrony is set).

   Default store asynchrony is <x> kbytes.

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

If the -files argument is provided without the -kbytes argument, theoutput reports the value that applies to each specified file along withthe default store asynchrony. If a particular value has previously beenset 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 amessage that confirms immediately that the setting has taken effect. Whenincluded without other arguments or flags, the -verbose flag reportsthe default store asynchrony only.

EXAMPLES

The following command enables the Cache Manager to return control to theapplication program that closed the file test.data when 100 kilobytesstill remain to be written to the File Server. The -verbose flagproduces output that confirms the new setting, and that the default storeasynchrony 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 thelocal superuser root.

To include the -kbytes and -files arguments, the issuer must eitherbe 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 -fileargument alone, or the -verbose argument alone), no privilege isrequired.

COPYRIGHT

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

This document was created byman2html,using the manual pages.