Section 5.1 Introduction
- 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: Constants
- 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: Configuration and Boundary Values
- 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: Interface Routine Opcodes
- 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: Transaction Flags
- 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: Volume Types
- 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: LWP State
- 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: States for struct vldbentry
- 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: Validity Checks
- 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: Miscellaneous
- 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: Exported Variables
- 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: Structures and Typedefs
- 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: struct volser trans
- 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: struct volDescription
- 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: struct partList
- 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: struct volser status
- 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: struct destServer
- 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: struct volintInfo
- 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: struct transDebugInfo
- 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: struct pIDs
- 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: struct diskPartition
- 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: struct restoreCookie
- 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: Error Codes
- 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: Standard
- 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: Low-Level
- 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: Macros
- The Volume Server defines a small number of macros, as described in this section.
Section 5.6.1: THOLD()
#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: ISNAMEVALID()
#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.