Chapter 5: File Server Interfaces

There are several interfaces offered by the File Server, allowing it to export the files stored within the set of AFS volumes resident on its disks to the AFS community in a secure fashion and to perform self-administrative tasks. This chapter will cover the three File Server interfaces, summarized below. There is one File Server interface that will not be discussed in this document, namely that used by the Volume Server. It will be fully described in the companion AFS-3 Programmer's Reference:Volume Server/Volume Location Server Interface.
  • RPC: This is the main File Server interface, supporting all of the Cache Manager's needs for providing its own clients with appropriate access to file system objects stored within AFS. It is closedly tied to the callback interface exported by the Cache Manager as described in Section 6.5, which has special implications for any application program making direct calls to this interface.
  • Signals: Certain operations on a File Server must be performed by it sending unix signals on the machine on which it is executing. These operations include performing clean shutdowns and adjusting debugging output levels. Properly-authenticated administrative users do not have to be physically logged into a File Server machine to generate these signals. Rather, they may use the RPC interface exported by that machine's BOS Server process to generate them from any AFS-capable machine.
  • Command Line: Many of the File Server's operating parameters may be set upon startup via its command line interface. Such choices as the number of data buffers and callback records to hold in memory may be made here, along with various other decisions such as lightweight thread stack size.

Section 5.1: RPC Interface

Section 5.1.1: Introduction and Caveats

The documentation for the AFS-3 File Server RPC interface commences with some basic definitions and data structures used in conjunction with the function calls. This is followed by an examination of the set of non-streamed RPC functions, namely those routines whose parameters are all fixed in size. Next, the streamed RPC functions, those with parameters that allow an arbitrary amount of data to be delivered, are described. A code fragment and accompanying description and analysis are offered as an example of how to use the streamed RPC calls. Finally, a description of the special requirements on any application program making direct calls to this File Server interface appears. The File Server assumes that any entity making calls to its RPC functionality is a bona fide and full-fledged Cache Manager. Thus, it expects this caller to export the Cache Manager's own RPC interface, even if the application simply uses File Server calls that don't transfer files and thus generate callbacks.
Within those sections describing the RPC functions themselves, the purpose of each call is detailed, and the nature and use of its parameters is documented. Each of these RPC interface routines returns an integer error code, and a subset of the possible values are described. A complete and systematic list of potential error returns for each function is difficult to construct and unwieldy to examine. This is due to fact that error codes from many different packages and from many different levels may arise. Instead of attempting completeness, the error return descriptions discuss error codes generated within the functions themselves (or a very small number of code levels below them) within the File Server code itself, and not from such associated packages as the Rx, volume, and protection modules. Many of these error code are defined in the companion AFS-3 documents.
By convention, a return value of zero reveals that the function call was successful and that all of its OUT parameters have been set by the File Server.

Section 5.1.2: Definitions and Structures

Section 5.1.2.1: Constants and Typedefs

The following constants and typedefs are required to properly use the File Server RPC interface, both to provide values and to interpret information returned by the calls. The constants appear first, followed by the list of typedefs, which sometimes depend on the constants above. Items are alphabetized within each group.
All of the constants appearing below whose names contain the XSTAT string are used in conjuction with the extended data collection facility supported by the File Server. The File Server defines some number of data collections, each of which consists of an array of longword values computed by the File Server.
There are currently two data collections defined for the File Server. The first is identified by the AFS XSTATSCOLL CALL INFO constant. This collection of longwords relates the number of times each internal function within the File Server code has been executed, thus providing profiling information. The second File Server data collection is identified by the AFS XSTATSCOLL PERF INFO constant. This set of longwords contains information related to the File Server's performance.
Section 5.1.2.1.1 AFS DISKNAMESIZE [Value = 32]
Specifies the maximum length for an AFS disk partition, used directly in the definition for the DiskName typedef. A DiskName appears as part of a struct ViceDisk, a group of which appear inside a struct ViceStatistics, used for carrying basic File Server statistics information.
Section 5.1.2.1.2 AFS MAX XSTAT LONGS [Value = 1,024]
Defines the maximum size for a File Server data collection, as exported via the RXAFS GetXStats() RPC call. It is used directly in the AFS CollData typedef.
Section 5.1.2.1.3 AFS XSTATSCOLL CALL INFO [Value = 0]
This constant identifies the File Server's data collection containing profiling information on the number of times each of its internal procedures has been called.
Please note that this data collection is not supported by the File Server at this time. A request for this data collection will result the return of a zero-length array.
Section 5.1.2.1.4 AFS XSTATSCOLL PERF INFO [Value = 1]
This constant identifies the File Server's data collection containing performance-related information.
Section 5.1.2.1.5 AFS CollData [typedef long AFS CollData;]
This typedef is used by Rxgen to create a structure used to pass File Server data collections to the caller. It resolves into a C typedef statement defining a structure of the same name with the following fields:
Fields
  • u int AFS CollData len - The number of longwords contained within the data pointed to by the next field.
  • long *AFS CollData val - A pointer to a sequence of AFS CollData len long-words.
Section 5.1.2.1.6 AFSBulkStats [typedef AFSFetchStatus
AFSBulkStats<AFSCBMAX>;] This typedef is used by Rxgen to create a structure used to pass a set of statistics structures, as described in the RXAFS BulkStatus documentation in Section 5.1.3.21. It resolves into a C typedef statement defining a structure of the same name with the following fields:
Fields
  • u int AFSBulkStats len - The number of struct AFSFetchStatus units contained within the data to which the next field points.
  • AFSFetchStatus *AFSBulkStats val - This field houses pointer to a sequence of AFSBulkStats len units of type struct AFSFetchStatus.
Section 5.1.2.1.7 DiskName [typedef opaque DiskName[AFS DISKNAMESIZE];]
The name of an AFS disk partition. This object appears as a field within a struct ViceDisk,a group of which appear inside a struct ViceStatistics, used for carrying basic File Server statistics information. The term opaque appearing above inidcates that the object being defined will be treated as an undifferentiated string of bytes.
Section 5.1.2.1.8 ViceLockType [typedef long ViceLockType;]
This defines the format of a lock used internally by the Cache Manager. The content of these locks is accessible via the RXAFSCB GetLock() RPC function. An isomorphic and more refined version of the lock structure used by the Cache Manager, mapping directly to this definition, is struct AFSDBLockDesc, defined in Section 4.3.1.

Section 5.1.2.2: struct AFSVolSync

This structure conveys volume synchronization information across many of the File Server RPC interface calls, allowing something akin to a "whole-volume callback" on read-only volumes.
Fields
  • unsigned long spare1 ... spare6 - The first longword, spare1, contains the volume's creation date. The rest are currently unused.

Section 5.1.2.3: struct AFSFetchStatus

This structure defines the information returned when a file system object is fetched from a File Server.
Fields
  • unsigned long InterfaceVersion - RPC interface version, defined to be 1.
  • unsigned long FileType - Distinguishes the object as either a file, directory, symlink, or invalid.
  • unsigned long LinkCount - Number of links to this object.
  • unsigned long Length - Length in bytes.
  • unsigned long DataVersion - Object's data version number.
  • unsigned long Author - Identity of the object's author.
  • unsigned long Owner - Identity of the object's owner.
  • unsigned long CallerAccess - The set of access rights computed for the caller on this object.
  • unsigned long AnonymousAccess - The set of access rights computed for any completely unauthenticated principal.
  • unsigned long UnixModeBits - Contents of associated unix mode bits.
  • unsigned long ParentVnode - Vnode for the object's parent directory.
  • unsigned long ParentUnique - Uniquifier field for the parent object.
  • unsigned long SegSize - (Not implemented).
  • unsigned long ClientModTime - Time when the caller last modified the data within the object.
  • unsigned long ServerModTime - Time when the server last modified the data within the object.
  • unsigned long Group - (Not implemented).
  • unsigned long SyncCounter - (Not implemented).
  • unsigned long spare1 ... spare4 - Spares.

