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

Section 5.1.3.11: RXAFS RemoveDir - Remove a

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).

Section 5.1: RPC Interface

: This chapter documents the API for the Rx facility. Included are descriptions of all the constants, structures, exported variables, macros, and interface functions available to the application programmer. This interface is identical regardless of whether the application lives within the unix kernel or above it.

: This chapter actually provides more information than what may be strictly considered the Rx API. Many objects that were intended to be opaque and for Rx internal use only are also described here. The reason driving the inclusion of this "extra" information is that such exported Rx interface files as rx.h make these objects visible to application programmers. It is prefereable to describe these objects here than to ignore them and leave application programmers wondering as to their meaning.

: An example application illustrating the use of this interface, showcasing code from both server and client sides, appears in the following chapter.

Section 5.2: Signal Interface

This section covers the basic constant definitions of interest to the Rx application programmer. Each subsection is devoted to describing the constants falling into the following categories:

Configuration quantities
Waiting options
Connection ID operations
Connection flags
Connection types
Call states
Call flags
Call modes
Packet header flags
Packet sizes
Packet types
Packet classes
Conditions prompting ack packets
Ack types
Error codes
Debugging values

: An attempt has been made to relate these constant definitions to the objects or routines that utilize them.

Section 5.2.1: SIGQUIT: Server Shutdown

: These definitions provide some basic Rx configuration parameters, including the number of simultaneous calls that may be handled on a single connection, lightweight thread parameters, and timeouts for various operations.

Name: RX IDLE DEAD TIME

Value: 60

Description: Default idle dead time for connections, in seconds.

Name: RX MAX SERVICES

Value: 20

Description: The maximum number of Rx services that may be installed within one application.

Name: RX PROCESS MAXCALLS

Value: 4

Description: The maximum number of asynchronous calls active simultaneously on any given Rx connection. This value must be set to a power of two.

Name: RX DEFAULT STACK SIZE

Value: 16,000

Description: Default lightweight thread stack size, measured in bytes. This value may be overridden by calling the rx_SetStackSize() macro.

Name: RX PROCESS PRIORITY

Value: LWP NORMAL PRIORITY

Description: This is the priority under which an Rx thread should run. There should not generally be any reason to change this setting.

Name: RX CHALLENGE TIMEOUT

Value: 2

Description: The number of seconds before another authentication request packet is generated.

Name: RX MAXACKS

Value: 255

Description: Maximum number of individual acknowledgements that may be carried in an Rx acknowledgement packet.

Section 5.2.2: SIGTSTP: Upgrade Debugging Level

: These definitions provide readable values indicating whether an operation should block when packet buffer resources are not available.

Name: RX DONTWAIT

Value: 0

Description: Wait until the associated operation completes.

Name: RX WAIT

Value: 1

Description: Don't wait if the associated operation would block.

Section 5.2.3: SIGHUP: Reset Debugging Level

: These values assist in extracting the call channel number from a connection identifier. A call channel is the index of a particular asynchronous call structure within a single Rx connection.

Name: RX CIDSHIFT

Value: 2

Description: Number of bits to right-shift to isolate a connection ID. Must be set to the log (base two) of RX MAXCALLS.

Name: RX CHANNELMASK

Value: (RX MAXCALLS-1)

Description: Mask used to isolate a call channel from a connection ID field.

Name: RX CIDMASK

Value: (~RX CHANNELMASK)

Description: Mask used to isolate the connection ID from its field, masking out the call channel information.

Section 5.2.4: SIGTERM: File Descriptor Check

: The values defined here appear in the flags field of Rx connections, as defined by the rx connection structure described in Section 5.3.2.2.

Name: RX CONN MAKECALL WAITING

Value: 1

Description: rx MakeCall() is waiting for a channel.

Name: RX CONN DESTROY ME

Value: 2

Description: Destroy this (client) connection after its last call completes.

Name: RX CONN USING PACKET CKSUM

Value: 4

Description: This packet is using security-related check-summing (a non-zero header, spare field has been seen.)

Section 5.2.5: Connection Types

: Rx stores different information in its connection structures, depending on whether the given connection represents the server side (the one providing the service) or the client side (the one requesting the service) of the protocol. The type field within the connection structure (described in Section 5.3.2.2) takes on the following values to differentiate the two types of connections, and identifies the fields that are active within the connection structure.

Name: RX CLIENT CONNECTION

Value: 0

Description: This is a client-side connection.

Name: CONNECTION

Value: 1

Description: This is a server-side connection.

Section 5.2.6: Call States

: An Rx call on a particular connection may be in one of several states at any instant in time. The following definitions identify the range of states that a call may assume.

Name: RX STATE NOTINIT

Value: 0

Description: The call structure has never been used, and is thus still completely uninitialized.

Name: RX STATE PRECALL

Value: 1

Description: A call is not yet in progress, but packets have arrived for it anyway. This only applies to calls within server-side connections.

Name: RX STATE ACTIVE

Value: 2

Description: This call is fully active, having an attached lightweight thread operating on its behalf.

Name: RX STATE DAILY

Value: 3

Description: The call structure is "dallying" after its lightweight thread has completed its most recent call. This is a "hot-standby" condition, where the call structure preserves state from the previous call and thus optimizes the arrival of further, related calls.

Section 5.2.7: Call Flags:

: These values are used within the flags field of a variable declared to be of type struct rx call, as described in Section 5.3.2.4. They provide additional information as to the state of the given Rx call, such as the type of event for which it is waiting (if any) and whether or not all incoming packets have been received in support of the call.

Name: RX CALL READER WAIT

Value: 1

Description: Reader is waiting for next packet.

Name: RX CALL WAIT WINDOW ALLOC

Value: 2

Description: Sender is waiting for a window so that it can allocate buffers.

Name: RX CALL WAIT WINDOW SEND

Value: 4

Description: Sender is waiting for a window so that it can send buffers.

Name: RX CALL WAIT PACKETS

Value: 8

Description: Sender is waiting for packet buffers.

Name: RX CALL RECEIVE DONE

Value: 16

Description: The call is waiting for a lightweight thread to be assigned to the operation it has just received.

Name: RX CALL RECEIVE DONE

Value: 32

Description: All packets have been received on this call.

Name: RX CALL CLEARED

Value: 64

Description: The receive queue has been cleared when in precall state.

Section 5.2.8: Call Modes

: These values define the modes of an Rx call when it is in the RX STATE ACTIVE state, having a lightweight thread assigned to it.

Name: RX MODE SENDING

Value: 1

Description: We are sending or ready to send.

Name: RX MODE RECEIVING

Value: 2

Description: We are receiving or ready to receive.

Name: RX MODE ERROR

Value: 3

Description: Something went wrong in the current conversation.

Name: RX MODE EOF

Value: 4

Description: The server side has flushed (or the client side has read) the last reply packet.

Section 5.2.9: Packet Header Flags

: Rx packets carry a flag field in their headers, providing additional information regarding the packet's contents. The Rx packet header's flag field's bits may take the following values:

Name: RX CLIENT INITIATED

Value: 1

Description: Signifies that a packet has been sent/received from the client side of the call.

Name: RX REQUEST ACK

Value: 2

Description: The Rx calls' peer entity requests an acknowledgement.

Name: RX LAST PACKET

Value: 4

Description: This is the final packet from this side of the call.

Name: RX MORE PACKETS

Value: 8

Description: There are more packets following this, i.e., the next sequence number seen by the receiver should be greater than this one, rather than a retransmission of an earlier sequence number.

Name: RX PRESET FLAGS

Value: (RX CLIENT INITIATED | RX LAST PACKET)

Description: This flag is preset once per Rx packet. It doesn't change on retransmission of the packet.

Section 5.2.10: Packet Sizes

: These values provide sizing information on the various regions within Rx packets. These packet sections include the IP/UDP headers and bodies as well Rx header and bodies. Also covered are such values as different maximum packet sizes depending on whether they are targeted to peers on the same local network or a more far-flung network. Note that the MTU term appearing below is an abbreviation for Maximum Transmission Unit.

Name: RX IPUDP SIZE

Value: 28

Description: The number of bytes taken up by IP/UDP headers.

Name: RX MAX PACKET SIZE

Value: (1500 - RX IPUDP SIZE)

Description: This is the Ethernet MTU minus IP and UDP header sizes.

Name: RX HEADER SIZE

Value: sizeof (struct rx header)

Description: The number of bytes in an Rx packet header.

Name: RX MAX PACKET DATA SIZE

Value: (RX MAX PACKET SIZE RX - HEADER SIZE)

Description: Maximum size in bytes of the user data in a packet.

Name: RX LOCAL PACKET SIZE

Value: RX MAX PACKET SIZE

Description: Packet size in bytes to use when being sent to a host on the same net.

Name: RX REMOTE PACKET SIZE

Value: (576 - RX IPUDP SIZE)

Description: Packet size in bytes to use when being sent to a host on a different net.

Section 5.2.11: Packet Types

: The following values are used in the packetType field within a struct rx packet, and define the different roles assumed by Rx packets. These roles include user data packets, different flavors of acknowledgements, busies, aborts, authentication challenges and responses, and debugging vehicles.

Name: RX PACKET TYPE DATA

Value: 1

Description: A user data packet.

Name: RX PACKET TYPE ACK

Value: 2

Description: Acknowledgement packet.

Name: RX PACKET TYPE BUSY

Value: 3

Description: Busy packet. The server-side entity cannot accept the call at the moment, but the requestor is encouraged to try again later.

Name: RX PACKET TYPE ABORT

Value: 4

Description: Abort packet. No response is needed for this packet type.

Name: RX PACKET TYPE ACKALL

Value: 5

Description: Acknowledges receipt of all packets on a call.

Name: RX PACKET TYPE CHALLENGE

Value: 6

Description: Challenge the client's identity, requesting credentials.

Name: RX PACKET TYPE RESPONSE

Value: 7

Description: Response to a RX PACKET TYPE CHALLENGE authentication challenge packet.

Name: RX PACKET TYPE DEBUG

Value: 8

Description: Request for debugging information.

Name: RX N PACKET TYPES

Value: 9

Description: The number of Rx packet types defined above. Note that it also includes packet type 0 (which is unused) in the count.

: The RX PACKET TYPES definition provides a mapping of the above values to human-readable string names, and is exported by the rx packetTypes variable catalogued in Section 5.4.9.

 {
        "data", 
        "ack", 
        "busy", 
        "abort", 
        "ackall", 
        "challenge", 
        "response", 
        "debug" 
 }

Section 5.2.12: Packet Classes

: These definitions are used internally to manage alloction of Rx packet buffers according to quota classifications. Each packet belongs to one of the following classes, and its buffer is derived from the corresponding pool.

Name: RX PACKET CLASS RECEIVE

Value: 0

Description: Receive packet for user data.

Name: RX PACKET CLASS SEND

Value: 1

Description: Send packet for user data.

Name: RX PACKET CLASS SPECIAL

Value: 2

Description: A special packet that does not hold user data, such as an acknowledgement or authentication challenge.

Name: RX N PACKET CLASSES

Value: 3

Description: The number of Rx packet classes defined above.

Section 5.2.13: Conditions Prompting Ack Packets

: Rx acknowledgement packets are constructed and sent by the protocol according to the following reasons. These values appear in the Rx packet header of the ack packet itself.

Name: RX ACK REQUESTED

Value: 1

Description: The peer has explicitly requested an ack on this packet.

Name: RX ACK DUPLICATE

Value: 2

Description: A duplicate packet has been received.

Name: RX ACK OUT OF SEQUENCE

Value: 3

Description: A packet has arrived out of sequence.

Name: RX ACK EXCEEDS WINDOW

Value: 4

Description: A packet sequence number higher than maximum value allowed by the call's window has been received.

Name: RX ACK NOSPACE

Value: 5

Description: No packet buffer space is available.

Name: RX ACK PING

Value: 6

Description: Acknowledgement for keep-alive purposes.

Name: RX ACK PING RESPONSE

Value: 7

Description: Response to a RX ACK PING packet.

Name: RX ACK DELAY

Value: 8

Description: An ack generated due to a period of inactivity after normal packet receptions.

: These are the set of values placed into the acks array in an Rx acknowledgement packet, whose data format is defined by struct rx ackPacket. These definitions are used to convey positive or negative acknowledgements for a given range of packets.

Name: RX ACK TYPE NACK

Value: 0

Description: Receiver doesn't currently have the associated packet; it may never hae been received, or received and then later dropped before processing.

Name: RX ACK TYPE ACK

Value: 1

Description: Receiver has the associated packet queued, although it may later decide to discard it.

Section 5.2.15: Error Codes

: Rx employs error codes ranging from -1 to -64. The Rxgen stub generator may use other error codes less than -64. User programs calling on Rx, on the other hand, are expected to return positive error codes. A return value of zero is interpreted as an indication that the given operation completed successfully.

Name: RX CALL DEAD

Value: -1

Description: A connection has been inactive past Rx's tolerance levels and has been shut down.

Name: RX INVALID OPERATION

Value: -2

Description: An invalid operation has been attempted, including such protocol errors as having a client-side call send data after having received the beginning of a reply from its server-side peer.

Name: RX CALL TIMEOUT

Value: -3

Description: The (optional) timeout value placed on this call has been exceeded (see Sections 5.5.3.4 and 5.6.5).

Name: RX EOF

Value: -4

Description: Unexpected end of data on a read operation.

Name: RX PROTOCOL ERROR

Value: -5

Description: An unspecified low-level Rx protocol error has occurred.

Name: RX USER ABORT

Value: -6

Description: A generic user abort code, used when no more specific error code needs to be communicated. For example, Rx clients employing the multicast feature (see Section 1.2.8) take advantage of this error code.

Section 5.2.16: Debugging Values

: Rx provides a set of data collections that convey information about its internal status and performance. The following values have been defined in support of this debugging and statistics-collection feature.

Section 5.2.16.1: Version Information

: Various versions of the Rx debugging/statistics interface are in existance, each defining different data collections and handling certain bugs. Each Rx facility is stamped with a version number of its debugging/statistics interface, allowing its clients to tailor their requests to the precise data collections that are supported by a particular Rx entity, and to properly interpret the data formats received through this interface. All existing Rx implementations should be at revision M.

Name: RX DEBUGI VERSION MINIMUM

Value: 'L'

Description: The earliest version of Rx statistics available.

Name: RX DEBUGI VERSION

Value: 'M'

Description: The latest version of Rx statistics available.

Name: RX DEBUGI VERSION W SECSTATS

Value: 'L'

Description: Identifies the earliest version in which statistics concerning Rx security objects is available.

Name: RX DEBUGI VERSION W GETALLCONN

Value: 'M'

Description: The first version that supports getting information about all current Rx connections, as specified y the RX DEBUGI GETALLCONN debugging request packet opcode described below.

Name: RX DEBUGI VERSION W RXSTATS

Value: 'M'

Description: The first version that supports getting all the Rx statistics in one operation, as specified by the RX DEBUGI RXSTATS debugging request packet opcode described below.

Name: RX DEBUGI VERSION W UNALIGNED CONN

Value: 'L'

Description: There was an alignment problem discovered when returning Rx connection information in older versions of this debugging/statistics interface. This identifies the last version that exhibited this alignment problem.

Section 5.2.16.2: Opcodes

: When requesting debugging/statistics information, the caller specifies one of the following supported data collections:

Name: RX DEBUGI GETSTATS

Value: 1

Description: Get basic Rx statistics.

Name: RX DEBUGI GETCONN

Value: 2

Description: Get information on all Rx connections considered "interesting" (as defined below), and no others.

Name: RX DEBUGI GETALLCONN

Value: 3

Description: Get information on all existing Rx connection structures, even "uninteresting" ones.

Name: RX DEBUGI RXSTATS

Value: 4

Description: Get all available Rx stats.

: An Rx connection is considered "interesting" if it is waiting for a call channel to free up or if it has been marked for destruction. If neither is true, a connection is still considered interesting if any of its call channels is actively handling a call or in its preparatory pre-call state. Failing all the above conditions, a connection is still tagged as interesting if any of its call channels is in either of the RX MODE SENDING or RX MODE RECEIVING modes, which are not allowed when the call is not active.

Section 5.2.16.3: Queuing

: These two queueing-related values indicate whether packets are present on the incoming and outgoing packet queues for a given Rx call. These values are only used in support of debugging and statistics-gathering operations.

Name: RX OTHER IN

Value: 1

Description: Packets available in in queue.

Name: RX OTHER OUT

Value: 2

Description: Packets available in out queue.

Section 5.3: Command Line Interface

This section describes the major exported Rx data structures of interest to application programmers. The following categories are utilized for the purpose of organizing the structure descriptions:

Security objects
Protocol objects
Packet formats
Debugging and statistics
Miscellaneous

: Please note that many fields described in this section are declared to be VOID. This is defined to be char, and is used to get around some compiler limitations.

Section 5.3.1: Security Objects

: As explained in Section 1.2.1, Rx provides a modular, extensible security model. This allows Rx applications to either use one of the built-in security/authentication protocol packages or write and plug in one of their own. This section examines the various structural components used by Rx to support generic security and authentication modules.

