PFSDoc.tioga
Carl Hauser, November 21, 1989
Michael Plass, January 4, 1990
Nichols, April 4, 1990 3:50 pm PDT
Chauser, September 28, 1990 2:10 pm PDT
FILE ACCESS IN PCEDAR
PCEDAR 2.0 — FOR INTERNAL XEROX USE ONLY
File Access in PCedar
The PFS and PFSNames Interfaces (and friends)
Release as: [PCedar2.0]<Documentation>PFSDoc.Tioga

© Copyright 1989, 1990 Xerox Corporation. All rights reserved.
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

For Internal Xerox Use Only
1. Quick Guide and Latest PFS News
This is preliminary documentation. Obviously, there is much more to be said about PFS.
News
Attachments are implemented for the -ux view. The FSOnPFSImpl.Copy operation, when told to make an attachment will try to do so; should the attachment fail, the bits will be copied. PFSImpl registers an error explainer for PFS.Error (thanks to Doug Wyatt).
The VUX error reporting has been beefed up to include the file name when possible. (mfp) September 19, 1990
While this document doesn't talk about them, two more interesting views are available: the MapViews command registers a view with PFS for looking at files using a version map as a directory and the XNSRemoteFile command registers a view for looking at files on XNS Filing servers. See the documentation in the respective packages. August 29, 1990
Collection of bug fixes: leading '. should be ok in VUX names; enumeration of / now works; case files get collected when the last file they pertain to is deleted; GetInfo returns fileType~tDirectory for unix directories in both VUX and UX; files (hence directories) without version numbers are visible in VUX views, so the cd command could determine if a directory exists before changing to it. August 29, 1990
New interface: PFSExtras with procedures for converting PFS PATHs to Unix names (for views that are unix-based) and for finding out if any part of a path is case-sensitive. Changes to PFSClass to support the above. August 13, 1990
Algorithmic improvements in the VUX view to reduce allocations and processor use. August 13, 1990
The VUX file enumerator now only matches "*" within a single component. Thus, a pattern like "/pcedar/*" only matchs the first-level subdirs of /pcedar instead of the entire subtree. Also, directories and unversioned files are now matched (and unversioned files have the directory flag set, sorry). Neither were matched before. (nichols) April 4, 1990
PFSBackdoorExtras added, allowing clients access to the Unix file descriptor underlying a (PFS) STREAM obtained from the UX or VUX view. Clients are warned that this interface is preliminary, and I do intend to change or replace it in the very near future. January 18, 1990 thanks to Jim Foote for the implementation.
State of the world after standard .pcr files have been loaded
PFS underlies the PCR world. It provides the PFS interface as well as replacement implementations for TFS (used by Tioga) and DFS (used by QBO, SModel, and various other things that wanted to see version numbers) and FS.
PFS initializes its PrefixMap (see Concepts in section 2, below) to have entries for important directories like /, /xrhome, /pcedar2.0, /fonts, /cedarchest7.0, /cedar7.0, and /pseudo.
You can update the PrefixMap with the command tool commands "PrefixMapAdd" and inspect it with "PrefixMapPrint" (abbreviated "pmp" and "pmp", resp.). The syntax of the arguments for PrefixMapAdd is just what you see printed by PrefixMapPrint.
[Wart: prefix map changes are not yet persistent across PCedar startup.]
Operations with Tioga will use PFS (indirectly through TFS). You'll see actual version numbers on files (instead of .~x~ suffices) and files that you openp will have /pcedar2.0/ at the beginning of their banner line instead of /volume/pixel1/pcedar2.0. Open without a suffix uses the suffix list from your profile and works, as does Open MesaFile.Proc.
[Wart: Openp without a suffix doesn't work.]
Gotchas
Beware the "umask" property of your Unix processes (controlled with the umask command of the C-shell) which may reduce the permissions on files created in the UX view from rw-rw-rw- to rw-rw-r-- or even rw-r--r--. (Also note below about tioga copying the previous mode of a file.)
Tioga Save or Store that fails with an uncaught error wedges Viewers. I don't know of any more user behaviors that will provoke this. I now consider any remaining problems Tioga's and Viewer's pending contrary evidence.
Things to know
In the -ux: view Save`ing from tioga creates a new file, and renames the old one with a ~ at the end of its name. I hope the implementation of this is such that you will never again see all the versions of your bytes disappear due to multiple failing Saves.
[Wart: There is no protection from tioga Save'ing into a "release" directory (such as /pcedar2.0). Please don't do that.]
Remember that (unlike FS) PFS doesn't synchronize multiple clients operating on an underlying Unix file. You can create many read and write OpenFiles for a single file. Do so only with trepidation and care.
Incompletenesses/Known bugs/Suspected bugs
The only implemented client properties are "UnixMode", "UnixOwner" and "UnixGroup".
Attachments are only implemented in the -ux view.
This documentation of incompletenesses is incomplete.
2. Introduction
Purpose of document
This document describes the standard facilities available for file access from PCedar. These facilities are available through the interfaces PFS and PFSNames. PFS and PFSNames contain facilities of interest to all users. PFSClass and PFSBackdoor provide facilities used in implementing new file system views and are not (yet) described here.
Location of interfaces
All interfaces are in the PCedar release through PFS-Suite.df. Eventually PFS will be a part of the BasicLoadees. For now, it is dynamically loaded.
There is also a dynamically loadable PFS implementation for Cedar7.0.
Concepts
Views
PFS is organized to support multiple views of many file systems. Currently there are two views supported, each looking at the Unix file system on the machine hosting PCedar.
The first view is called "-ux" (pronounced "ucks") and provides a fairly vanilla unix-like picture of the file system. That is, file names are treated case-sensitively and there are no versions. (But note that opening a file requesting it be created will rename any existing file and create a new file.) In the -ux view directory boundaries are quite significant and no automatic directory creation is provided.
[Wart: there is no way to create a directory.]
The second view is called "-vux" (pronounced "vucks") and provides case-insensitive file names and versions. The -vux view is compatible with the -NFS remote file view in the Cedar7.0 RemoteFile system. The -vux view automatically creates directories as needed when creating or storing files.
PATHs
All the PFS procedures that operate on named files (as opposed to open files) take the names in the form of a PFSNames.PATH. PATHs are immutable objects that can easily be manipulated with procedures from PFSNames produce new PATHs. A PATH is, conceptually, a sequence of Components. Each Component is, conceptually, a ROPE and a Version. A Version is either a numeric version or a version variable, or none. As of now, all the PATHs we're using have no versions except in the last component. The idea of using PATHs is to make it easy to pull names apart and put them together on a directory by directory basis.
The PFS interface provides procedures PathFromRope and RopeFromPath for going back and forth to conventional Cedar and Unix file names such as "[PCedar2.0]<Top>PFS-Suite.df" and "/pcedar2.0/top/pfs-suite.df". In fact, the syntax of Unix-style names has been extended to allow a view-name followed by a colon to precede the initial /. So "-vux:/pseudo/pcedar2.0" can also be translated to a PATH.
PFSNames has facilities for programs to construct PATHs from components. These would be used, for example, by a program that converted to some other file name syntax.
Working directories
Every Cedar process has a WorkingDirectory. Relative PATHs passed to PFS procedures (except PFS.RopeFromPath) are interpreted relative to the process's working directory. The working directory is not used in interpreting absolute file names passed to PFS.
[Wart: The WorkingDirectory process property is currently stored as a ROPE and has to be converted to a PATH each time it is used. This is so that PFS and the other xFS's currently used in PCedar all agree on the working directory. This is only a performance consideration but it needs fixing.]
The prefix map
The prefix map is a list of PATH pairs. The second element of each pair must be an absolute path including a valid view name. Following completion of the working directory processing mentioned above, every PATH is translated according to the current prefix map as follows: find the longest first element in the map matching the presented name and replace the matching subname by the second element. The matching is caseless and no patterns are allowed in the prefix map.
PFS creates an initial prefix map with the pair ["/", "-ux:/"] giving unix-style access to the Unix system's root directory. Notice that this matches any name presented to PFS, so all names can be successfully translated by this prefix map.
UniqueIDs
The PFS interface uses a RECORD type called UniqueID in places where FS used BasicTime.GMT's. This gives us the possibility of more resolution in times and also the opportunity to avoid conflicts between creating machines in choosing UniqueIDs. However, we don't have any servers that can store complete UniqueIDs so only the GMT field is significant, as of now.
Open files
STREAMs
Overview of Functions
History
PFS's functionality was principally inspired by the need to provide features similar to those in the Cedar7.0 FS interface. The architecture, however, draws more from the RemoteFile features of Cedar than the FS architecture. That is PFS provides uniform access to a collection of different kinds of file systems (and different views of those file systems). PFS is extensible by registering new views for looking at file systems.
The -vux: view is a clone of code orginally written by Alan Demers for Cedar7.0 to let it use SunNFS file servers to store versioned, caselessly named, immutable files.
The idea of mapping file names to get to the right place using the right view was inspired by the PseudoServer mechanism that Russ Atkinson designed for Cedar7.0. The idea of mapping prefixes instead of only the first component comes from Sprite.
PFSNames.PATH was, of course, inspired by the Cedar ROPE abstraction. Would that the implementation was molded more closely on the RopeImpl model.
Design of PFS began in early 1988. Implementation was a part-time effort from summer 1988 through summer of 1989, and a full-time effort during late August and the fall of 1989.
PFS File Access Using IO.STREAMs
Most clients of PFS simply want to create a file stream with which to read or write a file. If that's all you want to do then this section contains all you need to know about PFS. Suppose that r is a ROPE containing a file name. If your program needs to read characters from the file named by r (local or global file name, probably with no version part) from a STREAM "s", it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r]];
If your program will provide all new contents for the file named r (it ignores any existing versions of the file and creates a new version), it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r], $create];
If your program is logging output to the file named by r (it updates the file only by adding new characters to the end, and creates a new file of that name if none exists), it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r], $append];
Finally, if your program will both read and write the file named by r (it treats the file as an extendible, random-access sequence of bytes that it updates "in place"), it should call
s ← PFS.StreamOpen[PFS.PathFromRope[r], $write];
It is an unusual program that requires $write mode, while $create mode is used frequently.
If you do not wish to land in the debugger when the file name r is misspelled or otherwise garbled, your calls on PFS.StreamOpen should be protected with a catch phrase something like
! PFS.Error => IF error.group = user THEN {
YourProcedureToShowRopeToUser[error.explanation]; CONTINUE }
The moral of this tale: doing simple things is simple. You don't need to understand the multitude of parameters to StreamOpen and StreamFromOpenFile, since they default correctly for most purposes. You don't need to use any procedure from this interface except PFS.StreamOpen unless you are doing something special. There is only one signal to catch.
Having created a file stream, you may have questions about the semantics of the generic IO operations when applied to this stream: will SetIndex extend the file, and what does Reset do? To answer these questions, read the "File Streams" section below.
It is also possible that you aren't interested in streams at all, but want to do something else like enumerate a directory. Take a look at the PFS interface.
Olds (not news)
Files created in the UX view always have unix mode rw-rw-rw to allow the language tools to operate on them. Temporary until the language tools use PFS. November 30, 1989 -- but see above about the "x" bit.
VUX view properly ignores malformed names it encounters (rather than either ignoring the entire directory containing them or raising an uncaught error). November 30, 1989
Tioga Save/Store to an unwritable place now fails gracefully (i.e., viewers don't wedge). November 30, 1989
DFSOnPFSImpl now translates errors so that qbo's that try to store in non-existent -ux: directories get error messages instead of uncaught errors. (Remember that the -ux: view does not provide automatic directory creation). November 30, 1989
Delete command: trying to delete a directory in the -ux: view produces an error message instead of an uncaught error. November 30, 1989
The PFS components have once again been repackaged. PFSPackage no longer contains the pieces needed to give you commands, or to support Tioga and DF software. These have been moved to PFSControlPackage. PFS.install has been updated to reflect this, and runs everything needed. This is in anticipation of including PFSPackage among the standard packages available at a very low level in the system. November 30, 1989
Added documentation of the prefix map manipulation commands in the "Installing PFS" section below. November 28, 1989
Changed the stream buffer size to 4K bytes, hoping to improve SModel performance. November 28, 1989
Implemented Copy, Rename and Delete Commands. Took over the List and LS commands. PFSLS is decommissioned. November 28, 1989
Separated the Commands implementation from the rest of the package and provided a new module, PFSPrefixMapInit to initialize the prefix map in a standard way. November 28, 1989
PFSImpl.EnumerateForInfo and EnumerateForNames implement the enumeration bounds. January 18, 1990
Bug fixes to PFSImpl.FileInfo and FSOnPFSImpl.ExpandName. January 18, 1990
PFS is now run by all the standard .pcr files. It is no longer necessary to install it. Deleted instructions for such from this document. January 18, 1990
PFSImpl.FileLookup is now implemented. January 18, 1990
Added some things to PFSPrefixMapInit. (mfp) January 4, 1990
Removed dependency on CommandTool; also fixed some bugs in some of the esoteric options of the LS and Copy commands. (mfp) January 3, 1990
MONITORed several critical sections in the UX and VUX view implementations in hopes of allowing concurrent operations on a single PFS.OpenFile. (I now contend it's better to use multiple OpenFiles). December 21, 1989
Fixed the behavior of opening for "write" access in the UX view so the file is not truncated. December 21, 1989
Fixed the behavior of creating a stream for append access so the stream index is positioned at the end of the file. December 21, 1989
Added semantics for IO.Flush[PFSReadStream] -- forgets any buffered data for the stream. Allows clients to synchronize independent read and write streams on the same file. I don't see a lot of need for ever implementing PFS.StreamFromOpenStream. Yell if you disagree. December 21, 1989
Added finalization for PFS.OpenFiles. December 21, 1989
Added interpretation of directory components "." and ".." to PFS.AbsoluteName. I'm not convinced this is the right place, but it supports the new CommandTool nicely. December 21, 1989
The UX and VUX views support "UnixMode", "UnixOwner" and "UnixGroup" as PFS client properties. December 7, 1989
PFS.Copy preserves the execute bit of the source file's unix mode in the unix mode of the destination file (if both are on Unix systems). December 7, 1989
TFSOnPFSImpl.Create preserves the unix mode of the previous version of a file as the mode of the version being created. December 7, 1989