Section 5.1.2.4: struct AFSStoreStatus

This structure is used to convey which of a file system object's status fields should be set, and their new values. Several File Server RPC calls, including RXAFS StoreStatus(), RXAFS CreateFile(), RXAFS SymLink(), RXAFS MakeDir(), and the streamed call to store file data onto the File Server.
Fields
  • unsigned long Mask - Bit mask, specifying which of the following fields should be assigned into the File Server's status block on the object.
  • unsigned long ClientModTime - The time of day that the object was last modified.
  • unsigned long Owner - The principal identified as the owner of the file system object.
  • unsigned long Group - (Not implemented).
  • unsigned long UnixModeBits - The set of associated unix mode bits.
  • unsigned long SegSize - (Not implemented).

Section 5.1.2.5: struct ViceDisk

This structure occurs in struct ViceStatistics, and describes the characteristics and status of a disk partition used for AFS storage.
Fields
  • long BlocksAvailable - Number of 1 Kbyte disk blocks still available on the partition.
  • long TotalBlocks - Total number of disk blocks in the partition.
  • DiskName Name - The human-readable character string name of the disk partition (e.g., /vicepa).

Section 5.1.2.6: struct ViceStatistics

This is the File Server statistics structure returned by the RXAFS GetStatistics() RPC call.
Fields
  • unsigned long CurrentMsgNumber - Not used.
  • unsigned long OldestMsgNumber - Not used.
  • unsigned long CurrentTime - Time of day, as understood by the File Server.
  • unsigned long BootTime - Kernel's boot time.
  • unsigned long StartTime - Time when the File Server started up.
  • long CurrentConnections - Number of connections to Cache Manager instances.
  • unsigned long TotalViceCalls - Count of all calls made to the RPC interface.
  • unsigned long TotalFetchs - Total number of fetch operations, either status or data, performed.
  • unsigned long FetchDatas - Total number of data fetch operations exclusively.
  • unsigned long FetchedBytes - Total number of bytes fetched from the File Server since it started up.
  • long FetchDataRate - Result of dividing the FetchedBytes field by the number of seconds the File Server has been running.
  • unsigned long TotalStores - Total number of store operations, either status or data, performed.
  • unsigned long StoreDatas - Total number of data store operations exclusively.
  • unsigned long StoredBytes - Total number of bytes stored to the File Server since it started up.
  • long StoreDataRate - The result of dividing the StoredBytes field by the number of seconds the File Server has been running.
  • unsigned long TotalRPCBytesSent - Outdated
  • unsigned long TotalRPCBytesReceived - Outdated
  • unsigned long TotalRPCPacketsSent - Outdated
  • unsigned long TotalRPCPacketsReceived - Outdated
  • unsigned long TotalRPCPacketsLost - Outdated
  • unsigned long TotalRPCBogusPackets - Outdated
  • long SystemCPU - Result of reading from the kernel the usage times attributed to system activities.
  • long UserCPU - Result of reading from the kernel the usage times attributed to user-level activities.
  • long NiceCPU - Result of reading from the kernel the usage times attributed to File Server activities that have been nice()d (i.e., run at a lower priority).
  • long IdleCPU - Result of reading from the kernel the usage times attributed to idling activities.
  • long TotalIO - Summary of the number of bytes read/written from the disk.
  • long ActiveVM - Amount of virtual memory used by the File Server.
  • long TotalVM - Total space available on disk for virtual memory activities.
  • long EtherNetTotalErrors - Not used.
  • long EtherNetTotalWrites - Not used.
  • long EtherNetTotalInterupts - Not used.
  • long EtherNetGoodReads - Not used.
  • long EtherNetTotalBytesWritten - Not used.
  • long EtherNetTotalBytesRead - Not used.
  • long ProcessSize - The size of the File Server's data space in 1 Kbyte chunks.
  • long WorkStations - The total number of client Cache Managers (workstations) for which information is held by the File Server.
  • long ActiveWorkStations - The total number of client Cache Managers (workstations) that have recently interacted with the File Server. This number is strictly less than or equal to the WorkStations field.
  • long Spare1 ... Spare8 - Not used.
  • ViceDisk Disk1 ... Disk10 - Statistics concerning up to 10 disk partitions used by the File Server. These records keep information on all partitions, not just partitions reserved for AFS storage.

Section 5.1.2.7: struct afs PerfStats

This is the structure corresponding to the AFS XSTATSCOLL PERF INFO data collection that is defined by the File Server (see Section 5.1.2.1.4). It is accessible via the RXAFS GetXStats() interface routine, as defined in Section 5.1.3.26. The fields within this structure fall into the following classifications:
  • Number of requests for the structure.
  • Vnode cache information.
  • Directory package numbers.
  • Rx information.
  • Host module fields
  • Spares.