Section 5.3.1.1: struct rx securityOps

: As previously described, each Rx security object must export a fixed set of interface functions, providing the full set of operations defined on the object. The rx securityOps structure defines the array of functions comprising this interface. The Rx facility calls these routines at the appropriate times, without knowing the specifics of how any particular security object implements the operation.

: A complete description of these interface functions, including information regarding their exact purpose, parameters, and calling conventions, may be found in Section 5.5.7.

fields

int (*op Close)() - React to the disposal of a security object.
int (*op NewConnection)() - Invoked each time a new Rx connection utilizing the associated security object is created.
int (*op PreparePacket)() - Invoked each time an outgoing Rx packet is created and sent on a connection using the given security object.
int (*op SendPacket)() - Called each time a packet belonging to a call in a connection using the security object is physically transmitted.
int (*op CheckAuthentication)() - This function is executed each time it is necessary to check whether authenticated calls are being perfomed on a connection using the associated security object.
int (*op CreateChallenge)() - Invoked each time a server-side challenge event is created by Rx, namely when the identity of the principal associated with the peer process must be determined.
int (*op GetChallenge)() - Called each time a client-side packet is constructed in response to an authentication challenge.
int (*op GetResponse)() - Executed each time a response to a challenge event must be received on the server side of a connection.
int (*op CheckResponse)() - Invoked each time a response to an authentication has been received, validating the response and pulling out the required authentication information.
int (*op CheckPacket) () - Invoked each time an Rx packet has been received, making sure that the packet is properly formatted and that it hasn't been altered.
int (*op DestroyConnection)() - Called each time an Rx connection employing the given security object is destroyed.
int (*op GetStats)() - Executed each time a request for statistics on the given security object has been received.
int (*op Spare1)()-int (*op Spare3)() - Three spare function slots, reserved for future use.

Section 5.2.1.2: struct rx securityClass

: Variables of type struct rx securityClass are used to represent instantiations of a particular security model employed by Rx. It consists of a pointer to the set of interface operations implementing the given security object, along with a pointer to private storage as necessary to support its operations. These security objects are also reference-counted, tracking the number of Rx connections in existance that use the given security object. If the reference count drops to zero, the security module may garbage-collect the space taken by the unused security object.

fields

struct rx securityOps *ops - Pointer to the array of interface functions for the security object.
VOID *privateData - Pointer to a region of storage used by the security object to support its operations.
int refCount - A reference count on the security object, tracking the number of Rx connections employing this model.

Section 5.3.1.3: struct rx

securityObjectStats

: This structure is used to report characteristics for an instantiation of a security object on a particular Rx connection, as well as performance figures for that object. It is used by the debugging portions of the Rx package. Every security object defines and manages fields such as level and flags differently.

fields

