Unix CM: Make rootVolume array big enough
[openafs.git] / doc / protocol / vldb-vol-spec.h
1 /*!
2   \addtogroup vldb-spec VLDB Server Interface
3   @{
4
5         \page title AFS-3 Programmer's Reference: Volume Server/Volume Location
6 Server  Interface 
7
8         \author Edward R. Zayas 
9 Transarc Corporation 
10 \version 1.0
11 \date 29 August 1991 14:48 Copyright 1991 Transarc Corporation All Rights
12 Reserved FS-00-D165 
13
14
15         \page chap1 Chapter 1: Overview 
16
17         \section sec1-1 Section 1.1: Introduction 
18
19 \par
20 This document describes the architecture and interfaces for two of the
21 important agents of the AFS distributed file system, the Volume Server and the
22 Volume Location Server. The Volume Server allows operations affecting entire
23 AFS volumes to be executed, while the Volume Location Server provides a lookup
24 service for volumes, identifying the server or set of servers on which volume
25 instances reside. 
26
27         \section sec1-2 Section 1.2: Volumes 
28
29         \subsection sec1-2-1 Section 1.2.1: Definition 
30
31 \par
32 The underlying concept manipulated by the two AFS servers examined by this
33 document is the volume. Volumes are the basic mechanism for organizing the data
34 stored within the file system. They provide the foundation for addressing,
35 storing, and accessing file data, along with serving as the administrative
36 units for replication, backup, quotas, and data motion between File Servers. 
37 \par
38 Specifically, a volume is a container for a hierarchy of files, a connected
39 file system subtree. In this respect, a volume is much like a traditional unix
40 file system partition. Like a partition, a volume can be mounted in the sense
41 that the root directory of the volume can be named within another volume at an
42 AFS mount point. The entire file system hierarchy is built up in this manner,
43 using mount points to glue together the individual subtrees resident within
44 each volume. The root of this hierarchy is then mounted by each AFS client
45 machine using a conventional unix mount point within the workstation's local
46 file system. By convention, this entryway into the AFS domain is mounted on the
47 /afs local directory. From a user's point of view, there is only a single mount
48 point to the system; the internal mount points are generally transparent. 
49
50         \subsection sec1-2-2 Section 1.2.2: Volume Naming 
51
52 \par
53 There are two methods by which volumes may be named. The first is via a
54 human-readable string name, and the second is via a 32-bit numerical
55 identifier. Volume identifiers, whether string or numerical, must be unique
56 within any given cell. AFS mount points may use either representation to
57 specify the volume whose root directory is to be accessed at the given
58 position. Internally, however, AFS agents use the numerical form of
59 identification exclusively, having to translate names to the corresponding
60 32-bit value. 
61
62         \subsection sec1-2-3 Section 1.2.3: Volume Types 
63
64 \par
65 There are three basic volume types: read-write, read-only, and backup volumes. 
66 \li Read-write: The data in this volume may be both read and written by those
67 clients authorized to do so. 
68 \li Read-only: It is possible to create one or more read-only snapshots of
69 read-write volumes. The read-write volume serving as the source image is
70 referred to as the parent volume. Each read-only clone, or child, instance must
71 reside on a different unix disk partition than the other clones. Every clone
72 instance generated from the same parent read-write volume has the identical
73 volume name and numerical volume ID. This is the reason why no two clones may
74 appear on the same disk partition, as there would be no way to differentiate
75 the two. AFS clients are allowed to read files and directories from read-only
76 volumes, but cannot overwrite them individually. However, it is possible to
77 make changes to the read-write parent and then release the contents of the
78 entire volume to all the read-only replicas. The release operation fails if it
79 does not reach the appropriate replication sites. 
80 \li Backup: A backup volume is a special instance of a read-only volume. While
81 it is also a read-only snapshot of a given read-write volume, only one instance
82 is allowed to exist at any one time. Also, the backup volume must reside on the
83 same partition as the parent read-write volume from which it was created. It is
84 from a backup volume that the AFS backup system writes file system data to
85 tape. In addition, backup volumes may be mounted into the file tree just like
86 the other volume types. In fact, by convention, the backup volume for each
87 user's home directory subtree is typically mounted as OldFiles in that
88 directory. If a user accidentally deletes a file that resides in the backup
89 snapshot, the user may simply copy it out of the backup directly without the
90 assistance of a system administrator, or any kind of tape restore operation. 
91 Backup volume are implemented in a copy-on-write fashion. Thus, backup volumes
92 may be envisioned as consisting of a set of pointers to the true data objects
93 in the base read-write volume when they are first created. When a file is
94 overwritten in the read-write version for the first time after the backup
95 volume was created, the original data is physically written to the backup
96 volume, breaking the copyon-write link. With this mechanism, backup volumes
97 maintain the image of the read-write volume at the time the snapshot was taken
98 using the minimum amount of additional disk space. 
99
100         \section sec1-3 Section 1.3: Scope 
101
102 \par
103 This paper is a member of a documentation suite providing specifications of the
104 operation and interfaces offered by the various AFS servers and agents. The
105 scope of this work is to provide readers with a sufficiently detailed
106 description of the Volume Location Server and the Volume Server so that they
107 may construct client applications which call their RPC interface routines. 
108
109         \section sec1-4 Section 1.4: Document Layout 
110
111 \par
112 After this introductory portion of the document, Chapters 2 and 3 examine the
113 architecture and RPC interface of the Volume Location Server and its replicated
114 database. Similarly, Chapters 4 and 5 describe the architecture and RPC
115 interface of the Volume Server. 
116
117         \page chap2 Chapter 2: Volume Location Server Architecture 
118
119         \section sec2-1 Section 2.1: Introduction 
120
121 \par
122 The Volume Location Server allows AFS agents to query the location and basic
123 status of volumes resident within the given cell. Volume Location Server
124 functions may be invoked directly from authorized users via the vos utility. 
125 \par
126 This chapter briefly discusses various aspects of the Volume Location Server's
127 architecture. First, the need for volume location is examined, and the specific
128 parties that call the Volume Location Server interface routines are identified.
129 Then, the database maintained to provide volume location service, the Volume
130 Location Database (VLDB), is examined. Finally, the vlserver process which
131 implements the Volume Location Server is considered. 
132 \par
133 As with all AFS servers, the Volume Location Server uses the Rx remote
134 procedure call package for communication with its clients. 
135
136         \section sec2-2 Section 2.2: The Need For Volume Location 
137
138 \par
139 The Cache Manager agent is the primary consumer of AFS volume location service,
140 on which it is critically dependent for its own operation. The Cache Manager
141 needs to map volume names or numerical identifiers to the set of File Servers
142 on which its instances reside in order to satisfy the file system requests it
143 is processing on behalf of it clients. Each time a Cache Manager encounters a
144 mount point for which it does not have location information cached, it must
145 acquire this information before the pathname resolution may be successfully
146 completed. Once the File Server set is known for a particular volume, the Cache
147 Manager may then select the proper site among them (e.g. choosing the single
148 home for a read-write volume, or randomly selecting a site from a read-only
149 volume's replication set) and begin addressing its file manipulation operations
150 to that specific server. 
151 \par
152 While the Cache Manager consults the volume location service, it is not capable
153 of changing the location of volumes and hence modifying the information
154 contained therein. This capability to perform acts which change volume location
155 is concentrated within the Volume Server. The Volume Server process running on
156 each server machine manages all volume operations affecting that platform,
157 including creations, deletions, and movements between servers. It must update
158 the volume location database every time it performs one of these actions. 
159 \par
160 None of the other AFS system agents has a need to access the volume location
161 database for its site. Surprisingly, this also applies to the File Server
162 process. It is only aware of the specific set of volumes that reside on the set
163 of physical disks directly attached to the machine on which they execute. It
164 has no knowlege of the universe of volumes resident on other servers, either
165 within its own cell or in foreign cells. 
166
167         \section sec2-3 Section 2.3: The VLDB 
168
169 \par
170 The Volume Location Database (VLDB) is used to allow AFS application programs
171 to discover the location of any volume within its cell, along with select
172 information about the nature and state of that volume. It is organized in a
173 very straightforward fashion, and uses the ubik [4] [5] facility to to provide
174 replication across multiple server sites. 
175
176         \subsection sec2-3-1 Section 2.3.1: Layout 
177
178 \par
179 The VLDB itself is a very simple structure, and synchronized copies may be
180 maintained at two or more sites. Basically, each copy consists of header
181 information, followed by a linear (yet unbounded) array of entries. There are
182 several associated hash tables used to perform lookups into the VLDB. The first
183 hash table looks up volume location information based on the volume's name.
184 There are three other hash tables used for lookup, based on volume ID/type
185 pairs, one for each possible volume type. 
186 \par
187 The VLDB for a large site may grow to contain tens of thousands of entries, so
188 some attempts were made to make each entry as small as possible. For example,
189 server addresses within VLDB entries are represented as single-byte indicies
190 into a table containing the full longword IP addresses. 
191 \par
192 A free list is kept for deleted VLDB entries. The VLDB will not grow unless all
193 the entries on the free list have been exhausted, keeping it as compact as
194 possible. 
195
196         \subsection sec2-3-2 Section 2.3.2: Database Replication 
197
198 \par
199 The VLDB, along with other important AFS databases, may be replicated to
200 multiple sites to improve its availability. The ubik replication package is
201 used to implement this functionality for the VLDB. A full description of ubik
202 and of the quorum completion algorithm it implements may be found in [4] and
203 [5]. The basic abstraction provided by ubik is that of a disk file replicated
204 to multiple server locations. One machine is considered to be the
205 synchronization site, handling all write operations on the database file. Read
206 operations may be directed to any of the active members of the quorum, namely a
207 subset of the replication sites large enough to insure integrity across such
208 failures as individual server crashes and network partitions. All of the quorum
209 members participate in regular elections to determine the current
210 synchronization site. The ubik algorithms allow server machines to enter and
211 exit the quorum in an orderly and consistent fashion. All operations to one of
212 these replicated "abstract files" are performed as part of a transaction. If
213 all the related operations performed under a transaction are successful, then
214 the transaction is committed, and the changes are made permanent. Otherwise,
215 the transaction is aborted, and all of the operations for that transaction are
216 undone. 
217
218         \section sec2-4 Section 2.4: The vlserver Process 
219
220 \par
221 The user-space vlserver process is in charge of providing volume location
222 service for AFS clients. This program maintains the VLDB replica at its
223 particular server, and cooperates with all other vlserver processes running in
224 the given cell to propagate updates to the database. It implements the RPC
225 interface defined in the vldbint.xg definition file for the rxgen RPC stub
226 generator program. As part of its startup sequence, it must discover the VLDB
227 version it has on its local disk, move to join the quorum of replication sites
228 for the VLDB, and get the latest version if the one it came up with was out of
229 date. Eventually, it will synchronize with the other VLDB replication sites,
230 and it will begin accepting calls. 
231 \par
232 The vlserver program uses at most three Rx worker threads to listen for
233 incoming Volume Location Server calls. It has a single, optional command line
234 argument. If the string "-noauth" appears when the program is invoked, then
235 vlserver will run in an unauthenticated mode where any individual is considered
236 authorized to perform any VLDB operation. This mode is necessary when first
237 bootstrapping an AFS installation. 
238
239         \page chap3 Chapter 3: Volume Location Server Interface 
240
241         \section sec3-1 Section 3.1: Introduction 
242
243 \par
244 This chapter documents the API for the Volume Location Server facility, as
245 defined by the vldbint.xg Rxgen interface file and the vldbint.h include file.
246 Descriptions of all the constants, structures, macros, and interface functions
247 available to the application programmer appear here. 
248 \par
249 It is expected that Volume Location Server client programs run in user space,
250 as does the associated vos volume utility. However, the kernel-resident Cache
251 Manager agent also needs to call a subset of the Volume Location Server's RPC
252 interface routines. Thus, a second Volume Location Server interface is
253 available, built exclusively to satisfy the Cache Manager's limited needs. This
254 subset interface is defined by the afsvlint.xg Rxgen interface file, and is
255 examined in the final section of this chapter. 
256
257         \section sec3-2 3.2: Constants 
258
259 \par
260 This section covers the basic constant definitions of interest to the Volume
261 Location Server application programmer. These definitions appear in the
262 vldbint.h file, automatically generated from the vldbint.xg Rxgen interface
263 file, and in vlserver.h. 
264 \par
265 Each subsection is devoted to describing the constants falling into the
266 following categories: 
267 \li Configuration and boundary quantities 
268 \li Update entry bits 
269 \li List-by-attribute bits 
270 \li Volume type indices 
271 \li States for struct vlentry 
272 \li States for struct vldbentry 
273 \li ReleaseType argument values 
274 \li Miscellaneous items 
275
276         \subsection sec3-2-1 Section 3.2.1: Configuration and Boundary
277 Quantities 
278
279 \par
280 These constants define some basic system values, including configuration
281 information. 
282
283 \par Name
284 MAXNAMELEN
285 \par Value
286 65
287 \par Description
288 Maximum size of various character strings, including volume name fields in
289 structures and host names.
290
291 \par Name
292 MAXNSERVERS
293 \par Value
294 8
295 \par Description
296 Maximum number of replications sites for a volume.
297
298 \par Name
299 MAXTYPES
300 \par Value
301 3
302 \par Description
303 Maximum number of volume types.
304
305 \par Name
306 VLDBVERSION
307 \par Value
308 1
309 \par Description
310 VLDB database version number
311
312 \par Name
313 HASHSIZE
314 \par Value
315 8,191
316 \par Description
317 Size of internal Volume Location Server volume name and volume ID hash tables.
318 This must always be a prime number.
319
320 \par Name
321 NULLO
322 \par Value
323 0
324 \par Description
325 Specifies a null pointer value.
326
327 \par Name
328 VLDBALLOCCOUNT
329 \par Value
330 40
331 \par Description
332 Value used when allocating memory internally for VLDB entry records.
333
334 \par Name
335 BADSERVERID
336 \par Value
337 255
338 \par Description
339 Illegal Volume Location Server host ID.
340
341 \par Name
342 MAXSERVERID
343 \par Value
344 30
345 \par Description
346 Maximum number of servers appearing in the VLDB.
347
348 \par Name
349 MAXSERVERFLAG
350 \par Value
351 0x80
352 \par Description
353 First unused flag value in such fields as serverFlags in struct vldbentry and
354 RepsitesNewFlags in struct VldbUpdateEntry.
355
356 \par Name
357 MAXPARTITIONID
358 \par Value
359 126
360 \par Description
361 Maximum number of AFS disk partitions for any one server.
362
363 \par Name
364 MAXBUMPCOUNT
365 \par Value
366 0x7fffffff
367 \par Description
368 Maximum interval that the current high-watermark value for a volume ID can be
369 increased in one operation.
370
371 \par Name
372 MAXLOCKTIME
373 \par Value
374 0x7fffffff
375 \par Description
376 Maximum number of seconds that any VLDB entry can remain locked.
377
378 \par Name
379 SIZE
380 \par Value
381 1,024
382 \par Description
383 Maximum size of the name field within a struct.
384
385         \subsection sec3-2-2 Section 3.2.2: Update Entry Bits 
386
387 \par
388 These constants define bit values for the Mask field in the struct
389 VldbUpdateEntry. Specifically, setting these bits is equivalent to declaring
390 that the corresponding field within an object of type struct VldbUpdateEntry
391 has been set. For example, setting the VLUPDATE VOLUMENAME flag in Mask
392 indicates that the name field contains a valid value. 
393
394 \par Name
395 VLUPDATE VOLUMENAME
396 \par Value
397 0x0001
398 \par Description
399 If set, indicates that the name field is valid.
400
401 \par Name
402 VLUPDATE VOLUMETYPE
403 \par Value
404 0x0002
405 \par Description
406 If set, indicates that the volumeType field is valid.
407
408 \par Name
409 VLUPDATE FLAGS
410 \par Value
411 0x0004
412 \par Description
413 If set, indicates that the flags field is valid.
414
415 \par Name
416 VLUPDATE READONLYID
417 \par Value
418 0x0008
419 \par Description
420 If set, indicates that the ReadOnlyId field is valid.
421
422 \par Name
423 VLUPDATE BACKUPID
424 \par Value
425 0x0010
426 \par Description
427 If set, indicates that the BackupId field is valid.
428
429 \par Name
430 VLUPDATE REPSITES 
431 \par Value
432 0x0020
433 \par Description
434 If set, indicates that the nModifiedRepsites field is valid.
435
436 \par Name
437 VLUPDATE CLONEID
438 \par Value
439 0x0080
440 \par Description
441 If set, indicates that the cloneId field is valid.
442
443 \par Name
444 VLUPDATE REPS DELETE
445 \par Value
446 0x0100
447 \par Description
448 Is the replica being deleted?
449
450 \par Name
451 VLUPDATE REPS ADD
452 \par Value
453 0x0200
454 \par Description
455 Is the replica being added?
456
457 \par Name
458 VLUPDATE REPS MODSERV
459 \par Value
460 0x0400
461 \par Description
462 Is the server part of the replica location correct?
463
464 \par Name
465 VLUPDATE REPS MODPART
466 \par Value
467 0x0800
468 \par Description
469 Is the partition part of the replica location correct?
470
471 \par Name
472 VLUPDATE REPS MODFLAG 
473 \par Value
474 0x1000 
475 \par Description
476 Various modification flag values.
477
478         \subsection sec3-2-3 Section 3.2.3: List-By-Attribute Bits 
479
480 \par
481 These constants define bit values for the Mask field in the struct
482 VldbListByAttributes is to be used in a match. Specifically, setting these bits
483 is equivalent to declaring that the corresponding field within an object of
484 type struct VldbListByAttributes is set. For example, setting the VLLIST SERVER
485 flag in Mask indicates that the server field contains a valid value. 
486
487 \par Name
488 VLLIST SERVER
489 \par Value
490 0x1
491 \par Description
492 If set, indicates that the server field is valid.
493
494 \par Name
495 VLLIST PARTITION
496 \par Value
497 0x2
498 \par Description
499 If set, indicates that the partition field is valid.
500
501 \par Name
502 VLLIST VOLUMETYPE
503 \par Value
504 0x4
505 \par Description
506 If set, indicates that the volumetype field is valid.
507
508 \par Name
509 VLLIST VOLUMEID
510 \par Value
511 0x8
512 \par Description
513 If set, indicates that the volumeid field is valid.
514
515 \par Name
516 VLLIST FLAG
517 \par Value
518 0x10
519 \par Description
520 If set, indicates that that flag field is valid.
521
522         \subsection sec3-2-4 Section 3.2.4: Volume Type Indices 
523
524 \par
525 These constants specify the order of entries in the volumeid array in an object
526 of type struct vldbentry. They also identify the three different types of
527 volumes in AFS. 
528
529 \par Name
530 RWVOL
531 \par Value
532 0
533 \par Description
534 Read-write volume.
535
536 \par Name
537 ROVOL
538 \par Value
539 1
540 \par Description
541 Read-only volume.
542
543 \par Name
544 BACKVOL 
545 \par Value
546 2
547 \par Description
548 Backup volume.
549
550         \subsection sec3-2-5 Section 3.2.5: States for struct vlentry 
551
552 \par
553 The following constants appear in the flags field in objects of type struct
554 vlentry. The first three values listed specify the state of the entry, while
555 all the rest stamp the entry with the type of an ongoing volume operation, such
556 as a move, clone, backup, deletion, and dump. These volume operations are the
557 legal values to provide to the voloper parameter of the VL SetLock() interface
558 routine. 
559 \par
560 For convenience, the constant VLOP ALLOPERS is defined as the inclusive OR of
561 the above values from VLOP MOVE through VLOP DUMP. 
562
563 \par Name
564 VLFREE
565 \par Value
566 0x1
567 \par Description
568 Entry is in the free list.
569
570 \par Name
571 VLDELETED
572 \par Value
573 0x2
574 \par Description
575 Entry is soft-deleted.
576
577 \par Name
578 VLLOCKED
579 \par Value
580 0x4
581 \par Description
582 Advisory lock held on the entry.
583
584 \par Name
585 VLOP MOVE
586 \par Value
587 0x10
588 \par Description
589 The associated volume is being moved between servers.
590
591 \par Name
592 VLOP RELEASE
593 \par Value
594 0x20
595 \par Description
596 The associated volume is being cloned to its replication sites.
597
598 \par Name
599 VLOP BACKUP
600 \par Value
601 0x40
602 \par Description
603 A backup volume is being created for the associated volume.
604
605 \par Name
606 VLOP DELETE
607 \par Value
608 0x80
609 \par Description
610 The associated volume is being deleted.
611
612 \par Name
613 VLOP DUMP
614 \par Value
615 0x100 
616 \par Description
617 A dump is being taken of the associated volume.
618
619         \subsection sec3-2-6 Section 3.2.6: States for struct vldbentry 
620
621 \par
622 Of the following constants, the first three appear in the flags field within an
623 object of type struct vldbentry, advising of the existence of the basic volume
624 types for the given volume, and hence the validity of the entries in the
625 volumeId array field. The rest of the values provided in this table appear in
626 the serverFlags array field, and apply to the instances of the volume appearing
627 in the various replication sites. 
628 \par
629 This structure appears in numerous Volume Location Server interface calls,
630 namely VL CreateEntry(), VL GetEntryByID(), VL GetEntryByName(), VL
631 ReplaceEntry() and VL ListEntry(). 
632
633 \par Name
634 VLF RWEXISTS
635 \par Value
636 0x1000
637 \par Description
638 The read-write volume ID is valid.
639
640 \par Name
641 VLF ROEXISTS
642 \par Value
643 0x2000
644 \par Description
645 The read-only volume ID is valid.
646
647 \par Name
648 VLF BACKEXISTS
649 \par Value
650 0x4000
651 \par Description
652 The backup volume ID is valid.
653
654 \par Name
655 VLSF NEWREPSITE
656 \par Value
657 0x01
658 \par Description
659 Not used; originally intended to mark an entry as belonging to a
660 partially-created volume instance.
661
662 \par Name
663 VLSF ROVOL
664 \par Value
665 0x02
666 \par Description
667 A read-only version of the volume appears at this server.
668
669 \par Name
670 VLSF RWVOL
671 \par Value
672 0x02
673 \par Description
674 A read-write version of the volume appears at this server.
675
676 \par Name
677 VLSF BACKVOL
678 \par Value
679 0x08
680 \par Description
681 A backup version of the volume appears at this server. 
682
683         \subsection sec3-2-7 Section 3.2.7: ReleaseType Argument Values 
684
685 \par
686 The following values are used in the ReleaseType argument to various Volume
687 Location Server interface routines, namely VL ReplaceEntry(), VL UpdateEntry()
688 and VL ReleaseLock(). 
689
690 \par Name
691 LOCKREL TIMESTAMP
692 \par Value
693 1
694 \par Description
695 Is the LockTimestamp field valid?
696
697 \par Name
698 LOCKREL OPCODE
699 \par Value
700 2
701 \par Description
702 Are any of the bits valid in the flags field?
703
704 \par Name
705 LOCKREL AFSID
706 \par Value
707 4
708 \par Description
709 Is the LockAfsId field valid?
710
711         \subsection sec3-2-8 Section 3.2.8: Miscellaneous 
712
713 \par
714 Miscellaneous values. 
715 \par Name
716 VLREPSITE NEW   
717 \par Value
718 1       
719 \par Description
720 Has a replication site gotten a new release of a volume? 
721 \par 
722 A synonym for this constant is VLSF NEWREPSITE. 
723
724         \section sec3-3 Section 3.3: Structures and Typedefs 
725
726 \par
727 This section describes the major exported Volume Location Server data
728 structures of interest to application programmers, along with the typedefs
729 based upon those structures. 
730
731         \subsection sec3-3-1 Section 3.3.1: struct vldbentry 
732
733 \par
734 This structure represents an entry in the VLDB as made visible to Volume
735 Location Server clients. It appears in numerous Volume Location Server
736 interface calls, namely VL CreateEntry(), VL GetEntryByID(), VL
737 GetEntryByName(), VL ReplaceEntry() and VL ListEntry(). 
738 \n \b Fields 
739 \li char name[] - The string name for the volume, with a maximum length of
740 MAXNAMELEN (65) characters, including the trailing null. 
741 \li long volumeType - The volume type, one of RWVOL, ROVOL, or BACKVOL. 
742 \li long nServers - The number of servers that have an instance of this volume. 
743 \li long serverNumber[] - An array of indices into the table of servers,
744 identifying the sites holding an instance of this volume. There are at most
745 MAXNSERVERS (8) of these server sites allowed by the Volume Location Server. 
746 \li long serverPartition[] - An array of partition identifiers, corresponding
747 directly to the serverNumber array, specifying the partition on which each of
748 those volume instances is located. As with the serverNumber array,
749 serverPartition has up to MAXNSERVERS (8) entries. 
750 \li long serverFlags[] - This array holds one flag value for each of the
751 servers in the previous arrays. Again, there are MAXNSERVERS (8) slots in this
752 array. 
753 \li u long volumeId[] - An array of volume IDs, one for each volume type. There
754 are MAXTYPES slots in this array. 
755 \li long cloneId - This field is used during a cloning operation. 
756 \li long flags - Flags concerning the status of the fields within this
757 structure; see Section 3.2.6 for the bit values that apply. 
758
759         \subsection sec3-3-2 Section 3.3.2: struct vlentry 
760
761 \par
762 This structure is used internally by the Volume Location Server to fully
763 represent a VLDB entry. The client-visible struct vldbentry represents merely a
764 subset of the information contained herein. 
765 \n \b Fields 
766 \li u long volumeId[] - An array of volume IDs, one for each of the MAXTYPES of
767 volume types. 
768 \li long flags - Flags concerning the status of the fields within this
769 structure; see Section 3.2.6 for the bit values that apply. 
770 \li long LockAfsId - The individual who locked the entry.  This feature has not
771 yet been implemented. 
772 \li long LockTimestamp - Time stamp on the entry lock. 
773 \li long cloneId - This field is used during a cloning operation. 
774 \li long AssociatedChain - Pointer to the linked list of associated VLDB
775 entries. 
776 \li long nextIdHash[] - Array of MAXTYPES next pointers for the ID hash table
777 pointer, one for each related volume ID. 
778 \li long nextNameHash - Next pointer for the volume name hash table. 
779 \li long spares1[] - Two longword spare fields. 
780 \li char name[] - The volume's string name, with a maximum of MAXNAMELEN (65)
781 characters, including the trailing null. 
782 \li u char volumeType - The volume's type, one of RWVOL, ROVOL, or BACKVOL. 
783 \li u char serverNumber[] - An array of indices into the table of servers,
784 identifying the sites holding an instance of this volume. There are at most
785 MAXNSERVERS (8) of these server sites allowed by the Volume Location Server. 
786 \li u char serverPartition[] - An array of partition identifiers, corresponding
787 directly to the serverNumber array, specifying the partition on which each of
788 those volume instances is located. As with the serverNumber array,
789 serverPartition has up to MAXNSERVERS (8) entries. 
790 \li u char serverFlags[] - This array holds one flag value for each of the
791 servers in the previous arrays. Again, there are MAXNSERVERS (8) slots in this
792 array. 
793 \li u char RefCount - Only valid for read-write volumes, this field serves as a
794 reference count, basically the number of dependent children volumes. 
795 \li char spares2[] - This field is used for 32-bit alignment. 
796
797         \subsection sec3-3-3 Section 3.3.3: struct vital vlheader 
798
799 \par
800 This structure defines the leading section of the VLDB header, of type struct
801 vlheader. It contains frequently-used global variables and general statistics
802 information. 
803 \n \b Fields 
804 \li long vldbversion - The VLDB version number. This field must appear first in
805 the structure. 
806 \li long headersize - The total number of bytes in the header. 
807 \li long freePtr - Pointer to the first free enry in the free list, if any. 
808 \li long eofPtr - Pointer to the first free byte in the header file. 
809 \li long allocs - The total number of calls to the internal AllocBlock()
810 function directed at this file. 
811 \li long frees - The total number of calls to the internal FreeBlock() function
812 directed at this file. 
813 \li long MaxVolumeId - The largest volume ID ever granted for this cell. 
814 \li long totalEntries[] - The total number of VLDB entries by volume type in
815 the VLDB. This array has MAXTYPES slots, one for each volume type. 
816
817         \subsection sec3-3-4 Section 3.3.4: struct vlheader 
818
819 \par
820 This is the layout of the information stored in the VLDB header. Notice it
821 includes an object of type struct vital vlheader described above (see Section
822 3.3.3) as the first field. 
823 \n \b Fields 
824 \li struct vital vlheader vital header - Holds critical VLDB header
825 information. 
826 \li u long IpMappedAddr[] - Keeps MAXSERVERID+1 mappings of IP addresses to
827 relative ones. 
828 \li long VolnameHash[] - The volume name hash table, with HASHSIZE slots. 
829 \li long VolidHash[][] - The volume ID hash table. The first dimension in this
830 array selects which of the MAXTYPES volume types is desired, and the second
831 dimension actually implements the HASHSIZE hash table buckets for the given
832 volume type. 
833
834         \subsection sec3-3-5 Section 3.3.5: struct VldbUpdateEntry 
835
836 \par
837 This structure is used as an argument to the VL UpdateEntry() routine (see
838 Section 3.6.7). Please note that multiple entries can be updated at once by
839 setting the appropriate Mask bits. The bit values for this purpose are defined
840 in Section 3.2.2. 
841 \n \b Fields 
842 \li u long Mask - Bit values determining which fields are to be affected by the
843 update operation. 
844 \li char name[] - The volume name, up to MAXNAMELEN (65) characters including
845 the trailing null. 
846 \li long volumeType - The volume type. 
847 \li long flags - This field is used in conjuction with Mask (in fact, one of
848 the Mask bits determines if this field is valid) to choose the valid fields in
849 this record. 
850 \li u long ReadOnlyId - The read-only ID. 
851 \li u long BackupId - The backup ID. 
852 \li long cloneId - The clone ID. 
853 \li long nModifiedRepsites - Number of replication sites whose entry is to be
854 changed as below. 
855 \li u long RepsitesMask[] - Array of bit masks applying to the up to
856 MAXNSERVERS (8) replication sites involved. 
857 \li long RepsitesTargetServer[] - Array of target servers for the operation, at
858 most MAXNSERVERS (8) of them. 
859 \li long RepsitesTargetPart[] - Array of target server partitions for the
860 operation, at most MAXNSERVERS (8) of them. 
861 \li long RepsitesNewServer[] - Array of new server sites, at most MAXNSERVERS
862 (8) of them. 
863 \li long RepsitesNewPart[] - Array of new server partitions for the operation,
864 at most MAXNSERVERS (8) of them. 
865 \li long RepsitesNewFlags[] - Flags applying to each of the new sites, at most
866 MAXNSERVERS (8) of them. 
867
868         \subsection sec3-3-6 Section 3.3.6: struct VldbListByAttributes 
869
870 \par
871 This structure is used by the VL ListAttributes() routine (see Section 3.6.11). 
872 \n \b Fields 
873 \li u long Mask - Bit mask used to select the following attribute fields on
874 which to match. 
875 \li long server - The server address to match. 
876 \li long partition - The partition ID to match. 
877 \li long volumetype - The volume type to match. 
878 \li long volumeid - The volume ID to match. 
879 \li long flag - Flags concerning these values. 
880
881         \subsection sec3-3-7 Section 3.3.7: struct single vldbentry 
882
883 \par
884 This structure is used to construct the vldblist object (See Section 3.3.12),
885 which basically generates a queueable (singly-linked) version of struct
886 vldbentry. 
887 \n \b Fields 
888 \li vldbentry VldbEntry - The VLDB entry to be queued. 
889 \li vldblist next vldb - The next pointer in the list. 
890
891         \subsection sec3-3-8 Section 3.3.8: struct vldb list 
892
893 \par
894 This structure defines the item returned in linked list form from the VL
895 LinkedList() function (see Section 3.6.12). This same object is also returned
896 in bulk form in calls to the VL ListAttributes() routine (see Section 3.6.11). 
897 \n \b Fields 
898 \li vldblist node - The body of the first object in the linked list. 
899
900         \subsection sec3-3-9 Section 3.3.9: struct vldstats 
901
902 \par
903 This structure defines fields to record statistics on opcode hit frequency. The
904 MAX NUMBER OPCODES constant has been defined as the maximum number of opcodes
905 supported by this structure, and is set to 30. 
906 \n \b Fields 
907 \li unsigned long start time - Clock time when opcode statistics were last
908 cleared. 
909 \li long requests[] - Number of requests received for each of the MAX NUMBER
910 OPCODES opcode types. 
911 \li long aborts[] - Number of aborts experienced for each of the MAX NUMBER
912 OPCODES opcode types. 
913 \li long reserved[] - These five longword fields are reserved for future use. 
914
915         \subsection sec3-3-10 Section 3.3.10: bulk 
916
917 \code
918 typedef opaque bulk<DEFAULTBULK>; 
919 \endcode
920 \par
921 This typedef may be used to transfer an uninterpreted set of bytes across the
922 Volume Location Server interface. It may carry up to DEFAULTBULK (10,000)
923 bytes. 
924 \n \b Fields 
925 \li bulk len - The number of bytes contained within the data pointed to by the
926 next field. 
927 \li bulk val - A pointer to a sequence of bulk len bytes. 
928
929         \subsection sec3-3-11 Section 3.3.11: bulkentries 
930
931 \code
932 typedef vldbentry bulkentries<>; 
933 \endcode
934 \par
935 This typedef is used to transfer an unbounded number of struct vldbentry
936 objects. It appears in the parameter list for the VL ListAttributes() interface
937 function. 
938 \n \b Fields 
939 \li bulkentries len - The number of vldbentry structures contained within the
940 data pointed to by the next field. 
941 \li bulkentries val - A pointer to a sequence of bulkentries len vldbentry
942 structures. 
943
944         \subsection sec3-3-12 Section 3.3.12: vldblist 
945
946 \code
947 typedef struct single_vldbentry *vldblist; 
948 \endcode
949 \par
950 This typedef defines a queueable struct vldbentry object, referenced by the
951 single vldbentry typedef as well as struct vldb list. 
952
953         \subsection sec3-3-13 Section 3.3.13: vlheader 
954
955 \code
956 typedef struct vlheader vlheader; 
957 \endcode
958 \par
959 This typedef provides a short name for objects of type struct vlheader (see
960 Section 3.3.4). 
961
962         \subsection sec3-3-14 Section 3.3.14: vlentry 
963
964 \code
965 typedef struct vlentry vlentry; 
966 \endcode
967 \par
968 This typedef provides a short name for objects of type struct vlentry (see
969 Section 3.3.2). 
970
971         \section sec3-4 Section 3.4: Error Codes 
972
973 \par
974 This section covers the set of error codes exported by the Volume Location
975 Server, displaying the printable phrases with which they are associated. 
976
977 \par Name
978 VL IDEXIST
979 \par Value
980 (363520L)
981 \par Description
982 Volume Id entry exists in vl database.
983
984 \par Name
985 VL IO
986 \par Value
987 (363521L)
988 \par Description
989 I/O related error.
990
991 \par Name
992 VL NAMEEXIST
993 \par Value
994 (363522L)
995 \par Description
996 Volume name entry exists in vl database.
997
998 \par Name
999 VL CREATEFAIL
1000 \par Value
1001 (363523L)
1002 \par Description
1003 Internal creation failure.
1004
1005 \par Name
1006 VL NOENT
1007 \par Value
1008 (363524L)
1009 \par Description
1010 No such entry.
1011
1012 \par Name
1013 VL EMPTY
1014 \par Value
1015 (363525L)
1016 \par Description
1017 Vl database is empty.
1018
1019 \par Name
1020 VL ENTDELETED
1021 \par Value
1022 (363526L)
1023 \par Description
1024 Entry is deleted (soft delete).
1025
1026 \par Name
1027 VL BADNAME
1028 \par Value
1029 (363527L)
1030 \par Description
1031 Volume name is illegal.
1032
1033 \par Name
1034 VL BADINDEX
1035 \par Value
1036 (363528L)
1037 \par Description
1038 Index is out of range.
1039
1040 \par Name
1041 VL BADVOLTYPE
1042 \par Value
1043 (363529L)
1044 \par Description
1045 Bad volume range.
1046
1047 \par Name
1048 VL BADSERVER
1049 \par Value
1050 (363530L)
1051 \par Description
1052 Illegal server number (out of range).
1053
1054 \par Name
1055 VL BADPARTITION
1056 \par Value
1057 (363531L)
1058 \par Description
1059 Bad partition number.
1060
1061 \par Name
1062 VL REPSFULL
1063 \par Value
1064 (363532L)
1065 \par Description
1066 Run out of space for Replication sites.
1067
1068 \par Name
1069 VL NOREPSERVER
1070 \par Value
1071 (363533L)
1072 \par Description
1073 No such Replication server site exists.
1074
1075 \par Name
1076 VL DUPREPSERVER
1077 \par Value
1078 (363534L)
1079 \par Description
1080 Replication site already exists.
1081
1082 \par Name
1083 RL RWNOTFOUND
1084 \par Value
1085 (363535L)
1086 \par Description
1087 Parent R/W entry not found.
1088
1089 \par Name
1090 VL BADREFCOUNT
1091 \par Value
1092 (363536L)
1093 \par Description
1094 Illegal Reference Count number.
1095
1096 \par Name
1097 VL SIZEEXCEEDED
1098 \par Value
1099 (363537L)
1100 \par Description
1101 Vl size for attributes exceeded.
1102
1103 \par Name
1104 VL BADENTRY
1105 \par Value
1106 (363538L)
1107 \par Description
1108 Bad incoming vl entry.
1109
1110 \par Name
1111 VL BADVOLIDBUMP
1112 \par Value
1113 (363539L)
1114 \par Description
1115 Illegal max volid increment.
1116
1117 \par Name
1118 VL IDALREADYHASHED
1119 \par Value
1120 (363540L)
1121 \par Description
1122 RO/BACK id already hashed.
1123
1124 \par Name
1125 VL ENTRYLOCKED
1126 \par Value
1127 (363541L)
1128 \par Description
1129 Vl entry is already locked.
1130
1131 \par Name
1132 VL BADVOLOPER
1133 \par Value
1134 (363542L)
1135 \par Description
1136 Bad volume operation code.
1137
1138 \par Name
1139 VL BADRELLOCKTYPE
1140 \par Value
1141 (363543L)
1142 \par Description
1143 Bad release lock type.
1144
1145 \par Name
1146 VL RERELEASE
1147 \par Value
1148 (363544L)
1149 \par Description
1150 Status report: last release was aborted.
1151
1152 \par Name
1153 VL BADSERVERFLAG
1154 \par Value
1155 (363545L)
1156 \par Description
1157 Invalid replication site server flag.
1158
1159 \par Name
1160 VL PERM
1161 \par Value
1162 (363546L)
1163 \par Description
1164 No permission access.
1165
1166 \par Name
1167 VL NOMEM
1168 \par Value
1169 (363547L) 
1170 \par Description
1171 malloc(realloc) failed to alloc enough memory. 
1172
1173         \section sec3-5 Section 3.5: Macros 
1174
1175 \par
1176 The Volume Location Server defines a small number of macros, as described in
1177 this section. They are used to update the internal statistics variables and to
1178 compute offsets into character strings. All of these macros really refer to
1179 internal operations, and strictly speaking should not be exposed in this
1180 interface. 
1181
1182         \subsection sec3-5-1 Section 3.5.1: COUNT REQ() 
1183
1184 \code
1185 #define COUNT_REQ(op) 
1186 static int this_op = op-VL_LOWEST_OPCODE; 
1187 dynamic_statistics.requests[this_op]++ 
1188 \endcode
1189 \par
1190 Bump the appropriate entry in the variable maintaining opcode usage statistics
1191 for the Volume Location Server. Note that a static variable is set up to record
1192 this op, namely the index into the opcode monitoring array. This static
1193 variable is used by the related COUNT ABO() macro defined below. 
1194
1195         \subsection sec3-5-2 Section 3.5.2: COUNT ABO() 
1196
1197 \code
1198 #define COUNT_ABO dynamic_statistics.aborts[this_op]++ 
1199 \endcode
1200 \par
1201 Bump the appropriate entry in the variable maintaining opcode abort statistics
1202 for the Volume Location Server. Note that this macro does not take any
1203 arguemnts. It expects to find a this op variable in its environment, and thus
1204 depends on its related macro, COUNT REQ() to define that variable. 
1205
1206         \subsection sec3-5-3 Section 3.5.3: DOFFSET() 
1207
1208 \code
1209 #define DOFFSET(abase, astr, aitem) ((abase)+(((char *)(aitem)) -((char
1210 *)(astr)))) 
1211 \endcode
1212 \par
1213 Compute the byte offset of charcter object aitem within the enclosing object
1214 astr, also expressed as a character-based object, then offset the resulting
1215 address by abase. This macro is used ot compute locations within the VLDB when
1216 actually writing out information. 
1217
1218         \section sec3-6 Section 3.6: Functions 
1219
1220 \par
1221 This section covers the Volume Location Server RPC interface routines. The
1222 majority of them are generated from the vldbint.xg Rxgen file, and are meant to
1223 be used by user-space agents. There is also a subset interface definition
1224 provided in the afsvlint.xg Rxgen file. These routines, described in Section
1225 3.7, are meant to be used by a kernel-space agent when dealing with the Volume
1226 Location Server; in particular, they are called by the Cache Manager. 
1227
1228         \subsection sec3-6-1 Section 3.6.1: VL CreateEntry - Create a VLDB
1229 entry 
1230
1231 \code
1232 int VL CreateEntry(IN struct rx connection *z conn, 
1233                         IN vldbentry *newentry) 
1234 \endcode
1235 \par Description
1236 This function creates a new entry in the VLDB, as specified in the newentry
1237 argument. Both the name and numerical ID of the new volume must be unique
1238 (e.g., it must not already appear in the VLDB). For non-read-write entries, the
1239 read-write parent volume is accessed so that its reference count can be
1240 updated, and the new entry is added to the parent's chain of associated
1241 entries. 
1242 The VLDB is write-locked for the duration of this operation. 
1243 \par Error Codes 
1244 VL PERM The caller is not authorized to execute this function. VL NAMEEXIST The
1245 volume name already appears in the VLDB. VL CREATEFAIL Space for the new entry
1246 cannot be allocated within the VLDB. VL BADNAME The volume name is invalid. VL
1247 BADVOLTYPE The volume type is invalid. VL BADSERVER The indicated server
1248 information is invalid. VL BADPARTITION The indicated partition information is
1249 invalid. VL BADSERVERFLAG The server flag field is invalid. VL IO An error
1250 occurred while writing to the VLDB. 
1251
1252         \subsection sec3-6-2 Section 3.6.2: VL DeleteEntry - Delete a VLDB
1253 entry 
1254
1255 \code
1256 int VL DeleteEntry(IN struct rx connection *z conn, 
1257                         IN long Volid,  
1258                         IN long voltype)        
1259 \endcode
1260 \par Description 
1261 Delete the entry matching the given volume identifier and volume type as
1262 specified in the Volid and voltype arguments. For a read-write entry whose
1263 reference count is greater than 1, the entry is not actually deleted, since at
1264 least one child (read-only or backup) volume still depends on it. For cases of
1265 non-read-write volumes, the parent's reference count and associated chains are
1266 updated. 
1267 \par
1268 If the associated VLDB entry is already marked as deleted (i.e., its flags
1269 field has the VLDELETED bit set), then no further action is taken, and VL
1270 ENTDELETED is returned. The VLDB is write-locked for the duration of this
1271 operation. 
1272 \par Error Codes 
1273 VL PERM The caller is not authorized to execute this function. VL BADVOLTYPE An
1274 illegal volume type has been specified by the voltype argument. VL NOENT This
1275 volume instance does not appear in the VLDB. VL ENTDELETED The given VLDB entry
1276 has already been marked as deleted. VL IO An error occurred while writing to
1277 the VLDB. 
1278
1279         \subsection sec3-6-3 Section 3.6.3: VL GetEntryByID - Get VLDB entry by
1280 volume ID/type 
1281
1282 \code
1283 int VL GetEntryByID(IN struct rx connection *z conn, IN long Volid, IN long
1284 voltype, OUT vldbentry *entry) 
1285 \endcode
1286 \par Description 
1287 Given a volume's numerical identifier (Volid) and type (voltype), return a
1288 pointer to the entry in the VLDB describing the given volume instance. 
1289 \par
1290 The VLDB is read-locked for the duration of this operation. 
1291 \par Error Codes 
1292 VL BADVOLTYPE An illegal volume type has been specified by the voltype
1293 argument. 
1294 \n VL NOENT This volume instance does not appear in the VLDB. 
1295 \n VL ENTDELETED The given VLDB entry has already been marked as deleted. 
1296
1297         \subsection sec3-6-4 Section 3.6.4: VL GetEntryByName - Get VLDB entry
1298 by volume name 
1299
1300 \code
1301 int VL GetEntryByName(IN struct rx connection *z conn, 
1302                         IN char *volumename, 
1303                         OUT vldbentry *entry) 
1304 \endcode
1305 \par Description 
1306 Given the volume name in the volumename parameter, return a pointer to the
1307 entry in the VLDB describing the given volume. The name in volumename may be no
1308 longer than MAXNAMELEN (65) characters, including the trailing null. Note that
1309 it is legal to use the volume's numerical identifier (in string form) as the
1310 volume name. 
1311 \par
1312 The VLDB is read-locked for the duration of this operation. 
1313 \par
1314 This function is closely related to the VL GetEntryByID() routine, as might be
1315 expected. In fact, the by-ID routine is called if the volume name provided in
1316 volumename is the string version of the volume's numerical identifier. 
1317 \par Error Codes 
1318 VL BADVOLTYPE An illegal volume type has been specified by the voltype
1319 argument. 
1320 \n VL NOENT This volume instance does not appear in the VLDB. 
1321 \n VL ENTDELETED The given VLDB entry has already been marked as deleted. 
1322 \n VL BADNAME The volume name is invalid. 
1323
1324         \subsection sec3-6-5 Section 3.6.5: VL GetNewVolumeId - Generate a new
1325 volume ID 
1326
1327 \code
1328 int VL GetNewVolumeId(IN struct rx connection *z conn, 
1329                         IN long bumpcount, 
1330                         OUT long *newvolumid) 
1331 \endcode
1332 \par Description 
1333 Acquire bumpcount unused, consecutively-numbered volume identifiers from the
1334 Volume Location Server. The lowest-numbered of the newly-acquired set is placed
1335 in the newvolumid argument. The largest number of volume IDs that may be
1336 generated with any one call is bounded by the MAXBUMPCOUNT constant defined in
1337 Section 3.2.1. Currently, there is (effectively) no restriction on the number
1338 of volume identifiers that may thus be reserved in a single call. 
1339 \par
1340 The VLDB is write-locked for the duration of this operation. 
1341 \par Error Codes 
1342 VL PERM The caller is not authorized to execute this function. 
1343 \n VL BADVOLIDBUMP The value of the bumpcount parameter exceeds the system
1344 limit of MAXBUMPCOUNT. 
1345 \n VL IO An error occurred while writing to the VLDB. 
1346
1347         \subsection sec3-6-6 Section 3.6.6: VL ReplaceEntry - Replace entire
1348 contents of VLDB entry 
1349
1350 \code
1351 int VL ReplaceEntry(IN struct rx connection *z conn, 
1352                         IN long Volid, 
1353                         IN long voltype, 
1354                         IN vldbentry *newentry, 
1355                         IN long ReleaseType) 
1356 \endcode
1357 \par Description 
1358 Perform a wholesale replacement of the VLDB entry corresponding to the volume
1359 instance whose identifier is Volid and type voltype with the information
1360 contained in the newentry argument. Individual VLDB entry fields cannot be
1361 selectively changed while the others are preserved; VL UpdateEntry() should be
1362 used for this objective. The permissible values for the ReleaseType parameter
1363 are defined in Section 3.2.7. 
1364 \par
1365 The VLDB is write-locked for the duration of this operation. All of the hash
1366 tables impacted are brought up to date to incorporate the new information. 
1367 \par Error Codes 
1368 VL PERM The caller is not authorized to execute this function. 
1369 \n VL BADVOLTYPE An illegal volume type has been specified by the voltype
1370 argument. 
1371 \n VL BADRELLOCKTYPE An illegal release lock has been specified by the
1372 ReleaseType argument. 
1373 \n VL NOENT This volume instance does not appear in the VLDB. 
1374 \n VL BADENTRY An attempt was made to change a read-write volume ID. 
1375 \n VL IO An error occurred while writing to the VLDB. 
1376
1377         \subsection sec3-6-7 Section 3.6.7: VL UpdateEntry - Update contents of
1378 VLDB entry 
1379
1380 \code
1381 int VL UpdateEntry(IN struct rx connection *z conn, 
1382                         IN long Volid, 
1383                         IN long voltype, 
1384                         IN VldbUpdateEntry *UpdateEntry, 
1385                         IN long ReleaseType) 
1386 \endcode
1387 \par Description 
1388 Update the VLDB entry corresponding to the volume instance whose identifier is
1389 Volid and type voltype with the information contained in the UpdateEntry
1390 argument. Most of the entry's fields can be modified in a single call to VL
1391 UpdateEntry(). The Mask field within the UpdateEntry parameter selects the
1392 fields to update with the values stored within the other UpdateEntry fields.
1393 Permissible values for the ReleaseType parameter are defined in Section 3.2.7. 
1394 \par
1395 The VLDB is write-locked for the duration of this operation. 
1396 \par Error Codes 
1397 VL PERM The caller is not authorized to execute this function. 
1398 \n VL BADVOLTYPE An illegal volume type has been specified by the voltype
1399 argument. 
1400 \n VL BADRELLOCKTYPE An illegal release lock has been specified by the
1401 ReleaseType argument. 
1402 \n VL NOENT This volume instance does not appear in the VLDB. 
1403 \n VL IO An error occurred while writing to the VLDB. 
1404
1405         \subsection sec3-6-8 Section 3.6.8: VL SetLock - Lock VLDB entry 
1406
1407 \code
1408 int VL SetLock(IN struct rx connection *z conn, 
1409                 IN long Volid,  
1410                 IN long voltype,        
1411                 IN long voloper)        
1412 \endcode
1413 \par Description 
1414 Lock the VLDB entry matching the given volume ID (Volid) and type (voltype) for
1415 volume operation voloper (e.g., VLOP MOVE and VLOP RELEASE). If the entry is
1416 currently unlocked, then its LockTimestamp will be zero. If the lock is
1417 obtained, the given voloper is stamped into the flags field, and the
1418 LockTimestamp is set to the time of the call. 
1419 \Note 
1420 When the caller attempts to lock the entry for a release operation, special
1421 care is taken to abort the operation if the entry has already been locked for
1422 this operation, and the existing lock has timed out. In this case, VL SetLock()
1423 returns VL RERELEASE. 
1424 \par
1425 The VLDB is write-locked for the duration of this operation. 
1426 \par Error Codes 
1427 VL PERM The caller is not authorized to execute this function. 
1428 \n VL BADVOLTYPE An illegal volume type has been specified by the voltype
1429 argument. 
1430 \n VL BADVOLOPER An illegal volume operation was specified in the voloper
1431 argument.  Legal values are defined in the latter part of the table in Section
1432 3.2.5. 
1433 \n VL ENTDELETED The given VLDB entry has already been marked as deleted. 
1434 \n VL ENTRYLOCKED The given VLDB entry has already been locked (which has not
1435 yet timed out). 
1436 \n VL RERELEASE A VLDB entry locked for release has timed out, and the caller
1437 also wanted to perform a release operation on it. 
1438 \n VL IO An error was experienced while attempting to write to the VLDB. 
1439
1440         \subsection sec3-6-9 Section 3.6.9: VL ReleaseLock - Unlock VLDB entry 
1441
1442 \code
1443 int VL ReleaseLock(IN struct rx connection *z conn, 
1444                         IN long Volid,  
1445                         IN long voltype,        
1446                         IN long ReleaseType)    
1447 \endcode
1448 \par Description 
1449 Unlock the VLDB entry matching the given volume ID (Volid) and type (voltype).
1450 The ReleaseType argument determines which VLDB entry fields from flags and
1451 LockAfsId will be cleared along with the lock timestamp in LockTimestamp.
1452 Permissible values for the ReleaseType parameter are defined in Section 3.2.7. 
1453 \par
1454 The VLDB is write-locked for the duration of this operation. 
1455 \par Error Codes 
1456 VL PERM The caller is not authorized to execute this function. 
1457 \n VL BADVOLTYPE An illegal volume type has been specified by the voltype
1458 argument. 
1459 \n VL BADRELLOCKTYPE An illegal release lock has been specified by the
1460 ReleaseType argument. 
1461 \n VL NOENT This volume instance does not appear in the VLDB. 
1462 \n VL ENTDELETED The given VLDB entry has already been marked as deleted. 
1463 \n VL IO An error was experienced while attempting to write to the VLDB. 
1464
1465         \subsection sec3-6-10 Section 3.6.10: VL ListEntry - Get contents of
1466 VLDB via index 
1467
1468 \code
1469 int VL ListEntry(IN struct rx connection *z conn, 
1470                         IN long previous index, 
1471                         OUT long *count, 
1472                         OUT long *next index, 
1473                         OUT vldbentry *entry) 
1474 \endcode
1475 \par Description 
1476 This function assists in the task of enumerating the contents of the VLDB.
1477 Given an index into the database, previous index, this call return the single
1478 VLDB entry at that offset, placing it in the entry argument. The number of VLDB
1479 entries left to list is placed in count, and the index of the next entry to
1480 request is returned in next index. If an illegal index is provided, count is
1481 set to -1. 
1482 \par
1483 The VLDB is read-locked for the duration of this operation. 
1484 \par Error Codes 
1485 ---None. 
1486
1487         \subsection sec3-6-11 Section 3.6.11: VL ListAttributes - List all VLDB
1488 entry matching given attributes, single return object 
1489
1490 \code
1491 int VL ListAttributes(IN struct rx connection *z conn, 
1492                         IN VldbListByAttributes *attributes, 
1493                         OUT long *nentries, 
1494                         OUT bulkentries *blkentries) 
1495 \endcode
1496 \par Description 
1497 Retrieve all the VLDB entries that match the attributes listed in the
1498 attributes parameter, placing them in the blkentries object. The number of
1499 matching entries is placed in nentries. Matching can be done by server number,
1500 partition, volume type, flag, or volume ID. The legal values to use in the
1501 attributes argument are listed in Section 3.2.3. Note that if the VLLIST
1502 VOLUMEID bit is set in attributes, all other bit values are ignored and the
1503 volume ID provided is the sole search criterion. 
1504 \par
1505 The VLDB is read-locked for the duration of this operation. 
1506 \par
1507 Note that VL ListAttributes() is a potentially expensive function, as
1508 sequential search through all of the VLDB entries is performed in most cases. 
1509 \par Error Codes 
1510 VL NOMEM Memory for the blkentries object could not be allocated. 
1511 \n VL NOENT This specified volume instance does not appear in the VLDB. 
1512 \n VL SIZEEXCEEDED Ran out of room in the blkentries object. 
1513 \n VL IO Error while reading from the VLDB. 
1514
1515         \subsection sec3-6-12 Section 3.6.12: VL LinkedList - List all VLDB
1516 entry matching given attributes, linked list return object 
1517
1518 \code
1519 int VL LinkedList(IN struct rx connection *z conn, 
1520                         IN VldbListByAttributes *attributes, 
1521                         OUT long *nentries, 
1522                         OUT vldb list *linkedentries) 
1523 \endcode
1524 \par Description 
1525 Retrieve all the VLDB entries that match the attributes listed in the
1526 attributes parameter, creating a linked list of entries based in the
1527 linkedentries object. The number of matching entries is placed in nentries.
1528 Matching can be done by server number, partition, volume type, flag, or volume
1529 ID. The legal values to use in the attributes argument are listed in Section
1530 3.2.3. Note that if the VLLIST VOLUMEID bit is set in attributes, all other bit
1531 values are ignored and the volume ID provided is the sole search criterion. 
1532 \par
1533 The VL LinkedList() function is identical to the VL ListAttributes(), except
1534 for the method of delivering the VLDB entries to the caller. 
1535 \par
1536 The VLDB is read-locked for the duration of this operation. 
1537 \par Error Codes 
1538 VL NOMEM Memory for an entry in the list based at linkedentries object could
1539 not be allocated. 
1540 \n VL NOENT This specified volume instance does not appear in the VLDB. 
1541 \n VL SIZEEXCEEDED Ran out of room in the current list object. 
1542 \n VL IO Error while reading from the VLDB. 
1543
1544         \subsection sec3-6-13 Section 3.6.13: VL GetStats - Get Volume Location
1545 Server statistics 
1546
1547 \code
1548 int VL GetStats(IN struct rx connection *z conn, 
1549                 OUT vldstats *stats, 
1550                 OUT vital vlheader *vital header) 
1551 \endcode
1552 \par Description
1553 Collect the different types of VLDB statistics. Part of the VLDB header is
1554 returned in vital header, which includes such information as the number of
1555 allocations and frees performed, and the next volume ID to be allocated. The
1556 dynamic per-operation stats are returned in the stats argument, reporting the
1557 number and types of operations and aborts. 
1558 \par
1559 The VLDB is read-locked for the duration of this operation. 
1560 \par Error Codes 
1561 VL PERM The caller is not authorized to execute this function. 
1562
1563         \subsection sec3-6-14 Section 3.6.14: VL Probe - Verify Volume Location
1564 Server connectivity/status 
1565
1566 \code
1567 int VL Probe(IN struct rx connection *z conn) 
1568 \endcode
1569 \par Description 
1570 This routine serves a 'pinging' function to determine whether the Volume
1571 Location Server is still running. If this call succeeds, then the Volume
1572 Location Server is shown to be capable of responding to RPCs, thus confirming
1573 connectivity and basic operation. 
1574 \par
1575 The VLDB is not locked for this operation. 
1576 \par Error Codes 
1577 ---None. 
1578
1579         \section sec3-7 Section 3.7: Kernel Interface Subset 
1580
1581 \par
1582 The interface described by this document so far applies to user-level clients,
1583 such as the vos utility. However, some volume location operations must be
1584 performed from within the kernel. Specifically, the Cache Manager must find out
1585 where volumes reside and otherwise gather information about them in order to
1586 conduct its business with the File Servers holding them. In order to support
1587 Volume Location Server interconnection for agents operating within the kernel,
1588 the afsvlint.xg Rxgen interface was built. It is a minimal subset of the
1589 user-level vldbint.xg definition. Within afsvlint.xg, there are duplicate
1590 definitions for such constants as MAXNAMELEN, MAXNSERVERS, MAXTYPES, VLF
1591 RWEXISTS, VLF ROEXISTS, VLF BACKEXISTS, VLSF NEWREPSITE, VLSF ROVOL, VLSF
1592 RWVOL, and VLSF BACKVOL. Since the only operations the Cache Manager must
1593 perform are volume location given a specific volume ID or name, and to find out
1594 about unresponsive Volume Location Servers, the following interface routines
1595 are duplicated in afsvlint.xg, along with the struct vldbentry declaration: 
1596 \li VL GetEntryByID() 
1597 \li VL GetEntryByName() 
1598 \li VL Probe() 
1599
1600         \page chap4 Chapter 4: Volume Server Architecture 
1601
1602         \section sec4-1 Section 4.1: Introduction 
1603
1604 \par
1605 The Volume Server allows administrative tasks and probes to be performed on the
1606 set of AFS volumes residing on the machine on which it is running. As described
1607 in Chapter 2, a distributed database holding volume location info, the VLDB, is
1608 used by client applications to locate these volumes. Volume Server functions
1609 are typically invoked either directly from authorized users via the vos utility
1610 or by the AFS backup system. 
1611 \par
1612 This chapter briefly discusses various aspects of the Volume Server's
1613 architecture. First, the high-level on-disk representation of volumes is
1614 covered. Then, the transactions used in conjuction with volume operations are
1615 examined. Then, the program implementing the Volume Server, volserver, is
1616 considered. The nature and format of the log file kept by the Volume Server
1617 rounds out the description. 
1618 As with all AFS servers, the Volume Server uses the Rx remote procedure call
1619 package for communication with its clients. 
1620
1621         \section sec4-2 Section 4.2: Disk Representation 
1622
1623 \par
1624 For each volume on an AFS partition, there exists a file visible in the unix
1625 name space which describes the contents of that volume. By convention, each of
1626 these files is named by concatenating a prefix string, "V", the numerical
1627 volume ID, and the postfix string ".vol". Thus, file V0536870918.vol describes
1628 the volume whose numerical ID is 0536870918. Internally, each per-volume
1629 descriptor file has such fields as a version number, the numerical volume ID,
1630 and the numerical parent ID (useful for read-only or backup volumes). It also
1631 has a list of related inodes, namely files which are not visible from the unix
1632 name space (i.e., they do not appear as entries in any unix directory object).
1633 The set of important related inodes are: 
1634 \li Volume info inode: This field identifies the inode which hosts the on-disk
1635 representation of the volume's header. It is very similar to the information
1636 pointed to by the volume field of the struct volser trans defined in Section
1637 5.4.1, recording important status information for the volume. 
1638 \li Large vnode index inode: This field identifies the inode which holds the
1639 list of vnode identifiers for all directory objects residing within the volume.
1640 These are "large" since they must also hold the Access Control List (ACL)
1641 information for the given AFS directory. 
1642 \li Small vnode index inode: This field identifies the inode which holds the
1643 list of vnode identifiers for all non-directory objects hosted by the volume. 
1644 \par
1645 All of the actual files and directories residing within an AFS volume, as
1646 identified by the contents of the large and small vnode index inodes, are also
1647 free-floating inodes, not appearing in the conventional unix name space. This
1648 is the reason the vendor-supplied fsck program should not be run on partitions
1649 containing AFS volumes. Since the inodes making up AFS files and directories,
1650 as well as the inodes serving as volume indices for them, are not mapped to any
1651 directory, the standard fsck program would throw away all of these
1652 "unreferenced" inodes. Thus, a special version of fsck is provided that
1653 recognizes partitions containing AFS volumes as well as standard unix
1654 partitions. 
1655
1656         \section sec4-3 Section 4.3: Transactions 
1657
1658 \par
1659 Each individual volume operation is carried out by the Volume Server as a
1660 transaction, but not in the atomic sense of the word. Logically, creating a
1661 Volume Server transaction can be equated with performing an "exclusive open" on
1662 the given volume before beginning the actual work of the desired volume
1663 operation. No other Volume Server (or File Server) operation is allowed on the
1664 opened volume until the transaction is terminated. Thus, transactions in the
1665 context of the Volume Server serve to provide mutual exclusion without any of
1666 the normal atomicity guarantees. Volumes maintain enough internal state to
1667 enable recovery from interrupted or failed operations via use of the salvager
1668 program. Whenever volume inconsistencies are detected, this salvager program is
1669 run, which then attempts to correct the problem. 
1670 \par
1671 Volume transactions have timeouts associated with them. This guarantees that
1672 the death of the agent performing a given volume operation cannot result in the
1673 volume being permanently removed from circulation. There are actually two
1674 timeout periods defined for a volume transaction. The first is the warning
1675 time, defined to be 5 minutes. If a transaction lasts for more than this time
1676 period without making progress, the Volume Server prints a warning message to
1677 its log file (see Section 4.5). The second time value associated with a volume
1678 transaction is the hard timeout, defined to occur 10 minutes after any progress
1679 has been made on the given operation. After this period, the transaction will
1680 be unconditionally deleted, and the volume freed for any other operations.
1681 Transactions are reference-counted. Progress will be deemed to have occurred
1682 for a transaction, and its internal timeclock field will be updated, when: 
1683 \li 1 The transaction is first created. 
1684 \li 2 A reference is made to the transaction, causing the Volume Server to look
1685 it up in its internal tables. 
1686 \li 3 The transaction's reference count is decremented. 
1687
1688         \section sec4-4 Section 4.4: The volserver Process 
1689
1690 \par
1691 The volserver user-level program is run on every AFS server machine, and
1692 implements the Volume Server agent. It is responsible for providing the Volume
1693 Server interface as defined by the volint.xg Rxgen file. 
1694 \par
1695 The volserver process defines and launches five threads to perform the bulk of
1696 its duties. One thread implements a background daemon whose job it is to
1697 garbage-collect timed-out transaction structures. The other four threads are
1698 RPC interface listeners, primed to accept remote procedure calls and thus
1699 perform the defined set of volume operations. 
1700 \par
1701 Certain non-standard configuration settings are made for the RPC subsystem by
1702 the volserver program. For example, it chooses to extend the length of time
1703 that an Rx connection may remain idle from the default 12 seconds to 120
1704 seconds. The reasoning here is that certain volume operations may take longer
1705 than 12 seconds of processing time on the server, and thus the default setting
1706 for the connection timeout value would incorrectly terminate an RPC when in
1707 fact it was proceeding normally and correctly. 
1708 \par
1709 The volserver program takes a single, optional command line argument. If a
1710 positive integer value is provided on the command line, then it shall be used
1711 to set the debugging level within the Volume Server. By default, a value of
1712 zero is used, specifying that no special debugging output will be generated and
1713 fed to the Volume Server log file described below. 
1714
1715         \section sec4-5 Section 4.5: Log File 
1716
1717 \par
1718 The Volume Server keeps a log file, recording the set of events of special
1719 interest it has encountered. The file is named VolserLog, and is stored in the
1720 /usr/afs/logs directory on the local disk of the server machine on which the
1721 Volume Server runs. This is a human-readable file, with every entry
1722 time-stamped. 
1723 \par
1724 Whenever the volserver program restarts, it renames the current VolserLog file
1725 to VolserLog.old, and starts up a fresh log. A properly-authorized individual
1726 can easily inspect the log file residing on any given server machine. This is
1727 made possible by the BOS Server AFS agent running on the machine, which allows
1728 the contents of this file to be fetched and displayed on the caller's machine
1729 via the bos getlog command. 
1730 \par
1731 An excerpt from a Volume Server log file follows below. The numbers appearing
1732 in square brackets at the beginning of each line have been inserted so that we
1733 may reference the individual lines of the log excerpt in the following
1734 paragraph. 
1735 \code
1736 [1] Wed May 8 06:03:00 1991 AttachVolume: Error attaching volume
1737 /vicepd/V1969547815.vol; volume needs salvage 
1738 [2] Wed May 8 06:03:01 1991 Volser: ListVolumes: Could not attach volume
1739 1969547815 
1740 [3] Wed May 8 07:36:13 1991 Volser: Clone: Cloning volume 1969541499 to new
1741 volume 1969541501 
1742 [4] Wed May 8 11:25:05 1991 AttachVolume: Cannot read volume header
1743 /vicepd/V1969547415.vol 
1744 [5] Wed May 8 11:25:06 1991 Volser: CreateVolume: volume 1969547415
1745 (bld.dce.s3.dv.pmax_ul3) created 
1746 \endcode
1747 \par
1748 Line [1] indicates that the volume whose numerical ID is 1969547815 could not
1749 be attached on partition /vicepd. This error is probably the result of an
1750 aborted transaction which left the volume in an inconsistent state, or by
1751 actual damage to the volume structure or data. In this case, the Volume Server
1752 recommends that the salvager program be run on this volume to restore its
1753 integrity. Line [2] records the operation which revealed this situation, namely
1754 the invocation of an AFSVolListVolumes() RPC. 
1755 \par
1756 Line [4] reveals that the volume header file for a specific volume could not be
1757 read. Line [5], as with line [2] in the above paragraph, indicates why this is
1758 true. Someone had called the AFSVolCreateVolume() interface function, and as a
1759 precaution, the Volume Server first checked to see if such a volume was already
1760 present by attempting to read its header. 
1761 \par
1762 Thus verifying that the volume did not previously exist, the Volume Server
1763 allowed the AFSVolCreateVolume() call to continue its processing, creating and
1764 initializing the proper volume file, V1969547415.vol, and the associated header
1765 and index inodes. 
1766
1767         \page chap5 Chapter 5: Volume Server Interface 
1768
1769         \section sec5-1 Section 5.1 Introduction 
1770
1771 \par
1772 This chapter documents the API for the Volume Server facility, as defined by
1773 the volint.xg Rxgen interface file and the volser.h include file. Descriptions
1774 of all the constants, structures, macros, and interface functions available to
1775 the application programmer appear here. 
1776
1777         \section sec5-2 Section 5.2: Constants 
1778
1779 \par
1780 This section covers the basic constant definitions of interest to the Volume
1781 Server application programmer. These definitions appear in the volint.h file,
1782 automatically generated from the volint.xg Rxgen interface file, and in
1783 volser.h. 
1784 \par
1785 Each subsection is devoted to describing the constants falling into the
1786 following categories: 
1787 \li Configuration and boundary values 
1788 \li Interface routine opcodes 
1789 \li Transaction Flags 
1790 \li Volume Types 
1791 \li LWP State 
1792 \li States for struct vldbentry 
1793 \li Validity Checks 
1794 \li Miscellaneous 
1795
1796         \subsection sec5-2-1 Section 5.2.1: Configuration and Boundary Values 
1797
1798 \par
1799 These constants define some basic system configuration values, along with such
1800 things as maximum sizes of important arrays. 
1801
1802 MyPort  5,003   The Rx UDP port on which the Volume Server service may be
1803 found. 
1804 \par Name
1805 NameLen         
1806 \par Value
1807 80      
1808 \par Description
1809 Used by the vos utility to define maximum lengths for internal filename
1810 variables. 
1811
1812 \par Name
1813 VLDB MAXSERVERS         
1814 \par Value
1815 10      
1816 \par Description
1817 Maximum number of server agents implementing the AFS Volume Location Database
1818 (VLDB) for the cell. 
1819
1820 \par Name
1821 VOLSERVICE ID   
1822 \par Value
1823 4       
1824 \par Description
1825 The Rx service number on the given UDP port (MyPort) above. 
1826
1827 \par Name
1828 INVALID BID     
1829 \par Value
1830 0       
1831 \par Description
1832 Used as an invalid read-only or backup volume ID. 
1833
1834 \par Name
1835 VOLSER MAXVOLNAME       
1836 \par Value
1837 65      
1838 \par Description
1839 The number of characters in the longest possible volume name, including the
1840 trailing null. Note: this is only used by the vos utility; the Volume Server
1841 uses the "old" value below. 
1842
1843 \par Name
1844 VOLSER OLDMAXVOLNAME    
1845 \par Value
1846 32      
1847 \par Description
1848 The "old" maximum number of characters in an AFS volume name, including the
1849 trailing null. In reality, it is also the current maximum. 
1850
1851 \par Name
1852 VOLSER MAX REPSITES     
1853 \par Value
1854 7       
1855 \par Description
1856 The maximum number of replication sites for a volume. 
1857
1858 \par Name
1859 VNAMESIZE       
1860 \par Value
1861 32      
1862 \par Description
1863 Size in bytes of the name field in struct volintInfo (see Section 5.4.6). 
1864
1865
1866         \subsection sec5-2-2 Section 5.2.2: Interface Routine Opcodes 
1867
1868 \par
1869 These constants, appearing in the volint.xg Rxgen interface file for the Volume
1870 Server, define the opcodes for the RPC routines. Every Rx call on this
1871 interface contains this opcode, and the dispatcher uses it to select the proper
1872 code at the server site to carry out the call. 
1873
1874 \par Name       
1875 VOLCREATEVOLUME         
1876 \par Value      
1877 100     
1878 \par Description 
1879 Opcode for AFSVolCreateVolume() 
1880
1881 \par Name       
1882 VOLDELETEVOLUME         
1883 \par Value      
1884 101     
1885 \par Description 
1886 Opcode for AFSVolDeleteVolume() 
1887
1888 \par Name       
1889 VOLRESTORE      
1890 \par Value      
1891 102     
1892 \par Description 
1893 Opcode for AFSVolRestoreVolume() 
1894
1895 \par Name       
1896 VOLFORWARD      
1897 \par Value      
1898 103     
1899 \par Description 
1900 Opcode for AFSVolForward() 
1901
1902 \par Name       
1903 VOLENDTRANS     
1904 \par Value      
1905 104     
1906 \par Description 
1907 Opcode for AFSVolEndTrans() 
1908
1909 \par Name       
1910 VOLCLONE        
1911 \par Value      
1912 105     
1913 \par Description 
1914 Opcode for AFSVolClone() . 
1915
1916 \par Name       
1917 VOLSETFLAGS     
1918 \par Value      
1919 106     
1920 \par Description 
1921 Opcode for AFSVolSetFlags() 
1922
1923 \par Name       
1924 VOLGETFLAGS     
1925 \par Value      
1926 107     
1927 \par Description 
1928 Opcode for AFSVolGetFlags() 
1929
1930 \par Name       
1931 VOLTRANSCREATE  
1932 \par Value      
1933 108     
1934 \par Description 
1935 Opcode for AFSVolTransCreate() 
1936
1937 \par Name       
1938 VOLDUMP         
1939 \par Value      
1940 109     
1941 \par Description 
1942 Opcode for AFSVolDump() 
1943
1944 \par Name       
1945 VOLGETNTHVOLUME         
1946 \par Value      
1947 110     
1948 \par Description 
1949 Opcode for AFSVolGetNthVolume() 
1950
1951 \par Name       
1952 VOLSETFORWARDING        
1953 \par Value      
1954 111     
1955 \par Description 
1956 Opcode for AFSVolSetForwarding() 
1957
1958 \par Name       
1959 VOLGETNAME      
1960 \par Value      
1961 112     
1962 \par Description 
1963 Opcode for AFSVolGetName() 
1964
1965 \par Name       
1966 VOLGETSTATUS    
1967 \par Value      
1968 113     
1969 \par Description 
1970 Opcode for AFSVolGetStatus() 
1971
1972 \par Name       
1973 VOLSIGRESTORE   
1974 \par Value      
1975 114     
1976 \par Description 
1977 Opcode for AFSVolSignalRestore() 
1978
1979 \par Name       
1980 VOLLISTPARTITIONS       
1981 \par Value      
1982 115     
1983 \par Description 
1984 Opcode for AFSVolListPartitions() 
1985
1986 \par Name       
1987 VOLLISTVOLS     
1988 \par Value      
1989 116     
1990 \par Description 
1991 Opcode for AFSVolListVolumes() 
1992
1993 \par Name       
1994 VOLSETIDSTYPES  
1995 \par Value      
1996 117     
1997 \par Description 
1998 Opcode for AFSVolSetIdsTypes() 
1999
2000 \par Name       
2001 VOLMONITOR      
2002 \par Value      
2003 118     
2004 \par Description 
2005 Opcode for AFSVolMonitor() 
2006
2007 \par Name       
2008 VOLDISKPART     
2009 \par Value      
2010 119     
2011 \par Description 
2012 Opcode for AFSVolPartitionInfo() 
2013
2014 \par Name       
2015 VOLRECLONE      
2016 \par Value      
2017 120     
2018 \par Description 
2019 Opcode for AFSVolReClone() 
2020
2021 \par Name       
2022 VOLLISTONEVOL   
2023 \par Value      
2024 121     
2025 \par Description 
2026 Opcode for AFSVolListOneVolume() 
2027
2028 \par Name       
2029 VOLNUKE         
2030 \par Value      
2031 122     
2032 \par Description 
2033 Opcode for AFSVolNukeVolume() 
2034
2035 \par Name       
2036 VOLSETDATE      
2037 \par Value      
2038 123     
2039 \par Description 
2040 Opcode for AFSVolSetDate() 
2041
2042         \subsection sec5-2-3 Section 5.2.3: Transaction Flags 
2043
2044 \par
2045 These constants define the various flags the Volume Server uses in assocation
2046 with volume transactions, keeping track of volumes upon which operations are
2047 currently proceeding. There are three sets of flag values, stored in three
2048 different fields within a struct volser trans: general volume state, attachment
2049 modes, and specific transaction states. 
2050
2051         \subsubsection sec5-2-3-1: Section 5.2.3.1 vflags 
2052
2053 \par
2054 These values are used to represent the general state of the associated volume.
2055 They appear in the vflags field within a struct volser trans. 
2056
2057 \par Name       
2058 VTDeleteOnSalvage       
2059 \par Value      
2060 1       
2061 \par Description 
2062 The volume should be deleted on next salvage. 
2063
2064 \par Name       
2065 VTOutOfService  
2066 \par Value      
2067 2       
2068 \par Description 
2069 This volume should never be put online. 
2070
2071 \par Name       
2072 VTDeleted       
2073 \par Value      
2074 4       
2075 \par Description 
2076 This volume has been deleted (via AFSVolDeleteVol¬¨ume() ), and thus should not
2077 be manipulated. 
2078
2079         \subsubsection sec5-2-3-2 Section 5.2.3.2: iflags 
2080
2081 \par
2082 These constants represent the desired attachment mode for a volume at the start
2083 of a transaction. Once attached, the volume header is marked to reflect this
2084 mode. Attachment modes are useful in salvaging partitions, as they indicate
2085 whether the operations being performed on individual volumes at the time the
2086 crash occured could have introduced inconsistencies in their metadata
2087 descriptors. If a volume was attached in a read-only fashion, then the salvager
2088 may decide (taking other factors into consideration) that the volume doesn't
2089 need attention as a result of the crash. 
2090 \par
2091 These values appear in the iflags field within a struct volser trans. 
2092
2093 \par Name       
2094 ITOffline       
2095 \par Value      
2096 0x1     
2097 \par Description 
2098 Volume offline on server (returns VOFFLINE). 
2099
2100 \par Name       
2101 ITBusy  
2102 \par Value      
2103 0x2     
2104 \par Description 
2105 Volume busy on server (returns VBUSY). 
2106
2107 \par Name       
2108 ITReadOnly      
2109 \par Value      
2110 0x8     
2111 \par Description 
2112 Volume is read-only on client, read-write on server -DO NOT USE. 
2113
2114 \par Name       
2115 ITCreate        
2116 \par Value      
2117 0x10    
2118 \par Description 
2119 Volume does not exist correctly yet. 
2120
2121 \par Name       
2122 ITCreateVolID   
2123 \par Value      
2124 0x1000  
2125 \par Description 
2126 Create volid. 
2127
2128         \subsubsection sec5-2-3-3 Section 5.2.3.3: tflags 
2129
2130 \par
2131 This value is used to represent the transaction state of the associated volume,
2132 and appears in the tflags field within a struct volser trans. 
2133
2134 \par Name       
2135 TTDeleted       
2136 \par Value      
2137 1       
2138 \par Description 
2139 Delete transaction not yet freed due to high reference count. 
2140
2141         \subsection sec5-2-4 Section 5.2.4: Volume Types 
2142
2143 \par
2144 The following constants may be supplied as values for the type argument to the
2145 AFSVol-CreateVolume() interface call. They are just synonyms for the three
2146 values RWVOL, ROVOL, 
2147
2148 \par Name       
2149 volser RW       
2150 \par Value      
2151 0       
2152 \par Description 
2153 Specifies a read-write volume type. 
2154
2155 \par Name       
2156 volser RO       
2157 \par Value      
2158 1       
2159 \par Description 
2160 Specifies a read-only volume type. 
2161
2162 \par Name       
2163 volser BACK     
2164 \par Value      
2165 2       
2166 \par Description 
2167 Specifies a backup volume type. 
2168
2169         \subsection sec5-2-5 Section 5.2.5: LWP State 
2170
2171 \par
2172 This set of exported definitions refers to objects internal to the Volume
2173 Server, and strictly speaking should not be visible to other agents.
2174 Specifically, a busyFlags array keeps a set of flags referenced by the set of
2175 lightweight threads running within the Volume Server. These flags reflect and
2176 drive the state of each of these worker LWPs. 
2177
2178 \par Name       
2179 VHIdle  
2180 \par Value      
2181 1       
2182 \par Description 
2183 Volume Server LWP is idle, waiting for new work. 
2184
2185 \par Name       
2186 VHRequest       
2187 \par Value      
2188 2       
2189 \par Description 
2190 A work item has been queued. 
2191
2192         \subsection sec5-2-6 Section 5.2.6: States for struct vldbentry 
2193
2194 \par
2195 The Volume Server defines a collection of synonyms for certain values defined
2196 by the Volume Location Server. These particular constants are used within the
2197 flags field in objects of type struct vldbentry. The equivalent Volume Location
2198 Server values are described in Section 3.2.6. 
2199
2200 \par Name       
2201 RW EXISTS       
2202 \par Value      
2203 0x1000  
2204 \par Description 
2205 Synonym for VLF RWEXISTS. 
2206
2207 \par Name       
2208 RO EXISTS       
2209 \par Value      
2210 0x2000  
2211 \par Description 
2212 Synonym for VLF ROEXISTS. 
2213
2214 \par Name       
2215 BACK EXISTS     
2216 \par Value      
2217 0x4000  
2218 \par Description 
2219 Synonym for VLF BACKEXISTS. 
2220
2221 \par Name       
2222 NEW REPSITE     
2223 \par Value      
2224 0x01    
2225 \par Description 
2226 Synonym for VLSF NEWREPSITE. 
2227
2228 \par Name       
2229 ITSROVOL        
2230 \par Value      
2231 0x02    
2232 \par Description 
2233 Synonym for VLFS ROVOL. 
2234
2235 \par Name       
2236 ITSRWVOL        
2237 \par Value      
2238 0x04    
2239 \par Description 
2240 Synonym for VLSF RWVOL. 
2241
2242 \par Name       
2243 ITSBACKVOL      
2244 \par Value      
2245 0x08    
2246 \par Description 
2247 Synonym for VLSF BACKVOL. 
2248
2249         \subsection sec5-2-7 Section 5.2.7: Validity Checks 
2250
2251 \par
2252 These values are used for performing validity checks. The first one appears
2253 only within the partFlags field within objects of type partList (see Section
2254 5.4.3). The rest (except VOK and VBUSY) appear in the volFlags field within an
2255 object of type struct volDescription. These latter defintions are used within
2256 the volFlags field to mark whether the rest of the fields within the struct
2257 volDescription are valid. Note that while several constants are defined, only
2258 some are actually used internally by the Volume Server code. 
2259
2260 \par Name       
2261 PARTVALID       
2262 \par Value      
2263 0x01    
2264 \par Description 
2265 The indicated partition is valid. 
2266
2267 \par Name       
2268 CLONEVALID      
2269 \par Value      
2270 0x02    
2271 \par Description 
2272 The indicated clone (field volCloneId) is a valid one. 
2273
2274 \par Name       
2275 CLONEZAPPED     
2276 \par Value      
2277 0x04    
2278 \par Description 
2279 The indicated clone volume (field volCloneId) has been deleted. 
2280
2281 \par Name       
2282 IDVALID         
2283 \par Value      
2284 0x08    
2285 \par Description 
2286 The indicated volume ID (field volId) is valid. 
2287
2288 \par Name       
2289 NAMEVALID       
2290 \par Value      
2291 0x10    
2292 \par Description 
2293 The indicted volume name (field volName) is valid. Not used internally by the
2294 Volume Server. 
2295
2296 \par Name       
2297 SIZEVALID       
2298 \par Value      
2299 0x20    
2300 \par Description 
2301 The indicated volume size (field volSize) is valid. Not used internally by the
2302 Volume Server. 
2303
2304 \par Name       
2305 ENTRYVALID      
2306 \par Value      
2307 0x40    
2308 \par Description 
2309 The struct volDescription refers to a valid volume. 
2310
2311 \par Name       
2312 REUSECLONEID    
2313 \par Value      
2314 0x80    
2315 \par Description 
2316 The indicated clone ID (field volCloneId) should be reused. 
2317
2318 \par Name       
2319 VOK     
2320 \par Value      
2321 0x02    
2322 \par Description 
2323 Used in the status field of struct volintInfo to show that everything is OK. 
2324
2325 \par Name       
2326 VBUSY   
2327 \par Value      
2328 110     
2329 \par Description 
2330 Used in the status field of struct volintInfo to show that the volume is
2331 currently busy. 
2332
2333         \subsection sec5-2-8 Section 5.2.8: Miscellaneous 
2334
2335 \par
2336 This section covers the set of exported Volume Server definitions that don't
2337 easily fall into the above categories. 
2338
2339 \par Name       
2340 SIZE    
2341 \par Value      
2342 1,024   
2343 \par Description 
2344 Not used internally by the Volume Server; used as a maxi¬¨mum size for internal
2345 character arrays. 
2346
2347 \par Name       
2348 MAXHELPERS      
2349 \par Value      
2350 10      
2351 \par Description 
2352 Size of an internal Volume Server character array (busyFlags), it marks the
2353 maximum number of threads within the server. 
2354
2355 \par Name       
2356 STDERR  
2357 \par Value      
2358 stderr  
2359 \par Description 
2360 Synonym for the unix standard input file descriptor. 
2361
2362 \par Name       
2363 STDOUT  
2364 \par Value      
2365 stdout  
2366 \par Description 
2367 Synonym for the unix standard output file descriptor. 
2368
2369         \section sec5-3 Section 5.3: Exported Variables 
2370
2371 \par
2372 This section describes the single variable that the Volume Server exports to
2373 its applications. 
2374 \par
2375 The QI GlobalWriteTrans exported variable represents a pointer to the head of
2376 the global queue of transaction structures for operations being handled by a
2377 Volume Server. Each object in this list is of type struct volser trans (see
2378 Section 5.4.1 below). 
2379
2380         \section sec5-4 Section 5.4: Structures and Typedefs 
2381
2382 \par
2383 This section describes the major exported Volume Server data structures of
2384 interest to application programmers, along with some of the the typedefs based
2385 on those structures. Please note that typedefs in shose definitions angle
2386 brackets appear are those fed through the Rxgen RPC stub generator. Rxgen uses
2387 these angle brackets to specify an array of indefinite size. 
2388
2389         \subsection sec5-4-1 Section 5.4.1: struct volser trans 
2390
2391 \par
2392 This structure defines the transaction record for all volumes upon which an
2393 active operation is proceeding. 
2394 \n \b Fields 
2395 \li struct volser trans *next - Pointer to the next transaction structure in
2396 the queue. 
2397 \li long tid - Transaction ID. 
2398 \li long time - The time this transaction was last active, for timeout
2399 purposes. 
2400 \li This is the standard unix time format. 
2401 \li long creationTime - The time a which this transaction started. 
2402 \li long returnCode - The overall transaction error code. 
2403 \li struct Volume *volume - Pointer to the low-level object describing the
2404 associated volume. This is included here for the use of lower-level support
2405 code. 
2406 \li long volid - The associated volume's numerical ID. 
2407 \li long partition - The partition on which the given volume resides. 
2408 \li long dumpTransId - Not used. 
2409 \li long dumpSeq - Not used. 
2410 \li short refCount - Reference count on this structure. 
2411 \li short iflags - Initial attach mode flags. 
2412 \li char vflags - Current volume status flags. 
2413 \li char tflags - Transaction flags. 
2414 \li char incremental - If non-zero, indicates that an incremental restore
2415 operation should be performed. 
2416 \li char lastProcName[] - Name of the last internal Volume Server procedure
2417 that used this transaction. This field may be up to 30 characters long,
2418 including the trailing null, and is intended for debugging purposes only. 
2419 \li struct rx call *rxCallPtr - Pointer to latest associated rx call. This
2420 field is intended for debugging purposes only. 
2421
2422         \subsection sec5-4-2 Section 5.4.2: struct volDescription 
2423
2424 \par
2425 This structure is used by the AFS backup system to group certain key fields of
2426 volume information. 
2427 \n \b Fields 
2428 \li char volName[] -The name of the given volume; maximum length of this string
2429 is VOLSER MAXVOLNAME characters, including the trailing null. 
2430 \li long volId -The volume's numerical ID. 
2431 \li int volSize -The size of the volume, in bytes. 
2432 \li long volFlags -Keeps validity information on the given volume and its
2433 clones. This field takes on values from the set defined in Section 5.2.7 
2434 \li long volCloneId -The volume's current clone ID. 
2435
2436         \subsection sec5-4-3 Section 5.4.3: struct partList 
2437
2438 \par
2439 This structure is used by the backup system and the vos tool to keep track of
2440 the state of the AFS disk partitions on a given server. 
2441 \n \b Fields 
2442 \li long partId[] -Set of 26 partition IDs. 
2443 \li long partFlags[] -Set to PARTVALID if the associated partition slot
2444 corresponds to a valid partition. There are 26 entries in this array. 
2445
2446         \subsection sec5-4-4 Section 5.4.4: struct volser status 
2447
2448 \par
2449 This structure holds the status of a volume as it is known to the Volume
2450 Server, and is passed to clients through the AFSVolGetStatus() interface call. 
2451 \par
2452 Two fields appearing in this structure, accessDate and updateDate, deserve a
2453 special note. In particular, it is important to observe that these fields are
2454 not kept in full synchrony with reality. When a File Server provides one of its
2455 client Cache Managers with a chunk of a file on which to operate, it is
2456 incapable of determining exactly when the data in that chunk is accessed, or
2457 exactly when it is updated. This is because the manipulations occur on the
2458 client machine, without any information on these accesses or updates passed
2459 back to the server. The only time these fields can be modified is when the
2460 chunk of a file resident within the given volume is delivered to a client (in
2461 the case of accessDate), or when a client writes back a dirty chunk to the File
2462 Server (in the case of updateDate). 
2463 \n \b Fields 
2464 \li long volID - The volume's numerical ID, unique within the cell. 
2465 \li long nextUnique - Next value to use for a vnode uniquifier within this
2466 volume. 
2467 \li int type - Basic volume class, one of RWVOL, ROVOL, or BACKVOL. 
2468 \li long parentID - Volume ID of the parent, if this volume is of type ROVOL or
2469 BACKVOL. 
2470 \li long cloneID - ID of the latest read-only clone, valid iff the type field
2471 is set to RWVOL. 
2472 \li long backupID - Volume ID of the latest backup of this read-write volume. 
2473 \li long restoredFromID - The volume ID contained in the dump from which this
2474 volume was restored. This field is used to simply make sure that an incremental
2475 dump is not restored on top of something inappropriate. Note that this field
2476 itself is not dumped. 
2477 \li long maxQuota - The volume's maximum quota, in 1Kbyte blocks. 
2478 \li long minQuota - The volume's minimum quota, in 1Kbyte blocks. 
2479 \li long owner - The user ID of the person responsible for this volume. 
2480 \li long creationDate - For a volume of type RWVOL, this field marks its
2481 creation date.  For the original copy of a clone, this field represents the
2482 cloning date. 
2483 \li long accessDate - Last access time by a user for this volume. This value is
2484 expressed as a standard unix longword date quantity. 
2485 \li long updateDate - Last modification time by a user for this volume. This
2486 value is expressed as a standard unix longword date quantity. 
2487 \li long expirationDate - Expiration date for this volume. If the volume never
2488 expires, then this field is set to zero. 
2489 \li long backupDate - The last time a backup clone was created for this volume. 
2490 \li long copyDate - The time that this copy of this volume was created. 
2491
2492         \subsection sec5-4-5 Section 5.4.5: struct destServer 
2493
2494 \par
2495 Used to specify the destination server in an AFSVolForward() invocation (see
2496 Section 5.7.7). 
2497 \n \b Fields 
2498 \li long destHost - The IP address of the destination server. 
2499 \li long destPort - The UDP port for the Volume Server Rx service there. 
2500 \li long destSSID - Currently, this field is always set to 1. 
2501
2502         \subsection sec5-4-6 Section 5.4.6: struct volintInfo 
2503
2504 \par
2505 This structure is used to communicate volume information to the Volume Server's
2506 RPC clients. It is used to build the volEntries object, which appears as a
2507 parameter to the AFSVolListVolumes() call. 
2508 \par
2509 The comments in Section 5.4.4 concerning the accessDate and updateDate fields
2510 are equally valid for the analogue fields in this structure. 
2511 \n \b Fields 
2512 \li char name[] - The null-terminated name for the volume, which can be no
2513 longer than VNAMESIZE (32) characters, including the trailing null. 
2514 \li long volid - The volume's numerical ID. 
2515 \li long type - The volume's basic class, one of RWVOL, ROVOL, or BACKVOL. 
2516 \li long backupID - The latest backup volume's ID. 
2517 \li long parentID - The parent volume's ID. 
2518 \li long cloneID - The latest clone volume's ID. 
2519 \li long status - Status of the volume; may be one of VOK or VBUSY. 
2520 \li long copyDate - The time that this copy of this volume was created. 
2521 \li unsigned char inUse - If non-zero, an indication that this volume is
2522 online. 
2523 \li unsigned char needsSalvaged - If non-zero, an indication that this volume
2524 needs to be salvaged. 
2525 \li unsigned char destroyMe - If non-zero, an indication that this volume
2526 should be destroyed. 
2527 \li long creationDate - Creation date for a read/write volume; cloning date for
2528 the original copy of a read-only volume. 
2529 \li long accessDate - Last access time by a user for this volume. 
2530 \li long updateDate - Last modification time by a user for this volume. 
2531 \li long backupDate - Last time a backup copy was made of this volume. 
2532 \li int dayUse - Number of times this volume was accessed since midnight of the
2533 current day. 
2534 \li int filecount - the number of file system objects contained within the
2535 volume. 
2536 \li int maxquota - The upper limit on the number of 1-Kbyte disk blocks of
2537 storage that this volume may obtain. 
2538 \li int size - Not known. 
2539 \li long flags - Values used by the backup system are stored here. 
2540 \li long spare1 -spare3 -Spare fields, reserved for future use. 
2541
2542         \subsection sec5-4-7 Section 5.4.7: struct transDebugInfo 
2543
2544 \par
2545 This structure is provided for monitoring and debugging purposes. It is used to
2546 compose the transDebugEntries variable-sized object, which in turn appears as a
2547 parameter to the AFSVolMonitor() interface call. 
2548 \n \b Fields 
2549 \li long tid - The transaction ID. 
2550 \li long time - The time when the transaction was last active, for timeout
2551 purposes. 
2552 \li long creationTime - The time the transaction started. 
2553 \li long returnCode - The overall transaction error code. 
2554 \li long volid - The open volume's ID. 
2555 \li long partition - The open volume's partition. 
2556 \li short iflags - Initial attach mode flags (IT*). 
2557 \li char vflags - Current volume status flags (VT*). 
2558 \li char tflags - Transaction flags (TT*). 
2559 \li char lastProcName[] - The string name of the last procedure which used
2560 transaction. This field may be up to 30 characters long, including the trailing
2561 null, and is intended for debugging purposes only. 
2562 \li int callValid - Flag which determines if the following fields are valid. 
2563 \li long readNext - Sequence number of the next Rx packet to be read. 
2564 \li long transmitNext - Sequence number of the next Rx packet to be
2565 transmitted. 
2566 \li int lastSendTime - The last time anything was sent over the wire for this
2567 transaction. 
2568 \li int lastReceiveTime - The last time anything was received over the wire for
2569 this transaction. 
2570
2571         \subsection sec5-4-8 Section 5.4.8: struct pIDs 
2572
2573 \par
2574 Used by the AFSVolListPartitions() interface call, this structure is used to
2575 store information on all of the partitions on a given Volume Server. 
2576 \n \b Fields 
2577 \li long partIds[] - One per letter of the alphabet (/vicepa through /vicepz).
2578 Filled with 0 for "/vicepa", 25 for "/vicepz". Invalid partition slots are
2579 filled in with a -1. 
2580
2581         \subsection sec5-4-9 Section 5.4.9: struct diskPartition 
2582
2583 \par
2584 This structure contains information regarding an individual AFS disk partition.
2585 It is returned as a parameter to the AFSVolPartitionInfo() call. 
2586 \n \b Fields 
2587 \li char name[] -Mounted partition name, up to 32 characters long including the
2588 trailing null. 
2589 \li char devName[] -Device name on which the partition lives, up to 32
2590 characters long including the trailing null. 
2591 \li int lock fd -A lock used for mutual exclusion to the named partition. A
2592 value of -1 indicates the lock is not currently being held. Otherwise, it has
2593 the file descriptor resulting from the unix open() call on the file specified
2594 in the name field used to "acquire" the lock. 
2595 \li int totalUsable - The number of blocks within the partition which are
2596 available. 
2597 \li int free - The number of free blocks in the partition. 
2598 \li int minFree - The minimum number of blocks that must remain free regardless
2599 of allocation requests. 
2600
2601         \section sec5-4-10 Section 5.4.10: struct restoreCookie 
2602
2603 \par
2604 Used as a parameter to both AFSVolRestore() and AFSVolForward(),a restoreCookie
2605 keeps information that must be preserved between various Volume Server
2606 operations. 
2607 \n \b Fields 
2608 \li char name[] - The volume name, up to 32 characters long including the
2609 trailing null. 
2610 \li long type - The volume type, one of RWVOL, ROVOL, and BACKVOL. 
2611 \li long clone - The current read-only clone ID for this volume. 
2612 \li long parent - The parent ID for this volume. 
2613
2614         \section sec5-4-11 Section 5.4.11: transDebugEntries 
2615
2616 \code
2617 typedef transDebugInfo transDebugEntries<>; 
2618 \endcode
2619 \par
2620 This typedef is used to generate a variable-length object which is passed as a
2621 parameter to the AFSVolMonitor() interface function. Thus, it may carry any
2622 number of descriptors for active transactions on the given Volume Server.
2623 Specifi, it causes a C structure of the same name to be defined with the
2624 following fields: 
2625 \n \b Fields 
2626 \li u int transDebugEntries len - The number of struct transDebugInfo (see
2627 Section 5.4.7) objects appearing at the memory location pointed to by the
2628 transDebugEntries val field. 
2629 \li transDebugInfo *transDebugEntries val - A pointer to a region of memory
2630 containing an array of transDebugEntries len objects of type struct
2631 transDebugInfo. 
2632
2633         \subsection sec5-4-12 Section 5.4.12: volEntries 
2634
2635 \code
2636 typedef volintInfo volEntries<>; 
2637 \endcode
2638 \par
2639 This typedef is used to generate a variable-length object which is passed as a
2640 parameter to AFSVolListVolumes(). Thus, it may carry any number of descriptors
2641 for volumes on the given Volume Server. Specifically, it causes a C structure
2642 of the same name to be defined with the following fields: 
2643 \n \b Fields 
2644 \li u int volEntries len - The number of struct volintInfo (see Section 5.4.6)
2645 objects appearing at the memory location pointed to by the volEntries val
2646 field. 
2647 \li volintInfo *volEntries val -A pointer to a region of memory containing an
2648 array of volEntries len objects of type struct volintInfo. 
2649
2650         \section sec5-5 Section 5.5: Error Codes 
2651
2652 \par
2653 The Volume Server advertises two groups of error codes. The first set consists
2654 of the standard error codes defined by the package. The second is a collection
2655 of lower-level return values which are exported here for convenience. 
2656
2657 \par Name       
2658 VOLSERTRELE ERROR       
2659 \par Value      
2660 1492325120L     
2661 \par Description 
2662 internal error releasing transaction. 
2663
2664 \par Name       
2665 VOLSERNO OP     
2666 \par Value      
2667 1492325121L     
2668 \par Description 
2669 unknown internal error. 
2670
2671 \par Name       
2672 VOLSERREAD DUMPERROR    
2673 \par Value      
2674 1492325122L     
2675 \par Description 
2676 badly formatted dump. 
2677
2678 \par Name       
2679 VOLSERDUMPERROR         
2680 \par Value      
2681 1492325123L     
2682 \par Description 
2683 badly formatted dump(2). 
2684
2685 \par Name       
2686 VOLSERATTACH ERROR      
2687 \par Value      
2688 1492325124L     
2689 \par Description 
2690 could not attach volume. 
2691
2692 \par Name       
2693 VOLSERILLEGAL PARTITION         
2694 \par Value      
2695 1492325125L     
2696 \par Description 
2697 illegal partition. 
2698
2699 \par Name       
2700 VOLSERDETACH ERROR      
2701 \par Value      
2702 1492325126L     
2703 \par Description 
2704 could not detach volume. 
2705
2706 \par Name       
2707 VOLSERBAD ACCESS        
2708 \par Value      
2709 1492325127L     
2710 \par Description 
2711 insufficient privilege for volume operation. 
2712
2713 \par Name       
2714 VOLSERVLDB ERROR        
2715 \par Value      
2716 1492325128L     
2717 \par Description 
2718 error from volume location database. 
2719
2720 \par Name       
2721 VOLSERBADNAME   
2722 \par Value      
2723 1492325129L     
2724 \par Description 
2725 bad volume name. 
2726
2727 \par Name       
2728 VOLSERVOLMOVED  
2729 \par Value      
2730 1492325130L     
2731 \par Description 
2732 volume moved. 
2733
2734 \par Name       
2735 VOLSERBADOP     
2736 \par Value      
2737 1492325131L     
2738 \par Description 
2739 illegal volume operation. 
2740
2741 \par Name       
2742 VOLSERBADRELEASE        
2743 \par Value      
2744 1492325132L     
2745 \par Description 
2746 volume release failed. 
2747
2748 \par Name       
2749 VOLSERVOLBUSY   
2750 \par Value      
2751 1492325133L     
2752 \par Description 
2753 volume still in use by volserver. 
2754
2755 \par Name       
2756 VOLSERNO MEMORY         
2757 \par Value      
2758 1492325134L     
2759 \par Description 
2760 out of virtual memory in volserver. 
2761
2762 \par Name       
2763 VOLSERNOVOL     
2764 \par Value      
2765 1492325135L     
2766 \par Description 
2767 no such volume. 
2768
2769 \par Name       
2770 VOLSERMULTIRWVOL        
2771 \par Value      
2772 1492325136L     
2773 \par Description 
2774 more than one read/write volume. 
2775
2776 \par Name       
2777 VOLSERFAILEDOP  
2778 \par Value      
2779 1492325137L     
2780 \par Description 
2781 failed volume server operation. 
2782
2783         \subsection sec5-5-1 Section 5.5.1: Standard 
2784
2785 \par
2786 The error codes described in this section were defined by the Volume Server to
2787 describe exceptional conditions arising in the course of RPC call handling. 
2788
2789         \subsection sec5-5-2 Section 5.5.2: Low-Level 
2790
2791 \par
2792 These error codes are duplicates of those defined from a package which is
2793 internal to the Volume Server. They are re-defined here to make them visible to
2794 Volume Server clients. 
2795
2796 \par Name       
2797 VSALVAGE        
2798 \par Value      
2799 101     
2800 \par Description 
2801 Volume needs to be salvaged. 
2802
2803 \par Name       
2804 VNOVNODE        
2805 \par Value      
2806 102     
2807 \par Description 
2808 Bad vnode number encountered. 
2809
2810 \par Name       
2811 VNOVOL  
2812 \par Value      
2813 103     
2814 \par Description 
2815 The given volume is either not attached, doesn't exist, or is not online. 
2816
2817 \par Name       
2818 VVOLEXISTS      
2819 \par Value      
2820 104     
2821 \par Description 
2822 The given volume already exists. 
2823
2824 \par Name       
2825 VNOSERVICE      
2826 \par Value      
2827 105     
2828 \par Description 
2829 The volume is currently not in service. 
2830
2831 \par Name       
2832 VOFFLINE        
2833 \par Value      
2834 106     
2835 \par Description 
2836 The specified volume is offline, for the reason given in the offline message
2837 field (a subfield within the volume field in struct volser trans). 
2838
2839 \par Name       
2840 VONLINE         
2841 \par Value      
2842 107     
2843 \par Description 
2844 Volume is already online. 
2845
2846 \par Name       
2847 VDISKFULL       
2848 \par Value      
2849 108     
2850 \par Description 
2851 The disk partition is full. 
2852
2853 \par Name       
2854 VOVERQUOTA      
2855 \par Value      
2856 109     
2857 \par Description 
2858 The given volume's maximum quota, as expressed in the maxQuota field of the
2859 struct volintInfo, has been exceeded. 
2860
2861 \par Name       
2862 VBUSY   
2863 \par Value      
2864 110     
2865 \par Description 
2866 The named volume is temporarily unavailable, and the client is encouraged to
2867 retry the operation shortly. 
2868
2869 \par Name       
2870 VMOVED  
2871 \par Value      
2872 111     
2873 \par Description 
2874 The given volume has moved to a new server. 
2875
2876 \par
2877 The VICE SPECIAL ERRORS constant is defined to be the lowest of these error
2878 codes. 
2879
2880         \section sec5-6 Section 5.6: Macros 
2881
2882 \par
2883 The Volume Server defines a small number of macros, as described in this
2884 section. 
2885         \subsection sec5-6-1 Section 5.6.1: THOLD() 
2886
2887 \code
2888 #define THOLD(tt) ((tt)->refCount++) 
2889 \endcode
2890 \par
2891 This macro is used to increment the reference count field, refCount, in an
2892 object of type struct volser trans. Thus, the associated transaction is
2893 effectively "held" insuring it won't be garbage-collected. The counterpart to
2894 this operation, TRELE(), is implemented by the Volume Server as a function. 
2895
2896         \subsection sec5-6-2 Section 5.6.2: ISNAMEVALID() 
2897
2898 \code
2899 #define ISNAMEVALID(name) (strlen(name) < (VOLSER_OLDMAXVOLNAME -9)) 
2900 \endcode
2901 \par
2902 This macro checks to see if the given name argument is of legal length. It must
2903 be no more than the size of the container, which is at most VOLSER
2904 OLDMAXVOLNAME characters, minus the length of the longest standardized volume
2905 name postfix known to the system. That postfix is the 9-character .restored
2906 string, which is tacked on to the name of a volume that has been restored from
2907 a dump. 
2908
2909         \section sec5-7 Section 5.7: Functions 
2910
2911 \par
2912 This section covers the Volume Server RPC interface routines, defined by and
2913 generated from the volint.xg Rxgen file. The following is a summary of the
2914 interface functions and their purpose: 
2915
2916 \par Fcn Name   
2917 AFSVolCreateVolume      
2918 \par Description 
2919 Create a volume. 
2920
2921 \par Fcn Name   
2922 AFSVolDeleteVolume      
2923 \par Description 
2924 Delete a volume. 
2925
2926 \par Fcn Name   
2927 AFSVolNukeVolume        
2928 \par Description 
2929 Obliterate a volume completely. 
2930
2931 \par Fcn Name   
2932 AFSVolDump      
2933 \par Description 
2934 Dump (i.e., save) the contents of a volume. 
2935
2936 \par Fcn Name   
2937 AFSVolSignalRestore     
2938 \par Description 
2939 Show intention to call AFSVolRestore(). 
2940
2941 \par Fcn Name   
2942 AFSVolRestore   
2943 \par Description 
2944 Recreate a volume from a dump. 
2945
2946 \par Fcn Name   
2947 AFSVolForward   
2948 \par Description 
2949 Dump a volume, then restore to a given server and volume. 
2950
2951 \par Fcn Name   
2952 AFSVolClone     
2953 \par Description 
2954 Clone (and optionally purge) a volume. 
2955
2956 \par Fcn Name   
2957 AFSVolReClone   
2958 \par Description 
2959 Re-clone a volume. 
2960
2961 \par Fcn Name   
2962 AFSVolSetForwarding     
2963 \par Description 
2964 Set forwarding info for a moved volume. 
2965
2966 \par Fcn Name   
2967 AFSVolTransCreate       
2968 \par Description 
2969 Create transaction for a [volume, partition]. 
2970
2971 \par Fcn Name   
2972 AFSVolEndTrans  
2973 \par Description 
2974 End a transaction. 
2975
2976 \par Fcn Name   
2977 AFSVolGetFlags  
2978 \par Description 
2979 Get volume flags for a transaction. 
2980
2981 \par Fcn Name   
2982 AFSVolSetFlags  
2983 \par Description 
2984 Set volume flags for a transaction. 
2985
2986 \par Fcn Name   
2987 AFSVolGetName   
2988 \par Description 
2989 Get the volume name associated with a transaction. 
2990
2991 \par Fcn Name   
2992 AFSVolGetStatus         
2993 \par Description 
2994 Get status of a transaction/volume. 
2995
2996 \par Fcn Name   
2997 AFSVolSetIdsTypes       
2998 \par Description 
2999 Set header info for a volume. 
3000
3001 \par Fcn Name   
3002 AFSVolSetDate   
3003 \par Description 
3004 Set creation date in a volume. 
3005
3006 \par Fcn Name   
3007 AFSVolListPartitions    
3008 \par Description 
3009 Return a list of AFS partitions on a server. 
3010
3011 \par Fcn Name   
3012 AFSVolPartitionInfo     
3013 \par Description 
3014 Get partition information. 
3015
3016 \par Fcn Name   
3017 AFSVolListVolumes       
3018 \par Description 
3019 Return a list of volumes on the server. 
3020
3021 \par Fcn Name   
3022 AFSVolListOneVolume     
3023 \par Description 
3024 Return header info for a single volume. 
3025
3026 \par Fcn Name   
3027 AFSVolGetNthVolume      
3028 \par Description 
3029 Get volume header given its index. 
3030
3031 \par Fcn Name   
3032 AFSVolMonitor   
3033 \par Description 
3034 Collect server transaction state. 
3035
3036
3037 \par
3038 There are two general comments that apply to most of the Volume Server
3039 interface routines: 
3040 \li 1. AFS partitions are identified by integers ranging from 0 to 25,
3041 corresponding to the letters "a" through "z". By convention, AFS partitions are
3042 named /vicepx, where x is any lower-case letter. 
3043 \li 2. Legal volume types to pass as parameters are RWVOL, ROVOL, and BACKVOL,
3044 as defined in Section 3.2.4. 
3045
3046         \subsection sec5-7-1 Section 5.7.1: AFSVolCreateVolume - Create a
3047 volume 
3048
3049 \code
3050 int AFSVolCreateVolume(IN struct rx connection *z conn, 
3051                         IN long partition, 
3052                         IN char *name, 
3053                         IN long type, 
3054                         IN long parent, 
3055                         INOUT long *volid, 
3056                         OUT long *trans) 
3057 \endcode
3058 \par Description 
3059 Create a volume named name, with numerical identifier volid, and of type type.
3060 The new volume is to be placed in the specified partition for the server
3061 machine as identified by the Rx connection information pointed to by z conn. If
3062 a value of 0 is provided for the parent argument, it will be set by the Volume
3063 Server to the value of volid itself. The trans parameter is set to the Volume
3064 Location Server transaction ID corresponding to the volume created by this
3065 call, if successful. 
3066 The numerical volume identifier supplied in the volid parameter must be
3067 generated beforehand by calling VL GetNewVolumeID() (see Section 3.6.5). After
3068 AFSVolCreateVolume() completes correctly, the new volume is marked as offline.
3069 It must be explicitly brought online through a call to AFSVolSetFlags() (see
3070 Section 5.7.14) while passing the trans transaction ID generated by
3071 AFSVolCreateVolume(). The "hold" on the new volume guaranteed by the trans
3072 transaction may be "released" by calling AFSVolEnd-Trans(). Until then, no
3073 other process may operate on the volume. 
3074 Upon creation, a volume's maximum quota (as specified in the maxquota field of
3075 a struct volintInfo) is set to 5,000 1-Kbyte blocks. 
3076 Note that the AFSVolCreateVolume() routine is the only Volume Server function
3077 that manufactures its own transaction. All others must have already acquired a
3078 transaction ID via either a previous call to AFSVolCreateVolume() or
3079 AFSVolTransCreate(). 
3080 \par Error Codes 
3081 VOLSERBADNAME The volume name parameter was longer than 31 characters plus the
3082 trailing null. 
3083 \n VOLSERBAD ACCESS The caller is not authorized to create a volume. 
3084 \n EINVAL The type parameter was illegal. E2BIG A value of 0 was provided in
3085 the volid parameter. VOLSERVOLBUSY A transaction could not be created, thus the
3086 given volume was busy. 
3087 \n EIO The new volume entry could not be created. 
3088 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3089 dropped to the proper level. 
3090 \n <misc> If the partition parameter is unintelligible, this routine will
3091 return a low-level unix error. 
3092
3093         \subsection sec5-7-2 Section 5.7.2: AFSVolDeleteVolume - Delete a
3094 volume 
3095
3096 \code
3097 int AFSVolDeleteVolume(IN struct rx connection *z conn, IN long trans) 
3098 \endcode
3099 \par Description 
3100 Delete the volume associated with the open transaction ID specified within
3101 trans. All of the file system objects contained within the given volume are
3102 destroyed, and the on-disk volume metadata structures are reclaimed. In
3103 addition, the in-memory volume descriptor's vflags field is set to VTDeleted,
3104 indicating that it has been deleted. 
3105 \par
3106 Under some circumstances, a volume should be deleted by calling
3107 AFSVolNukeVolume() instead of this routine. See Section 5.7.3 for more details. 
3108 \par Error Codes 
3109 VOLSERBAD ACCESS The caller is not authorized to delete a volume. 
3110 \n ENOENT The trans transaction was not found. 
3111 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3112 dropped to the proper level. 
3113
3114         \subsection sec5-7-3 Section 5.7.3: AFSVolNukeVolume - Obliterate a
3115 volume completely 
3116
3117 \code
3118 int AFSVolNukeVolume(IN struct rx connection *z conn, 
3119                         IN long partID, 
3120                         IN long volID) 
3121 \endcode
3122 \par Description 
3123 Completely obliterate the volume living on partition partID whose ID is volID.
3124 This involves scanning all inodes on the given partition and removing those
3125 marked with the specified volID. If the volume is a read-only clone, only the
3126 header inodes are removed, since they are the only ones stamped with the
3127 read-only ID. To reclaim the space taken up by the actual data referenced
3128 through a read-only clone, this routine should be called on the read-write
3129 master. Note that calling AFSVolNukeVolume() on a read-write volume effectively
3130 destroys all the read-only volumes cloned from it, since everything except for
3131 their indicies to the (now-deleted) data will be gone. 
3132 \par
3133 Under normal circumstances, it is preferable to use AFSVolDeleteVolume()
3134 instead of AFSVolNukeVolume() to delete a volume. The former is much more
3135 efficient, as it only touches those objects in the partition that belong to the
3136 named volume, walking the on-disk volume metadata structures. However,
3137 AFSVolNukeVolume() must be used in situations where the volume metadata
3138 structures are known to be damaged. Since a complete scan of all inodes in the
3139 partition is performed, all disconnected or unreferenced portions of the given
3140 volume will be reclaimed. 
3141 \par Error Codes 
3142 VOLSERBAD ACCESS The caller is not authorized to call this routine. 
3143 \n VOLSERNOVOL The partition specified by the partID argument is illegal. 
3144
3145         \subsection sec5-7-4 Section 5.7.4: AFSVolDump - Dump (i.e., save) the
3146 contents of a volume 
3147
3148 \code
3149 int AFSVolDump(IN struct rx connection *z conn, 
3150                 IN long fromTrans, 
3151                 IN long fromDate) 
3152 \endcode
3153 \par Description 
3154 Generate a canonical dump of the contents of the volume associated with
3155 transaction fromTrans as of calendar time fromDate. If the given fromDate is
3156 zero, then a full dump will be carried out. Otherwise, the resulting dump will
3157 be an incremental one. 
3158 \par
3159 This is specified as a split function within the volint.xg Rxgen interface
3160 file. This specifies that two routines are generated, namely StartAFSVolDump()
3161 and EndAFSVolDump(). The former is used to marshall the IN arguments, and the
3162 latter is used to unmarshall the return value of the overall operation. The
3163 actual dump data appears in the Rx stream for the call (see the section
3164 entitled Example Server and Client in the companion AFS-3 Programmer's
3165 Reference: Specification for the Rx Remote Procedure Call Facility document). 
3166 \par Error Codes 
3167 VOLSERBAD ACCESS The caller is not authorized to dump a volume. 
3168 \n ENOENT The fromTrans transaction was not found. 
3169 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3170 dropped to the proper level. 
3171
3172         \subsection sec5-7-5 Section 5.7.5: AFSVolSignalRestore - Show
3173 intention to call AFSVolRestore() 
3174
3175 \code
3176 int AFSVolSignalRestore(IN struct rx connection *z conn, 
3177                         IN char *name, 
3178                         IN int type, 
3179                         IN long pid, 
3180                         IN long cloneid) 
3181 \endcode
3182 \par Description 
3183 Show an intention to the Volume Server that the client will soon call
3184 AFSVolRestore(). The parameters, namely the volume name, type, parent ID pid
3185 and clone ID cloneid are stored in a well-known set of global variables. These
3186 values are used to set the restored volume's header, overriding those values
3187 present in the dump from which the volume will be resurrected. 
3188 \par Error Codes 
3189 VOLSERBAD ACCESS The caller is not authorized to call this routine. 
3190 \n VOLSERBADNAME The volume name contained in name was longer than 31
3191 characters plus the trailing null. 
3192
3193         \subsection sec5-7-6 Section 5.7.6: AFSVolRestore - Recreate a volume
3194 from a dump 
3195
3196 \code
3197 int AFSVolRestore(IN struct rx connection *z conn, 
3198                         IN long toTrans, 
3199                         IN long flags, 
3200                         IN struct restoreCookie *cookie) 
3201 \endcode
3202 \par Description 
3203 Interpret a canonical volume dump (generated as the result of calling
3204 AFSVolDumpVolume()), passing it to the volume specified by the toTrans
3205 transaction. Only the low bit in the flags argument is inspected. If this low
3206 bit is turned on, the dump will be restored as incremental; otherwise, a full
3207 restore will be carried out. 
3208 \par
3209 All callbacks to the restored volume are broken. 
3210 \par
3211 This is specified as a split function within the volint.xg Rxgen interface
3212 file. This specifies that two routines are generated, namely
3213 StartAFSVolRestore() and EndAFSVolRestore() . The former is used to marshall
3214 the IN arguments, and the latter is used to unmarshall the return value of the
3215 overall operation. The actual dump data flows over the Rx stream for the call
3216 (see the section entitled Example Server and Client in the companion AFS-3
3217 Programmer's Reference: Specification for the Rx Remote Procedure Call Facility
3218 document). 
3219 \par
3220 The AFSVolSignalRestore() routine (see Section 5.7.5) should be called before
3221 invoking this function in order to signal the intention to restore a particular
3222 volume. 
3223 \par Error Codes 
3224 VOLSERREAD DUMPERROR Dump data being restored is corrupt. 
3225 \n VOLSERBAD ACCESS The caller is not authorized to restore a volume. 
3226 \n ENOENT The fromTrans transaction was not found. 
3227 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3228 dropped to the proper level. 
3229
3230         \subsection sec5-7-7 Section 5.7.7: AFSVolForward - Dump a volume, then
3231 restore to given server and volume 
3232
3233 \code
3234 int AFSVolForward(IN struct rx connection *z conn, 
3235                         IN long fromTrans, 
3236                         IN long fromDate, 
3237                         IN struct destServer *destination, 
3238                         IN long destTrans, 
3239                         IN struct restoreCookie *cookie) 
3240 \endcode
3241 \par Description 
3242 Dumps the volume associated with transaction fromTrans from the given fromDate.
3243 The dump itself is sent to the server described by destination, where it is
3244 restored as the volume associated with transaction destTrans. In reality, an Rx
3245 connection is set up to the destServer, StartAFSVolRestore() directs writing to
3246 the Rx call's stream, and then EndAFSVolRestore() is used to deliver the dump
3247 for the volume corresponding to fromTrans. If a non-zero fromDate is provided,
3248 then the dump will be incremental from that date. Otherwise, a full dump will
3249 be delivered. 
3250 \par
3251 The Rx connection set up for this task is always destroyed before the function
3252 returns. The destination volume should exist before carrying out this
3253 operation, and the invoking process should have started transactions on both
3254 participating volumes. 
3255 \par Error Codes 
3256 VOLSERBAD ACCESS The caller is not authorized to forward a volume. 
3257 \n ENOENT The fromTrans transaction was not found. 
3258 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3259 dropped to the proper level. 
3260 \n ENOTCONN An Rx connection to the destination server could not be
3261 established. 
3262
3263         \subsection sec5-7-8 Section 5.7.8: AFSVolClone - Clone (and optionally
3264 purge) a volume 
3265
3266 \code
3267 int AFSVolClone(IN struct rx connection *z conn, 
3268                 IN long trans, 
3269                 IN long purgeVol, 
3270                 IN long newType, 
3271                 IN char *newName, 
3272                 INOUT long *newVol) 
3273 \endcode
3274 \par Description 
3275 Make a clone of the read-write volume associated with transaction trans, giving
3276 the cloned volume a name of newName. The newType parameter specifies the type
3277 for the new clone, and may be either ROVOL or BACKVOL. If purgeVol is set to a
3278 non-zero value, then that volume will be purged during the clone operation.
3279 This may be more efficient that separate clone and purge calls when making
3280 backup volumes. The newVol parameter sets the new clone's ID. It is illegal to
3281 pass a zero in newVol. 
3282 \par Error Codes 
3283 VOLSERBADNAME The volume name contained in newName was longer than 31
3284 characters plus the trailing null. 
3285 \n VOLSERBAD ACCESS The caller is not authorized to clone a volume. 
3286 \n ENOENT The fromTrans transaction was not found. 
3287 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3288 dropped to the proper level. 
3289 \n VBUSY The given transaction was already in use; indicating that someone else
3290 is currently manipulating the specified clone. 
3291 \n EROFS The volume associated with the given trans is read-only (either ROVOL
3292 or BACKVOL). 
3293 \n EXDEV The volume associated with the trans transaction and the one specified
3294 by purgeVol must be on the same disk device, and they must be cloned from the
3295 same parent volume. 
3296 \n EINVAL The purgeVol must be read-only, i.e. either type ROVOL or BACKVOL. 
3297
3298         \subsection sec5-7-9 Section 5.7.9: AFSVolReClone - Re-clone a volume 
3299
3300 \code
3301 int AFSVolReClone(IN struct rx connection *z conn, 
3302                         IN long tid, 
3303                         IN long cloneID) 
3304 \endcode
3305 \par Description 
3306 Recreate an existing clone, with identifier cloneID, from the volume associated
3307 with transaction tid. 
3308 \par Error Codes 
3309 VOLSERBAD ACCESS The caller is not authorized to clone a volume. 
3310 \n ENOENT The tid transaction was not found. 
3311 \n VOLSERTRELE ERROR The tid transaction's reference count could not be dropped
3312 to the proper level. 
3313 \n VBUSY The given transaction was already in use; indicating that someone else
3314 is currently manipulating the specified clone. 
3315 \n EROFS The volume to be cloned must be read-write (of type RWVOL). 
3316 \n EXDEV The volume to be cloned and the named clone itself must be on the same
3317 device. Also, cloneID must have been cloned from the volume associated with
3318 transaction tid. 
3319 \n EINVAL The target clone must be a read-only volume (i.e., of type ROVOL or
3320 BACKVOL). 
3321
3322         \subsection sec5-7-10 Section 5.7.10: AFSVolSetForwarding - Set
3323 forwarding info for a moved volume 
3324
3325 \code
3326 int AFSVolSetForwarding(IN struct rx connection *z conn, 
3327                         IN long tid, 
3328                         IN long newsite) 
3329 \endcode
3330 \par Description 
3331 Record the IP address specified within newsite as the location of the host
3332 which now hosts the volume associated with transaction tid, formerly resident
3333 on the current host. This is intended to gently guide Cache Managers who have
3334 stale volume location cached to the volume's new site, ensuring the move is
3335 transparent to clients using that volume. 
3336 \par Error Codes 
3337 VOLSERBAD ACCESS The caller is not authorized to create a forwarding address. 
3338 \n ENOENT The trans transaction was not found. 
3339
3340         \subsection sec5-7-11 Section 5.7.11: AFSVolTransCreate - Create
3341 transaction for a [volume, partition] 
3342
3343 \code
3344 int AFSVolTransCreate(IN struct rx connection *z conn, 
3345                         IN long volume, 
3346                         IN long partition, 
3347                         IN long flags, 
3348                         OUT long *trans) 
3349 \endcode
3350 \par Description 
3351 Create a new Volume Server transaction associated with volume ID volume on
3352 partition partition. The type of volume transaction is specified by the flags
3353 parameter. The values in flags specify whether the volume should be treated as
3354 busy (ITBusy), offline (ITOffline), or in shared read-only mode (ITReadOnly).
3355 The identifier for the new transaction built by this function is returned in
3356 trans. 
3357 \par
3358 Creating a transaction serves as a signal to other agents that may be
3359 interested in accessing a volume that it is unavailable while the Volume Server
3360 is manipulating it. This prevents the corruption that could result from
3361 multiple simultaneous operations on a volume. 
3362 \par Error Codes 
3363 EINVAL Illegal value encountered in flags. 
3364 \n VOLSERVOLBUSY A transaction could not be created, thus the given [volume,
3365 partition] pair was busy. 
3366 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3367 dropped to the proper level after creation. 
3368
3369         \subsection sec5-7-12 Section 5.7.12: AFSVolEndTrans - End a
3370 transaction 
3371
3372 \code
3373 int AFSVolEndTrans(IN struct rx connection *z conn, 
3374                         IN long trans, 
3375                         OUT long *rcode) 
3376 \endcode
3377 \par Description 
3378 End the transaction identified by trans, returning its final error code into
3379 rcode. This makes the associated [volume, partition] pair eligible for further
3380 Volume Server operations. 
3381 \par Error Codes 
3382 VOLSERBAD ACCESS The caller is not authorized to create a transaction. 
3383 \n ENOENT The trans transaction was not found. 
3384
3385         \subsection sec5-7-13 Section 5.7.13: AFSVolGetFlags - Get volume flags
3386 for a transaction 
3387
3388 \code
3389 int AFSVolGetFlags(IN struct rx connection *z conn, 
3390                         IN long trans, 
3391                         OUT long *flags) 
3392 \endcode
3393 \par Description 
3394 Return the value of the vflags field of the struct volser trans object
3395 describing the transaction identified as trans. The set of values placed in the
3396 flags parameter is described in Section 5.2.3.1. Briefly, they indicate whether
3397 the volume has been deleted (VTDeleted), out of service (VTOutOfService), or
3398 marked delete-on-salvage (VTDeleteOnSalvage). 
3399 \par Error Codes 
3400 ENOENT The trans transaction was not found. 
3401 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3402 dropped to the proper level. 
3403
3404         \subsection sec5-7-14 Section 5.7.14: AFSVolSetFlags - Set volume flags
3405 for a transaction 
3406
3407 \code
3408 int AFSVolSetFlags(IN struct rx connection *z conn, 
3409                         IN long trans, 
3410                         IN long flags) 
3411 \endcode
3412 \par Description 
3413 Set the value of the vflags field of the struct volser trans object describing
3414 the transaction identified as trans to the contents of flags. The set of legal
3415 values for the flags parameter is described in Section 5.2.3.1. Briefly, they
3416 indicate whether the volume has been deleted (VTDeleted), out of service
3417 (VTOutOfService), or marked delete-onsalvage (VTDeleteOnSalvage). 
3418 \par Error Codes 
3419 ENOENT The trans transaction was not found. 
3420 \n EROFS Updates to this volume are not allowed. 
3421 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3422 dropped to the proper level. 
3423
3424         \subsection sec5-7-15 Section 5.7.15: AFSVolGetName - Get the volume
3425 name associated with a transaction 
3426
3427 \code
3428 int AFSVolGetName(IN struct rx connection *z conn, 
3429                         IN long tid, 
3430                         OUT char **tname) 
3431 \endcode
3432 \par Description 
3433 Given a transaction identifier tid, return the name of the volume associated
3434 with the given transaction. The tname parameter is set to point to the address
3435 of a string buffer of at most 256 chars containing the desired information,
3436 which is created for this purpose. Note: the caller is responsible for freeing
3437 the buffer pointed to by tname when its information is no longer needed. 
3438 \par Error Codes 
3439 ENOENT The tid transaction was not found, or a volume was not associated with
3440 it (VSrv internal error). 
3441 \n E2BIG The volume name was too big (greater than or equal to SIZE (1,024)
3442 characters. 
3443 \n VOLSERTRELE ERROR The trans transaction's reference count could not be
3444 dropped to the proper level. 
3445
3446         \subsection sec5-7-16 Section 5.7.16: AFSVolGetStatus - Get status of a
3447 transaction/volume 
3448
3449 \code
3450 int AFSVolGetStatus(IN struct rx connection *z conn, 
3451                         IN long tid, 
3452                         OUT struct volser status *status) 
3453 \endcode
3454 \par Description 
3455 This routine fills the status structure passed as a parameter with status
3456 information for the volume identified by the transaction identified by tid, if
3457 it exists. Included in this status information are the volume's ID, its type,
3458 disk quotas, the IDs of its clones and backup volumes, and several other
3459 administrative details. 
3460 \par Error Codes 
3461 ENOENT The tid transaction was not found. 
3462 \n VOLSERTRELE ERROR The tid transaction's reference count could not be dropped
3463 to the proper level. 
3464
3465         \subsection sec5-7-17 Section 5.7.17: AFSVolSetIdsTypes - Set header
3466 info for a volume 
3467
3468 \code
3469 int AFSVolSetIdsTypes(IN struct rx connection *z conn, 
3470                         IN long tId 
3471                         IN char *name, 
3472                         IN long type, 
3473                         IN long pId, 
3474                         IN long cloneId, 
3475                         IN long backupId) 
3476 \endcode
3477 \par Description 
3478 The transaction identifed by tId is located, and the values supplied for the
3479 volume name, volume type, parent ID pId, clone ID cloneId and backup ID
3480 backupId are recorded into the given transaction. 
3481 \par Error Codes 
3482 ENOENT The tId transaction was not found. 
3483 \n VOLSERBAD ACCESS The caller is not authorized to call this routine. 
3484 \n VOLSERBADNAME The volume name contained in name was longer than 31
3485 characters plus the trailing null. 
3486 \n VOLSERTRELE ERROR The tId transaction's reference count could not be dropped
3487 to the proper level. 
3488
3489         \subsection sec5-7-18 Section 5.7.18: AFSVolSetDate - Set creation date
3490 in a volume 
3491
3492 \code
3493 int AFSVolSetDate(IN struct rx connection *z conn, 
3494                         IN long tid, 
3495                         IN long newDate) 
3496 \endcode
3497 \par Description 
3498 Set the creationDate of the struct volintInfo describing the volume associated
3499 with transaction tid to newDate. 
3500 \par Error Codes 
3501 VOLSERBAD ACCESS The caller is not authorized to call this routine. 
3502 \n ENOENT The tId transaction was not found. 
3503 \n VOLSERTRELE ERROR The tid transaction's reference count could not be dropped
3504 to the proper level. 
3505
3506         \subsection sec5-7-19 Section 5.7.19: AFSVolListPartitions - Return a
3507 list of AFS partitions on a server 
3508
3509 \code
3510 int AFSVolListPartitions(IN struct rx connection *z conn, 
3511                                 OUT struct pIDs *partIDs) 
3512 \endcode
3513 \par Description 
3514 Return a list of AFS partitions in use by the server processing this call. The
3515 output parameter is the fixed-length partIDs array, with one slot for each of
3516 26 possible partitions. By convention, AFS partitions are named /vicepx, where
3517 x is any letter. The /vicepa partition is represented by a zero in this array,
3518 /vicepa bya1, andsoon. Unused partitions are represented by slots filled with a
3519 -1. 
3520 \par Error Codes 
3521 ---None. 
3522
3523         \subsection sec5-7-20 Section 5.7.20: AFSVolPartitionInfo - Get
3524 partition information 
3525
3526 \code
3527 int AFSVolPartitionInfo(IN struct rx connection *z conn, 
3528                         IN char *name, 
3529                         OUT struct diskPartition *partition) 
3530 \endcode
3531 \par Description 
3532 Collect information regarding the partition with the given character string
3533 name, and place it into the partition object provided. 
3534 \par Error Codes 
3535 VOLSERBAD ACCESS The caller is not authorized to call this routine. 
3536 \n VOLSERILLEGAL PARTITION An illegal partition was specified by name 
3537
3538         \subsection sec5-7-21 Section 5.7.21: AFSVolListVolumes - Return a list
3539 of volumes on the server 
3540
3541 \code
3542 int AFSVolListVolumes(IN struct rx connection *z conn, 
3543                         IN long partID, 
3544                         IN long flags, 
3545                         OUT volEntries *resultEntries) 
3546 \endcode
3547 \par Description 
3548 Sweep through all the volumes on the partition identified by partid, filling in
3549 consecutive records in the resultEntries object. If the flags parameter is set
3550 to a non-zero value, then full status information is gathered. Otherwise, just
3551 the volume ID field is written for each record. The fields for a volEntries
3552 object like the one pointed to by resultEntries are described in Section 5.4.6,
3553 which covers the struct volintInfo definition. 
3554 \par Error Codes 
3555 VOLSERILLEGAL PARTITION An illegal partition was specified by partID 
3556 \n VOLSERNO MEMORY Not enough memory was available to hold all the required
3557 entries within resultEntries. 
3558
3559         \subsection sec5-7-22 Section 5.7.22: AFSVolListOneVolume - Return
3560 header info for a single volume 
3561
3562 \code
3563 int AFSVolListOneVolume(IN struct rx connection *z conn, 
3564                         IN long partID, 
3565                         IN long volid, 
3566                         OUT volEntries *resultEntries) 
3567 \endcode
3568 \par Description 
3569 Find the information for the volume living on partition partID whose ID is
3570 volid, and place a single struct volintInfo entry within the variable-size
3571 resultEntries object. 
3572 \par
3573 This is similar to the AFSVolListVolumes() call, which returns information on
3574 all volumes on the specified partition. The full volume information is always
3575 written into the returned entry (equivalent to setting the flags argument to
3576 AFSVolListVolumes() to a non-zero value). 
3577 \par Error Codes 
3578 VOLSERILLEGAL PARTITION An illegal partition was specified by partID 
3579 \n ENODEV The given volume was not found on the given partition. 
3580
3581         \subsection sec5-7.23 Section 5.7.23: AFSVolGetNthVolume - Get volume
3582 header given its index 
3583
3584 \code
3585 int AFSVolGetNthVolume(IN struct rx connection *z conn, 
3586                         IN long index, 
3587                         OUT long *volume, 
3588                         OUT long *partition) 
3589 \endcode
3590 \par Description 
3591 Using index as a zero-based index into the set of volumes hosted by the server
3592 chosen by the z conn argument, return the volume ID and partition of residence
3593 for the given index. 
3594 \Note This functionality has not yet been implemented. 
3595 \par Error Codes 
3596 VOLSERNO OP Not implemented. 
3597
3598         \subsection sec5-7.24 Section 5.7.24: AFSVolMonitor - Collect server
3599 transaction state 
3600
3601 \code
3602 int AFSVolMonitor(IN struct rx connection *z conn, 
3603                         OUT transDebugEntries *result) 
3604 \endcode
3605 \par Description 
3606 This call allows the transaction state of a Volume Server to be monitored for
3607 debugging purposes. Anyone wishing to supervise this Volume Server state may
3608 call this routine, causing all active transactions to be recorded in the given
3609 result object. 
3610 \par Error Codes 
3611 ---None. 
3612
3613         \page biblio Bibliography 
3614
3615 \li [1] Transarc Corporation. AFS 3.0 System Administrator's Guide,
3616 F-30-0-D102, Pittsburgh, PA, April 1990. 
3617 \li [2] Transarc Corporation. AFS 3.0 Command Reference Manual, F-30-0-D103,
3618 Pittsburgh, PA, April 1990. 
3619 \li [3] CMU Information Technology Center.      Synchronization and Caching
3620 Issues in the Andrew File System, USENIX Proceedings, Dallas, TX, Winter 1988. 
3621 \li [4] Information Technology Center, Carnegie Mellon University. Ubik -A
3622 Library For Managing Ubiquitous Data, ITCID, Pittsburgh, PA, Month, 1988. 
3623 \li [5] Information Technology Center, Carnegie Mellon University. Quorum
3624 Completion, ITCID, Pittsburgh, PA, Month, 1988. 
3625
3626   @}
3627 */