Please note that the Rx fields represent the contents of the rx stats structure maintained by Rx RPC facility itself. Also, a full description of all the structure's fields is not possible here. For example, the reader is referred to the companion Rx document for further clarification on the Rx-related fields within afs PerfStats.
Fields
  • long numPerfCalls - Number of performance collection calls received.
  • long vcache L Entries - Number of entries in large (directory) vnode cache.
  • long vcache L Allocs - Number of allocations for the large vnode cache.
  • long vcache L Gets - Number of get operations for the large vnode cache.
  • long vcache L Reads - Number of reads performed on the large vnode cache.
  • long vcache L Writes - Number of writes executed on the large vnode.cache.
  • long vcache S Entries - Number of entries in the small (file) vnode cache.
  • long vcache S Allocs - Number of allocations for the small vnode cache.
  • long vcache S Gets - Number of get operations for the small vnode cache.
  • long vcache S Reads - Number of reads performed on the small vnode cache.
  • long vcache S Writes - Number of writes executed on the small vnode cache.
  • long vcache H Entries - Number of entries in the header of the vnode cache.
  • long vcache H Gets - Number of get operations on the header of the vnode cache.
  • long vcache H Replacements - Number of replacement operations on the header of the vnode cache.
  • long dir Buffers - Number of directory package buffers in use.
  • long dir Calls - Number of read calls made to the directory package.
  • long dir IOs - Number of directory I/O operations performed.
  • long rx packetRequests - Number of Rx packet allocation requests.
  • long rx noPackets RcvClass - Number of failed packet reception requests.
  • long rx noPackets SendClass - Number of failed packet transmission requests.
  • long rx noPackets SpecialClass - Number of 'special' Rx packet rquests.
  • long rx socketGreedy - Did setting the Rx socket to SO GREEDY succeed?
  • long rx bogusPacketOnRead - Number of short packets received.
  • long rx bogusHost - Latest host address from bogus packets.
  • long rx noPacketOnRead - Number of attempts to read a packet when one was not physically available.
  • long rx noPacketBuffersOnRead - Number of packets dropped due to buffer shortages.
  • long rx selects - Number of selects performed, waiting for a packet arrival or a timeout.
  • long rx sendSelects - Number of selects forced upon a send.
  • long rx packetsRead RcvClass - Number of packets read belonging to the 'Rcv' class.
  • long rx packetsRead SendClass - Number of packets read that belong to the 'Send' class.
  • long rx packetsRead SpecialClass - Number of packets read belonging to the 'Special' class.
  • long rx dataPacketsRead - Number of unique data packets read off the wire.
  • long rx ackPacketsRead - Number of acknowledgement packets read.
  • long rx dupPacketsRead - Number of duplicate data packets read.
  • long rx spuriousPacketsRead - Number of inappropriate packets read.
  • long rx packetsSent RcvClass - Number of packets sent belonging to the 'Rcv' class.
  • long rx packetsSent SendClass - Number of packets sent belonging to the 'Send' class.
  • long rx packetsSent SpecialClass - Number of packets sent belonging to the 'Special' class.
  • long rx ackPacketsSent - Number of acknowledgement packets sent.
  • long rx pingPacketsSent - Number of ping packets sent.
  • long rx abortPacketsSent - Number of abort packets sent.
  • long rx busyPacketsSent - Number of busy packets sent.
  • long rx dataPacketsSent - Number of unique data packets sent.
  • long rx dataPacketsReSent - Number of retransmissions sent.
  • long rx dataPacketsPushed - Number of retransmissions pushed by a NACK.
  • long rx ignoreAckedPacket - Number of packets whose acked flag was set at rxi Start() time.
  • long rx totalRtt Sec - Total round trip time in seconds.
  • long rx totalRtt Usec - Microsecond portion of the total round trip time,
  • long rx minRtt Sec - Minimum round trip time in seconds.
  • long rx minRtt Usec - Microsecond portion of minimal round trip time.
  • long rx maxRtt Sec - Maximum round trip time in seconds.
  • long rx maxRtt Usec - Microsecond portion of maximum round trip time.
  • long rx nRttSamples - Number of round trip samples.
  • long rx nServerConns - Total number of server connections.
  • long rx nClientConns - Total number of client connections.
  • long rx nPeerStructs - Total number of peer structures.
  • long rx nCallStructs - Total number of call structures.
  • long rx nFreeCallStructs - Total number of call structures residing on the free list.
  • long host NumHostEntries - Number of host entries.
  • long host HostBlocks - Number of blocks in use for host entries.
  • long host NonDeletedHosts - Number of non-deleted host entries.
  • long host HostsInSameNetOrSubnet - Number of host entries in the same [sub]net as the File Server.
  • long host HostsInDiffSubnet - Number of host entries in a different subnet as the File Server.
  • long host HostsInDiffNetwork - Number of host entries in a different network entirely as the File Server.
  • long host NumClients - Number of client entries.
  • long host ClientBlocks - Number of blocks in use for client entries.
  • long spare[32] - Spare fields, reserved for future use.

Section 5.1.2.8: struct AFSFetchVolumeStatus

The results of asking the File Server for status information concerning a particular volume it hosts.
Fields
  • long Vid - Volume ID.
  • long ParentId - Volume ID in which the given volume is 'primarily' mounted.
  • This is used to properly resolve pwd operations, as a volume may be mounted simultaneously at multiple locations.
  • char Online - Is the volume currently online and fully available?
  • char InService - This field records whether the volume is currently in service. It is indistinguishable from the Blessed field,
  • char Blessed - See the description of the InService field immediately above.
  • char NeedsSalvage -Should this volume be salvaged (run through a consistency- checking procedure)?
  • long Type - The classification of this volume, namely a read/write volume (RWVOL = 0), read-only volume (ROVOL = 1), or backup volume (BACKVOL = 2).
  • long MinQuota - Minimum number of 1 Kbyte disk blocks to be set aside for this volume. Note: this field is not currently set or accessed by any AFS agents.
  • long MaxQuota - Maximum number of 1 Kbyte disk blocks that may be occupied by this volume.
  • long BlocksInUse - Number of 1 Kbyte disk blocks currently in use by this volume.
  • long PartBlocksAvail - Number of available 1 Kbyte blocks currently unused in the volume's partition.
  • long PartMaxBlocks - Total number of blocks, in use or not, for the volume's partition.

Section 5.1.2.9: struct AFSStoreVolumeStatus

This structure is used to convey which of a file system object's status fields should be set, and their new values. The RXAFS SetVolumeStatus() RPC call is the only user of this structure.
Fields
  • long Mask - Bit mask to determine which of the following two fields should be stored in the centralized status for a given volume.
  • long MinQuota - Minimum number of 1 Kbyte disk blocks to be set aside for this volume.
  • long MaxQuota - Maximum number of 1 Kbyte disk blocks that may be occupied by this volume.

Section 5.1.2.10: struct AFSVolumeInfo

This field conveys information regarding a particular volume through certain File Server RPC interface calls. For information regarding the different volume types that exist, please consult the companion document, AFS-3 Programmer's Reference:Volume Server/Volume Location Server Interface.
Fields
  • unsigned long Vid - Volume ID.
  • long Type - Volume type (see struct AFSFetchVolumeStatus in Section 5.1.2.8 above).
  • unsigned long Type0 ... Type4 - The volume IDs for the possible volume types in existance for this volume.
  • unsigned long ServerCount - The number of File Server machines on which an instance of this volume is located.
  • unsigned long Server0 ... Server7 - Up to 8 IP addresses of File Server machines hosting an instance on this volume. The first ServerCount of these fields hold valid server addresses.
  • unsigned short Port0 ... Port7 - Up to 8 UDP port numbers on which operations on this volume should be directed. The first ServerCount of these fields hold valid port identifiers.

Section 5.1.3: Non-Streamed Function Calls

The following is a description of the File Server RPC interface routines that utilize only parameters with fixed maximum lengths. The majority of the File Server calls fall into this suite, with only a handful using streaming techniques to pass objects of unbounded size between a File Server and Cache Manager.
Each function is labeled with an opcode number. This is the low-level numerical identifier for the function, and appears in the set of network packets constructed for the RPC call.

Section 5.1.3.1: RXAFS FetchACL - Fetch the

ACL associated with the given AFS file identifier

int RXAFS FetchACL(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a dirFidP, 
                        OUT AFSOpaque *a ACLP, 
                        OUT AFSFetchStatus *a dirNewStatP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 131] Fetch the ACL for the directory identified by a dirFidP, placing it in the space described by the opaque structure to which a ACLP points. Also returned is the given directory's status, written to a dirNewStatP. An ACL may thus take up at most AFSOPAQUEMAX (1,024) bytes, since this is the maximum size of an AFSOpaque.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller is not permitted to perform this operation. EINVAL An internal error in looking up the client record was encountered, or an invalid fid was provided. VICETOKENDEAD Caller's authentication token has expired.

Section 5.1.3.2: RXAFS FetchStatus - Fetch

the status information regarding a given file system object

int RXAFS FetchStatus(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a fidToStatP, 
                        OUT AFSFetchStatus *a currStatP, 
                        OUT AFSCallBack *a callBackP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 132] Fetch the current status information for the file or directory identified by a fidToStatP, placing it into the area to which a currStatP points. If the object resides in a read/write volume, then the related callback information is returned in a callBackP.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller is not permitted to perform this operation. EINVAL An internal error in looking up the client record was encountered, or an invalid fid was provided. VICETOKENDEAD Caller's authentication token has expired.