char type - The type of security object being implemented. Existing values are:
0: The null security package.
1: An obsolete Kerberos-like security object.
2: The rxkad discipline (see Chapter 3).
char level - The level at which encryption is utilized.
char sparec[10] - Used solely for alignment purposes.
long flags - Status flags regarding aspects of the connection relating to the security object.
u long expires - Absolute time when the authentication information cached by the given connection expires. A value of zero indicates that the associated authentication information is valid for all time.
u long packetsReceived - Number of packets received on this particular connection, and thus the number of incoming packets handled by the associated security object.
u long packetsSent - Number of packets sent on this particular connection, and thus the number of outgoing packets handled by the associated security object.
u long bytesReceived - Overall number of "payload" bytes received (i.e., packet bytes not associated with IP headers, UDP headers, and the security module's own header and trailer regions) on this connection.
u long bytesSent - Overall number of "payload" bytes sent (i.e., packet bytes not associated with IP headers, UDP headers, and the security module's own header and trailer regions) on this connection.
short spares[4] - Several shortword spares, reserved for future use.
long sparel[8] - Several longword spares, reserved for future use.

Section 5.3.2: Protocol Objects

: The structures describing the main abstractions and entities provided by Rx, namely services, peers, connections and calls are covered in this section.

Section 5.3.2.1: struct rx service

: An Rx-based server exports services, or specific RPC interfaces that accomplish certain tasks. Services are identified by (host-address, UDP-port, serviceID) triples. An Rx service is installed and initialized on a given host through the use of the rx NewService() routine (See Section 5.6.3). Incoming calls are stamped with the Rx service type, and must match an installed service to be accepted. Internally, Rx services also carry string names for purposes of identification. These strings are useful to remote debugging and statistics-gathering programs. The use of a service ID allows a single server process to export multiple, independently-specified Rx RPC services.

: Each Rx service contains one or more security classes, as implemented by individual security objects. These security objects implement end-to-end security protocols. Individual peer-to-peer connections established on behalf of an Rx service will select exactly one of the supported security objects to define the authentication procedures followed by all calls associated with the connection. Applications are not limited to using only the core set of built-in security objects offered by Rx. They are free to define their own security objects in order to execute the specific protocols they require.

: It is possible to specify both the minimum and maximum number of lightweight processes available to handle simultaneous calls directed to an Rx service. In addition, certain procedures may be registered with the service and called at set times in the course of handling an RPC request.

fields

u short serviceId - The associated service number.
u short servicePort - The chosen UDP port for this service.
char *serviceName - The human-readable service name, expressed as a character
string. osi socket socket - The socket structure or file descriptor used by this service.
u short nSecurityObjects - The number of entries in the array of supported security objects.
struct rx securityClass **securityObjects - The array of pointers to the ser vice's security class objects.
long (*executeRequestProc)() - A pointer to the routine to call when an RPC request is received for this service.
VOID (*destroyConnProc)() - A pointer to the routine to call when one of the server-side connections associated with this service is destroyed.
VOID (*newConnProc)() - A pointer to the routine to call when a server-side connection associated with this service is created.
VOID (*beforeProc)() - A pointer to the routine to call before an individual RPC call on one of this service's connections is executed.
VOID (*afterProc)() - A pointer to the routine to call after an individual RPC call on one of this service's connections is executed.
short nRequestsRunning - The number of simultaneous RPC calls currently in progress for this service.
short maxProcs - This field has two meanings. first, maxProcs limits the total number of requests that may execute in parallel for any one service. It also guarantees that this many requests may be handled in parallel if there are no active calls for any other service.
short minProcs - The minimum number of lightweight threads (hence requests) guaranteed to be simultaneously executable.
short connDeadTime - The number of seconds until a client of this service will be declared to be dead, if it is not responding to the RPC protocol.
short idleDeadTime - The number of seconds a server-side connection for this service will wait for packet I/O to resume after a quiescent period before the connection is marked as dead.

Section 5.3.2.2: struct rx connection

: An Rx connection represents an authenticated communication path, allowing multiple asynchronous conversations (calls). Each connection is identified by a connection ID. The low-order bits of the connection ID are reserved so they may be stamped with the index of a particular call channel. With up to RX MAXCALLS concurrent calls (set to 4 in this implementation), the bottom two bits are set aside for this purpose. The connection ID is not sufficient by itself to uniquely identify an Rx connection. Should a client crash and restart, it may reuse a connection ID, causing inconsistent results. In addition to the connection ID, the epoch, or start time for the client side of the connection, is used to identify a connection. Should the above scenario occur, a different epoch value will be chosen by the client, differentiating this incarnation from the orphaned connection record on the server side.

: Each connection is associated with a parent service, which defines a set of supported security models. At creation time, an Rx connection selects the particular security protocol it will implement, referencing the associated service. The connection structure maintains state about the individual calls being simultaneously handled.

fields

struct rx connection *next - Used for internal queueing.
struct rx peer *peer - Pointer to the connection's peer information (see below).
u long epoch - Process start time of the client side of the connection.
u long cid - Connection identifier. The call channel (i.e., the index into the connection's array of call structures) may appear in the bottom bits.
VOID *rock - Pointer to an arbitrary region of memory in support of the connection's operation. The contents of this area are opaque to the Rx facility in general, but are understood by any special routines used by this connection.
struct rx call *call[RX MAXCALLS] - Pointer to the call channel structures, describing up to RX MAXCALLS concurrent calls on this connection.
u long callNumber[RX MAXCALLS] - The set of current call numbers on each of the call channels.
int timeout - Obsolete; no longer used.
u char flags - Various states of the connection; see Section 5.2.4 for individual bit definitions.
u char type - Whether the connection is a server-side or client-side one. See Section 5.2.5 for individual bit definitions.
u short serviceId - The service ID that should be stamped on requests. This field is only used by client-side instances of connection structures.
struct rx service *service - A pointer to the service structure associated with this connection. This field is only used by server-side instances of connection structures.
u long serial - Serial number of the next outgoing packet associated with this connection.
u long lastSerial - Serial number of the last packet received in association with this connection. This field is used in computing packet skew.
u short secondsUntilDead - Maximum numer of seconds of silence that should be tolerated from the connection's peer before calls will be terminated with an RX CALL DEAD error.
u char secondsUntilPing - The number of seconds between "pings" (keep-alive probes) when at least one call is active on this connection.
u char securityIndex - The index of the security object being used by this connection. This number selects a slot in the security class array maintained by the service associated with the connection.
long error - Records the latest error code for calls occurring on this connection.
struct rx securityClass *securityObject - A pointer to the security object used by this connection. This should coincide with the slot value chosen by the securityIndex field described above.
VOID *securityData - A pointer to a region dedicated to hosting any storage required by the security object being used by this connection.
u short securityHeaderSize - The length in bytes of the portion of the packet header before the user's data that contains the security module's information.
u short securityMaxTrailerSize - The length in bytes of the packet trailer, appearing after the user's data, as mandated by the connection's security module.
struct rxevent *challengeEvent -Pointer to an event that is scheduled when the server side of the connection is challenging the client to authenticate itself.
int lastSendTime - The last time a packet was sent on this connection.
long maxSerial - The largest serial number seen on incoming packets.
u short hardDeadTime - The maximum number of seconds that any call on this connection may execute. This serves to throttle runaway calls.

Section 5.3.2.3: struct rx peer

: For each connection, Rx maintains information describing the entity, or peer, on the other side of the wire. A peer is identified by a (host, UDP-port) pair. Included in the information kept on this remote communication endpoint are such network parameters as the maximum packet size supported by the host, current readings on round trip time to retransmission delays, and packet skew (see Section 1.2.7). There are also congestion control fields, ranging from descriptions of the maximum number of packets that may be sent to the peer without pausing and retransmission statistics. Peer structures are shared between connections whenever possible, and hence are reference-counted. A peer object may be garbage-collected if it is not actively referenced by any connection structure and a sufficient period of time has lapsed since the reference count dropped to zero.

fields

struct rx peer *next - Use to access internal lists.
u long host - Remote IP address, in network byte order
u short port - Remote UDP port, in network byte order
short packetSize - Maximum packet size for this host, if known.
u long idleWhen - When the refCount reference count field (see below) went to zero.
short refCount - Reference count for this structure
u char burstSize - Reinitialization size for the burst field (below).
u char burst - Number of packets that can be transmitted immediately without pausing.
struct clock burstWait - Time delay until new burst aimed at this peer is allowed.
struct queue congestionQueue - Queue of RPC call descriptors that are waiting for a non-zero burst value.
int rtt - Round trip time to the peer, measured in milliseconds.
struct clock timeout - Current retransmission delay to the peer.
int nSent - Total number of distinct data packets sent, not including retransmissions.
int reSends - Total number of retransmissions for this peer since the peer structure instance was created.
u long inPacketSkew - Maximum skew on incoming packets (see Section 1.2.7)
u long outPacketSkew - Peer-reported maximum skew on outgoing packets (see Section 1.2.7).

Section 5.3.2.4: struct rx call

: This structure records the state of an active call proceeding on a given Rx connection. As described above, each connection may have up to RX MAXCALLS calls active at any one instant, and thus each connection maintains an array of RX MAXCALLS rx call structures. The information contained here is specific to the given call; "permanent" call state, such as the call number, is maintained in the connection structure itself.

fields

struct queue queue item header - Queueing information for this structure.
struct queue tq - Queue of outgoing ("transmit") packets.
struct queue rq - Queue of incoming ("receive") packets.
char *bufPtr - Pointer to the next byte to fill or read in the call's current packet, depending on whether it is being transmitted or received.
u short nLeft - Number of bytes left to read in the first packet in the reception queue (see field rq).
u short nFree - Number of bytes still free in the last packet in the transmission queue (see field tq).
struct rx packet *currentPacket - Pointer to the current packet being assembled or read.
struct rx connection *conn - Pointer to the parent connection for this call.
u long *callNumber - Pointer to call number field within the call's current packet.
u char channel - Index within the parent connection's call array that describes this call.
u char dummy1, dummy2 - These are spare fields, reserved for future use.
u char state - Current call state. The associated bit definitions appear in Section 5.2.7.
u char mode - Current mode of a call that is in RX STATE ACTIVE state. The associated bit definitions appear in Section 5.2.8.
u char flags - Flags pertaining to the state of the given call. The associated bit definitions appear in Section 5.2.7.
u char localStatus - Local user status information, sent out of band. This field is currently not in use, set to zero.
u char remoteStatus - Remote user status information, received out of band. This field is currently not in use, set to zero.
long error - Error condition for this call.
u long timeout - High level timeout for this call
u long rnext - Next packet sequence number expected to be received.
u long rprev - Sequence number of the previous packet received. This number is used to decide the proper sequence number for the next packet to arrive, and may be used to generate a negative acknowledgement.
u long rwind - Width of the packet receive window for this call. The peer must not send packets with sequence numbers greater than or equal to rnext + rwind.
u long tfirst - Sequence number of the first unacknowledged transmit packet for this call.
u long tnext - Next sequence number to use for an outgoing packet.
u long twind - Width of the packet transmit window for this call. Rx cannot assign a sequence number to an outgoing packet greater than or equal to tfirst + twind.
struct rxevent *resendEvent - Pointer to a pending retransmission event, if any.
struct rxevent *timeoutEvent - Pointer to a pending timeout event, if any.
struct rxevent *keepAliveEvent - Pointer to a pending keep-alive event, if this is an active call.
struct rxevent *delayedAckEvent - Pointer to a pending delayed acknowledgement packet event, if any. Transmission of a delayed acknowledgement packet is scheduled after all outgoing packets for a call have been sent. If neither a reply nor a new call are received by the time the delayedAckEvent activates, the ack packet will be sent.
int lastSendTime - Last time a packet was sent for this call.
int lastReceiveTime - Last time a packet was received for this call.
VOID (*arrivalProc)() - Pointer to the procedure to call when reply is received.
VOID *arrivalProcHandle - Pointer to the handle to pass to the arrivalProc as its first argument.
VOID *arrivalProcArg - Pointer to an additional argument to pass to the given arrivalProc.
u long lastAcked - Sequence number of the last packet "hard-acked" by the receiver. A packet is considered to be hard-acked if an acknowledgement is generated after the reader has processed it. The Rx facility may sometimes "soft-ack" a windowfull of packets before they have been picked up by the receiver.
u long startTime - The time this call started running.
u long startWait - The time that a server began waiting for input data or send quota.

Section 5.3.3: Packet Formats

: The following sections cover the different data formats employed by the suite of Rx packet types, as enumerated in Section 5.2.11. A description of the most commonly-employed Rx packet header appears first, immediately followed by a description of the generic packet container and descriptor. The formats for Rx acknowledgement packets and debugging/statistics packets are also examined.

Section 5.3.3.1: struct rx header

: Every Rx packet has its own header region, physically located after the leading IP/UDP headers. This header contains connection, call, security, and sequencing information. Along with a type identifier, these fields allow the receiver to properly interpret the packet. In addition, every client relates its "epoch", or Rx incarnation date, in each packet. This assists in identifying protocol problems arising from reuse of connection identifiers due to a client restart. Also included in the header is a byte of user-defined status information, allowing out-of-band channel of communication for the higher-level application using Rx as a transport mechanism.

fields

u long epoch - Birth time of the client Rx facility.
u long cid - Connection identifier, as defined by the client. The last RX CIDSHIFT bits in the cid field identify which of the server-side RX MAXCALLS call channels is to receive the packet.
u long callNumber - The current call number on the chosen call channel.
u long seq - Sequence number of this packet. Sequence numbers start with 0 for each new Rx call.
u long serial - This packet's serial number. A new serial number is stamped on each packet transmitted (or retransmitted).
u char type - What type of Rx packet this is; see Section 5.2.11 for the list of legal definitions.
u char flags - Flags describing this packet; see Section 5.2.9 for the list of legal settings.
u char userStatus - User-defined status information, uninterpreted by the Rx facility itself. This field may be easily set or retrieved from Rx packets via calls to the rx GetLocalStatus(), rx SetLocalStatus(), rx GetRemoteStatus(), and rx SetRemoteStatus() macros.
u char securityIndex - Index in the associated server-side service class of the security object used by this call.
u short serviceId - The server-provided service ID to which this packet is directed.
u short spare - This field was originally a true spare, but is now used by the built-in rxkad security module for packet header checksums. See the descriptions of the related rx IsUsingPktChecksum(), rx GetPacketCksum(), and rx SetPacketCksum() macros.

Section 5.3.3.2: struct rx packet

: This structure is used to describe an Rx packet, and includes the wire version of the packet contents, where all fields exist in network byte order. It also includes acknowledgement, length, type, and queueing information.

fields

struct queue queueItemHeader - field used for internal queueing.
u char acked - If non-zero, this field indicates that this packet has been tentatively (soft-) acknowledged. Thus, the packet has been accepted by the rx peer entity on the other side of the connection, but has not yet necessarily been passed to the true reader. The sender is not free to throw the packet away, as it might still get dropped by the peer before it is delivered to its destination process.
short length - Length in bytes of the user data section.
u char packetType - The type of Rx packet described by this record. The set of legal choices is available in Section 5.2.11.
struct clock retryTime - The time when this packet should be retransmitted next.
struct clock timeSent - The last time this packet was transmitted.
struct rx header header - A copy of the internal Rx packet header.
wire - The text of the packet as it appears on the wire. This structure has the following sub-fields:
u long head[RX HEADER SIZE/sizeof(long)] The wire-level contents of IP, UDP, and Rx headers.
u long data[RX MAX PACKET DATA SIZE/sizeof(long)] The wire form of the packet's "payload", namely the user data it carries.

Section 5.3.3.3: struct rx ackPacket

: This is the format for the data portion of an Rx acknowledgement packet, used to inform a peer entity performing packet transmissions that a subset of its packets has been properly received.

fields

u short bufferSpace - Number of packet buffers available. Specifically, the number of packet buffers that the ack packet's sender is willing to provide for data on this or subsequent calls. This number does not have to fully accurate; it is acceptable for the sender to provide an estimate.
u short maxSkew - The maximum difference seen between the serial number of the packet being acknowledged and highest packet yet received. This is an indication of the degree to which packets are arriving out of order at the receiver.
u long firstPacket - The serial number of the first packet in the list of acknowledged packets, as represented by the acks field below.
u long previousPacket - The previous packet serial number received.
u long serial - The serial number of the packet prompted the acknowledgement.
u char reason - The reason given for the acknowledgement; legal values for this field are described in Section 5.2.13.
u char nAcks - Number of acknowledgements active in the acks array immediately following.
u char acks[RX MAXACKS] - Up to RX MAXACKS packet acknowledgements. The legal values for each slot in the acks array are described in Section 5.2.14. Basically, these fields indicate either positive or negative acknowledgements.

: All packets with serial numbers prior to firstPacket are implicitly acknowledged by this packet, indicating that they have been fully processed by the receiver. Thus, the sender need no longer be concerned about them, and may release all of the resources that they occupy. Packets with serial numbers firstPacket + nAcks and higher are not acknowledged by this ack packet. Packets with serial numbers in the range [firstPacket, firstPacket + nAcks) are explicitly acknowledged, yet their sender-side resources must not yet be released, as there is yet no guarantee that the receiver will not throw them away before they can be processed there.

: There are some details of importance to be noted. For one, receiving a positive acknowlegement via the acks array does not imply that the associated packet is immune from being dropped before it is read and processed by the receiving entity. It does, however, imply that the sender should stop retransmitting the packet until further notice. Also, arrival of an ack packet should prompt the transmitter to immediately retransmit all packets it holds that have not been explicitly acknowledged and that were last transmitted with a serial number less than the highest serial number acknowledged by the acks array. Note: The fields in this structure are always kept in wire format, namely in network byte order.

Section 5.3.4: Debugging and Statistics

: The following structures are defined in support of the debugging and statistics-gathering interfaces provided by Rx.

Section 5.3.4.1: struct rx stats

: This structure maintains Rx statistics, and is gathered by such tools as the rxdebug program. It must be possible for all of the fields placed in this structure to be successfully converted from their on-wire network byte orderings to the host-specific ordering.

fields

int packetRequests - Number of packet allocation requests processed.
int noPackets[RX N PACKET CLASSES] - Number of failed packet requests, organized per allocation class.
int socketGreedy - Whether the SO GREEDY setting succeeded for the Rx socket.
int bogusPacketOnRead - Number of inappropriately short packets received.
int bogusHost - Contains the host address from the last bogus packet received.
int noPacketOnRead - Number of attempts to read a packet off the wire when there was actually no packet there.
int noPacketBuffersOnRead - Number of dropped data packets due to lack of packet buffers.
int selects - Number of selects waiting for a packet arrival or a timeout.
int sendSelects - Number of selects forced when sending packets.
int packetsRead[RX N PACKET TYPES] - Total number of packets read, classified by type.
int dataPacketsRead - Number of unique data packets read off the wire.
int ackPacketsRead - Number of ack packets read.
int dupPacketsRead - Number of duplicate data packets read.
int spuriousPacketsRead - Number of inappropriate data packets.
int packetsSent[RX N PACKET TYPES] - Number of packet transmissions, broken down by packet type.
int ackPacketsSent - Number of ack packets sent.
int pingPacketsSent - Number of ping packets sent.
int abortPacketsSent - Number of abort packets sent.
int busyPacketsSent - Number of busy packets sent.
int dataPacketsSent - Number of unique data packets sent.
int dataPacketsReSent - Number of retransmissions.
int dataPacketsPushed - Number of retransmissions pushed early by a negative acknowledgement.
int ignoreAckedPacket - Number of packets not retransmitted because they have already been acked.
int struct clock totalRtt - Total round trip time measured for packets, used to compute average time figure.
struct clock minRtt - Minimum round trip time measured for packets. struct clock maxRtt - Maximum round trip time measured for packets.
int nRttSamples - Number of round trip samples.
int nServerConns - Number of server connections.
int nClientConns - Number of client connections.
int nPeerStructs - Number of peer structures.
int nCallStructs - Number of call structures physically allocated (using the internal storage allocator routine).
int nFreeCallStructs - Number of call structures which were pulled from the free queue, thus avoiding a call to the internal storage allocator routine.
int spares[10] - Ten integer spare fields, reserved for future use.

Section 5.3.4.2: struct rx debugIn

: This structure defines the data format for a packet requesting one of the statistics collections maintained by Rx.

fields

long type - The specific data collection that the caller desires. Legal settings for this field are described in Section 5.2.16.2.
long index - This field is only used when gathering information on Rx connections. Choose the index of the server-side connection record of which we are inquiring. This field may be used as an iterator, stepping through all the connection records, one per debugging request, until they have all been examined.

Section 5.3.4.3: struct rx debugStats

: This structure describes the data format for a reply to an RX DEBUGI GETSTATS debugging request packet. These fields are given values indicating the current state of the Rx facility.

fields

long nFreePackets - Number of packet buffers currently assigned to the free pool.
long packetReclaims - Currently unused.
long callsExecuted - Number of calls executed since the Rx facility was initialized.
char waitingForPackets - Is Rx currently blocked waiting for a packet buffer to come free?
char usedFDs - If the Rx facility is executing in the kernel, return the number of unix file descriptors in use. This number is not directly related to the Rx package, but rather describes the state of the machine on which Rx is running.
char version - Version number of the debugging package.
char spare1[1] - Byte spare, reserved for future use.
long spare2[10] - Set of 10 longword spares, reserved for future use.

Section 5.3.4.4: struct rx debugConn

: This structure defines the data format returned when a caller requests information concerning an Rx connection. Thus, rx debugConn defines the external packaging of interest to external parties. Most of these fields are set from the rx connection structure, as defined in Section 5.3.2.2, and others are obtained by indirecting through such objects as the connection's peer and call structures.

fields

long host - Address of the host identified by the connection's peer structure.
long cid - The connection ID.
long serial - The serial number of the next outgoing packet associated with this connection.
long callNumber[RX MAXCALLS] - The current call numbers for the individual call channels on this connection.
long error - Records the latest error code for calls occurring on this connection.
short port - UDP port associated with the connection's peer.
char flags - State of the connection; see Section 5.2.4 for individual bit definitions.
char type - Whether the connection is a server-side or client-side one. See Section 5.2.5 for individual bit definitions.
char securityIndex - Index in the associated server-side service class of the security object being used by this call.
char sparec[3] - Used to force alignment for later fields.
char callState[RX MAXCALLS] - Current call state on each call channel. The associated bit definitions appear in Section 5.2.7.
char callMode[RX MAXCALLS] - Current mode of all call channels that are in RX STATE ACTIVE state. The associated bit definitions appear in Section 5.2.8.
char callFlags[RX MAXCALLS] - Flags pertaining to the state of each of the connection's call channels. The associated bit definitions appear in Section 5.2.7.
char callOther[RX MAXCALLS] - Flag field for each call channel, where the presence of the RX OTHER IN flag indicates that there are packets present on the given call's reception queue, and the RX OTHER OUT flag indicates the presence of packets on the transmission queue.
struct rx securityObjectStats secStats - The contents of the statistics related to the security object selected by the securityIndex field, if any.
long epoch - The connection's client-side incarnation time.
long sparel[10] - A set of 10 longword fields, reserved for future use.

Section 5.3.4.5: struct rx debugConn vL

: This structure is identical to rx debugConn defined above, except for the fact that it is missing the sparec field. This sparec field is used in rx debugConn to fix an alignment problem that was discovered in version L of the debugging/statistics interface (hence the trailing "tt vL tag in the structure name). This alignment problem is fixed in version M, which utilizes and exports the rx debugConn structure exclusively. Information regarding the range of version-numbering values for the Rx debugging/statistics interface may be found in Section 5.2.16.1.

Section 5.4: Exported Variables

: This section describes the set of variables that the Rx facility exports to its applications. Some of these variables have macros defined for the sole purpose of providing the caller with a convenient way to manipulate them. Note that some of these exported variables are never meant to be altered by application code (e.g., rx nPackets).

Section 5.4.1: rx connDeadTime

: This integer-valued variable determines the maximum number of seconds that a connection may remain completely inactive, without receiving packets of any kind, before it is eligible for garbage collection. Its initial value is 12 seconds. The rx SetRxDeadTime macro sets the value of this variable.

Section 5.4.2: rx idleConnectionTime

: This integer-valued variable determines the maximum number of seconds that a server connection may "idle" (i.e., not have any active calls and otherwise not have sent a packet) before becoming eligible for garbage collection. Its initial value is 60 seconds.

Section 5.4.3: rx idlePeerTime

: This integer-valued variable determines the maximum number of seconds that an Rx peer structure is allowed to exist without any connection structures referencing it before becoming eligible for garbage collection. Its initial value is 60 seconds.

Section 5.4.4: rx extraQuota

: This integer-valued variable is part of the Rx packet quota system (see Section 1.2.6), which is used to avoid system deadlock. This ensures that each server-side thread has a minimum number of packets at its disposal, allowing it to continue making progress on active calls. This particular variable records how many extra data packets a user has requested be allocated. Its initial value is 0.

Section 5.4.5: rx extraPackets

: This integer-valued variable records how many additional packet buffers are to be created for each Rx server thread. The caller, upon setting this variable, is applying some application-specific knowledge of the level of network activity expected. The rx extraPackets variable is used to compute the overall number of packet buffers to reserve per server thread, namely rx nPackets, described below. The initial value is 32 packets.

Section 5.4.6: rx nPackets

: This integer-valued variable records the total number of packet buffers to be allocated per Rx server thread. It takes into account the quota packet buffers and the extra buffers requested by the caller, if any.

Note:: This variable should never be set directly; the Rx facility itself computes its value. Setting it incorrectly may result in the service becoming deadlocked due to insufficient resources. Callers wishing to allocate more packet buffers to their server threads should indicate that desire by setting the rx extraPackets variable described above.

Section 5.4.7: rx nFreePackets

: This integer-valued variable records the number of Rx packet buffers not currently used by any call. These unused buffers are collected into a free pool.

Section 5.4.8: rx stackSize

: This integer-valued variable records the size in bytes for the lightweight process stack. The variable is initially set to RX DEFAULT STACK SIZE, and is typically manipulated via the rx SetStackSize() macro.

Section 5.4.9: rx packetTypes

: This variable holds an array of string names used to describe the different roles for Rx packets. Its value is derived from the RX PACKET TYPES definition found in Section 5.2.11.

Section 5.4.10: rx stats

: This variable contains the statistics structure that keeps track of Rx statistics. The struct rx stats structure it provides is defined in Section 5.3.4.1.

Section 5.5: Macros

Rx uses many macro definitions in preference to calling C functions directly. There are two main reasons for doing this:

field selection: Many Rx operations are easily realized by returning the value of a particular structure's field. It is wasteful to invoke a C routine to simply fetch a structure's field, incurring unnecessary function call overhead. Yet, a convenient, procedure-oriented operation is still provided to Rx clients for such operations by the use of macros. For example, the rx ConnectionOf() macro, described in Section 5.5.1.1, simply indirects through the Rx call structure pointer parameter to deliver the conn field.
Performance optimization: In some cases, a simple test or operation can be performed to accomplish a particular task. When this simple, straightforward operation fails, then a true C routine may be called to handle to more complex (and rarer) situation. The Rx macro rx Write(), described in Section 5.5.6.2, is a perfect example of this type of optimization. Invoking rx Write() first checks to determine whether or not the outgoing call's internal buffer has enough room to accept the specified data bytes. If so, it copies them into the call's buffer, updating counts and pointers as appropriate. Otherwise, rx Write() calls the rx WriteProc() to do the work, which in this more complicated case involves packet manipulations, dispatches, and allocations. The result is that the common, simple cases are often handled in-line, with more complex (and rarer) cases handled through true function invocations.

The set of Rx macros is described according to the following categories.

field selections/assignments
Boolean operations
Service attributes
Security-related operations
Sizing operations
Complex operation
Security operation invocations

Section 5.5.1: field Selections/Assignments

: These macros facilitate the fetching and setting of fields from the structures described Chapter 5.3.

Section 5.5.1.1: rx ConnectionOf()

: #define rx_ConnectionOf(call) ((call)->conn)

: Generate a reference to the connection field within the given Rx call structure. The value supplied as the call argument must resolve into an object of type (struct rx call *). An application of the rx ConnectionOf() macro itself yields an object of type rx peer.

Section 5.5.1.2: rx PeerOf()

: #define rx_PeerOf(conn) ((conn)->peer)

: Generate a reference to the peer field within the given Rx call structure. The value supplied as the conn argument must resolve into an object of type (struct rx connection *). An instance of the rx PeerOf() macro itself resolves into an object of type rx peer.

Section 5.5.1.3: rx HostOf()

: #define rx_HostOf(peer) ((peer)->host)

: Generate a reference to the host field within the given Rx peer structure. The value supplied as the peer argument must resolve into an object of type (struct rx peer *). An instance of the rx HostOf() macro itself resolves into an object of type u long.

Section 5.5.1.4: rx PortOf()

: #define rx_PortOf(peer) ((peer)->port)

: Generate a reference to the port field within the given Rx peer structure. The value supplied as the peer argument must resolve into an object of type (struct rx peer *). An instance of the rx PortOf() macro itself resolves into an object of type u short.

Section 5.5.1.5: rx GetLocalStatus()

: #define rx_GetLocalStatus(call, status) ((call)->localStatus)

: Generate a reference to the localStatus field, which specifies the local user status sent out of band, within the given Rx call structure. The value supplied as the call argument must resolve into an object of type (struct rx call *). The second argument, status, is not used. An instance of the rx GetLocalStatus() macro itself resolves into an object of type u char.

Section 5.5.1.6: rx SetLocalStatus()

: #define rx_SetLocalStatus(call, status) ((call)->localStatus = (status))

: Assign the contents of the localStatus field, which specifies the local user status sent out of band, within the given Rx call structure. The value supplied as the call argument must resolve into an object of type (struct rx call *). The second argument, status, provides the new value of the localStatus field, and must resolve into an object of type u char. An instance of the rx GetLocalStatus() macro itself resolves into an object resulting from the assignment, namely the u char status parameter.

Section 5.5.1.7: rx GetRemoteStatus()

: #define rx_GetRemoteStatus(call) ((call)->remoteStatus)

: Generate a reference to the remoteStatus field, which specifies the remote user status received out of band, within the given Rx call structure. The value supplied as the call argument must resolve into an object of type (struct rx call *). An instance of the rx GetRemoteStatus() macro itself resolves into an object of type u char.

Section 5.5.1.8: rx Error()

: #define rx_Error(call) ((call)->error)

: Generate a reference to the error field, which specifies the current error condition, within the given Rx call structure. The value supplied as the call argument must resolve into an object of type (struct rx call *). An instance of the rx Error() macro itself resolves into an object of type long.

Section 5.5.1.9: rx DataOf()

: #define rx_DataOf(packet) ((char *) (packet)->wire.data)

: Generate a reference to the beginning of the data portion within the given Rx packet as it appears on the wire. Any encryption headers will be resident at this address. For Rx packets of type RX PACKET TYPE DATA, the actual user data will appear at the address returned by the rx DataOf macro plus the connection's security header size. The value supplied as the packet argument must resolve into an object of type (struct rx packet *). An instance of the rx DataOf() macro itself resolves into an object of type (u long *).

Section 5.5.1.10: rx GetDataSize()

: #define rx_GetDataSize(packet) ((packet)->length)

: Generate a reference to the length field, which specifies the number of bytes of user data contained within the wire form of the packet, within the given Rx packet description structure. The value supplied as the packet argument must resolve into an object of type (struct rx packet *). An instance of the rx GetDataSize() macro itself resolves into an object of type short.

Section 5.5.1.11: rx SetDataSize()

: #define rx_SetDataSize(packet, size) ((packet)->length = (size))

: Assign the contents of the length field, which specifies the number of bytes of user data contained within the wire form of the packet, within the given Rx packet description structure. The value supplied as the packet argument must resolve into an object of type (struct rx packet *). The second argument, size, provides the new value of the length field, and must resolve into an object of type short. An instance of the rx SetDataSize() macro itself resolves into an object resulting from the assignment, namely the short length parameter.

Section 5.5.1.12: rx GetPacketCksum()

: #define rx_GetPacketCksum(packet) ((packet)->header.spare)

: Generate a reference to the header checksum field, as used by the built-in rxkad security module (See Chapter 3), within the given Rx packet description structure. The value supplied as the packet argument must resolve into an object of type (struct rx packet *). An instance of the rx GetPacketCksum() macro itself resolves into an object of type u short.

Section 5.5.1.13: rx SetPacketCksum()

: #define rx_SetPacketCksum(packet, cksum) ((packet)->header.spare = (cksum))

: Assign the contents of the header checksum field, as used by the built-in rxkad security module (See Chapter 3), within the given Rx packet description structure. The value supplied as the packet argument must resolve into an object of type (struct rx packet *). The second argument, cksum, provides the new value of the checksum, and must resolve into an object of type u short. An instance of the rx SetPacketCksum() macro itself resolves into an object resulting from the assignment, namely the u short checksum parameter.

Section 5.5.1.14: rx GetRock()

: #define rx_GetRock(obj, type) ((type)(obj)->rock)

: Generate a reference to the field named rock within the object identified by the obj pointer. One common Rx structure to which this macro may be applied is struct rx connection. The specified rock field is casted to the value of the type parameter, which is the overall value of the rx GetRock() macro.

Section 5.5.1.15: rx SetRock()

: #define rx_SetRock(obj, newrock) ((obj)->rock = (VOID *)(newrock))

: Assign the contents of the newrock parameter into the rock field of the object pointed to by obj. The given object's rock field must be of type (VOID *). An instance of the rx SetRock() macro itself resolves into an object resulting from the assignment and is of type (VOID *).

Section 5.5.1.16: rx SecurityClassOf()

: #define rx_SecurityClassOf(conn) ((conn)->securityIndex)

: Generate a reference to the security index field of the given Rx connection description structure. This identifies the security class used by the connection. The value supplied as the conn argument must resolve into an object of type (struct rx connection *). An instance of the rx SecurityClassOf() macro itself resolves into an object of type u char.

Section 5.5.1.17: rx SecurityObjectOf()

: #define rx_SecurityObjectOf(conn) ((conn)->securityObject)

: Generate a reference to the security object in use by the given Rx connection description structure. The choice of security object determines the authentication protocol enforced by the connection. The value supplied as the conn argument must resolve into an object of type (struct rx connection *). An instance of the rx SecurityObjectOf() macro itself resolves into an object of type (struct rx securityClass *).

Section 5.5.2: Boolean Operations

: The macros described in this section all return Boolean values. They are used to query such things as the whether a connection is a server-side or client-side one and if extra levels of checksumming are being used in Rx packet headers.

Section 5.5.2.1: rx IsServerConn()

: #define rx_IsServerConn(conn) ((conn)->type == RX_SERVER_CONNECTION)

: Determine whether or not the Rx connection specified by the conn argument is a server-side connection. The value supplied for conn must resolve to an object of type struct rx connection. The result is determined by testing whether or not the connection's type field is set to RX SERVER CONNECTION.

Note:: Another macro, rx ServerConn(), performs the identical operation.

Section 5.5.2.2: rx IsClientConn()

: #define rx_IsClientConn(conn) ((conn)->type == RX_CLIENT_CONNECTION)

: Determine whether or not the Rx connection specified by the conn argument is a client-side connection. The value supplied for conn must resolve to an object of type struct rx connection. The result is determined by testing whether or not the connection's type field is set to RX CLIENT CONNECTION.

Note:: Another macro, rx ClientConn(), performs the identical operation.

Section 5.5.2.2: rx IsUsingPktCksum()

: #define rx_IsUsingPktCksum(conn) ((conn)->flags & RX_CONN_USING_PACKET_CKSUM)

: Determine whether or not the Rx connection specified by the conn argument is checksum-ming the headers of all packets on its calls. The value supplied for conn must resolve to an object of type struct rx connection. The result is determined by testing whether or not the connection's flags field has the RX CONN USING PACKET CKSUM bit enabled.

Section 5.5.3: Service Attributes

: This section describes user-callable macros that manipulate the attributes of an Rx service. Note that these macros must be called (and hence their operations performed) before the given service is installed via the appropriate invocation of the associated rx StartServer() function.

Section 5.5.3.1: rx SetStackSize()

: rx_stackSize = (((stackSize) stackSize) > rx_stackSize) ? stackSize : rx_stackSize)

: Inform the Rx facility of the stack size in bytes for a class of threads to be created in support of Rx services. The exported rx stackSize variable tracks the high-water mark for all stack size requests before the call to rx StartServer(). If no calls to rx SetStackSize() are made, then rx stackSize will retain its default setting of RX DEFAULT STACK SIZE.

: In this macro, the first argument is not used. It was originally intended that thread stack sizes would be settable on a per-service basis. However, calls to rx SetStackSize() will ignore the service parameter and set the high-water mark for all Rx threads created after the use of rx SetStackSize(). The second argument, stackSize, specifies determines the new stack size, and should resolve to an object of type int. The value placed in the stackSize parameter will not be recorded in the global rx stackSize variable unless it is greater than the variable's current setting.

: An instance of the rx SetStackSize() macro itself resolves into the result of the assignment, which is an object of type int.

Section 5.5.3.2: rx SetMinProcs()

: #define rx_SetMinProcs(service, min) ((service)->minProcs = (min))

: Choose min as the minimum number of threads guaranteed to be available for parallel execution of the given Rx service. The service parameter should resolve to an object of type struct rx service. The min parameter should resolve to an object of type short. An instance of the rx SetMinProcs() macro itself resolves into the result of the assignment, which is an object of type short.

Section 5.5.3.3: rx SetMaxProcs()

: #define rx_SetMaxProcs(service, max) ((service)->maxProcs = (max))

: Limit the maximum number of threads that may be made available to the given Rx service for parallel execution to be max. The service parameter should resolve to an object of type struct rx service. The max parameter should resolve to an object of type short. An instance of the rx SetMaxProcs() macro itself resolves into the result of the assignment, which is an object of type short.

Section 5.5.3.4: rx SetIdleDeadTime()

: #define rx_SetIdleDeadTime(service, time) ((service)->idleDeadTime = (time))

: Every Rx service has a maximum amount of time it is willing to have its active calls sit idle (i.e., no new data is read or written for a call marked as RX STATE ACTIVE) before unilaterally shutting down the call. The expired call will have its error field set to RX CALL TIMEOUT. The operative assumption in this situation is that the client code is exhibiting a protocol error that prevents progress from being made on this call, and thus the call's resources on the server side should be freed. The default value, as recorded in the service's idleDeadTime field, is set at service creation time to be 60 seconds. The rx SetIdleTime() macro allows a caller to dynamically set this idle call timeout value.

: The service parameter should resolve to an object of type struct rx service. Also, the time parameter should resolve to an object of type short. finally, an instance of the rx SetIdleDeadTime() macro itself resolves into the result of the assignment, which is an object of type short.

Section 5.5.3.5: rx SetServiceDeadTime()

: #define rx_SetServiceDeadTime(service, seconds) ((service)->secondsUntilDead = (seconds))

Note:: This macro definition is obsolete and should NOT be used. Including it in application code will generate a compile-time error, since the service structure no longer has such a field defined.

: See the description of the rx SetConnDeadTime() macro below to see how hard timeouts may be set for situations of complete call inactivity.

Section 5.5.3.6: rx SetRxDeadTime()

: #define rx_SetRxDeadTime(seconds) (rx_connDeadTime = (seconds))

: Inform the Rx facility of the maximum number of seconds of complete inactivity that will be tolerated on an active call. The exported rx connDeadTime variable tracks this value, and is initialized to a value of 12 seconds. The current value of rx connDeadTime will be copied into new Rx service and connection records upon their creation.

: The seconds argument determines the value of rx connDeadTime, and should resolve to an object of type int. An instance of the rx SetRxDeadTime() macro itself resolves into the result of the assignment, which is an object of type int.

Section 5.5.3.7: rx SetConnDeadTime()

: #define rx_SetConnDeadTime(conn, seconds) (rxi_SetConnDeadTime(conn, seconds))

: Every Rx connection has a maximum amount of time it is willing to have its active calls on a server connection sit without receiving packets of any kind from its peer. After such a quiescent time, during which neither data packets (regardless of whether they are properly sequenced or duplicates) nor keep-alive packets are received, the call's error field is set to RX CALL DEAD and the call is terminated. The operative assumption in this situation is that the client making the call has perished, and thus the call's resources on the server side should be freed. The default value, as recorded in the connection's secondsUntilDead field, is set at connection creation time to be the same as its parent service. The rx SetConnDeadTime() macro allows a caller to dynamically set this timeout value.

: The conn parameter should resolve to an object of type struct rx connection. Also, the seconds parameter should resolve to an object of type int. finally, an instance of the rx SetConnDeadTime() macro itself resolves into the a call to rxi SetConnDeadTime(), whose return value is void.

Section 5.5.3.8: rx SetConnHardDeadTime()

: #define rx_SetConnHardDeadTime(conn, seconds) ((conn)->hardDeadTime = (seconds))

: It is convenient to be able to specify that calls on certain Rx connections have a hard absolute timeout. This guards against protocol errors not caught by other checks in which one or both of the client and server are looping. The rx SetConnHardDeadTime() macro is available for this purpose. It will limit calls on the connection identified by the conn parameter to execution times of no more than the given number of seconds. By default, active calls on an Rx connection may proceed for an unbounded time, as long as they are not totally quiescent (see Section 5.5.3.7 for a description of the rx SetConnDeadTime()) or idle (see Section 5.5.3.4 for a description of the rx SetIdleDeadTime()).

: The conn parameter should resolve to an object of type (struct rx connection *). The seconds parameter should resolve to an object of type u short. An instance of the rx SetConnHardDeadTime() macro itself resolves into the result of the assignment, which is an object of type u short.

Section 5.5.3.9: rx GetBeforeProc()

: #define rx_GetBeforeProc(service) ((service)->beforeProc)

: Return a pointer of type (VOID *)() to the procedure associated with the given Rx service that will be called immediately upon activation of a server thread to handle an incoming call. The service parameter should resolve to an object of type struct rx service.

: When an Rx service is first created (via a call to the rx NewService() function), its beforeProc field is set to a null pointer. See the description of the rx SetBeforeProc() below.

Section 5.5.3.10: rx SetBeforeProc()

: #define rx_SetBeforeProc(service, proc) ((service)->beforeProc = (proc))

: Instruct the Rx facility to call the procedure identified by the proc parameter immediately upon activation of a server thread to handle an incoming call. The specified procedure will be called with a single parameter, a pointer of type struct rx call, identifying the call this thread will now be responsible for handling. The value returned by the procedure, if any, is discarded.

: The service parameter should resolve to an object of type struct rx service. The proc parameter should resolve to an object of type (VOID *)(). An instance of the rx SetBeforeProc() macro itself resolves into the result of the assignment, which is an object of type (VOID *)().

Section 5.5.3.11: rx GetAfterProc()

: #define rx_GetAfterProc(service) ((service)->afterProc)

: Return a pointer of type (VOID *)() to the procedure associated with the given Rx service that will be called immediately upon completion of the particular Rx call for which a server thread was activated. The service parameter should resolve to an object of type struct rx service.

: When an Rx service is first created (via a call to the rx NewService() function), its afterProc field is set to a null pointer. See the description of the rx SetAfterProc() below.

Section 5.5.3.12: rx SetAfterProc()

: #define rx_SetAfterProc(service, proc) ((service)->afterProc = (proc))

: Instruct the Rx facility to call the procedure identified by the proc parameter immediately upon completion of the particular Rx call for which a server thread was activated. The specified procedure will be called with a single parameter, a pointer of type struct rx call, identifying the call this thread just handled. The value returned by the procedure, if any, is discarded.

: The service parameter should resolve to an object of type struct rx service. The proc parameter should resolve to an object of type (VOID *)(). An instance of the rx SetAfterProc() macro itself resolves into the result of the assignment, which is an object of type (VOID *)().

Section 5.5.3.13: rx SetNewConnProc()

: #define rx_SetNewConnProc(service, proc) ((service)->newConnProc = (proc))

: Instruct the Rx facility to call the procedure identified by the proc parameter as the last step in the creation of a new Rx server-side connection for the given service. The specified procedure will be called with a single parameter, a pointer of type (struct rx connection *), identifying the connection structure that was just built. The value returned by the procedure, if any, is discarded.

: The service parameter should resolve to an object of type struct rx service. The proc parameter should resolve to an object of type (VOID *)(). An instance of the rx SetNewConnProc() macro itself resolves into the result of the assignment, which is an object of type (VOID *)().

Note:: There is no access counterpart defined for this macro, namely one that returns the current setting of a service's newConnProc.

Section 5.5.3.14: rx SetDestroyConnProc()

: #define rx_SetDestroyConnProc(service, proc) ((service)->destroyConnProc = (proc))

: Instruct the Rx facility to call the procedure identified by the proc parameter just before a server connection associated with the given Rx service is destroyed. The specified procedure will be called with a single parameter, a pointer of type (struct rx connection *), identifying the connection about to be destroyed. The value returned by the procedure, if any, is discarded.

: The service parameter should resolve to an object of type struct rx service. The proc parameter should resolve to an object of type (VOID *)(). An instance of the rx SetDestroyConnProc() macro itself resolves into the result of the assignment, which is an object of type (VOID *)().

Note:: There is no access counterpart defined for this macro, namely one that returns the current setting of a service's destroyConnProc.

Section 5.5.4: Security-Related Operations

: The following macros are callable by Rx security modules, and assist in getting and setting header and trailer lengths, setting actual packet size, and finding the beginning of the security header (or data).

Section 5.5.4.1: rx GetSecurityHeaderSize()

: #define rx_GetSecurityHeaderSize(conn) ((conn)->securityHeaderSize)

: Generate a reference to the field in an Rx connection structure that records the length in bytes of the associated security module's packet header data.

: The conn parameter should resolve to an object of type struct rx connection. An instance of the rx GetSecurityHeaderSize() macro itself resolves into an object of type u short.

Section 5.5.4.2: rx SetSecurityHeaderSize()

: #define rx_SetSecurityHeaderSize(conn, length) ((conn)->securityHeaderSize = (length))

: Set the field in a connection structure that records the length in bytes of the associated security module's packet header data.

: The conn parameter should resolve to an object of type struct rx connection. The length parameter should resolve to an object of type u short. An instance of the rx SetSecurityHeaderSize() macro itself resolves into the result of the assignment, which is an object of type u short.

Section 5.5.4.3: rx

GetSecurityMaxTrailerSize()

: #define rx_GetSecurityMaxTrailerSize(conn) ((conn)->securityMaxTrailerSize)

: Generate a reference to the field in an Rx connection structure that records the maximum length in bytes of the associated security module's packet trailer data.

: The conn parameter should resolve to an object of type struct rx connection. An instance of the rx GetSecurityMaxTrailerSize() macro itself resolves into an object of type u short.

Section 5.5.4.4: rx

SetSecurityMaxTrailerSize()

: #define rx_SetSecurityMaxTrailerSize(conn, length) ((conn)->securityMaxTrailerSize = (length))

: Set the field in a connection structure that records the maximum length in bytes of the associated security module's packet trailer data.

: The conn parameter should resolve to an object of type struct rx connection. The length parameter should resolve to an object of type u short. An instance of the rx SetSecurityHeaderSize() macro itself resolves into the result of the assignment, which is an object of type u short.

Section 5.5.5: Sizing Operations

: The macros described in this section assist the application programmer in determining the sizes of the various Rx packet regions, as well as their placement within a packet buffer.

Section 5.5.5.1: rx UserDataOf()

: #define rx_UserDataOf(conn, packet) (((char *) (packet)->wire.data) + (conn)->securityHeaderSize)

: Generate a pointer to the beginning of the actual user data in the given Rx packet, that is associated with the connection described by the conn pointer. User data appears immediately after the packet's security header region, whose length is determined by the security module used by the connection. The conn parameter should resolve to an object of type struct rx connection. The packet parameter should resolve to an object of type struct rx packet. An instance of the rx UserDataOf() macro itself resolves into an object of type (char *).

Section 5.5.5.2: rx MaxUserDataSize()

: #define rx_MaxUserDataSize(conn)
((conn)->peer->packetSize
-RX_HEADER_SIZE
-(conn)->securityHeaderSize
-(conn)->securityMaxTrailerSize)

: Return the maximum number of user data bytes that may be carried by a packet on the Rx connection described by the conn pointer. The overall packet size is reduced by the IP, UDP, and Rx headers, as well as the header and trailer areas required by the connection's security module.

: The conn parameter should resolve to an object of type struct rx connection. An instance of the rx MaxUserDataSize() macro itself resolves into the an object of type (u short).

Section 5.5.6: Complex Operations

: Two Rx macros are designed to handle potentially complex operations, namely reading data from an active incoming call and writing data to an active outgoing call. Each call structure has an internal buffer that is used to collect and cache data traveling through the call. This buffer is used in conjunction with reading or writing to the actual Rx packets traveling on the wire in support of the call. The rx Read() and rx Write() macros allow their caller to simply manipulate the internal data buffer associated with the Rx call structures whenever possible, thus avoiding the overhead associated with a function call. When buffers are either filled or drained (depending on the direction of the data flow), these macros will then call functions to handle the more complex cases of generating or receiving packets in support of the operation.

Section 5.5.6.1: rx Read()

: #define rx_Read(call, buf, nbytes)
((call)->nLeft > (nbytes) ?
bcopy((call)->bufPtr, (buf), (nbytes)),
(call)->nLeft -= (nbytes), (call)->bufPtr += (nbytes), (nbytes)
: rx_ReadProc((call), (buf), (nbytes)))

: Read nbytes of data from the given Rx call into the buffer to which buf points. If the call's internal buffer has at least nbytes bytes already filled, then this is done in-line with a copy and some pointer and counter updates within the call structure. If the call's internal buffer doesn't have enough data to satisfy the request, then the rx ReadProc() function will handle this more complex situation.

: In either case, the rx Read() macro returns the number of bytes actually read from the call, resolving to an object of type int. If rx Read() returns fewer than nbytes bytes, the call status should be checked via the rx Error() macro.

Section 5.5.6.2: rx Write()

: #define rx_Write(call, buf, nbytes)
((call)->nFree > (nbytes) ?
bcopy((buf), (call)->bufPtr, (nbytes)),
(call)->nFree -= (nbytes),
(call)->bufPtr += (nbytes), (nbytes)
: rx_WriteProc((call), (buf), (nbytes)))

: Write nbytes of data from the buffer pointed to by buf into the given Rx call. If the call's internal buffer has at least nbytes bytes free, then this is done in-line with a copy and some pointer and counter updates within the call structure. If the call's internal buffer doesn't have room, then the rx WriteProc() function will handle this more complex situation.

: In either case, the rx Write() macro returns the number of bytes actually written to the call, resolving to an object of type int. If zero is returned, the call status should be checked via the rx Error() macro.

Section 5.5.7: Security Operation Invocations

: Every Rx security module is required to implement an identically-named set of operations, through which the security mechanism it defines is invoked. This characteristic interface is reminiscent of the vnode interface defined and popularized for file systems by Sun Microsystems [4]. The structure defining this function array is described in Section 5.3.1.1.

: These security operations are part of the struct rx securityClass, which keeps not only the ops array itself but also any private data they require and a reference count. Every Rx service contains an array of these security class objects, specifying the range of security mechanisms it is capable of enforcing. Every Rx connection within a service is associated with exactly one of that service's security objects, and every call issued on the connection will execute the given security protocol.

: The macros described below facilitate the execution of the security module interface functions. They are covered in the same order they appear in the struct rx securityOps declaration.

Section 5.5.7.1: RXS OP()

 #if defined(__STDC__) && !defined(__HIGHC__) 
        #define RXS_OP(obj, op, args) 
                ((obj->ops->op_ ## op) ? (*(obj)->ops->op_ ## op)args : 0) 
 #else 
        #define RXS_OP(obj, op, args) 
                ((obj->ops->op_op) ? (*(obj)->ops->op_op)args : 0) 
 #endif

: The RXS OP macro represents the workhorse macro in this group, used by all the others. It takes three arguments, the first of which is a pointer to the security object to be referenced. This obj parameter must resolve to an object of type (struct rx securityOps *). The second parameter identifies the specific op to be performed on this security object. The actual text of this op argument is used to name the desired opcode function. The third and final argument, args, specifies the text of the argument list to be fed to the chosen security function. Note that this argument must contain the bracketing parentheses for the function call's arguments. In fact, note that each of the security function access macros defined below provides the enclosing parentheses to this third RXS OP() macro.

Section 5.5.7.1: RXS Close()

: #define RXS_Close(obj) RXS_OP(obj, Close, (obj))

: This macro causes the execution of the interface routine occupying the op Close() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx immediately before a security object is discarded. Among the responsibilities of such a function might be decrementing the object's refCount field, and thus perhaps freeing up any space contained within the security object's private storage region, referenced by the object's privateData field.

: The obj parameter must resolve into an object of type (struct rx securityOps *). In generating a call to the security object's op Close() routine, the obj pointer is used as its single parameter. An invocation of the RXS Close() macro results in a return value identical to that of the op Close() routine, namely a value of type int.

Section 5.5.7.3: RXS NewConnection()

: #define RXS_NewConnection(obj, conn) RXS_OP(obj, NewConnection, (obj, conn))

: This macro causes the execution of the interface routine in the op NewConnection() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx immediately after a connection using the given security object is created. Among the responsibilities of such a function might be incrementing the object's refCount field, and setting any per-connection information based on the associated security object's private storage region, as referenced by the object's privateData field.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the newly-created connection structure, and must resolve into an object of type (struct rx connection *).

: In generating a call to the routine located at the security object's op NewConnection() slot, the obj and conn pointers are used as its two parameters. An invocation of the RXS NewConnection() macro results in a return value identical to that of the op NewConnection() routine, namely a value of type int.

Section 5.5.7.4: RXS PreparePacket()

: #define RXS_PreparePacket(obj, call, packet)
RXS_OP(obj, PreparePacket, (obj, call, packet))

: This macro causes the execution of the interface routine in the op PreparePacket() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time it prepares an outward-bound packet. Among the responsibilities of such a function might be computing information to put into the packet's security header and/or trailer.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The call argument contains a pointer to the Rx call to which the given packet belongs, and must resolve to an object of type (struct rx call *). The final argument, packet, contains a pointer to the packet itself. It should resolve to an object of type (struct rx packet *).

: In generating a call to the routine located at the security object's op PreparePacket() slot, the obj, call, and packet pointers are used as its three parameters. An invocation of the RXS PreparePacket() macro results in a return value identical to that of the op PreparePacket() routine, namely a value of type int.

Section 5.5.7.5: RXS SendPacket()

: #define RXS_SendPacket(obj, call, packet) RXS_OP(obj, SendPacket, (obj, call, packet))

: This macro causes the execution of the interface routine occupying the op SendPacket() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time it physically transmits an outward-bound packet. Among the responsibilities of such a function might be recomputing information in the packet's security header and/or trailer.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The call argument contains a pointer to the Rx call to which the given packet belongs, and must resolve to an object of type (struct rx call *). The final argument, packet, contains a pointer to the packet itself. It should resolve to an object of type (struct rx packet *).

: In generating a call to the routine located at the security object's op SendPacket() slot, the obj, call, and packet pointers are used as its three parameters. An invocation of the RXS SendPacket() macro results in a return value identical to that of the op SendPacket() routine, namely a value of type int.

Section 5.5.7.6: RXS CheckAuthentication()

: #define RXS_CheckAuthentication(obj, conn) RXS_OP(obj, CheckAuthentication, (obj, conn))

: This macro causes the execution of the interface routine in the op CheckAuthentication() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time it needs to check whether the given connection is one on which authenticated calls are being performed. Specifically, a value of 0 is returned if authenticated calls are not being executed on this connection, and a value of 1 is returned if they are.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx connection checked as to whether authentication is being performed, and must resolve to an object of type (struct rx connection *).

: In generating a call to the routine in the security object's op CheckAuthentication() slot, the obj and conn pointers are used as its two parameters. An invocation of the RXS CheckAuthentication() macro results in a return value identical to that of the op CheckAuthentication() routine, namely a value of type int.

Section 5.5.7.7: RXS CreateChallenge()

: #define RXS_CreateChallenge(obj, conn) RXS_OP(obj, CreateChallenge, (obj, conn))

: This macro causes the execution of the interface routine in the op CreateChallenge() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time a challenge event is constructed for a given connection. Among the responsibilities of such a function might be marking the connection as temporarily unauthenticated until the given challenge is successfully met.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx connection for which the authentication challenge is being constructed, and must resolve to an object of type (struct rx connection *).

: In generating a call to the routine located at the security object's op CreateChallenge() slot, the obj and conn pointers are used as its two parameters. An invocation of the RXS CreateChallenge() macro results in a return value identical to that of the op CreateChallenge() routine, namely a value of type int.

Section 5.5.7.8: RXS GetChallenge()

: #define RXS_GetChallenge(obj, conn, packet) RXS_OP(obj, GetChallenge, (obj, conn, packet))

: This macro causes the execution of the interface routine occupying the op GetChallenge() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time a challenge packet is constructed for a given connection. Among the responsibilities of such a function might be constructing the appropriate challenge structures in the area of packet dedicated to security matters.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx connection to which the given challenge packet belongs, and must resolve to an object of type (struct rx connection *). The final argument, packet, contains a pointer to the challenge packet itself. It should resolve to an object of type (struct rx packet *).

: In generating a call to the routine located at the security object's op GetChallenge() slot, the obj, conn, and packet pointers are used as its three parameters. An invocation of the RXS GetChallenge() macro results in a return value identical to that of the op GetChallenge() routine, namely a value of type int.

Section 5.5.7.9: RXS GetResponse()

: #define RXS_GetResponse(obj, conn, packet) RXS_OP(obj, GetResponse, (obj, conn, packet))

: This macro causes the execution of the interface routine occupying the op GetResponse() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx on the server side each time a response to a challenge packet must be received.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx client connection that must respond to the authentication challenge, and must resolve to a (struct rx connection *) object. The final argument, packet, contains a pointer to the packet to be built in response to the challenge. It should resolve to an object of type (struct rx packet *).

: In generating a call to the routine located at the security object's op GetResponse() slot, the obj, conn, and packet pointers are used as its three parameters. An invocation of the RXS GetResponse() macro results in a return value identical to that of the op GetResponse() routine, namely a value of type int.

Section 5.5.7.10: RXS CheckResponse()

: #define RXS_CheckResponse(obj, conn, packet) RXS_OP(obj, CheckResponse, (obj, conn, packet))

: This macro causes the execution of the interface routine in the op CheckResponse() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx on the server side each time a response to a challenge packet is received for a given connection. The responsibilities of such a function might include verifying the integrity of the response, pulling out the necessary security information and storing that information within the affected connection, and otherwise updating the state of the connection.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx server connection to which the given challenge response is directed. This argument must resolve to an object of type (struct rx connection *). The final argument, packet, contains a pointer to the packet received in response to the challenge itself. It should resolve to an object of type (struct rx packet *).

: In generating a call to the routine located at the security object's op CheckResponse() slot, the obj, conn, and packet pointers are ued as its three parameters. An invocation of the RXS CheckResponse() macro results in a return value identical to that of the op CheckResponse() routine, namely a value of type int.

Section 5.5.7.11: RXS CheckPacket()

: #define RXS_CheckPacket(obj, call, packet) RXS_OP(obj, CheckPacket, (obj, call, packet))

: This macro causes the execution of the interface routine occupying the op CheckPacket() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time a packet is received. The responsibilities of such a function might include verifying the integrity of given packet, detecting any unauthorized modifications or tampering.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx connection to which the given challenge response is directed, and must resolve to an object of type (struct rx connection *). The final argument, packet, contains a pointer to the packet received in response to the challenge itself. It should resolve to an object of type (struct rx packet *).

: In generating a call to the routine located at the security object's op CheckPacket() slot, the obj, conn, and packet pointers are used as its three parameters. An invocation of the RXS CheckPacket() macro results in a return value identical to that of the op CheckPacket() routine, namely a value of type int.

: Please note that any non-zero return will cause Rx to abort all calls on the connection. Furthermore, the connection itself will be marked as being in error in such a case, causing it to reject any further incoming packets.

Section 5.5.7.12: RXS DestroyConnection()

: #define RXS_DestroyConnection(obj, conn) RXS_OP(obj, DestroyConnection, (obj, conn))

: This macro causes the execution of the interface routine in the op DestroyConnection() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time a connection employing the given security object is being destroyed. The responsibilities of such a function might include deleting any private data maintained by the security module for this connection.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx connection being reaped, and must resolve to a (struct rx connection *) object.

: In generating a call to the routine located at the security object's op DestroyConnection() slot, the obj and conn pointers are used as its two parameters. An invocation of the RXS DestroyConnection() macro results in a return value identical to that of the op DestroyConnection() routine, namely a value of type int.

Section 5.5.7.13: RXS GetStats()

: #define RXS_GetStats(obj, conn, stats) RXS_OP(obj, GetStats, (obj, conn, stats))

: This macro causes the execution of the interface routine in the op GetStats() slot in the Rx security object identified by the obj pointer. This interface function is invoked by Rx each time current statistics concerning the given security object are desired.

: The obj parameter must resolve into an object of type (struct rx securityOps *). The conn argument contains a pointer to the Rx connection using the security object to be examined, and must resolve to an object of type (struct rx connection *). The final argument, stats, contains a pointer to a region to be filled with the desired statistics. It should resolve to an object of type (struct rx securityObjectStats *).

: In generating a call to the routine located at the security object's op GetStats() slot, the obj, conn, and stats pointers are used as its three parameters. An invocation of the RXS GetStats() macro results in a return value identical to that of the op GetStats() routine, namely a value of type int.

Section 5.6: Functions

: Rx exports a collection of functions that, in conjuction with the macros explored in Section 5.5, allows its clients to set up and export services, create and tear down connections to these services, and execute remote procedure calls along these connections.

: This paper employs two basic categorizations of these Rx routines. One set of functions is meant to be called directly by clients of the facility, and are referred to as the exported operations. The individual members of the second set of functions are not meant to be called directly by Rx clients, but rather are called by the collection of defined macros, so they must still be lexically visible. These indirectly-executed routines are referred to here as the semi-exported operations.

: All Rx routines return zero upon success. The range of error codes employed by Rx is defined in Section 5.2.15.

Section 5.6.1: Exported Operations

Section 5.6.2: rx Init _ Initialize Rx

: int rx Init(IN int port)

Description: Initialize the Rx facility. If a non-zero port number is provided, it becomes the default port number for any service installed later. If 0 is provided for the port, a random port will be chosen by the system. The rx Init() function sets up internal tables and timers, along with starting up the listener thread.

Error Codes: RX ADDRINUSE The port provided has already been taken.

Section 5.6.3: rx NewService _ Create and install

a new service

: struct rx service *rx NewService(IN u short port; IN u short serviceId; IN char *serviceName; IN struct rx securityClass **securityObjects; IN int nSecurityObjects; IN long (*serviceProc)())

Description: Create and advertise a new Rx service. A service is uniquely named by a UDP port number plus a non-zero 16-bit serviceId on the given host. The port argument may be set to zero if rx Init() was called with a non-zero port number, in which case that original port will be used. A serviceName must also be provided, to be used for identification purposes (e.g., the service name might be used for probing for statistics). A pointer to an array of nSecurityObjects security objects to be associated with the new service is given in . securityObjects. The service's executeRequestProc() pointer is set to serviceProc.

The function returns a pointer to a descriptor for the requested Rx service. A null return value indicates that the new service could not be created. Possible reasons include:

The serviceId parameter was found to be zero.
A port value of zero was specified at Rx initialization time (i.e., when rx init() was called), requiring a non-zero value for the port parameter here.
Another Rx service is already using serviceId.
Rx has already created the maximum RX MAX SERVICES Rx services (see Section 5.2.1).

Error Codes: (struct rx service *) NULL The new Rx service could not be created, due to one of the errors listed above.

Section 5.6.4: rx NewConnection _ Create a new

connection to a given service

: struct rx connection *rx NewConnection( IN u long shost, IN u short sport, IN u short sservice, IN struct rx securityClass *securityObject, IN int service SecurityIndex)

Description: Create a new Rx client connection to service sservice on the host whose IP address is contained in shost and to that host's sport UDP port. The corresponding Rx service identifier is expected in sservice. The caller also provides a pointer to the security object to use for the connection in securityObject, along with that object's serviceSecurityIndex among the security objects associated with service sservice via a previous rx NewService() call (see Section 5.6.3).

Note:: It is permissible to provide a null value for the securityObject parameter if the chosen serviceSecurityIndex is zero. This corresponds to the pre-defined null security object, which does not engage in authorization checking of any kind.

Error Codes: --- A pointer to an initialized Rx connection is always returned, unless osi Panic() is called due to memory allocation failure.

Section 5.6.5: rx NewCall _ Start a new call on

the given connection

: struct rx call *rx NewCall( IN struct rx connection *conn)

Description: Start a new Rx remote procedure call on the connection specified by the conn parameter. The existing call structures (up to RX MAXCALLS of them) are examined in order. The first non-active call encountered (i.e., either unused or whose call->state is RX STATE DALLY) will be appropriated and reset if necessary. If all call structures are in active use, the RX CONN MAKECALL WAITING flag is set in the conn->flags field, and the thread handling this request will sleep until a call structure comes free. Once a call structure has been reserved, the keep-alive protocol is enabled for it.

: The state of the given connection determines the detailed behavior of the function. The conn->timeout field specifies the absolute upper limit of the number of seconds this particular call may be in operation. After this time interval, calls to such routines as rx SendData() or rx ReadData() will fail with an RX CALL TIMEOUT indication.

Error Codes: --- A pointer to an initialized Rx call is always returned, unless osi Panic() is called due to memory allocation failure.

Section 5.6.6: rx EndCall _ Terminate the given

call

: int rx EndCall(

Parameters:

IN	struct rx call *call,
IN	long rc )

Description: Indicate that the Rx call described by the structure located at call is finished, possibly prematurely. The value passed in the rc parameter is returned to the peer, if appropriate. The final error code from processing the call will be returned as rx EndCall()'s value. The given call's state will be set to RX STATE DALLY, and threads waiting to establish a new call on this connection are signalled (see the description of the rx NewCall() in Section 5.6.5).

Error Codes: -1 Unspecified error has occurred.

Section 5.6.7: rx StartServer _ Activate installed

rx service(s)

: void rx StartServer( IN int donateMe)

Description: This function starts server threads in support of the Rx services installed via calls to rx NewService() (see Section 5.6.3). This routine first computes the number of server threads it must create, governed by the minProcs and maxProcs fields in the installed service descriptors. The minProcs field specifies the minimum number of threads that are guaranteed to be concurrently available to the given service. The maxProcs field specifies the maximum number of threads that may ever be concurrently assigned to the particular service, if idle threads are available. Using this information, rx StartServer() computes the correct overall number of threads as follows: For each installed service, minProcs threads will be created, enforcing the minimality guarantee. Calculate the maximum difference between the maxProcs and minProcs fields for each service, and create this many additional server threads, enforcing the maximality guarantee.

: If the value placed in the donateMe argument is zero, then rx StartServer() will simply return after performing as described above. Otherwise, the thread making the rx StartServer() call will itself begin executing the server thread loop. In this case, the rx StartServer() call will never return.

Error Codes: ---None.

Section 5.6.8: rx PrintStats -- Print basic

statistics to a file

: void rx PrintStats( IN FILE *file)

Description: Prints Rx statistics (basically the contents of the struct rx stats holding the statistics for the Rx facility) to the open file descriptor identified by file. The output is ASCII text, and is intended for human consumption.

Note:: This function is available only if the Rx package has been compiled with the RXDEBUG flag.

Error Codes: ---None.

Section 5.6.9: rx PrintPeerStats _ Print peer

statistics to a file

: void rx PrintPeerStats( IN FILE *file, IN struct rx peer *peer)

Description: Prints the Rx peer statistics found in peer to the open file descriptor identified by file. The output is in normal ASCII text, and is intended for human consumption.

Note:: This function is available only if the Rx package has been compiled with the RXDEBUG flag.

Error Codes: ---None.

Section 5.6.10: rx finalize _ Shut down Rx

gracefully

: void rx finalize()

Description: This routine may be used to shut down the Rx facility for either server or client applications. All of the client connections will be gracefully garbage-collected after their active calls are cleaned up. The result of calling rx finalize() from a client program is that the server-side entity will be explicitly advised that the client has terminated. This notification frees the server-side application from having to probe the client until its records eventually time out, and also allows it to free resources currently assigned to that client's support.

Error Codes: ---None.

Section 5.6.11: Semi-Exported Operations

: As described in the introductory text in Section 5.6, entries in this lexically-visible set of Rx functions are not meant to be called directly by client applications, but rather are invoked by Rx macros called by users.

Section 5.6.12: rx WriteProc _ Write data to an

outgoing call

: int rx WriteProc( IN struct rx call *call, IN char *buf, IN int nbytes)

Description: Write nbytes of data from buffer buf into the Rx call identified by the call parameter. The value returned by rx WriteProc() reports the number of bytes actually written into the call. If zero is returned, then the rx Error() macro may be used to obtain the call status.

: This routine is called by the rx Write() macro, which is why it must be exported by the Rx facility.

Error Codes: Indicates error in the given Rx call; use the rx Error() macro to determine the call status.

Section 5.6.13: rx ReadProc _ Read data from an

incoming call

: int rx ReadProc( IN struct rx call *call, IN char *buf, IN int nbytes)

Description: Read up to nbytes of data from the Rx call identified by the call parameter into the buf buffer. The value returned by rx ReadProc() reports the number of bytes actually read from the call. If zero is returned, then the rx Error() macro may be used to obtain the call status.

: This routine is called by the rx Read() macro, which is why it must be exported by the Rx facility.

Error Codes: Indicates error in the given Rx call; use the rx Error() macro to determine the call status.

Section 5.6.1: Exported Operations

data on outgoing call

: void rx FlushWrite( IN struct rx call *call)

Description: Flush any buffered data on the given Rx call to the stream. If the call is taking place on a server connection, the call->mode is set to RX MODE EOF. If the call is taking place on a client connection, the call->mode is set to RX MODE RECEIVING.

Error Codes: ---None.

Section 5.6.15: rx SetArrivalProc _ Set function

to invoke upon call packet arrival

: void rx SetArrivalProc( IN struct rx call *call, IN VOID (*proc)(), IN VOID *handle, IN VOID *arg)

Description: Establish a procedure to be called when a packet arrives for a call. This routine will be called at most once after each call, and will also be called if there is an error condition on the call or the call is complete. The rx SetArrivalProc() function is used by multicast Rx routines to build a selection function that determines which of several calls is likely to be a good one to read from. The implementor's comments in the Rx code state that, due to the current implementation, it is probably only reasonable to use rx SetArrivalProc() immediately after an rx NewCall(), and to only use it once.

Error Codes: ---None.

Section 5.1: RPC Interface

: This chapter documents the API for the Volume Server facility, as defined by the volint.xg Rxgen interface file and the volser.h include file. Descriptions of all the constants, structures, macros, and interface functions available to the application programmer appear here.

Section 5.2: Signal Interface

: This section covers the basic constant definitions of interest to the Volume Server application programmer. These definitions appear in the volint.h file, automatically generated from the volint.xg Rxgen interface file, and in volser.h.

Each subsection is devoted to describing the constants falling into the following categories:

Configuration and boundary values
Interface routine opcodes
Transaction Flags
Volume Types
LWP State
States for struct vldbentry
Validity Checks
Miscellaneous

Section 5.2.1: SIGQUIT: Server Shutdown

: These constants define some basic system configuration values, along with such things as maximum sizes of important arrays.

MyPort 5,003 The Rx UDP port on which the Volume Server service may be found.

Name: NameLen

Value: 80

Description: Used by the vos utility to define maximum lengths for internal filename variables.

Name: VLDB MAXSERVERS

Value: 10

Description: Maximum number of server agents implementing the AFS Volume Location Database (VLDB) for the cell.

Name: VOLSERVICE ID

Value: 4

Description: The Rx service number on the given UDP port (MyPort) above.

Name: INVALID BID

Value: 0

Description: Used as an invalid read-only or backup volume ID.

Name: VOLSER MAXVOLNAME

Value: 65

Description: The number of characters in the longest possible volume name, including the trailing null. Note: this is only used by the vos utility; the Volume Server uses the "old" value below.

Name: VOLSER OLDMAXVOLNAME

Value: 32

Description: The "old" maximum number of characters in an AFS volume name, including the trailing null. In reality, it is also the current maximum.

Name: VOLSER MAX REPSITES

Value: 7

Description: The maximum number of replication sites for a volume.

Name: VNAMESIZE

Value: 32

Description: Size in bytes of the name field in struct volintInfo (see Section 5.4.6).

Section 5.2.2: SIGTSTP: Upgrade Debugging Level

: These constants, appearing in the volint.xg Rxgen interface file for the Volume Server, define the opcodes for the RPC routines. Every Rx call on this interface contains this opcode, and the dispatcher uses it to select the proper code at the server site to carry out the call.

Name: VOLCREATEVOLUME

Value: 100

Description: Opcode for AFSVolCreateVolume()

Name: VOLDELETEVOLUME

Value: 101

Description: Opcode for AFSVolDeleteVolume()

Name: VOLRESTORE

Value: 102

Description: Opcode for AFSVolRestoreVolume()

Name: VOLFORWARD

Value: 103

Description: Opcode for AFSVolForward()

Name: VOLENDTRANS

Value: 104

Description: Opcode for AFSVolEndTrans()

Name: VOLCLONE

Value: 105

Description: Opcode for AFSVolClone() .

Name: VOLSETFLAGS

Value: 106

Description: Opcode for AFSVolSetFlags()

Name: VOLGETFLAGS

Value: 107

Description: Opcode for AFSVolGetFlags()

Name: VOLTRANSCREATE

Value: 108

Description: Opcode for AFSVolTransCreate()

Name: VOLDUMP

Value: 109

Description: Opcode for AFSVolDump()

Name: VOLGETNTHVOLUME

Value: 110

Description: Opcode for AFSVolGetNthVolume()

Name: VOLSETFORWARDING

Value: 111

Description: Opcode for AFSVolSetForwarding()

Name: VOLGETNAME

Value: 112

Description: Opcode for AFSVolGetName()

Name: VOLGETSTATUS

Value: 113

Description: Opcode for AFSVolGetStatus()

Name: VOLSIGRESTORE

Value: 114

Description: Opcode for AFSVolSignalRestore()

Name: VOLLISTPARTITIONS

Value: 115

Description: Opcode for AFSVolListPartitions()

Name: VOLLISTVOLS

Value: 116

Description: Opcode for AFSVolListVolumes()

Name: VOLSETIDSTYPES

Value: 117

Description: Opcode for AFSVolSetIdsTypes()

Name: VOLMONITOR

Value: 118

Description: Opcode for AFSVolMonitor()

Name: VOLDISKPART

Value: 119

Description: Opcode for AFSVolPartitionInfo()

Name: VOLRECLONE

Value: 120

Description: Opcode for AFSVolReClone()

Name: VOLLISTONEVOL

Value: 121

Description: Opcode for AFSVolListOneVolume()

Name: VOLNUKE

Value: 122

Description: Opcode for AFSVolNukeVolume()

Name: VOLSETDATE

Value: 123

Description: Opcode for AFSVolSetDate()

Section 5.2.3: SIGHUP: Reset Debugging Level

: These constants define the various flags the Volume Server uses in assocation with volume transactions, keeping track of volumes upon which operations are currently proceeding. There are three sets of flag values, stored in three different fields within a struct volser trans: general volume state, attachment modes, and specific transaction states.

: Section 5.2.3.1 vflags

: These values are used to represent the general state of the associated volume. They appear in the vflags field within a struct volser trans.

Name: VTDeleteOnSalvage

Value: 1

Description: The volume should be deleted on next salvage.

Name: VTOutOfService

Value: 2

Description: This volume should never be put online.

Name: VTDeleted

Value: 4

Description: This volume has been deleted (via AFSVolDeleteVol�ume() ), and thus should not be manipulated.

Section 5.2.3.2: iflags

: These constants represent the desired attachment mode for a volume at the start of a transaction. Once attached, the volume header is marked to reflect this mode. Attachment modes are useful in salvaging partitions, as they indicate whether the operations being performed on individual volumes at the time the crash occured could have introduced inconsistencies in their metadata descriptors. If a volume was attached in a read-only fashion, then the salvager may decide (taking other factors into consideration) that the volume doesn't need attention as a result of the crash.

: These values appear in the iflags field within a struct volser trans.

Name: ITOffline

Value: 0x1

Description: Volume offline on server (returns VOFFLINE).

Name: ITBusy

Value: 0x2

Description: Volume busy on server (returns VBUSY).

Name: ITReadOnly

Value: 0x8

Description: Volume is read-only on client, read-write on server -DO NOT USE.

Name: ITCreate

Value: 0x10

Description: Volume does not exist correctly yet.

Name: ITCreateVolID

Value: 0x1000

Description: Create volid.

Section 5.2.3.3: tflags

: This value is used to represent the transaction state of the associated volume, and appears in the tflags field within a struct volser trans.

Name: TTDeleted

Value: 1

Description: Delete transaction not yet freed due to high reference count.

Section 5.2.4: SIGTERM: File Descriptor Check

: The following constants may be supplied as values for the type argument to the AFSVol-CreateVolume() interface call. They are just synonyms for the three values RWVOL, ROVOL,

Name: volser RW

Value: 0

Description: Specifies a read-write volume type.

Name: volser RO

Value: 1

Description: Specifies a read-only volume type.

Name: volser BACK

Value: 2

Description: Specifies a backup volume type.

Section 5.2.5: Connection Types

: This set of exported definitions refers to objects internal to the Volume Server, and strictly speaking should not be visible to other agents. Specifically, a busyFlags array keeps a set of flags referenced by the set of lightweight threads running within the Volume Server. These flags reflect and drive the state of each of these worker LWPs.

Name: VHIdle

Value: 1

Description: Volume Server LWP is idle, waiting for new work.

Name: VHRequest

Value: 2

Description: A work item has been queued.

Section 5.2.6: Call States

: The Volume Server defines a collection of synonyms for certain values defined by the Volume Location Server. These particular constants are used within the flags field in objects of type struct vldbentry. The equivalent Volume Location Server values are described in Section 3.2.6.

Name: RW EXISTS

Value: 0x1000

Description: Synonym for VLF RWEXISTS.

Name: RO EXISTS

Value: 0x2000

Description: Synonym for VLF ROEXISTS.

Name: BACK EXISTS

Value: 0x4000

Description: Synonym for VLF BACKEXISTS.

Name: NEW REPSITE

Value: 0x01

Description: Synonym for VLSF NEWREPSITE.

Name: ITSROVOL

Value: 0x02

Description: Synonym for VLFS ROVOL.

Name: ITSRWVOL

Value: 0x04

Description: Synonym for VLSF RWVOL.

Name: ITSBACKVOL

Value: 0x08

Description: Synonym for VLSF BACKVOL.

Section 5.2.7: Call Flags:

: These values are used for performing validity checks. The first one appears only within the partFlags field within objects of type partList (see Section 5.4.3). The rest (except VOK and VBUSY) appear in the volFlags field within an object of type struct volDescription. These latter defintions are used within the volFlags field to mark whether the rest of the fields within the struct volDescription are valid. Note that while several constants are defined, only some are actually used internally by the Volume Server code.

Name: PARTVALID

Value: 0x01

Description: The indicated partition is valid.

Name: CLONEVALID

Value: 0x02

Description: The indicated clone (field volCloneId) is a valid one.

Name: CLONEZAPPED

Value: 0x04

Description: The indicated clone volume (field volCloneId) has been deleted.

Name: IDVALID

Value: 0x08

Description: The indicated volume ID (field volId) is valid.

Name: NAMEVALID

Value: 0x10

Description: The indicted volume name (field volName) is valid. Not used internally by the Volume Server.

Name: SIZEVALID

Value: 0x20

Description: The indicated volume size (field volSize) is valid. Not used internally by the Volume Server.

Name: ENTRYVALID

Value: 0x40

Description: The struct volDescription refers to a valid volume.

Name: REUSECLONEID

Value: 0x80

Description: The indicated clone ID (field volCloneId) should be reused.

Name: VOK

Value: 0x02

Description: Used in the status field of struct volintInfo to show that everything is OK.

Name: VBUSY

Value: 110

Description: Used in the status field of struct volintInfo to show that the volume is currently busy.

Section 5.2.8: Call Modes

: This section covers the set of exported Volume Server definitions that don't easily fall into the above categories.

Name: SIZE

Value: 1,024

Description: Not used internally by the Volume Server; used as a maxi�mum size for internal character arrays.

Name: MAXHELPERS

Value: 10

Description: Size of an internal Volume Server character array (busyFlags), it marks the maximum number of threads within the server.

Name: STDERR

Value: stderr

Description: Synonym for the unix standard input file descriptor.

Name: STDOUT

Value: stdout

Description: Synonym for the unix standard output file descriptor.

Section 5.3: Command Line Interface

: This section describes the single variable that the Volume Server exports to its applications.

: The QI GlobalWriteTrans exported variable represents a pointer to the head of the global queue of transaction structures for operations being handled by a Volume Server. Each object in this list is of type struct volser trans (see Section 5.4.1 below).

Section 5.4: Exported Variables

: This section describes the major exported Volume Server data structures of interest to application programmers, along with some of the the typedefs based on those structures. Please note that typedefs in shose definitions angle brackets appear are those fed through the Rxgen RPC stub generator. Rxgen uses these angle brackets to specify an array of indefinite size.

Section 5.4.1: rx connDeadTime

This structure defines the transaction record for all volumes upon which an active operation is proceeding.
Fields

struct volser trans *next - Pointer to the next transaction structure in the queue.
long tid - Transaction ID.
long time - The time this transaction was last active, for timeout purposes.
This is the standard unix time format.
long creationTime - The time a which this transaction started.
long returnCode - The overall transaction error code.
struct Volume *volume - Pointer to the low-level object describing the associated volume. This is included here for the use of lower-level support code.
long volid - The associated volume's numerical ID.
long partition - The partition on which the given volume resides.
long dumpTransId - Not used.
long dumpSeq - Not used.
short refCount - Reference count on this structure.
short iflags - Initial attach mode flags.
char vflags - Current volume status flags.
char tflags - Transaction flags.
char incremental - If non-zero, indicates that an incremental restore operation should be performed.
char lastProcName[] - Name of the last internal Volume Server procedure that used this transaction. This field may be up to 30 characters long, including the trailing null, and is intended for debugging purposes only.
struct rx call *rxCallPtr - Pointer to latest associated rx call. This field is intended for debugging purposes only.

Section 5.4.2: rx idleConnectionTime

This structure is used by the AFS backup system to group certain key fields of volume information.
Fields

char volName[] -The name of the given volume; maximum length of this string is VOLSER MAXVOLNAME characters, including the trailing null.
long volId -The volume's numerical ID.
int volSize -The size of the volume, in bytes.
long volFlags -Keeps validity information on the given volume and its clones. This field takes on values from the set defined in Section 5.2.7
long volCloneId -The volume's current clone ID.

Section 5.4.3: rx idlePeerTime

This structure is used by the backup system and the vos tool to keep track of the state of the AFS disk partitions on a given server.
Fields

long partId[] -Set of 26 partition IDs.
long partFlags[] -Set to PARTVALID if the associated partition slot corresponds to a valid partition. There are 26 entries in this array.

Section 5.4.4: rx extraQuota

: This structure holds the status of a volume as it is known to the Volume Server, and is passed to clients through the AFSVolGetStatus() interface call.

Two fields appearing in this structure, accessDate and updateDate, deserve a special note. In particular, it is important to observe that these fields are not kept in full synchrony with reality. When a File Server provides one of its client Cache Managers with a chunk of a file on which to operate, it is incapable of determining exactly when the data in that chunk is accessed, or exactly when it is updated. This is because the manipulations occur on the client machine, without any information on these accesses or updates passed back to the server. The only time these fields can be modified is when the chunk of a file resident within the given volume is delivered to a client (in the case of accessDate), or when a client writes back a dirty chunk to the File Server (in the case of updateDate).
Fields

long volID - The volume's numerical ID, unique within the cell.
long nextUnique - Next value to use for a vnode uniquifier within this volume.
int type - Basic volume class, one of RWVOL, ROVOL, or BACKVOL.
long parentID - Volume ID of the parent, if this volume is of type ROVOL or BACKVOL.
long cloneID - ID of the latest read-only clone, valid iff the type field is set to RWVOL.
long backupID - Volume ID of the latest backup of this read-write volume.
long restoredFromID - The volume ID contained in the dump from which this volume was restored. This field is used to simply make sure that an incremental dump is not restored on top of something inappropriate. Note that this field itself is not dumped.
long maxQuota - The volume's maximum quota, in 1Kbyte blocks.
long minQuota - The volume's minimum quota, in 1Kbyte blocks.
long owner - The user ID of the person responsible for this volume.
long creationDate - For a volume of type RWVOL, this field marks its creation date. For the original copy of a clone, this field represents the cloning date.
long accessDate - Last access time by a user for this volume. This value is expressed as a standard unix longword date quantity.
long updateDate - Last modification time by a user for this volume. This value is expressed as a standard unix longword date quantity.
long expirationDate - Expiration date for this volume. If the volume never expires, then this field is set to zero.
long backupDate - The last time a backup clone was created for this volume.
long copyDate - The time that this copy of this volume was created.

Section 5.4.5: rx extraPackets

Used to specify the destination server in an AFSVolForward() invocation (see Section 5.7.7).
Fields

long destHost - The IP address of the destination server.
long destPort - The UDP port for the Volume Server Rx service there.
long destSSID - Currently, this field is always set to 1.

Section 5.4.6: rx nPackets

: This structure is used to communicate volume information to the Volume Server's RPC clients. It is used to build the volEntries object, which appears as a parameter to the AFSVolListVolumes() call.

The comments in Section 5.4.4 concerning the accessDate and updateDate fields are equally valid for the analogue fields in this structure.
Fields

char name[] - The null-terminated name for the volume, which can be no longer than VNAMESIZE (32) characters, including the trailing null.
long volid - The volume's numerical ID.
long type - The volume's basic class, one of RWVOL, ROVOL, or BACKVOL.
long backupID - The latest backup volume's ID.
long parentID - The parent volume's ID.
long cloneID - The latest clone volume's ID.
long status - Status of the volume; may be one of VOK or VBUSY.
long copyDate - The time that this copy of this volume was created.
unsigned char inUse - If non-zero, an indication that this volume is online.
unsigned char needsSalvaged - If non-zero, an indication that this volume needs to be salvaged.
unsigned char destroyMe - If non-zero, an indication that this volume should be destroyed.
long creationDate - Creation date for a read/write volume; cloning date for the original copy of a read-only volume.
long accessDate - Last access time by a user for this volume.
long updateDate - Last modification time by a user for this volume.
long backupDate - Last time a backup copy was made of this volume.
int dayUse - Number of times this volume was accessed since midnight of the current day.
int filecount - the number of file system objects contained within the volume.
int maxquota - The upper limit on the number of 1-Kbyte disk blocks of storage that this volume may obtain.
int size - Not known.
long flags - Values used by the backup system are stored here.
long spare1 -spare3 -Spare fields, reserved for future use.

Section 5.4.7: rx nFreePackets

This structure is provided for monitoring and debugging purposes. It is used to compose the transDebugEntries variable-sized object, which in turn appears as a parameter to the AFSVolMonitor() interface call.
Fields

long tid - The transaction ID.
long time - The time when the transaction was last active, for timeout purposes.
long creationTime - The time the transaction started.
long returnCode - The overall transaction error code.
long volid - The open volume's ID.
long partition - The open volume's partition.
short iflags - Initial attach mode flags (IT*).
char vflags - Current volume status flags (VT*).
char tflags - Transaction flags (TT*).
char lastProcName[] - The string name of the last procedure which used transaction. This field may be up to 30 characters long, including the trailing null, and is intended for debugging purposes only.
int callValid - Flag which determines if the following fields are valid.
long readNext - Sequence number of the next Rx packet to be read.
long transmitNext - Sequence number of the next Rx packet to be transmitted.
int lastSendTime - The last time anything was sent over the wire for this transaction.
int lastReceiveTime - The last time anything was received over the wire for this transaction.

Section 5.4.8: rx stackSize

Used by the AFSVolListPartitions() interface call, this structure is used to store information on all of the partitions on a given Volume Server.
Fields

long partIds[] - One per letter of the alphabet (/vicepa through /vicepz). Filled with 0 for "/vicepa", 25 for "/vicepz". Invalid partition slots are filled in with a -1.

Section 5.4.9: rx packetTypes

This structure contains information regarding an individual AFS disk partition. It is returned as a parameter to the AFSVolPartitionInfo() call.
Fields

char name[] -Mounted partition name, up to 32 characters long including the trailing null.
char devName[] -Device name on which the partition lives, up to 32 characters long including the trailing null.
int lock fd -A lock used for mutual exclusion to the named partition. A value of -1 indicates the lock is not currently being held. Otherwise, it has the file descriptor resulting from the unix open() call on the file specified in the name field used to "acquire" the lock.
int totalUsable - The number of blocks within the partition which are available.
int free - The number of free blocks in the partition.
int minFree - The minimum number of blocks that must remain free regardless of allocation requests.

Section 5.4.10: rx stats

Used as a parameter to both AFSVolRestore() and AFSVolForward(),a restoreCookie keeps information that must be preserved between various Volume Server operations.
Fields

char name[] - The volume name, up to 32 characters long including the trailing null.
long type - The volume type, one of RWVOL, ROVOL, and BACKVOL.
long clone - The current read-only clone ID for this volume.
long parent - The parent ID for this volume.

Section 5.4.11: transDebugEntries

typedef transDebugInfo transDebugEntries<>;

This typedef is used to generate a variable-length object which is passed as a parameter to the AFSVolMonitor() interface function. Thus, it may carry any number of descriptors for active transactions on the given Volume Server. Specifi, it causes a C structure of the same name to be defined with the following fields:
Fields

u int transDebugEntries len - The number of struct transDebugInfo (see Section 5.4.7) objects appearing at the memory location pointed to by the transDebugEntries val field.
transDebugInfo *transDebugEntries val - A pointer to a region of memory containing an array of transDebugEntries len objects of type struct transDebugInfo.

Section 5.4.12: volEntries

typedef volintInfo volEntries<>;

This typedef is used to generate a variable-length object which is passed as a parameter to AFSVolListVolumes(). Thus, it may carry any number of descriptors for volumes on the given Volume Server. Specifically, it causes a C structure of the same name to be defined with the following fields:
Fields

u int volEntries len - The number of struct volintInfo (see Section 5.4.6) objects appearing at the memory location pointed to by the volEntries val field.
volintInfo *volEntries val -A pointer to a region of memory containing an array of volEntries len objects of type struct volintInfo.

Section 5.5: Macros

: The Volume Server advertises two groups of error codes. The first set consists of the standard error codes defined by the package. The second is a collection of lower-level return values which are exported here for convenience.

Name: VOLSERTRELE ERROR

Value: 1492325120L

Description: internal error releasing transaction.

Name: VOLSERNO OP

Value: 1492325121L

Description: unknown internal error.

Name: VOLSERREAD DUMPERROR

Value: 1492325122L

Description: badly formatted dump.

Name: VOLSERDUMPERROR

Value: 1492325123L

Description: badly formatted dump(2).

Name: VOLSERATTACH ERROR

Value: 1492325124L

Description: could not attach volume.

Name: VOLSERILLEGAL PARTITION

Value: 1492325125L

Description: illegal partition.

Name: VOLSERDETACH ERROR

Value: 1492325126L

Description: could not detach volume.

Name: VOLSERBAD ACCESS

Value: 1492325127L

Description: insufficient privilege for volume operation.

Name: VOLSERVLDB ERROR

Value: 1492325128L

Description: error from volume location database.

Name: VOLSERBADNAME

Value: 1492325129L

Description: bad volume name.

Name: VOLSERVOLMOVED

Value: 1492325130L

Description: volume moved.

Name: VOLSERBADOP

Value: 1492325131L

Description: illegal volume operation.

Name: VOLSERBADRELEASE

Value: 1492325132L

Description: volume release failed.

Name: VOLSERVOLBUSY

Value: 1492325133L

Description: volume still in use by volserver.

Name: VOLSERNO MEMORY

Value: 1492325134L

Description: out of virtual memory in volserver.

Name: VOLSERNOVOL

Value: 1492325135L

Description: no such volume.

Name: VOLSERMULTIRWVOL

Value: 1492325136L

Description: more than one read/write volume.

Name: VOLSERFAILEDOP

Value: 1492325137L

Description: failed volume server operation.

Section 5.5.1: field Selections/Assignments

: The error codes described in this section were defined by the Volume Server to describe exceptional conditions arising in the course of RPC call handling.

Section 5.5.2: Boolean Operations

: These error codes are duplicates of those defined from a package which is internal to the Volume Server. They are re-defined here to make them visible to Volume Server clients.

Name: VSALVAGE

Value: 101

Description: Volume needs to be salvaged.

Name: VNOVNODE

Value: 102

Description: Bad vnode number encountered.

Name: VNOVOL

Value: 103

Description: The given volume is either not attached, doesn't exist, or is not online.

Name: VVOLEXISTS

Value: 104

Description: The given volume already exists.

Name: VNOSERVICE

Value: 105

Description: The volume is currently not in service.

Name: VOFFLINE

Value: 106

Description: The specified volume is offline, for the reason given in the offline message field (a subfield within the volume field in struct volser trans).

Name: VONLINE

Value: 107

Description: Volume is already online.

Name: VDISKFULL

Value: 108

Description: The disk partition is full.

Name: VOVERQUOTA

Value: 109

Description: The given volume's maximum quota, as expressed in the maxQuota field of the struct volintInfo, has been exceeded.

Name: VBUSY

Value: 110

Description: The named volume is temporarily unavailable, and the client is encouraged to retry the operation shortly.

Name: VMOVED

Value: 111

Description: The given volume has moved to a new server.

: The VICE SPECIAL ERRORS constant is defined to be the lowest of these error codes.

Section 5.6: Functions

: The Volume Server defines a small number of macros, as described in this section.

Section 5.6.1: Exported Operations

#define THOLD(tt) ((tt)->refCount++)

: This macro is used to increment the reference count field, refCount, in an object of type struct volser trans. Thus, the associated transaction is effectively "held" insuring it won't be garbage-collected. The counterpart to this operation, TRELE(), is implemented by the Volume Server as a function.

Section 5.6.2: rx Init _ Initialize Rx

#define ISNAMEVALID(name) (strlen(name) < (VOLSER_OLDMAXVOLNAME -9))

: This macro checks to see if the given name argument is of legal length. It must be no more than the size of the container, which is at most VOLSER OLDMAXVOLNAME characters, minus the length of the longest standardized volume name postfix known to the system. That postfix is the 9-character .restored string, which is tacked on to the name of a volume that has been restored from a dump.

Section 5.7: Functions

: This section covers the Volume Server RPC interface routines, defined by and generated from the volint.xg Rxgen file. The following is a summary of the interface functions and their purpose:

Fcn Name: AFSVolCreateVolume

Description: Create a volume.

Fcn Name: AFSVolDeleteVolume

Description: Delete a volume.

Fcn Name: AFSVolNukeVolume

Description: Obliterate a volume completely.

Fcn Name: AFSVolDump

Description: Dump (i.e., save) the contents of a volume.

Fcn Name: AFSVolSignalRestore

Description: Show intention to call AFSVolRestore().

Fcn Name: AFSVolRestore

Description: Recreate a volume from a dump.

Fcn Name: AFSVolForward

Description: Dump a volume, then restore to a given server and volume.

Fcn Name: AFSVolClone

Description: Clone (and optionally purge) a volume.

Fcn Name: AFSVolReClone

Description: Re-clone a volume.

Fcn Name: AFSVolSetForwarding

Description: Set forwarding info for a moved volume.

Fcn Name: AFSVolTransCreate

Description: Create transaction for a [volume, partition].

Fcn Name: AFSVolEndTrans

Description: End a transaction.

Fcn Name: AFSVolGetFlags

Description: Get volume flags for a transaction.

Fcn Name: AFSVolSetFlags

Description: Set volume flags for a transaction.

Fcn Name: AFSVolGetName

Description: Get the volume name associated with a transaction.

Fcn Name: AFSVolGetStatus

Description: Get status of a transaction/volume.

Fcn Name: AFSVolSetIdsTypes

Description: Set header info for a volume.

Fcn Name: AFSVolSetDate

Description: Set creation date in a volume.

Fcn Name: AFSVolListPartitions

Description: Return a list of AFS partitions on a server.

Fcn Name: AFSVolPartitionInfo

Description: Get partition information.

Fcn Name: AFSVolListVolumes

Description: Return a list of volumes on the server.

Fcn Name: AFSVolListOneVolume

Description: Return header info for a single volume.

Fcn Name: AFSVolGetNthVolume

Description: Get volume header given its index.

Fcn Name: AFSVolMonitor

Description: Collect server transaction state.

There are two general comments that apply to most of the Volume Server interface routines:

1. AFS partitions are identified by integers ranging from 0 to 25, corresponding to the letters "a" through "z". By convention, AFS partitions are named /vicepx, where x is any lower-case letter.
2. Legal volume types to pass as parameters are RWVOL, ROVOL, and BACKVOL, as defined in Section 3.2.4.

Section 5.7.1: AFSVolCreateVolume - Create a

volume

int AFSVolCreateVolume(IN struct rx connection *z conn, 
                        IN long partition, 
                        IN char *name, 
                        IN long type, 
                        IN long parent, 
                        INOUT long *volid, 
                        OUT long *trans)

Description: Create a volume named name, with numerical identifier volid, and of type type. The new volume is to be placed in the specified partition for the server machine as identified by the Rx connection information pointed to by z conn. If a value of 0 is provided for the parent argument, it will be set by the Volume Server to the value of volid itself. The trans parameter is set to the Volume Location Server transaction ID corresponding to the volume created by this call, if successful. The numerical volume identifier supplied in the volid parameter must be generated beforehand by calling VL GetNewVolumeID() (see Section 3.6.5). After AFSVolCreateVolume() completes correctly, the new volume is marked as offline. It must be explicitly brought online through a call to AFSVolSetFlags() (see Section 5.7.14) while passing the trans transaction ID generated by AFSVolCreateVolume(). The "hold" on the new volume guaranteed by the trans transaction may be "released" by calling AFSVolEnd-Trans(). Until then, no other process may operate on the volume. Upon creation, a volume's maximum quota (as specified in the maxquota field of a struct volintInfo) is set to 5,000 1-Kbyte blocks. Note that the AFSVolCreateVolume() routine is the only Volume Server function that manufactures its own transaction. All others must have already acquired a transaction ID via either a previous call to AFSVolCreateVolume() or AFSVolTransCreate().

Error Codes: VOLSERBADNAME The volume name parameter was longer than 31 characters plus the trailing null.
VOLSERBAD ACCESS The caller is not authorized to create a volume.
EINVAL The type parameter was illegal. E2BIG A value of 0 was provided in the volid parameter. VOLSERVOLBUSY A transaction could not be created, thus the given volume was busy.
EIO The new volume entry could not be created.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.
<misc> If the partition parameter is unintelligible, this routine will return a low-level unix error.

Section 5.7.2: AFSVolDeleteVolume - Delete a

volume

int AFSVolDeleteVolume(IN struct rx connection *z conn, IN long trans)

Description: Delete the volume associated with the open transaction ID specified within trans. All of the file system objects contained within the given volume are destroyed, and the on-disk volume metadata structures are reclaimed. In addition, the in-memory volume descriptor's vflags field is set to VTDeleted, indicating that it has been deleted.

: Under some circumstances, a volume should be deleted by calling AFSVolNukeVolume() instead of this routine. See Section 5.7.3 for more details.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to delete a volume.
ENOENT The trans transaction was not found.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.

Section 5.7.3: AFSVolNukeVolume - Obliterate a

volume completely

int AFSVolNukeVolume(IN struct rx connection *z conn, 
                        IN long partID, 
                        IN long volID)

Description: Completely obliterate the volume living on partition partID whose ID is volID. This involves scanning all inodes on the given partition and removing those marked with the specified volID. If the volume is a read-only clone, only the header inodes are removed, since they are the only ones stamped with the read-only ID. To reclaim the space taken up by the actual data referenced through a read-only clone, this routine should be called on the read-write master. Note that calling AFSVolNukeVolume() on a read-write volume effectively destroys all the read-only volumes cloned from it, since everything except for their indicies to the (now-deleted) data will be gone.

: Under normal circumstances, it is preferable to use AFSVolDeleteVolume() instead of AFSVolNukeVolume() to delete a volume. The former is much more efficient, as it only touches those objects in the partition that belong to the named volume, walking the on-disk volume metadata structures. However, AFSVolNukeVolume() must be used in situations where the volume metadata structures are known to be damaged. Since a complete scan of all inodes in the partition is performed, all disconnected or unreferenced portions of the given volume will be reclaimed.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to call this routine.
VOLSERNOVOL The partition specified by the partID argument is illegal.

Section 5.7.4: AFSVolDump - Dump (i.e., save) the

contents of a volume

int AFSVolDump(IN struct rx connection *z conn, 
                IN long fromTrans, 
                IN long fromDate)

Description: Generate a canonical dump of the contents of the volume associated with transaction fromTrans as of calendar time fromDate. If the given fromDate is zero, then a full dump will be carried out. Otherwise, the resulting dump will be an incremental one.

: This is specified as a split function within the volint.xg Rxgen interface file. This specifies that two routines are generated, namely StartAFSVolDump() and EndAFSVolDump(). The former is used to marshall the IN arguments, and the latter is used to unmarshall the return value of the overall operation. The actual dump data appears in the Rx stream for the call (see the section entitled Example Server and Client in the companion AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure Call Facility document).

Error Codes: VOLSERBAD ACCESS The caller is not authorized to dump a volume.
ENOENT The fromTrans transaction was not found.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.

Section 5.7.5: AFSVolSignalRestore - Show

intention to call AFSVolRestore()

int AFSVolSignalRestore(IN struct rx connection *z conn, 
                        IN char *name, 
                        IN int type, 
                        IN long pid, 
                        IN long cloneid)

Description: Show an intention to the Volume Server that the client will soon call AFSVolRestore(). The parameters, namely the volume name, type, parent ID pid and clone ID cloneid are stored in a well-known set of global variables. These values are used to set the restored volume's header, overriding those values present in the dump from which the volume will be resurrected.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to call this routine.
VOLSERBADNAME The volume name contained in name was longer than 31 characters plus the trailing null.

Section 5.7.6: AFSVolRestore - Recreate a volume

from a dump

int AFSVolRestore(IN struct rx connection *z conn, 
                        IN long toTrans, 
                        IN long flags, 
                        IN struct restoreCookie *cookie)

Description: Interpret a canonical volume dump (generated as the result of calling AFSVolDumpVolume()), passing it to the volume specified by the toTrans transaction. Only the low bit in the flags argument is inspected. If this low bit is turned on, the dump will be restored as incremental; otherwise, a full restore will be carried out.

: All callbacks to the restored volume are broken.

: This is specified as a split function within the volint.xg Rxgen interface file. This specifies that two routines are generated, namely StartAFSVolRestore() and EndAFSVolRestore() . The former is used to marshall the IN arguments, and the latter is used to unmarshall the return value of the overall operation. The actual dump data flows over the Rx stream for the call (see the section entitled Example Server and Client in the companion AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure Call Facility document).

: The AFSVolSignalRestore() routine (see Section 5.7.5) should be called before invoking this function in order to signal the intention to restore a particular volume.

Error Codes: VOLSERREAD DUMPERROR Dump data being restored is corrupt.
VOLSERBAD ACCESS The caller is not authorized to restore a volume.
ENOENT The fromTrans transaction was not found.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.

Section 5.7.7: AFSVolForward - Dump a volume, then

restore to given server and volume

int AFSVolForward(IN struct rx connection *z conn, 
                        IN long fromTrans, 
                        IN long fromDate, 
                        IN struct destServer *destination, 
                        IN long destTrans, 
                        IN struct restoreCookie *cookie)

Description: Dumps the volume associated with transaction fromTrans from the given fromDate. The dump itself is sent to the server described by destination, where it is restored as the volume associated with transaction destTrans. In reality, an Rx connection is set up to the destServer, StartAFSVolRestore() directs writing to the Rx call's stream, and then EndAFSVolRestore() is used to deliver the dump for the volume corresponding to fromTrans. If a non-zero fromDate is provided, then the dump will be incremental from that date. Otherwise, a full dump will be delivered.

: The Rx connection set up for this task is always destroyed before the function returns. The destination volume should exist before carrying out this operation, and the invoking process should have started transactions on both participating volumes.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to forward a volume.
ENOENT The fromTrans transaction was not found.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.
ENOTCONN An Rx connection to the destination server could not be established.

Section 5.7.8: AFSVolClone - Clone (and optionally

purge) a volume

int AFSVolClone(IN struct rx connection *z conn, 
                IN long trans, 
                IN long purgeVol, 
                IN long newType, 
                IN char *newName, 
                INOUT long *newVol)

Description: Make a clone of the read-write volume associated with transaction trans, giving the cloned volume a name of newName. The newType parameter specifies the type for the new clone, and may be either ROVOL or BACKVOL. If purgeVol is set to a non-zero value, then that volume will be purged during the clone operation. This may be more efficient that separate clone and purge calls when making backup volumes. The newVol parameter sets the new clone's ID. It is illegal to pass a zero in newVol.

Error Codes: VOLSERBADNAME The volume name contained in newName was longer than 31 characters plus the trailing null.
VOLSERBAD ACCESS The caller is not authorized to clone a volume.
ENOENT The fromTrans transaction was not found.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.
VBUSY The given transaction was already in use; indicating that someone else is currently manipulating the specified clone.
EROFS The volume associated with the given trans is read-only (either ROVOL or BACKVOL).
EXDEV The volume associated with the trans transaction and the one specified by purgeVol must be on the same disk device, and they must be cloned from the same parent volume.
EINVAL The purgeVol must be read-only, i.e. either type ROVOL or BACKVOL.

Section 5.7.9: AFSVolReClone - Re-clone a volume

int AFSVolReClone(IN struct rx connection *z conn, 
                        IN long tid, 
                        IN long cloneID)

Description: Recreate an existing clone, with identifier cloneID, from the volume associated with transaction tid.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to clone a volume.
ENOENT The tid transaction was not found.
VOLSERTRELE ERROR The tid transaction's reference count could not be dropped to the proper level.
VBUSY The given transaction was already in use; indicating that someone else is currently manipulating the specified clone.
EROFS The volume to be cloned must be read-write (of type RWVOL).
EXDEV The volume to be cloned and the named clone itself must be on the same device. Also, cloneID must have been cloned from the volume associated with transaction tid.
EINVAL The target clone must be a read-only volume (i.e., of type ROVOL or BACKVOL).

Section 5.7.10: AFSVolSetForwarding - Set

forwarding info for a moved volume

int AFSVolSetForwarding(IN struct rx connection *z conn, 
                        IN long tid, 
                        IN long newsite)

Description: Record the IP address specified within newsite as the location of the host which now hosts the volume associated with transaction tid, formerly resident on the current host. This is intended to gently guide Cache Managers who have stale volume location cached to the volume's new site, ensuring the move is transparent to clients using that volume.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to create a forwarding address.
ENOENT The trans transaction was not found.

Section 5.7.11: AFSVolTransCreate - Create

transaction for a [volume, partition]

int AFSVolTransCreate(IN struct rx connection *z conn, 
                        IN long volume, 
                        IN long partition, 
                        IN long flags, 
                        OUT long *trans)

Description: Create a new Volume Server transaction associated with volume ID volume on partition partition. The type of volume transaction is specified by the flags parameter. The values in flags specify whether the volume should be treated as busy (ITBusy), offline (ITOffline), or in shared read-only mode (ITReadOnly). The identifier for the new transaction built by this function is returned in trans.

: Creating a transaction serves as a signal to other agents that may be interested in accessing a volume that it is unavailable while the Volume Server is manipulating it. This prevents the corruption that could result from multiple simultaneous operations on a volume.

Error Codes: EINVAL Illegal value encountered in flags.
VOLSERVOLBUSY A transaction could not be created, thus the given [volume, partition] pair was busy.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level after creation.

Section 5.7.12: AFSVolEndTrans - End a

transaction

int AFSVolEndTrans(IN struct rx connection *z conn, 
                        IN long trans, 
                        OUT long *rcode)

Description: End the transaction identified by trans, returning its final error code into rcode. This makes the associated [volume, partition] pair eligible for further Volume Server operations.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to create a transaction.
ENOENT The trans transaction was not found.

Section 5.7.13: AFSVolGetFlags - Get volume flags

for a transaction

int AFSVolGetFlags(IN struct rx connection *z conn, 
                        IN long trans, 
                        OUT long *flags)

Description: Return the value of the vflags field of the struct volser trans object describing the transaction identified as trans. The set of values placed in the flags parameter is described in Section 5.2.3.1. Briefly, they indicate whether the volume has been deleted (VTDeleted), out of service (VTOutOfService), or marked delete-on-salvage (VTDeleteOnSalvage).

Error Codes: ENOENT The trans transaction was not found.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.

Section 5.7.14: AFSVolSetFlags - Set volume flags

for a transaction

int AFSVolSetFlags(IN struct rx connection *z conn, 
                        IN long trans, 
                        IN long flags)

Description: Set the value of the vflags field of the struct volser trans object describing the transaction identified as trans to the contents of flags. The set of legal values for the flags parameter is described in Section 5.2.3.1. Briefly, they indicate whether the volume has been deleted (VTDeleted), out of service (VTOutOfService), or marked delete-onsalvage (VTDeleteOnSalvage).

Error Codes: ENOENT The trans transaction was not found.
EROFS Updates to this volume are not allowed.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.

Section 5.7.15: AFSVolGetName - Get the volume

name associated with a transaction

int AFSVolGetName(IN struct rx connection *z conn, 
                        IN long tid, 
                        OUT char **tname)

Description: Given a transaction identifier tid, return the name of the volume associated with the given transaction. The tname parameter is set to point to the address of a string buffer of at most 256 chars containing the desired information, which is created for this purpose. Note: the caller is responsible for freeing the buffer pointed to by tname when its information is no longer needed.

Error Codes: ENOENT The tid transaction was not found, or a volume was not associated with it (VSrv internal error).
E2BIG The volume name was too big (greater than or equal to SIZE (1,024) characters.
VOLSERTRELE ERROR The trans transaction's reference count could not be dropped to the proper level.

Section 5.7.16: AFSVolGetStatus - Get status of a

transaction/volume

int AFSVolGetStatus(IN struct rx connection *z conn, 
                        IN long tid, 
                        OUT struct volser status *status)

Description: This routine fills the status structure passed as a parameter with status information for the volume identified by the transaction identified by tid, if it exists. Included in this status information are the volume's ID, its type, disk quotas, the IDs of its clones and backup volumes, and several other administrative details.

Error Codes: ENOENT The tid transaction was not found.
VOLSERTRELE ERROR The tid transaction's reference count could not be dropped to the proper level.

Section 5.7.17: AFSVolSetIdsTypes - Set header

info for a volume

int AFSVolSetIdsTypes(IN struct rx connection *z conn, 
                        IN long tId 
                        IN char *name, 
                        IN long type, 
                        IN long pId, 
                        IN long cloneId, 
                        IN long backupId)

Description: The transaction identifed by tId is located, and the values supplied for the volume name, volume type, parent ID pId, clone ID cloneId and backup ID backupId are recorded into the given transaction.

Error Codes: ENOENT The tId transaction was not found.
VOLSERBAD ACCESS The caller is not authorized to call this routine.
VOLSERBADNAME The volume name contained in name was longer than 31 characters plus the trailing null.
VOLSERTRELE ERROR The tId transaction's reference count could not be dropped to the proper level.

Section 5.7.18: AFSVolSetDate - Set creation date

in a volume

int AFSVolSetDate(IN struct rx connection *z conn, 
                        IN long tid, 
                        IN long newDate)

Description: Set the creationDate of the struct volintInfo describing the volume associated with transaction tid to newDate.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to call this routine.
ENOENT The tId transaction was not found.
VOLSERTRELE ERROR The tid transaction's reference count could not be dropped to the proper level.

Section 5.7.19: AFSVolListPartitions - Return a

list of AFS partitions on a server

int AFSVolListPartitions(IN struct rx connection *z conn, 
                                OUT struct pIDs *partIDs)

Description: Return a list of AFS partitions in use by the server processing this call. The output parameter is the fixed-length partIDs array, with one slot for each of 26 possible partitions. By convention, AFS partitions are named /vicepx, where x is any letter. The /vicepa partition is represented by a zero in this array, /vicepa bya1, andsoon. Unused partitions are represented by slots filled with a -1.

Error Codes: ---None.

Section 5.7.20: AFSVolPartitionInfo - Get

partition information

int AFSVolPartitionInfo(IN struct rx connection *z conn, 
                        IN char *name, 
                        OUT struct diskPartition *partition)

Description: Collect information regarding the partition with the given character string name, and place it into the partition object provided.

Error Codes: VOLSERBAD ACCESS The caller is not authorized to call this routine.
VOLSERILLEGAL PARTITION An illegal partition was specified by name

Section 5.7.21: AFSVolListVolumes - Return a list

of volumes on the server

int AFSVolListVolumes(IN struct rx connection *z conn, 
                        IN long partID, 
                        IN long flags, 
                        OUT volEntries *resultEntries)

Description: Sweep through all the volumes on the partition identified by partid, filling in consecutive records in the resultEntries object. If the flags parameter is set to a non-zero value, then full status information is gathered. Otherwise, just the volume ID field is written for each record. The fields for a volEntries object like the one pointed to by resultEntries are described in Section 5.4.6, which covers the struct volintInfo definition.

Error Codes: VOLSERILLEGAL PARTITION An illegal partition was specified by partID
VOLSERNO MEMORY Not enough memory was available to hold all the required entries within resultEntries.

Section 5.7.22: AFSVolListOneVolume - Return

header info for a single volume

int AFSVolListOneVolume(IN struct rx connection *z conn, 
                        IN long partID, 
                        IN long volid, 
                        OUT volEntries *resultEntries)

Description: Find the information for the volume living on partition partID whose ID is volid, and place a single struct volintInfo entry within the variable-size resultEntries object.

: This is similar to the AFSVolListVolumes() call, which returns information on all volumes on the specified partition. The full volume information is always written into the returned entry (equivalent to setting the flags argument to AFSVolListVolumes() to a non-zero value).

Error Codes: VOLSERILLEGAL PARTITION An illegal partition was specified by partID
ENODEV The given volume was not found on the given partition.

header given its index

int AFSVolGetNthVolume(IN struct rx connection *z conn, 
                        IN long index, 
                        OUT long *volume, 
                        OUT long *partition)

Description: Using index as a zero-based index into the set of volumes hosted by the server chosen by the z conn argument, return the volume ID and partition of residence for the given index. This functionality has not yet been implemented.

Error Codes: VOLSERNO OP Not implemented.

transaction state

int AFSVolMonitor(IN struct rx connection *z conn, 
                        OUT transDebugEntries *result)

Description: This call allows the transaction state of a Volume Server to be monitored for debugging purposes. Anyone wishing to supervise this Volume Server state may call this routine, causing all active transactions to be recorded in the given result object.

Error Codes: ---None.