Chapter 4: Common Definitions and Data Structures

This chapter discusses the definitions used in common by the File Server and the Cache Manager. They appear in the common.xg file, used by Rxgen to generate the C code instantiations of these definitions.

Section 4.1: File-Related Definitions

Section 4.1.1: struct AFSFid

This is the type for file system objects within AFS.

Fields
  • unsigned long Volume - This provides the identifier for the volume in which the object resides.
  • unsigned long Vnode - This specifies the index within the given volume corresponding to the object.
  • unsigned long Unique - This is a 'uniquifier' or generation number for the slot identified by the Vnode field.

Section 4.2: Callback-related Definitions

Section 4.2.1: Types of Callbacks

There are three types of callbacks defined by AFS-3:

Section 4.2.2: struct AFSCallBack

This is the canonical callback structure passed in many File Server RPC interface calls.
Fields
  • unsigned long CallBackVersion - Callback version number.
  • unsigned long ExpirationTime - Time when the callback expires, measured in seconds.
  • unsigned long CallBackType - The type of callback involved, one of EXCLUSIVE, SHARED, or DROPPED.

Section 4.2.3: Callback Arrays

AFS-3 sometimes does callbacks in bulk. Up to AFSCBMAX (50) callbacks can be handled at once. Layouts for the two related structures implementing callback arrays, struct AFSCBFids and struct AFSCBs, follow below. Note that the callback descriptor in slot i of the array in the AFSCBs structure applies to the file identifier contained in slot i in the fid array in the matching AFSCBFids structure.

Section 4.2.3.1: struct AFSCBFids


Fields

Section 4.2.3.2: struct AFSCBs


Fields

Section 4.3: Locking Definitions

Section 4.3.1: struct AFSDBLockDesc

This structure describes the state of an AFS lock.
Fields
  • char waitStates - Types of lockers waiting for the lock.
  • char exclLocked - Does anyone have a boosted, shared or write lock? (A boosted lock allows the holder to have data read-locked and then 'boost' up to a write lock on the data without ever relinquishing the lock.)
  • char readersReading - Number of readers that actually hold a read lock on the associated object.
  • char numWaiting - Total number of parties waiting to acquire this lock in some fashion.

Section 4.3.2: struct AFSDBCacheEntry

This structure defines the description of a Cache Manager local cache entry, as made accessible via the RXAFSCB GetCE() callback RPC call. Note that File Servers do not make the above call. Rather, client debugging programs (such as cmdebug) are the agents which call RXAFSCB GetCE().
Fields
  • long addr - Memory location in the Cache Manager where this description is located.
  • long cell - Cell part of the fid.
  • AFSFid netFid - Network (standard) part of the fid
  • long Length - Number of bytes in the cache entry.
  • long DataVersion - Data version number for the contents of the cache entry.
  • struct AFSDBLockDesc lock - Status of the lock object controlling access to this cache entry.
  • long callback - Index in callback records for this object.
  • long cbExpires - Time when the callback expires.
  • short refCount - General reference count.
  • short opens - Number of opens performed on this object.
  • short writers - Number of writers active on this object.
  • char mvstat - The file classification, indicating one of normal file, mount point, or volume root.
  • char states - Remembers the state of the given file with a set of bits indicating, from lowest-order to highest order: stat info valid, read-only file, mount point valid, pending core file, wait-for-store, and mapped file.

Section 4.3.3: struct AFSDBLock

This is a fuller description of an AFS lock, including a string name used to identify it.
Fields
  • char name[16] - String name of the lock.
  • struct AFSDBLockDesc lock - Contents of the lock itself.

Section 4.4: Miscellaneous Definitions

Section 4.4.1: Opaque structures

A maximum size for opaque structures passed via the File Server interface is defined as AFSOPAQUEMAX. Currently, this is set to 1,024 bytes. The AFSOpaque typedef is defined for use by those parameters that wish their contents to travel completely uninterpreted across the network.

Section 4.4.2: String Lengths

Two common definitions used to specify basic AFS string lengths are AFSNAMEMAX and AFSPATHMAX. AFSNAMEMAX places an upper limit of 256 characters on such things as file and directory names passed as parameters. AFSPATHMAX defines the longest pathname expected by the system, composed of slash-separated instances of the individual directory and file names mentioned above. The longest acceptable pathname is currently set to 1,024 characters.