Section 5.1.3.3: RXAFS StoreACL - Associate

the given ACL with the named directory

int RXAFS StoreACL(IN struct rx connection *a rxConnP, 
                        IN AFSOpaque *a ACLToStoreP, 
                        IN AFSFid *a dirFidP, 
                        OUT AFSFetchStatus *a dirNewStatP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 134] Store the ACL information to which a ACLToStoreP points to the File Server, associating it with the directory identified by a dirFidP. The resulting status information for the a dirFidP directory is returned in a dirNewStatP. Note that the ACL supplied via a ACLToStoreP may be at most AFSOPAQUEMAX (1,024) bytes long, since this is the maximum size accommodated by an AFSOpaque.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller is not permitted to perform this operation.
E2BIG The given ACL is too large.
EINVAL The given ACL could not translated to its on-disk format.

Section 5.1.3.4: RXAFS StoreStatus - Store

the given status information for the specified file

int RXAFS StoreStatus(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a fidP, 
                        IN AFSStoreStatus *a currStatusP, 
                        OUT AFSFetchStatus *a srvStatusP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 135] Store the status information to which a currStatusP points, associating it with the file identified by a fidP. All outstanding callbacks on this object are broken. The resulting status structure stored at the File Server is returned in a srvStatusP.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller is not permitted to perform this operation.
EINVAL An internal error in looking up the client record was encountered, or an invalid fid was provided, or an attempt was made to change the mode of a symbolic link.
VICETOKENDEAD Caller's authentication token has expired.

Section 5.1.3.5: RXAFS RemoveFile - Delete

the given file

int RXAFS RemoveFile(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a dirFidP, 
                        IN char *a name<AFSNAMEMAX>, 
                        OUT AFSFetchStatus *a srvStatusP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 136] Destroy the file named a name within the directory identified by a dirFidP. All outstanding callbacks on this object are broken. The resulting status structure stored at the File Server is returned in a srvStatusP.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller is not permitted to perform this operation.
EINVAL An internal error in looking up the client record was encountered, or an invalid fid was provided, or an attempt was made to remove "." or "..".
EISDIR The target of the deletion was supposed to be a file, but it is really a directory.
ENOENT The named file was not found.
ENOTDIR The a dirFidP parameter references an object which is not a directory, or the deletion target is supposed to be a directory but is not.
ENOTEMPTY The target directory being deleted is not empty.
VICETOKENDEAD Caller's authentication token has expired.

Section 5.1.3.6: RXAFS CreateFile - Create

the given file

int RXAFS CreateFile(IN struct rx connection *a rxConnP, 
                        IN AFSFid *DirFid, 
                        IN char *Name, 
                        IN AFSStoreStatus *InStatus, 
                        OUT AFSFid *OutFid, 
                        OUT AFSFetchStatus *OutFidStatus, 
                        OUT AFSFetchStatus *OutDirStatus, 
                        OUT AFSCallBack *CallBack, 
                        OUT AFSVolSync *a volSyncP) 
/* associated with the new file. */
Description
[Opcode 137] This call is used to create a file, but not for creating a directory or a symbolic link. If this call succeeds, it is the Cache Manager's responsibility to either create an entry locally in the directory specified by DirFid or to invalidate this directory's cache entry.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller is not permitted to perform this operation.
EINVAL An internal error in looking up the client record was encountered, or an invalid fid or name was provided.
ENOTDIR The DirFid parameter references an object which is not a directory.
VICETOKENDEAD Caller's authentication token has expired.

Section 5.1.3.7: RXAFS Rename - Rename the

specified file in the given directory

int RXAFS Rename(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a origDirFidP, 
                        IN char *a origNameP, 
                        IN AFSFid *a newDirFidP, 
                        IN char *a newNameP, 
                        OUT AFSFetchStatus *a origDirStatusP, 
                        OUT AFSFetchStatus *a newDirStatusP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 138] Rename file a origNameP in the directory identified by a origDirFidP. Its new name is to be a newNameP, and it will reside in the directory identified by a newDirFidP. Each of these names must be no more than AFSNAMEMAX (256) characters long. The status of the original and new directories after the rename operation completes are deposited in a origDirStatusP and a newDirStatusP respectively. Existing callbacks are broken for all files and directories involved in the operation.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES New file exists but user doesn't have Delete rights in the directory.
EINVAL Name provided is invalid.
EISDIR Original object is a file and new object is a directory.
ENOENT The object to be renamed doesn't exist in the parent directory.
ENOTDIR Original object is a directory and new object is a file.
EXDEV Rename attempted across a volume boundary, or create a pathname loop, or hard links exist to the file.

Section 5.1.3.8: RXAFS Symlink - Create a

symbolic link

int RXAFS Symlink(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a dirFidP, 
                        IN char *a nameP, 
                        IN char *a linkContentsP, 
                        IN AFSStoreStatus *a origDirStatP, 
                        OUT AFSFid *a newFidP, 
                        OUT AFSFetchStatus *a newFidStatP, 
                        OUT AFSFetchStatus *a newDirStatP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 139] Create a symbolic link named a nameP in the directory identified by a dirFidP. The text of the symbolic link is provided in a linkContentsP, and the desired status fields for the symbolic link given by a origDirStatP. The name offered in a nameP must be less than AFSNAMEMAX (256) characters long, and the text of the link to which a linkContentsP points must be less than AFSPATHMAX (1,024) characters long. Once the symbolic link has been successfully created, its file identifier is returned in a newFidP. Existing callbacks to the a dirFidP directory are broken before the symbolic link creation completes. The status fields for the symbolic link itself and its parent's directory are returned in a newFidStatP and a newDirStatP respectively.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.
EINVAL Illegal symbolic link name provided.

Section 5.1.3.9: RXAFS Link - Create a hard

link

int RXAFS Link(IN struct rx connection *a rxConnP, 
                IN AFSFid *a dirFidP, 
                IN char *a nameP, 
                IN AFSFid *a existingFidP, 
                OUT AFSFetchStatus *a newFidStatP, 
                OUT AFSFetchStatus *a newDirStatP, 
                OUT AFSVolSync *a volSyncP) 
Description
[Opcode 140] Create a hard link named a nameP in the directory identified by a dirFidP. The file serving as the basis for the hard link is identified by existingFidP. The name offered in a nameP must be less than AFSNAMEMAX (256) characters long. Existing callbacks to the a dirFidP directory are broken before the hard link creation completes. The status fields for the file itself and its parent's directory are returned in a newFidStatP and a newDirStatP respectively. Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.
EISDIR An attempt was made to create a hard link to a directory.
EXDEV Hard link attempted across directories.

Section 5.1.3.10: RXAFS MakeDir - Create a

directory

int RXAFS MakeDir(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a parentDirFid,P 
                        IN char *a newDirNameP, 
                        IN AFSStoreStatus *a currStatP, 
                        OUT AFSFid *a newDirFidP, 
                        OUT AFSFetchStatus *a dirFidStatP, 
                        OUT AFSFetchStatus *a parentDirStatP, 
                        OUT AFSCallBack *a newDirCallBackP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 141] Create a directory named a newDirNameP within the directory identified by a parentDirFidP. The initial status fields for the new directory are provided in a currStatP. The new directory's name must be less than AFSNAMEMAX (256) characters long. The new directory's ACL is inherited from its parent. Existing callbacks on the parent directory are broken before the creation completes. Upon successful directory creation, the new directory's file identifier is returned in a newDirFidP, and the resulting status information for the new and parent directories are stored in a dirFidStatP and a parentDirStatP respectively. In addition, a callback for the new directory is returned in a newDirCallBackP.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.
EINVAL The directory name provided is unacceptable.

Section 5.1.3.11: RXAFS RemoveDir - Remove a

directory

int RXAFS RemoveDir(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a parentDirFidP, 
                        IN char *a dirNameP, 
                        OUT AFSFetchStatus *a newParentDirStatP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 142] Remove the directory named a dirNameP from within its parent directory, identified by a parentDirFid. The directory being removed must be empty, and its name must be less than AFSNAMEMAX (256) characters long. Existing callbacks to the directory being removed and its parent directory are broken before the deletion completes. Upon successful deletion, the status fields for the parent directory are returned in a newParentDirStatP.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.

Section 5.1.3.12: RXAFS GetStatistics - Get

common File Server statistics

int RXAFS GetStatistics(IN struct rx connection *a rxConnP, 
                        OUT ViceStatistics *a FSInfoP) 
Description
[Opcode 146] Fetch the structure containing a set of common File Server statistics. These numbers represent accumulated readings since the time the File Server last restarted. For a full description of the individual fields contained in this structure, please see Section 5.1.2.6.
Rx connection information for the related File Server is contained in a rxConnP.
Error Codes
---No error codes generated.

Section 5.1.3.13: RXAFS GiveUpCallBacks -

Ask the File Server to break the given set of callbacks on the corresponding set of file identifiers

int RXAFS GiveUpCallBacks(IN struct rx connection *a rxConnP, 
                                IN AFSCBFids *a fidArrayP, 
                                IN AFSCBs *a callBackArrayP) 
Description
[Opcode 147] Given an array of up to AFSCBMAX file identifiers in a fidArrayP and a corresponding number of callback structures in a callBackArrayP, ask the File Server to remove these callbacks from its register. Note that this routine only affects callbacks outstanding on the given set of files for the host issuing the RXAFS GiveUpCallBacks call. Callback promises made to other machines on any or all of these files are not affected.
Rx connection information for the related File Server is contained in a rxConnP.
Error Codes
EINVAL More file identifiers were provided in the a fidArrayP than callbacks in the a callBackArray.

Section 5.1.3.14: RXAFS GetVolumeInfo - Get

information about a volume given its name

int RXAFS GetVolumeInfo(IN struct rx connection *a rxConnP, 
                        IN char *a volNameP, 
                        OUT VolumeInfo *a volInfoP) 
Description
[Opcode 148] Ask the given File Server for information regarding a volume whose name is a volNameP. The volume name must be less than AFSNAMEMAX characters long, and the volume itself must reside on the File Server being probed.
Rx connection information for the related File Server is contained in a rxConnP. Please note that definitions for the error codes with VL prefixes may be found in the vlserver.h include file
Error Codes
Could not contact any of the corresponding Volume Location Servers. VL BADNAME An improperly-formatted volume name provided.
VL ENTDELETED An entry was found for the volume, reporting that the volume has been deleted.
VL NOENT The given volume was not found.

Section 5.1.3.15: RXAFS GetVolumeStatus -

Get basic status information for the named volume

int RXAFS GetVolumeStatus(IN struct rx connection *a rxConnP, 
                                IN long a volIDP, 
                                OUT AFSFetchVolumeStatus *a volFetchStatP, 
                                OUT char *a volNameP, 
                                OUT char *a offLineMsgP, 
                                OUT char *a motdP) 
Description
[Opcode 149] Given the numeric volume identifier contained in a volIDP, fetch the basic status information corresponding to that volume. This status information is stored into a volFetchStatP. A full description of this status structure is found in Section 5.1.2.8. In addition, three other facts about the volume are returned. The volume's character string name is placed into a volNameP. This name is guaranteed to be less than AFSNAMEMAX characters long. The volume's offline message, namely the string recording why the volume is off-line (if it is), is stored in a offLineMsgP . Finally, the volume's "Message of the Day" is placed in a motdP. Each of the character strings deposited into a offLineMsgP and a motdP is guaranteed to be less than AFSOPAQUEMAX (1,024) characters long.
Rx connection information for the related File Server is contained in a rxConnP.
Error Codes
EACCES The caller does not have the necessary access rights.
EINVAL A volume identifier of zero was specified.

Section 5.1.3.16: RXAFS SetVolumeStatus -

Set the basic status information for the named volume

int RXAFS SetVolumeStatus(struct rx connection *a rxConnP,
                                long avolIDP, 
                                AFSStoreVolumeStatus *a volStoreStatP, 
                                char *a volNameP, 
                                char *a offLineMsgP, 
                                char *a motdP) 
/* for the named volume */
Description
[Opcode 150] Given the numeric volume identifier contained in a volIDP, set that volume's basic status information to the values contained in a volStoreStatP. A full description of the fields settable by this call, including the necessary masking, is found in Section 5.1.2.9. In addition, three other items relating to the volume may be set. Non-null character strings found in a volNameP, a offLineMsgP, and a motdP will be stored in the volume's printable name, off-line message, and "Message of the Day" fields respectively. The volume name provided must be less than AFSNAMEMAX (256) characters long, and the other two strings must be less than AFSOPAQUEMAX (1,024) characters long each.
Rx connection information for the related File Server is contained in a rxConnP.
Error Codes
EACCES The caller does not have the necessary access rights.
EINVAL A volume identifier of zero was specified.

Section 5.1.3.17: RXAFS GetRootVolume -

Return the name of the root volume for the file system

int RXAFS GetRootVolume(IN struct rx connection *a rxConnP, 
                        OUT char *a rootVolNameP) 
Description
[Opcode 151] Fetch the name of the volume which serves as the root of the AFS file system and place it into a rootVolNameP. This name will always be less than AFSNAMEMAX characters long. Any File Server will respond to this call, not just the one hosting the root volume. The queried File Server first tries to discover the name of the root volume by reading from the /usr/afs/etc/RootVolume file on its local disks. If that file doesn't exist, then it will return the default value, namely "root.afs".
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
---No error codes generated.

5.1.3.18: RXAFS CheckToken - (Obsolete)

Check that the given user identifier matches the one in the supplied authentication token

int RXAFS CheckToken(IN struct rx connection *a rxConnP, 
                        IN long ViceId, 
                        IN AFSOpaque *token) 
Description
[Opcode 152] This function only works for the now-obsolete RPC facility used by AFS, R. For modern systems using the Rx RPC mechanism, we always get an error return from this routine.
Rx connection information for the related File Server is contained in a rxConnP.
Error Codes
ECONNREFUSED Always returned on Rx connections.

Section 5.1.3.19: RXAFS GetTime - Get the

File Server's time of day

int RXAFS GetTime(IN struct rx connection *a rxConnP, 
                        OUT unsigned long *a secondsP, 
                        OUT unsigned long *a uSecondsP) 
Description
[Opcode 153] Get the current time of day from the File Server specified in the Rx connection information contained in a rxConnP. The time is returned in elapsed seconds (a secondsP) and microseconds (a uSecondsP) since that standard unix "start of the world".
Error Codes
---No error codes generated.

Section 5.1.3.20: RXAFS NGetVolumeInfo - Get

information about a volume given its name

int RXAFS NGetVolumeInfo(IN struct rx connection *a rxConnP, 
                                IN char *a volNameP, 
                                OUT AFSVolumeInfo *a volInfoP) 
Description
[Opcode 154] This function is identical to RXAFS GetVolumeInfo() (see Section 5.1.3.14), except that it returns a struct AFSVolumeInfo instead of a struct VolumeInfo. The basic difference is that struct AFSVolumeInfo also carries an accompanying UDP port value for each File Server listed in the record.

Section 5.1.3.21: RXAFS BulkStatus - Fetch

the status information regarding a set of given file system objects

int RXAFS BulkStatus(IN struct rx connection *a rxConnP, 
                        IN AFSCBFids *a fidToStatArrayP, 
                        OUT AFSBulkStats *a currStatArrayP, 
                        OUT AFSCBs *a callBackArrayP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 155] This routine is identical to RXAFS FetchStatus() as described in Section 5.1.3.2, except for the fact that it allows the caller to ask for the current status fields for a set of up to AFSCBMAX (50) file identifiers at once.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.
EINVAL The number of file descriptors for which status information was requested is illegal.

Section 5.1.3.22: RXAFS SetLock - Set an

advisory lock on the given file identifier

int RXAFS SetLock(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a fidToLockP, 
                        IN ViceLockType a lockType, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 156] Set an advisory lock on the file identified by a fidToLockP. There are two types of locks that may be specified via a lockType: LockRead and LockWrite. An advisory lock times out after AFS LOCKWAIT (5) minutes, and must be extended in order to stay in force (see RXAFS ExtendLock(), Section 5.1.3.23).
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.
EINVAL An illegal lock type was specified.
EWOULDBLOCK The lock was already incompatibly granted to another party.

Section 5.1.3.23: RXAFS ExtendLock - Extend

an advisory lock on a file

int RXAFS ExtendLock(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a fidToBeExtendedP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 157] Extend the advisory lock that has already been granted to the caller on the file identified by a fidToBeExtendedP.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EINVAL The caller does not already have the given file locked.

Section 5.1.3.24: RXAFS ReleaseLock -

Release the advisory lock on a file

int RXAFS ReleaseLock(IN struct rx connection *a rxConnP, 
                        IN AFSFid *a fidToUnlockP, 
                        OUT AFSVolSync *a volSyncP) 
Description
[Opcode 158] Release the advisory lock held on the file identified by a fidToUnlockP. If this was the last lock on this file, the File Server will break all existing callbacks to this file.
Rx connection information for the related File Server is contained in a rxConnP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.

Section 5.1.3.25: RXAFS XStatsVersion - Get

the version number associated with the File Server's extended statistics structure

int RXAFS XStatsVersion(IN struct rx connection *a rxConnP, 
                        OUT long *a versionNumberP) 
Description
[Opcode 159] This call asks the File Server for the current version number of the extended statistics structures it exports (see RXAFS GetXStats(), Section 5.1.3.26). The version number is placed into a versionNumberP.
Rx connection information for the related File Server is contained in a rxConnP.
Error Codes
---No error codes generated.

Section 5.1.3.26: RXAFS GetXStats - Get the

current contents of the specified extended statistics structure

int RXAFS GetXStats(IN struct rx connection *a rxConnP, 
                        IN long a clientVersionNumber, 
                        IN long a collectionNumber, 
                        OUT long *a srvVersionNumberP, 
                        OUT long *a timeP, 
                        OUT AFS CollData *a dataP) 
Description
[Opcode 160] This function fetches the contents of the specified File Server extended statistics structure. The caller provides the version number of the data it expects to receive in a clientVersionNumber. Also provided in a collectionNumber is the numerical identifier for the desired data collection. There are currently two of these data collections defined: AFS XSTATSCOLL CALL INFO, which is the list of tallies of the number of invocations of internal File Server procedure calls, and AFS XSTATSCOLL PERF INFO, which is a list of performance-related numbers. The precise contents of these collections are described in Sections 5.1.2.7. The current version number of the File Server collections is returned in a srvVersionNumberP, and is always set upon return, even if the caller has asked for a difierent version. If the correct version number has been specified, and a supported collection number given, then the collection data is returned in a dataP. The time of collection is also returned, being placed in a timeP.
Rx connection information for the related File Server is contained in a rxConnP.
Error Codes
---No error codes are generated.

Section 5.1.4: Streamed Function Calls

There are two streamed functions in the File Server RPC interface, used to fetch and store arbitrary amounts of data from a file. While some non-streamed calls pass such variable-length objects as struct AFSCBFids, these objects have a pre-determined maximum size.
The two streamed RPC functions are also distinctive in that their single Rxgen declarations generate not one but two client-side stub routines. The first is used to ship the IN parameters off to the designated File Server, and the second to gather the OUT parameters and the error code. If a streamed definition declares a routine named X YZ(), the two resulting stubs will be named StartX YZ() and EndX YZ(). It is the application programmer's job to first invoke StartX YZ(), then manage the unbounded data transfer, then finish up by calling EndX YZ(). The first longword in the unbounded data stream being fetched from a File Server contains the number of data bytes to follow. The application then reads the specified number of bytes from the stream.
The following sections describe the four client-side functions resulting from the Fetch-Data() and StoreData() declarations in the Rxgen interface definition file. These are the actual routines the application programmer will include in the client code. For reference, here are the interface definitions that generate these functions. Note that the split keyword is what causes Rxgen to generate the separate start and end routines. In each case, the number after the equal sign specifies the function's identifying opcode number. The opcode is passed to the File Server by the StartRXAFS FetchData() and StartRXAFS StoreData() stub routines.
FetchData(IN AFSFid *a_fidToFetchP, 
                IN long a_offset, 
                IN long a_lenInBytes, 
                OUT AFSFetchStatus *a_fidStatP, 
                OUT AFSCallBack *a_callBackP, 
                OUT AFSVolSync *a_volSyncP) split = 130; 

StoreData(IN AFSFid *Fid, 
                IN AFSStoreStatus *InStatus, 
                IN long Pos, 
                IN long Length, 
                IN long FileLength, 
                OUT AFSFetchStatus *OutStatus, 
                OUT AFSVolSync *a_volSyncP) split = 133; 

Section 5.1.4.1: StartRXAFS FetchData - Begin

a request to fetch file data

int StartRXAFS FetchData(IN struct rx call *a rxCallP, 
                                IN AFSFid *a fidToFetchP, 
                                IN long a offset, 
                                IN long a lenInBytes) 
Description
Begin a request for a lenInBytes bytes of data starting at byte offset a offset from the file identified by a fidToFetchP. After successful completion of this call, the data stream will make the desired bytes accessible. The first longword in the stream contains the number of bytes to actually follow.
Rx call information to the related File Server is contained in a rxCallP.
Error Codes
---No error codes generated.

Section 5.1.4.2: EndRXAFS FetchData -

Conclude a request to fetch file data

int EndRXAFS FetchData(IN struct rx call *a rxCallP, 
                        OUT AFSFetchStatus *a fidStatP, 
                        OUT AFSCallBack *a callBackP, 
                        OUT AFSVolSync *a volSyncP) 
Description
Conclude a request to fetch file data, as commenced by an StartRXAFS FetchData() invocation. By the time this routine has been called, all of the desired data has been read off the data stream. The status fields for the file from which the data was read are stored in a fidStatP. If the file was from a read/write volume, its callback information is placed in a callBackP.
Rx call information to the related File Server is contained in a rxCallP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights. EIO Given file could not be opened or statted on the File Server, or there was an error reading the given data off the File Server's disk.
-31 An Rx write into the stream ended prematurely.

Section 5.1.4.3: StartRXAFS StoreData - Begin

a request to store file data

int StartRXAFS StoreData(IN struct rx call *a rxCallP, 
                                IN AFSFid *a fidToStoreP, 
                                IN reStatus *a fidStatusP, 
                                IN AFSStolong a offset, 
                                IN long a lenInBytes, 
                                IN long a fileLenInBytes) 
Description
Begin a request to write a lenInBytes of data starting at byte offset a offset to the file identified by a fidToStoreP, causing that file's length to become a fileLenInBytes bytes. After successful completion of this call, the data stream will be ready to begin accepting the actual data being written.
Rx call information to the related File Server is contained in a rxCallP.
Error Codes
---No error codes generated.

Section 5.1.4.4: EndRXAFS StoreData -

Conclude a request to store file data

int EndRXAFS StoreData(IN struct rx call *a rxCallP, 
                        OUT AFSFetchStatus *a fidStatP, 
                        OUT AFSCallBack *a callBackP, 
                        OUT AFSVolSync *a volSyncP) 
Description
Conclude a request to store file data, as commenced by a StartRXAFS StoreData() invocation. By the time this routine has been called, all of the file data has been inserted into the data stream. The status fields for the file to which the data was written are stored in a fidStatP. All existing callbacks to the given file are broken before the store concludes.
Rx call information to the related File Server is contained in a rxCallP. Volume version information is returned for synchronization purposes in a volSyncP.
Error Codes
EACCES The caller does not have the necessary access rights.
EISDIR The file being written to is a symbolic link.
ENOSPEC A write to the File Server's file on local disk failed.
-32 A short read was encountered by the File Server on the data stream.

Section 5.1.5: Example of Streamed Function Call

Usage

Section 5.1.5.1: Preface

The following code fragment is offered as an example of how to use the streamed File Server RPC calls. In this case, a client fetches some amount of data from the given File Server and writes it to a local file it uses to cache the information. For simplicity, many issues faced by a true application programmer are not addressed here. These issues include locking, managing file chunking, data version number mismatches, volume location, Rx connection management, defensive programming (e.g., checking parameters before using them), client-side cache management algorithms, callback management, and full error detection and recovery. Pseudocode is incorporated when appropriate to keep the level of detail reasonable. For further descriptions of some of these details and issues, the reader is referred to such companion documents as AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure Call Facility, AFS-3 Programmer's Reference:Volume Server/Volume Location Server Interface, and AFS-3 Programmer's Reference: Architectural Overview.
A discussion of the methods used within the example code fragment follows immediately afterwards in Section 5.1.5.3.

Section 5.1.5.2: Code Fragment Illustrating

Fetch Operation

int code; /*Return code*/ 
long bytesRead; /*Num bytes read from Rx*/ 
struct myConnInfo *connP; /*Includes Rx conn info*/ 
struct rx_call *rxCallP; /*Rx call ptr*/ 
struct AFSFid *afsFidP; /*Fid for file to fetch*/ 
int lclFid; /*Fid for local cache file*/ 
long offsetBytes; /*Starting fetch offset*/ 
long bytesToFetch; /*Num bytes to fetch*/ 
long bytesFromFS; /*Num bytes FileServer returns*/ 
char *fetchBuffP; /*Buffer to hold stream data*/ 
int currReadBytes; /*Num bytes for current read*/ 
/* 
 Assume that connP, afsFidP, offsetBytes, lclFid,and 
 bytesToFetch have all been given their desired values. 
*/ . . . 
rxCallP = rx_NewCall(connP->rxConnP); 
code = StartRXAFS_FetchData( rxCallP, /*Rx call to use*/ 
                        afsFidP, /*Fid being fetched from*/ 
                        offsetBytes, /*Offset in bytes*/ 
                        bytesToFetch); /*Num bytes wanted*/ 
if (code == 0) 
{ 
        bytesRead = rx_Read(rxCallP, &bytesFromFS, sizeof(long)); 
        if (bytesRead != sizeof(long)) ExitWithError(SHORT_RX_READ); 
        bytesFromFS = ntohl(bytesFromFS); 
        xmitBuffer = malloc(FETCH_BUFF_BYTES); 
        lclFid = open(CacheFileName, O_RDWR, mode); 
        pos = lseek(lclFid, offsetBytes, L_SET); 
        while (bytesToFetch > 0) { 
                currReadBytes = (bytesToFetch > FETCH_BUFF_BYTES) ?  
                                FETCH_BUFF_BYTES : bytesToFetch; 
                bytesRead = rx_Read(rxCallP, fetchBuffP, currReadBytes); 
                if (bytesRead != currReadBytes) ExitWithError(SHORT_RX_READ); 
                code = write(lclFid, fetchBuffP, currReadBytes); 
                if (code) ExitWithError(LCL_WRITE_FAILED); 
                bytesToFetch -= bytesRead; 
        } /*Read from the Rx stream*/ 
        close(lclFid); 
} else ExitWithError(code); 
code = EndRXAFS_FetchData( rxCallP, /*Rx call to use*/ 
                                fidStatP, /*Resulting stat fields*/ 
                                fidCallBackP, /*Resulting callback info*/ 
                                volSynchP); /*Resulting volume sync info*/ 
                                code = rx_EndCall(rxCallP, code); 
return(code); . . . 

Section 5.1.5.3: Discussion and Analysis

The opening assumption in this discussion is that all the information required to do the fetch has already been set up. These mandatory variables are the client-side connection information for the File Server hosting the desired file, the corresponding AFS file identifier, the byte offset into the file, the number of bytes to fetch, and the identifier for the local file serving as a cached copy.
Given the Rx connection information stored in the client's connP record, rx NewCall() is used to create a new Rx call to handle this fetch operation. The structure containing this call handle is placed into rxCallP. This call handle is used immediately in the invocation of StartRXAFS FetchData(). If this setup call fails, the fragment exits. Upon success, though, the File Server will commence writing the desired data into the Rx data stream. The File Server first writes a single longword onto the stream announcing to the client how many bytes of data will actually follow. The fragment reads this number with its first rx Read() call. Since all Rx stream data is written in network byte order, the fragment translates the byte count to its own host byte order first to properly interpret it. Once the number of bytes to appear on the stream is known, the client code proceeds to open the appropriate cache file on its own local disk and seeks to the appropriate spot within it. A buffer into which the stream data will be placed is also created at this time.
The example code then falls into a loop where it reads all of the data from the File Server and stores it in the corresponding place in the local cache file. For each iteration, the code decides whether to read a full buffer's worth or the remaining number of bytes, whichever is smaller. After all the data is pulled off the Rx stream, the local cache file is closed. At this point, the example finishes off the RPC by calling EndRXAFS FetchData(). This gathers in the required set of OUT parameters, namely the status fields for the file just fetched, callback and volume synchronization information, and the overall error code for the streamed routine. The Rx call created to perform the fetch is then terminated and cleaned up by invoking rx EndCall().

Section 5.1.6: Required Caller Functionality

The AFS File Server RPC interface was originally designed to interact only with Cache Manager agents, and thus made some assumptions about its callers. In particular, the File Server expected that the agents calling it would potentially have stored callback state on file system objects, and would have to be periodically pinged in order to garbage-collect its records, removing information on dead client machines. Thus, any entity making direct calls to this interface must mimic certain Cache Manager actions, and respond to certain Cache Manager RPC interface calls.
To be safe, any application calling the File Server RPC interface directly should export the entire Cache Manager RPC interface. Realistically, though, it will only need to provide stubs for the three calls from this interface that File Servers know how to make: RXAFSCB InitCallBackState(), RXAFSCB Probe() and RXAFSCB CallBack(). The very first File Server call made by this application will prompt the given File Server to call RXAFSCB InitCallBackState(). This informs the application that the File Server has no record of its existence and hence this "Cache Manager" should clear all callback information for that server. Once the application responds positively to the inital RXAFSCB InitCallBackState(), the File Server will treat it as a bona fide, fully-fledged Cache Manager, and probe it every so often with RXAFSCB Probe() calls to make sure it is still alive.

Section 5.2: Signal Interface

While the majority of communication with AFS File Servers occurs over the RPC interface, some important operations are invoked by sending unix signals to the process. This section describes the set of signals recognized by the File Server and the actions they trigger upon receipt, as summarized below:
  • SIGQUIT: Shut down a File Server.
  • SIGTSTP: Upgrade debugging output level.
  • SIGHUP: Reset debugging output level.
  • SIGTERM: Generate debugging output specifically concerning open files within the File Server process.

Section 5.2.1: SIGQUIT: Server Shutdown

Upon receipt of this signal, the File Server shuts itself down in an orderly fashion. It first writes a message to the console and to its log file (/usr/afs/logs/FileLog) stating that a shutdown has commenced. The File Server then flushes all modified buffers and prints out a set of internal statistics, including cache and disk numbers. Finally, each attached volume is taken offline, which means the volume header is written to disk with the appropriate bits set.
In typical usage, human operators do not send the SIGQUIT signal directly to the File Server in order to affect an orderly shutdown. Rather, the BOS Server managing the server processes on that machine issues the signal upon receipt of a properly-authorized shutdown RPC request.

Section 5.2.2: SIGTSTP: Upgrade Debugging Level

Arrival of a SIGTSTP signal results in an increase of the debugging level used by the File Server. The routines used for writing to log files are sensitive to this debugging level, as recorded in the global LogLevel variable. Specifically, these routines will only generate output if the value of LogLevel is greater than or equal to the value of its threshold parameter. By default, the File Server sets LogLevel to zero upon startup. If a SIGTSTP signal is received when the debugging level is zero, it will be bumped to 1. If the signal arrives when the debugging level is positive, its value will be multiplied by 5. Thus, as more SIGTSTPs are received, the set of debugging messages eligible to be delivered to log files grows.
Since the SIGTSTP signal is not supported under IBM's AIX 2.2.1 operating system, this form of debugging output manipulation is not possible on those platforms.

Section 5.2.3: SIGHUP: Reset Debugging Level

Receiving a SIGHUP signal causes a File Server to reset its debugging level to zero. This effectively reduces the set of debugging messages eligible for delivery to log files to a bare minimum. This signal is used in conjunction with SIGTSTP to manage the verbosity of log information.
Since the SIGHUP signal is not supported under IBM's AIX 2.2.1 operating system, this form of debugging output manipulation is not possible on those platforms.

Section 5.2.4: SIGTERM: File Descriptor Check

Receipt of a SIGTERM signal triggers a routine which sweeps through the given File Server's unix file descriptors. For each possible unix fid slot, an fstat() is performed on that descriptor, and the particulars of each open file are printed out. This action is designed solely for debugging purposes.

Section 5.3: Command Line Interface

Another interface exported by the File Server is the set of command line switches it accepts. Using these switches, many server parameters and actions can be set. Under normal conditions, the File Server process is started up by the BOS Server on that machine, as described in AFS-3 Programmer's Reference: BOS Server Interface. So, in order to utilize any combination of these command-line options, the system administrator must define the File Server bnode in such a way that these parameters are properly included. Note that the switch names must be typed exactly as listed, and that abbreviations are not allowed. Thus, specifying -b 300 on the command line is unambiguous, directing that 300 buffers are to be allocated. It is not an abbreviation for the -banner switch, asking that a message is to be printed to the console periodically.
A description of the set of currently-supported command line switches follows.
  • -b <# buffers> Choose the number of 2,048-byte data buffers to allocate at system startup. If this switch is not provided, the File Server will operate with 70 such buffers by default.
  • -banner This switch instructs the File Server to print messages to the console every 10 minutes to demonstrate it is still running correctly. The text of the printed message is: File Server is running at <time>.
  • -cb <# callbacks stored> Specify the maximum number of callback records stored simultaneously by the File Server. The default pool size is 20,000 records.
  • -d <debug level>=""> Set the debugging output level at which File Server runs to the value provided. Specifically, the LogLevel global variable is set to the given value (See Section 5.2.2). If this switch is not provided, the default initial File Server debugging level is set to zero, producing the minimal debugging output to the log files.
  • -k <stack size>=""> Set the stack size to provide server LWPs upon creation, measured in 1,024-byte blocks. The default LWP stack size is 24 blocks, or 24,576 bytes.
  • -l <large (directory) vnodes> Select the number of "large" vnodes the File Server will cache. These vnodes are suitable for recording information about AFS directories. The extra space in the vnode allows ACL information to be stored along with the directory. The default allocation value is 200 directory vnodes.
  • -pctspare <percent overrun="" blocks="" past="" quota>=""> Similar to the -spare switch, except that the number of allowable overrun blocks is expressed as a percentage of the given volume's quota. Note: this switch cannot be used in combination with the -spare switch.
  • -rxdbg Instruct the File Server to open a file named rx dbg in the current directory, into which the Rx package will write general debugging information. If the file is already open (due to the appearance of the -rxdbge switch earlier in the command line), this results in a no-op.
  • -rxdbge Instruct the File Server to open a file named rx dbg in the current directory, into which the Rx package will write debugging information related to its event-scheduling activities. If the file is already open (due to the appearance of the -rxdbg switch earlier in the command line), this results in a no-op.
  • -rxpck <# packets> Set the number of extra Rx packet buffers to hold in reserve. These pre-allocated buffers assist in responding to spikes in network traffic demands. By default, 100 such packet buffers are maintained.
  • -s <small (file) vnodes> Select the number of "small" vnodes the File Server will cache. These vnodes are suitable for recording information about non-directory files. As with directory vnodes, the File Server will allocate 200 small vnodes by default.
  • -spare <# overrun blocks to allow> Tell the File Server to allow users performing a store operation to overrun the host volume's disk quota by a certain number of (1,024-byte) blocks. In other words, the first store resulting in a quota overrun will be allowed to succeed if and only if it uses no more than these many blocks beyond the quota. Further store operations will be rejected until the volume's storage is once again reduced below quota. By default, overruns of 1,024 blocks of 1,024 bytes each (1 megabyte total) are tolerated. Note: this switch cannot be used in combination with the -pctspare switch.
  • -w <callback wait="" interval="" in="" seconds>=""> This switch determines how often the File Server periodic daemon lightweight processes run. Among other things, these daemon LWPs check on the validity of callback records, keep disk usage statistics up to date, and check the health of the various client machines that have previously interacted with the File Server. For a full description of these daemon LWPs, consult Section 2.3. The associated argument specifies the number of seconds to sleep between daemon invocations. By default, these periodic daemons run every 300 seconds (5 minutes).