scout: Tidy header includes
[openafs.git] / doc / protocol / fs-cm-spec.h
1 /*! 
2
3         \page title AFS-3 Programmer's Reference: File Server/Cache Manager
4 Interface 
5
6 \author Edward R. Zayas 
7 Transarc Corporation 
8 \version 1.1
9 \date 20 Aug 1991 9:38 Copyright 1991 Transarc Corporation All Rights Reserved
10 FS-00-D162 
11
12         \page chap1 Chapter 1: Overview 
13
14         \section sec1-1 Section 1.1: Introduction 
15
16         \subsection sec1-1-1 Section 1.1.1: The AFS 3.1 Distributed File System 
17
18 \par
19 AFS 3.1 is a distributed file system (DFS) designed to meet the following set
20 of requirements: 
21 \li Server-client model: Permanent file storage for AFS is maintained by a
22 collection of file server machines. This centralized storage is accessed by
23 individuals running on client machines, which also serve as the computational
24 engines for those users. A single machine may act as both an AFS file server
25 and client simultaneously. However, file server machines are generally assumed
26 to be housed in a secure environment, behind locked doors. 
27 \li Scale: Unlike other existing DFSs, AFS was designed with the specific goal
28 of supporting a very large user community. Unlike the rule-of-thumb ratio of 20
29 client machines for every server machine (20:1) used by Sun Microsystem's NFS
30 distributed file system [4][5], the AFS architecture aims at smoothly
31 supporting client/server ratios more along the lines of 200:1 within a single
32 installation. 
33 \par
34 AFS also provides another, higher-level notion of scalability. Not only can
35 each independently-administered AFS site, or cell, grow very large (on the
36 order of tens of thousands of client machines), but individual cells may easily
37 collaborate to form a single, unified file space composed of the union of the
38 individual name spaces. Thus, users have the image of a single unix file system
39 tree rooted at the /afs directory on their machine. Access to files in this
40 tree is performed with the standard unix commands, editors, and tools,
41 regardless of a file's location. 
42 \par
43 These cells and the files they export may be geographically dispersed, thus
44 requiring client machines to access remote file servers across network pathways
45 varying widely in speed, latency, and reliability. The AFS architecture
46 encourages this concept of a single, wide-area file system. As of this writing,
47 the community AFS filespace includes sites spanning the continental United
48 States and Hawaii, and also reaches overseas to various installations in
49 Europe, Japan, and Australia. 
50 \li Performance: This is a critical consideration given the scalability and
51 connectivity requirements described above. A high-performance system in the
52 face of high client/server ratios and the existence of low-bandwidth,
53 high-latency network connections as well as the normal high-speed ones is
54 achieved by two major mechanisms: 
55 \li Caching: Client machines make extensive use of caching techniques wherever
56 possible. One important application of this methodology is that each client is
57 required to maintain a cache of files it has accessed from AFS file servers,
58 performing its operations exclusively on these local copies. This file cache is
59 organized in a least-recently-used (LRU) fashion. Thus, each machine will build
60 a local working set of objects being referenced by its users. As long as the
61 cached images remain 'current' (i.e., compatible with the central version
62 stored at the file servers), operations may be performed on these files without
63 further communication with the central servers. This results in significant
64 reductions in network traffic and server loads, paving the way for the target
65 client/server ratios. 
66 \par
67 This file cache is typically located on the client's local hard disk, although
68 a strictly in-memory cache is also supported. The disk cache has the advantage
69 that its contents will survive crashes and reboots, with the expectation that
70 the majority of cached objects will remain current. The local cache parameters,
71 including the maximum number of blocks it may occupy on the local disk, may be
72 changed on the fly. In order to avoid having the size of the client file cache
73 become a limit on the length of an AFS file, caching is actually performed on
74 chunks of the file. These chunks are typically 64 Kbytes in length, although
75 the chunk size used by the client is settable when the client starts up. 
76 \li Callbacks: The use of caches by the file system, as described above, raises
77 the thorny issue of cache consistency. Each client must efficiently determine
78 whether its cached file chunks are identical to the corresponding sections of
79 the file as stored at the server machine before allowing a user to operate on
80 those chunks. AFS employs the notion of a callback as the backbone of its cache
81 consistency algorithm. When a server machine delivers one or more chunks of a
82 file to a client, it also includes a callback 'promise' that the client will be
83 notified if any modifications are made to the data in the file. Thus, as long
84 as the client machine is in possession of a callback for a file, it knows it is
85 correctly synchronized with the centrally-stored version, and allows its users
86 to operate on it as desired without any further interaction with the server.
87 Before a file server stores a more recent version of a file on its own disks,
88 it will first break all outstanding callbacks on this item. A callback will
89 eventually time out, even if there are no changes to the file or directory it
90 covers. 
91 \li Location transparency: The typical AFS user does not know which server or
92 servers houses any of his or her files. In fact, the user's storage may be
93 distributed among several servers. This location transparency also allows user
94 data to be migrated between servers without users having to take corrective
95 actions, or even becoming aware of the shift. 
96 \li Reliability: The crash of a server machine in any distributed file system
97 will cause the information it hosts to become unavailable to the user
98 community. The same effect is caused when server and client machines are
99 isolated across a network partition. AFS addresses this situation by allowing
100 data to be replicated across two or more servers in a read-only fashion. If the
101 client machine loses contact with a particular server from which it is
102 attempting to fetch data, it hunts among the remaining machines hosting
103 replicas, looking for one that is still in operation. This search is performed
104 without the user's knowledge or intervention, smoothly masking outages whenever
105 possible. Each client machine will automatically perform periodic probes of
106 machines on its list of known servers, updating its internal records concerning
107 their status. Consequently, server machines may enter and exit the pool without
108 administrator intervention. 
109 \par
110 Replication also applies to the various databases employed by the AFS server
111 processes. These system databases are read/write replicated with a single
112 synchronization site at any instant. If a synchronization site is lost due to
113 failure, the remaining database sites elect a new synchronization site
114 automatically without operator intervention. 
115 \li Security: A production file system, especially one which allows and
116 encourages transparent access between administrative domains, must be conscious
117 of security issues. AFS considers the server machines as 'trusted', being kept
118 behind locked doors and only directly manipulated by administrators. On the
119 other hand, client machines are, by definition, assumed to exist in inherently
120 insecure environments. These client machines are recognized to be fully
121 accessible to their users, making AFS servers open to attacks mounted by
122 possibly modified hardware, operating systems, and software from its clients. 
123 \li To provide credible file system security, AFS employs an authentication
124 system based on the Kerberos facility developed by Project Athena at MIT
125 [6][7]. Users operating from client machines are required to interact with
126 Authentication Server agents running on the secure server machines to generate
127 secure tokens of identity. These tokens express the user's identity in an
128 encrypted fashion, and are stored in the kernel of the client machine. When the
129 user attempts to fetch or store files, the server may challenge the user to
130 verify his or her identity. This challenge, hidden from the user and handled
131 entirely by the RPC layer, will transmit this token to the file server involved
132 in the operation. The server machine, upon decoding the token and thus
133 discovering the user's true identity, will allow the caller to perform the
134 operation if permitted. Access control: The standard unix access control
135 mechanism associates mode bits with every file and directory, applying them
136 based on the user's numerical identifier and the user's membership in various
137 groups. AFS has augmented this traditional access control mechanism with Access
138 Control Lists (ACLs). Every AFS directory has an associated ACL which defines
139 the principals or parties that may operate on all files contained in the
140 directory, and which operations these principals may perform. Rights granted by
141 these ACLs include read, write, delete, lookup, insert (create new files, but
142 don't overwrite old files), and administer (change the ACL). Principals on
143 these ACLs include individual users and groups of users. These groups may be
144 defined by AFS users without administrative intervention. AFS ACLs provide for
145 much finer-grained access control for its files. 
146 \li Administrability: Any system with the scaling goals of AFS must pay close
147 attention to its ease of administration. The task of running an AFS
148 installation is facilitated via the following mechanisms: 
149 \li Pervasive RPC interfaces: Access to AFS server agents is performed mostly
150 via RPC interfaces. Thus, servers may be queried and operated upon regardless
151 of their location. In combination with the security system outlined above, even
152 administrative functions such as instigating backups, reconfiguring server
153 machines, and stopping and restarting servers may be performed by an
154 administrator sitting in front of any AFS-capable machine, as long as the
155 administrator holds the proper tokens. 
156 \li Replication: As AFS supports read-only replication for user data and
157 read-write replication for system databases, much of the system reconfiguration
158 work in light of failures is performed transparently and without human
159 intervention. Administrators thus typically have more time to respond to many
160 common failure situations. 
161 \li Data mobility: Improved and balanced utilization of disk resources is
162 facilitated by the fact that AFS supports transparent relocation of user data
163 between partitions on a single file server machine or between two different
164 machines. In a situation where a machine must be brought down for an extended
165 period, all its storage may be migrated to other servers so that users may
166 continue their work completely unaffected. 
167 \li Automated 'nanny' services: Each file server machine runs a BOS Server
168 process, which assists in the machine's administration. This server is
169 responsible for monitoring the health of the AFS agents under its care,
170 bringing them up in the proper order after a system reboot, answering requests
171 as to their status and restarting them when they fail. It also accepts commands
172 to start, suspend, or resume these processes, and install new server binaries.
173 Accessible via an RPC interface, this supervisory process relieves
174 administrators of some oversight responsibilities and also allows them to
175 perform their duties from any machine running AFS, regardless of location or
176 geographic distance from the targeted file server machine. 
177 \li On-line backup: Backups may be performed on the data stored by the AFS file
178 server machines without bringing those machines down for the duration.
179 Copy-on-write 'snapshots' are taken of the data to be preserved, and tape
180 backup is performed from these clones. One added benefit is that these backup
181 clones are on-line and accessible by users. Thus, if someone accidentally
182 deletes a file that is contained in their last snapshot, they may simply copy
183 its contents as of the time the snapshot was taken back into their active
184 workspace. This facility also serves to improve the administrability of the
185 system, greatly reducing the number of requests to restore data from tape. 
186 \li On-line help: The set of provided program tools used to interact with the
187 active AFS agents are self-documenting in that they will accept command-line
188 requests for help, displaying descriptive text in response. 
189 \li Statistics: Each AFS agent facilitates collection of statistical data on
190 its performance, configuration, and status via its RPC interface. Thus, the
191 system is easy to monitor. One tool that takes advantage of this facility is
192 the scout program. Scout polls file server machines periodically, displaying
193 usage statistics, current disk capacities, and whether the server is
194 unavailable. Administrators monitoring this information can thus quickly react
195 to correct overcrowded disks and machine crashes. 
196 \li Coexistence: Many organizations currently employ other distributed file
197 systems, most notably NFS. AFS was designed to run simultaneously with other
198 DFSs without interfering in their operation. In fact, an NFS-AFS translator
199 agent exists that allows pure-NFS client machines to transparently access files
200 in the AFS community. 
201 \li Portability: Because AFS is implemented using the standard VFS and vnode
202 interfaces pioneered and advanced by Sun Microsystems, AFS is easily portable
203 between different platforms from a single vendor or from different vendors. 
204
205         \subsection sec1-1-2 Section 1.1.2: Scope of this Document 
206
207 \par
208 This document is a member of a documentation suite providing specifications of
209 the operations and interfaces offered by the various AFS servers and agents.
210 Specifically, this document will focus on two of these system agents: 
211 \li File Server: This AFS entity is responsible for providing a central disk
212 repository for a particular set of files and for making these files accessible
213 to properly-authorized users running on client machines. The File Server is
214 implemented as a user-space process 
215 \li Cache Manager: This code, running within the kernel of an AFS client
216 machine, is a user's representative in communicating with the File Servers,
217 fetching files back and forth into the local cache as needed. The Cache Manager
218 also keeps information as to the composition of its own cell as well as the
219 other AFS cells in existence. It resolves file references and operations,
220 determining the proper File Server (or group of File Servers) that may satisfy
221 the request. In addition, it is also a reliable repository for the user's
222 authentication information, holding on to their tokens and wielding them as
223 necessary when challenged. 
224
225         \subsection sec1-1-3 Section 1.1.3: Related Documents 
226
227 \par
228 The full AFS specification suite of documents is listed below: 
229 \li AFS-3 Programmer's Reference: Architectural Overview: This paper provides
230 an architectual overview of the AFS distributed file system, describing the
231 full set of servers and agents in a coherent way, illustrating their
232 relationships to each other and examining their interactions. 
233 \li AFS-3 Programmer's Reference:Volume Server/Volume Location Server
234 Interface: This document describes the services through which 'containers' of
235 related user data are located and managed. 
236 \li AFS-3 Programmer's Reference: Protection Server Interface: This paper
237 describes the server responsible for providing two-way mappings between
238 printable usernames and their internal AFS identifiers. The Protection Server
239 also allows users to create, destroy, and manipulate 'groups' of users, which
240 are suitable for placement on ACLs. AFS-3 Programmer's Reference: BOS Server
241 Interface: This paper explicates the 'nanny' service described above, which
242 assists in the administrability of the AFS environment. 
243 \li AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure
244 Call Facility: This document specifies the design and operation of the remote
245 procedure call and lightweight process packages used by AFS. 
246 \par
247 In addition to these papers, the AFS 3.1 product is delivered with its own
248 user, administrator, installation, and command reference documents. 
249
250         \section sec1-2 Section 1.2: Basic Concepts 
251
252 \par
253 To properly understand AFS operation, specifically the tasks and objectives of
254 the File Server and Cache Manager, it is necessary to introduce and explain the
255 following concepts: 
256 \li Cell: A cell is the set of server and client machines operated by an
257 administratively independent organization. The cell administrators make
258 decisions concerning such issues as server deployment and configuration, user
259 backup schedules, and replication strategies on their own hardware and disk
260 storage completely independently from those implemented by other cell
261 administrators regarding their own domains. Every client machine belongs to
262 exactly one cell, and uses that information to determine the set of database
263 servers it uses to locate system resources and generate authentication
264 information. 
265 \li Volume: AFS disk partitions do not directly host individual user files or
266 directories. Rather, connected subtrees of the system's directory structure are
267 placed into containers called volumes. Volumes vary in size dynamically as
268 objects are inserted, overwritten, and deleted. Each volume has an associated
269 quota, or maximum permissible storage. A single unix disk partition may host
270 one or more volumes, and in fact may host as many volumes as physically fit in
271 the storage space. However, a practical maximum is 3,500 volumes per disk
272 partition, since this is the highest number currently handled by the salvager
273 program. The salvager is run on occasions where the volume structures on disk
274 are inconsistent, repairing the damage. A compile-time constant within the
275 salvager imposes the above limit, causing it to refuse to repair any
276 inconsistent partition with more than 3,500 volumes. Volumes serve many
277 purposes within AFS. First, they reduce the number of objects with which an
278 administrator must be concerned, since operations are normally performed on an
279 entire volume at once (and thus on all files and directories contained within
280 the volume). In addition, volumes are the unit of replication, data mobility
281 between servers, and backup. Disk utilization may be balanced by transparently
282 moving volumes between partitions. 
283 \li Mount Point: The connected subtrees contained within individual volumes
284 stored at AFS file server machines are 'glued' to their proper places in the
285 file space defined by a site, forming a single, apparently seamless unix tree.
286 These attachment points are referred to as mount points. Mount points are
287 persistent objects, implemented as symbolic links whose contents obey a
288 stylized format. Thus, AFS mount points differ from NFS-style mounts. In the
289 NFS environment, the user dynamically mounts entire remote disk partitions
290 using any desired name. These mounts do not survive client restarts, and do not
291 insure a uniform namespace between different machines. 
292 \par
293 As a Cache Manager resolves an AFS pathname as part of a file system operation
294 initiated by a user process, it recognizes mount points and takes special
295 action to resolve them. The Cache Manager consults the appropriate Volume
296 Location Server to discover the File Server (or set of File Servers) hosting
297 the indicated volume. This location information is cached, and the Cache
298 Manager then proceeds to contact the listed File Server(s) in turn until one is
299 found that responds with the contents of the volume's root directory. Once
300 mapped to a real file system object, the pathname resolution proceeds to the
301 next component. 
302 \li Database Server: A set of AFS databases is required for the proper
303 functioning of the system. Each database may be replicated across two or more
304 file server machines. Access to these databases is mediated by a database
305 server process running at each replication site. One site is declared to be the
306 synchronization site, the sole location accepting requests to modify the
307 databases. All other sites are read-only with respect to the set of AFS users.
308 When the synchronization site receives an update to its database, it
309 immediately distributes it to the other sites. Should a synchronization site go
310 down through either a hard failure or a network partition, the remaining sites
311 will automatically elect a new synchronization site if they form a quorum, or
312 majority. This insures that multiple synchronization sites do not become active
313 in the network partition scenario. 
314 \par
315 The classes of AFS database servers are listed below: 
316 \li Authentication Server: This server maintains the authentication database
317 used to generate tokens of identity. 
318 \li Protection Server: This server maintains mappings between human-readable
319 user account names and their internal numerical AFS identifiers. It also
320 manages the creation, manipulation, and update of user-defined groups suitable
321 for use on ACLs. 
322 \li Volume Location Server: This server exports information concerning the
323 location of the individual volumes housed within the cell. 
324
325         \section sec1-3 Section 1.3: Document Layout 
326
327 \par
328 Following this introduction and overview, Chapter 2 describes the architecture
329 of the File Server process design. Similarly, Chapter 3 describes the
330 architecture of the in-kernel Cache Manager agent. Following these
331 architectural examinations, Chapter 4 provides a set of basic coding
332 definitions common to both the AFS File Server and Cache Manager, required to
333 properly understand the interface specifications which follow. Chapter 5 then
334 proceeds to specify the various File Server interfaces. The myriad Cache
335 Manager interfaces are presented in Chapter 6, thus completing the document. 
336
337         \page chap2 Chapter 2: File Server Architecture 
338
339         \section sec2-1 Section 2.1: Overview 
340
341 \par
342 The AFS File Server is a user-level process that presides over the raw disk
343 partitions on which it supports one or more volumes. It provides 'half' of the
344 fundamental service of the system, namely exporting and regimenting access to
345 the user data entrusted to it. The Cache Manager provides the other half,
346 acting on behalf of its human users to locate and access the files stored on
347 the file server machines. 
348 \par
349 This chapter examines the structure of the File Server process. First, the set
350 of AFS agents with which it must interact are discussed. Next, the threading
351 structure of the server is examined. Some details of its handling of the race
352 conditions created by the callback mechanism are then presented. This is
353 followed by a discussion of the read-only volume synchronization mechanism.
354 This functionality is used in each RPC interface call and intended to detect
355 new releases of read-only volumes. File Servers do not generate callbacks for
356 objects residing in read-only volumes, so this synchronization information is
357 used to implement a 'whole-volume' callback. Finally, the fact that the File
358 Server may drop certain information recorded about the Cache Managers with
359 which it has communicated and yet guarantee correctness of operation is
360 explored. 
361
362         \section sec2-2 Section 2.2: Interactions 
363
364 \par
365 By far the most frequent partner in File Server interactions is the set of
366 Cache Managers actively fetching and storing chunks of data files for which the
367 File Server provides central storage facilities. The File Server also
368 periodically probes the Cache Managers recorded in its tables with which it has
369 recently dealt, determining if they are still active or whether their records
370 might be garbage-collected. 
371 \par
372 There are two other server entities with which the File Server interacts,
373 namely the Protection Server and the BOS Server. Given a fetch or store request
374 generated by a Cache Manager, the File Server needs to determine if the caller
375 is authorized to perform the given operation. An important step in this process
376 is to determine what is referred to as the caller's Current Protection
377 Subdomain, or CPS. A user's CPS is a list of principals, beginning with the
378 user's internal identifier, followed by the the numerical identifiers for all
379 groups to which the user belongs. Once this CPS information is determined, the
380 File Server scans the ACL controlling access to the file system object in
381 question. If it finds that the ACL contains an entry specifying a principal
382 with the appropriate rights which also appears in the user's CPS, then the
383 operation is cleared. Otherwise, it is rejected and a protection violation is
384 reported to the Cache Manager for ultimate reflection back to the caller. 
385 \par
386 The BOS Server performs administrative operations on the File Server process.
387 Thus, their interactions are quite one-sided, and always initiated by the BOS
388 Server. The BOS Server does not utilize the File Server's RPC interface, but
389 rather generates unix signals to achieve the desired effect. 
390
391         \section sec2-3 Section 2.3: Threading 
392
393 \par
394 The File Server is organized as a multi-threaded server. Its threaded behavior
395 within a single unix process is achieved by use of the LWP lightweight process
396 facility, as described in detail in the companion "AFS-3 Programmer's
397 Reference: Specification for the Rx Remote Procedure Call Facility" document.
398 The various threads utilized by the File Server are described below: 
399 \li WorkerLWP: This lightweight process sleeps until a request to execute one
400 of the RPC interface functions arrives. It pulls the relevant information out
401 of the request, including any incoming data delivered as part of the request,
402 and then executes the server stub routine to carry out the operation. The
403 thread finishes its current activation by feeding the return code and any
404 output data back through the RPC channel back to the calling Cache Manager. The
405 File Server initialization sequence specifies that at least three but no more
406 than six of these WorkerLWP threads are to exist at any one time. It is
407 currently not possible to configure the File Server process with a different
408 number of WorkerLWP threads. 
409 \li FiveMinuteCheckLWP: This thread runs every five minutes, performing such
410 housekeeping chores as cleaning up timed-out callbacks, setting disk usage
411 statistics, and executing the special handling required by certain AIX
412 implementations. Generally, this thread performs activities that do not take
413 unbounded time to accomplish and do not block the thread. If reassurance is
414 required, FiveMinuteCheckLWP can also be told to print out a banner message to
415 the machine's console every so often, stating that the File Server process is
416 still running. This is not strictly necessary and an artifact from earlier
417 versions, as the File Server's status is now easily accessible at any time
418 through the BOS Server running on its machine. 
419 \li HostCheckLWP: This thread, also activated every five minutes, performs
420 periodic checking of the status of Cache Managers that have been previously
421 contacted and thus appear in this File Server's internal tables. It generates
422 RXAFSCB Probe() calls from the Cache Manager interface, and may find itself
423 suspended for an arbitrary amount of time when it enounters unreachable Cache
424 Managers. 
425
426         \section sec2-4 Section 2.4: Callback Race Conditions 
427
428 \par
429 Callbacks serve to implement the efficient AFS cache consistency mechanism, as
430 described in Section 1.1.1. Because of the asynchronous nature of callback
431 generation and the multi-threaded operation and organization of both the File
432 Server and Cache Manager, race conditions can arise in their use. As an
433 example, consider the case of a client machine fetching a chunk of file X. The
434 File Server thread activated to carry out the operation ships the contents of
435 the chunk and the callback information over to the requesting Cache Manager.
436 Before the corresponding Cache Manager thread involved in the exchange can be
437 scheduled, another request arrives at the File Server, this time storing a
438 modified image of the same chunk from file X. Another worker thread comes to
439 life and completes processing of this second request, including execution of an
440 RXAFSCB CallBack() to the Cache Manager who still hasn't picked up on the
441 results of its fetch operation. If the Cache Manager blindly honors the RXAFSCB
442 CallBack() operation first and then proceeds to process the fetch, it will wind
443 up believing it has a callback on X when in reality it is out of sync with the
444 central copy on the File Server. To resolve the above class of callback race
445 condition, the Cache Manager effectively doublechecks the callback information
446 received from File Server calls, making sure they haven't already been
447 nullified by other file system activity. 
448
449         \section sec2-5 Section 2.5: Read-Only Volume Synchronization 
450
451 \par
452 The File Server issues a callback for each file chunk it delivers from a
453 read-write volume, thus allowing Cache Managers to efficiently synchronize
454 their local caches with the authoritative File Server images. However, no
455 callbacks are issued when data from read-only volumes is delivered to clients.
456 Thus, it is possible for a new snapshot of the read-only volume to be
457 propagated to the set of replication sites without Cache Managers becoming
458 aware of the event and marking the appropriate chunks in their caches as stale.
459 Although the Cache Manager refreshes its volume version information
460 periodically (once an hour), there is still a window where a Cache Manager will
461 fail to notice that it has outdated chunks. 
462 \par
463 The volume synchronization mechanism was defined to close this window,
464 resulting in what is nearly a 'whole-volume' callback device for read-only
465 volumes. Each File Server RPC interface function handling the transfer of file
466 data is equipped with a parameter (a volSyncP), which carries this volume
467 synchronization information. This parameter is set to a non-zero value by the
468 File Server exclusively when the data being fetched is coming from a read-only
469 volume. Although the struct AFSVolSync defined in Section 5.1.2.2 passed via a
470 volSyncP consists of six longwords, only the first one is set. This leading
471 longword carries the creation date of the read-only volume. The Cache Manager
472 immediately compares the synchronization value stored in its cached volume
473 information against the one just received. If they are identical, then the
474 operation is free to complete, secure in the knowledge that all the information
475 and files held from that volume are still current. A mismatch, though,
476 indicates that every file chunk from this volume is potentially out of date,
477 having come from a previous release of the read-only volume. In this case, the
478 Cache Manager proceeds to mark every chunk from this volume as suspect. The
479 next time the Cache Manager considers accessing any of these chunks, it first
480 checks with the File Server it came from which the chunks were obtained to see
481 if they are up to date. 
482
483         \section sec2-6 Section 2.6: Disposal of Cache Manager Records 
484
485 \par
486 Every File Server, when first starting up, will, by default, allocate enough
487 space to record 20,000 callback promises (see Section 5.3 for how to override
488 this default). Should the File Server fully populate its callback records, it
489 will not allocate more, allowing its memory image to possibly grow in an
490 unbounded fashion. Rather, the File Server chooses to break callbacks until it
491 acquires a free record. All reachable Cache Managers respond by marking their
492 cache entries appropriately, preserving the consistency guarantee. In fact, a
493 File Server may arbitrarily and unilaterally purge itself of all records
494 associated with a particular Cache Manager. Such actions will reduce its
495 performance (forcing these Cache Managers to revalidate items cached from that
496 File Server) without sacrificing correctness. 
497
498         \page chap3 Chapter 3: Cache Manager Architecture 
499
500         \section sec3-1 Section 3.1: Overview 
501
502 \par
503 The AFS Cache Manager is a kernel-resident agent with the following duties and
504 responsibilities: 
505 \li Users are to be given the illusion that files stored in the AFS distributed
506 file system are in fact part of the local unix file system of their client
507 machine. There are several areas in which this illusion is not fully realized: 
508 \li Semantics: Full unix semantics are not maintained by the set of agents
509 implementing the AFS distributed file system. The largest deviation involves
510 the time when changes made to a file are seen by others who also have the file
511 open. In AFS, modifications made to a cached copy of a file are not necessarily
512 reflected immediately to the central copy (the one hosted by File Server disk
513 storage), and thus to other cache sites. Rather, the changes are only
514 guaranteed to be visible to others who simultaneously have their own cached
515 copies open when the modifying process executes a unix close() operation on the
516 file. 
517 \par
518 This differs from the semantics expected from the single-machine, local unix
519 environment, where writes performed on one open file descriptor are immediately
520 visible to all processes reading the file via their own file descriptors. Thus,
521 instead of the standard "last writer wins" behavior, users see "last closer
522 wins" behavior on their AFS files. Incidentally, other DFSs, such as NFS, do
523 not implement full unix semantics in this case either. 
524 \li Partial failures: A panic experienced by a local, single-machine unix file
525 system will, by definition, cause all local processes to terminate immediately.
526 On the other hand, any hard or soft failure experienced by a File Server
527 process or the machine upon which it is executing does not cause any of the
528 Cache Managers interacting with it to crash. Rather, the Cache Managers will
529 now have to reflect their failures in getting responses from the affected File
530 Server back up to their callers. Network partitions also induce the same
531 behavior. From the user's point of view, part of the file system tree has
532 become inaccessible. In addition, certain system calls (e.g., open() and
533 read()) may return unexpected failures to their users. Thus, certain coding
534 practices that have become common amongst experienced (single-machine) unix
535 programmers (e.g., not checking error codes from operations that "can't" fail)
536 cause these programs to misbehave in the face of partial failures. 
537 \par
538 To support this transparent access paradigm, the Cache Manager proceeds to: 
539 \li Intercept all standard unix operations directed towards AFS objects,
540 mapping them to references aimed at the corresponding copies in the local
541 cache. 
542 \li Keep a synchronized local cache of AFS files referenced by the client
543 machine's users. If the chunks involved in an operation reading data from an
544 object are either stale or do not exist in the local cache, then they must be
545 fetched from the File Server(s) on which they reside. This may require a query
546 to the volume location service in order to locate the place(s) of residence.
547 Authentication challenges from File Servers needing to verify the caller's
548 identity are handled by the Cache Manager, and the chunk is then incorporated
549 into the cache. 
550 \li Upon receipt of a unix close, all dirty chunks belonging to the object will
551 be flushed back to the appropriate File Server. 
552 \li Callback deliveries and withdrawals from File Servers must be processed,
553 keeping the local cache in close synchrony with the state of affairs at the
554 central store. 
555 \li Interfaces are also be provided for those principals who wish to perform
556 AFS-specific operations, such as Access Control List (ACL) manipulations or
557 changes to the Cache Manager's configuration. 
558 \par
559 This chapter takes a tour of the Cache Manager's architecture, and examines how
560 it supports these roles and responsibilities. First, the set of AFS agents with
561 which it must interact are discussed. Next, some of the Cache Manager's
562 implementation and interface choices are examined. Finally, the server's
563 ability to arbitrarily dispose of callback information without affecting the
564 correctness of the cache consistency algorithm is explained. 
565
566         \section sec3-2 Section 3.2: Interactions 
567
568 \par
569 The main AFS agent interacting with a Cache Manager is the File Server. The
570 most common operation performed by the Cache Manager is to act as its users'
571 agent in fetching and storing files to and from the centralized repositories.
572 Related to this activity, a Cache Manager must be prepared to answer queries
573 from a File Server concerning its health. It must also be able to accept
574 callback revocation notices generated by File Servers. Since the Cache Manager
575 not only engages in data transfer but must also determine where the data is
576 located in the first place, it also directs inquiries to Volume Location Server
577 agents. There must also be an interface allowing direct interactions with both
578 common and administrative users. Certain AFS-specific operations must be made
579 available to these parties. In addition, administrative users may desire to
580 dynamically reconfigure the Cache Manager. For example, information about a
581 newly-created cell may be added without restarting the client's machine. 
582
583         \section sec3-3 Section 3.3: Implementation Techniques 
584
585 \par
586 The above roles and behaviors for the Cache Manager influenced the
587 implementation choices and methods used to construct it, along with the desire
588 to maximize portability. This section begins by showing how the VFS/vnode
589 interface, pioneered and standardized by Sun Microsystems, provides not only
590 the necessary fine-grain access to user file system operations, but also
591 facilitates Cache Manager ports to new hardware and operating system platforms.
592 Next, the use of unix system calls is examined. Finally, the threading
593 structure employed is described. 
594
595         \subsection sec3-3-1 Section 3.3.1: VFS Interface 
596
597 \par
598 As mentioned above, Sun Microsystems has introduced and propagated an important
599 concept in the file system world, that of the Virtual File System (VFS)
600 interface. This abstraction defines a core collection of file system functions
601 which cover all operations required for users to manipulate their data. System
602 calls are written in terms of these standardized routines. Also, the associated
603 vnode concept generalizes the original unix inode idea and provides hooks for
604 differing underlying environments. Thus, to port a system to a new hardware
605 platform, the system programmers have only to construct implementations of this
606 base array of functions consistent with the new underlying machine. 
607 \par
608 The VFS abstraction also allows multiple file systems (e.g., vanilla unix, DOS,
609 NFS, and AFS) to coexist on the same machine without interference. Thus, to
610 make a machine AFS-capable, a system designer first extends the base vnode
611 structure in well-defined ways in order to store AFS-specific operations with
612 each file description. Then, the base function array is coded so that calls
613 upon the proper AFS agents are made to accomplish each function's standard
614 objectives. In effect, the Cache Manager consists of code that interprets the
615 standard set of unix operations imported through this interface and executes
616 the AFS protocols to carry them out. 
617
618         \subsection sec3-3-2 Section 3.3.2: System Calls 
619
620 \par
621 As mentioned above, many unix system calls are implemented in terms of the base
622 function array of vnode-oriented operations. In addition, one existing system
623 call has been modified and two new system calls have been added to perform
624 AFS-specific operations apart from the Cache Manager's unix 'emulation'
625 activities. The standard ioctl() system call has been augmented to handle
626 AFS-related operations on objects accessed via open unix file descriptors. One
627 of the brand-new system calls is pioctl(), which is much like ioctl() except it
628 names targeted objects by pathname instead of file descriptor. Another is afs
629 call(), which is used to initialize the Cache Manager threads, as described in
630 the section immediately following. 
631
632         \subsection sec3-3-3 Section 3.3.3: Threading 
633
634 \par
635 In order to execute its many roles, the Cache Manager is organized as a
636 multi-threaded entity. It is implemented with (potentially multiple
637 instantiations of) the following three thread classes: 
638 \li CallBack Listener: This thread implements the Cache Manager callback RPC
639 interface, as described in Section 6.5. 
640 \li Periodic Maintenance: Certain maintenance and checkup activities need to be
641 performed at five set intervals. Currently, the frequency of each of these
642 operations is hard-wired. It would be a simple matter, though, to make these
643 times configurable by adding command-line parameters to the Cache Manager. 
644 \li Thirty seconds: Flush pending writes for NFS clients coming in through the
645 NFS-AFS Translator facility. 
646 \li One minute: Make sure local cache usage is below the assigned quota, write
647 out dirty buffers holding directory data, and keep flock()s alive. 
648 \li Three minutes: Check for the resuscitation of File Servers previously
649 determined to be down, and check the cache of previously computed access
650 information in light of any newly expired tickets. 
651 \li Ten minutes: Check health of all File Servers marked as active, and
652 garbage-collect old RPC connections. 
653 \li One hour: Check the status of the root AFS volume as well as all cached
654 information concerning read-only volumes. 
655 \li Background Operations: The Cache Manager is capable of prefetching file
656 system objects, as well as carrying out delayed stores, occurring sometime
657 after a close() operation. At least two threads are created at Cache Manager
658 initialization time and held in reserve to carry out these objectives. This
659 class of background threads implements the following three operations: 
660 \li Prefetch operation: Fetches particular file system object chunks in the
661 expectation that they will soon be needed. 
662 \li Path-based prefetch operation: The prefetch daemon mentioned above operates
663 on objects already at least partly resident in the local cache, referenced by
664 their vnode. The path-based prefetch daemon performs the same actions, but on
665 objects named solely by their unix pathname. 
666 \li Delayed store operation: Flush all modified chunks from a file system
667 object to the appropriate File Server's disks. 
668
669         \section sec3-4 Section 3.4: Disposal of Cache Manager Records 
670
671 \par
672 The Cache Manager is free to throw away any or all of the callbacks it has
673 received from the set of File Servers from which it has cached files. This
674 housecleaning does not in any way compromise the correctness of the AFS cache
675 consistency algorithm. The File Server RPC interface described in this paper
676 provides a call to allow a Cache Manager to advise of such unilateral
677 jettisoning. However, failure to use this routine still leaves the machine's
678 cache consistent. Let us examine the case of a Cache Manager on machine C
679 disposing of its callback on file X from File Server F. The next user access on
680 file X on machine C will cause the Cache Manager to notice that it does not
681 currently hold a callback on it (although the File Server will think it does).
682 The Cache Manager on C attempts to revalidate its entry when it is entirely
683 possible that the file is still in sync with the central store. In response,
684 the File Server will extend the existing callback information it has and
685 deliver the new promise to the Cache Manager on C. Now consider the case where
686 file X is modified by a party on a machine other than C before such an access
687 occurs on C. Under these circumstances, the File Server will break its callback
688 on file X before performing the central update. The Cache Manager on C will
689 receive one of these "break callback" messages. Since it no longer has a
690 callback on file X, the Cache Manager on C will cheerfully acknowledge the File
691 Server's notification and move on to other matters. In either case, the
692 callback information for both parties will eventually resynchronize. The only
693 potential penalty paid is extra inquiries by the Cache Manager and thus
694 providing for reduced performance instead of failure of operation. 
695
696         \page chap4 Chapter 4: Common Definitions and Data Structures 
697
698 \par
699 This chapter discusses the definitions used in common by the File Server and
700 the Cache Manager. They appear in the common.xg file, used by Rxgen to generate
701 the C code instantiations of these definitions. 
702
703         \section sec4-1 Section 4.1: File-Related Definitions 
704
705         \subsection sec4-1-1 Section 4.1.1: struct AFSFid 
706
707 \par
708 This is the type for file system objects within AFS. 
709 \n \n Fields 
710 \li unsigned long Volume - This provides the identifier for the volume in which
711 the object resides. 
712 \li unsigned long Vnode - This specifies the index within the given volume
713 corresponding to the object. 
714 \li unsigned long Unique - This is a 'uniquifier' or generation number for the
715 slot identified by the Vnode field. 
716
717         \section sec4-2 Section 4.2: Callback-related Definitions 
718
719         \subsection sec4-2-1 Section 4.2.1: Types of Callbacks 
720
721 \par
722 There are three types of callbacks defined by AFS-3: 
723
724 \li EXCLUSIVE: This version of callback has not been implemented. Its intent
725 was to allow a single Cache Manager to have exclusive rights on the associated
726 file data. 
727 \li SHARED: This callback type indicates that the status information kept by a
728 Cache Manager for the associated file is up to date. All cached chunks from
729 this file whose version numbers match the status information are thus
730 guaranteed to also be up to date. This type of callback is non-exclusive,
731 allowing any number of other Cache Managers to have callbacks on this file and
732 cache chunks from the file. 
733 \li DROPPED: This is used to indicate that the given callback promise has been
734 cancelled by the issuing File Server. The Cache Manager is forced to mark the
735 status of its cache entry as unknown, forcing it to stat the file the next time
736 a user attempts to access any chunk from it. 
737
738         \subsection sec4-2-2 Section 4.2.2: struct AFSCallBack 
739
740 \par
741 This is the canonical callback structure passed in many File Server RPC
742 interface calls. 
743 \n \b Fields 
744 \li unsigned long CallBackVersion - Callback version number. 
745 \li unsigned long ExpirationTime - Time when the callback expires, measured in
746 seconds. 
747 \li unsigned long CallBackType - The type of callback involved, one of
748 EXCLUSIVE, SHARED, or DROPPED. 
749
750         \subsection sec4-2-3 Section 4.2.3: Callback Arrays 
751
752 \par
753 AFS-3 sometimes does callbacks in bulk. Up to AFSCBMAX (50) callbacks can be
754 handled at once. Layouts for the two related structures implementing callback
755 arrays, struct AFSCBFids and struct AFSCBs, follow below. Note that the
756 callback descriptor in slot i of the array in the AFSCBs structure applies to
757 the file identifier contained in slot i in the fid array in the matching
758 AFSCBFids structure. 
759
760         \subsubsection sec4-2-3-1 Section 4.2.3.1: struct AFSCBFids 
761
762 \n \b Fields 
763 \li u int AFSCBFids len - Number of AFS file identifiers stored in the
764 structure, up to a maximum of AFSCBMAX. 
765 \li AFSFid *AFSCBFids val - Pointer to the first element of the array of file
766 identifiers. 
767
768         \subsubsection sec4-2-3-2 Section 4.2.3.2: struct AFSCBs 
769
770 \n \b Fields 
771 \li u int AFSCBs len - Number of AFS callback descriptors stored in the
772 structure, up to a maximum of AFSCBMAX. 
773 \li AFSCallBack *AFSCBs val - Pointer to the actual array of callback
774 descriptors 
775
776         \section sec4-3 Section 4.3: Locking Definitions 
777
778         \subsection sec4-3-1 Section 4.3.1: struct AFSDBLockDesc 
779
780 \par
781 This structure describes the state of an AFS lock. 
782 \n \b Fields 
783 \li char waitStates - Types of lockers waiting for the lock. 
784 \li char exclLocked - Does anyone have a boosted, shared or write lock? (A
785 boosted lock allows the holder to have data read-locked and then 'boost' up to
786 a write lock on the data without ever relinquishing the lock.) 
787 \li char readersReading - Number of readers that actually hold a read lock on
788 the associated object. 
789 \li char numWaiting - Total number of parties waiting to acquire this lock in
790 some fashion. 
791
792         \subsection sec4-3-2 Section 4.3.2: struct AFSDBCacheEntry 
793
794 \par
795 This structure defines the description of a Cache Manager local cache entry, as
796 made accessible via the RXAFSCB GetCE() callback RPC call. Note that File
797 Servers do not make the above call. Rather, client debugging programs (such as
798 cmdebug) are the agents which call RXAFSCB GetCE(). 
799 \n \b Fields 
800 \li long addr - Memory location in the Cache Manager where this description is
801 located. 
802 \li long cell - Cell part of the fid. 
803 \li AFSFid netFid - Network (standard) part of the fid 
804 \li long Length - Number of bytes in the cache entry. 
805 \li long DataVersion - Data version number for the contents of the cache entry. 
806 \li struct AFSDBLockDesc lock - Status of the lock object controlling access to
807 this cache entry. 
808 \li long callback - Index in callback records for this object. 
809 \li long cbExpires - Time when the callback expires. 
810 \li short refCount - General reference count. 
811 \li short opens - Number of opens performed on this object. 
812 \li short writers - Number of writers active on this object. 
813 \li char mvstat - The file classification, indicating one of normal file, mount
814 point, or volume root. 
815 \li char        states - Remembers the state of the given file with a set of
816 bits indicating, from lowest-order to highest order: stat info valid, read-only
817 file, mount point valid, pending core file, wait-for-store, and mapped file. 
818
819         \subsection sec4-3-3 Section 4.3.3: struct AFSDBLock 
820
821 \par
822 This is a fuller description of an AFS lock, including a string name used to
823 identify it. 
824 \n \b Fields 
825 \li char name[16] - String name of the lock. 
826 \li struct AFSDBLockDesc lock - Contents of the lock itself. 
827
828         \section sec4-4 Section 4.4: Miscellaneous Definitions 
829
830         \subsection sec4-4-1 Section 4.4.1: Opaque structures 
831
832 \par
833 A maximum size for opaque structures passed via the File Server interface is
834 defined as AFSOPAQUEMAX. Currently, this is set to 1,024 bytes. The AFSOpaque
835 typedef is defined for use by those parameters that wish their contents to
836 travel completely uninterpreted across the network. 
837
838         \subsection sec4-4-2 Section 4.4.2: String Lengths 
839
840 \par
841 Two common definitions used to specify basic AFS string lengths are AFSNAMEMAX
842 and AFSPATHMAX. AFSNAMEMAX places an upper limit of 256 characters on such
843 things as file and directory names passed as parameters. AFSPATHMAX defines the
844 longest pathname expected by the system, composed of slash-separated instances
845 of the individual directory and file names mentioned above. The longest
846 acceptable pathname is currently set to 1,024 characters. 
847
848         \page chap5 Chapter 5: File Server Interfaces 
849
850 \par
851 There are several interfaces offered by the File Server, allowing it to export
852 the files stored within the set of AFS volumes resident on its disks to the AFS
853 community in a secure fashion and to perform self-administrative tasks. This
854 chapter will cover the three File Server interfaces, summarized below. There is
855 one File Server interface that will not be discussed in this document, namely
856 that used by the Volume Server. It will be fully described in the companion
857 AFS-3 Programmer's Reference:Volume Server/Volume Location Server Interface. 
858 \li RPC: This is the main File Server interface, supporting all of the Cache
859 Manager's needs for providing its own clients with appropriate access to file
860 system objects stored within AFS. It is closedly tied to the callback interface
861 exported by the Cache Manager as described in Section 6.5, which has special
862 implications for any application program making direct calls to this interface. 
863 \li Signals: Certain operations on a File Server must be performed by it
864 sending unix signals on the machine on which it is executing. These operations
865 include performing clean shutdowns and adjusting debugging output levels.
866 Properly-authenticated administrative users do not have to be physically logged
867 into a File Server machine to generate these signals. Rather, they may use the
868 RPC interface exported by that machine's BOS Server process to generate them
869 from any AFS-capable machine. 
870 \li Command Line: Many of the File Server's operating parameters may be set
871 upon startup via its command line interface. Such choices as the number of data
872 buffers and callback records to hold in memory may be made here, along with
873 various other decisions such as lightweight thread stack size. 
874
875         \section sec5-1 Section 5.1: RPC Interface 
876
877         \subsection sec5-1-1 Section 5.1.1: Introduction and Caveats 
878
879 \par
880 The documentation for the AFS-3 File Server RPC interface commences with some
881 basic definitions and data structures used in conjunction with the function
882 calls. This is followed by an examination of the set of non-streamed RPC
883 functions, namely those routines whose parameters are all fixed in size. Next,
884 the streamed RPC functions, those with parameters that allow an arbitrary
885 amount of data to be delivered, are described. A code fragment and accompanying
886 description and analysis are offered as an example of how to use the streamed
887 RPC calls. Finally, a description of the special requirements on any
888 application program making direct calls to this File Server interface appears.
889 The File Server assumes that any entity making calls to its RPC functionality
890 is a bona fide and full-fledged Cache Manager. Thus, it expects this caller to
891 export the Cache Manager's own RPC interface, even if the application simply
892 uses File Server calls that don't transfer files and thus generate callbacks. 
893 \par
894 Within those sections describing the RPC functions themselves, the purpose of
895 each call is detailed, and the nature and use of its parameters is documented.
896 Each of these RPC interface routines returns an integer error code, and a
897 subset of the possible values are described. A complete and systematic list of
898 potential error returns for each function is difficult to construct and
899 unwieldy to examine. This is due to fact that error codes from many different
900 packages and from many different levels may arise. Instead of attempting
901 completeness, the error return descriptions discuss error codes generated
902 within the functions themselves (or a very small number of code levels below
903 them) within the File Server code itself, and not from such associated packages
904 as the Rx, volume, and protection modules. Many of these error code are defined
905 in the companion AFS-3 documents. 
906 \par
907 By convention, a return value of zero reveals that the function call was
908 successful and that all of its OUT parameters have been set by the File Server. 
909
910         \subsection sec5-1-2 Section 5.1.2: Definitions and Structures 
911
912         \subsubsection sec5-1-2-1 Section 5.1.2.1: Constants and Typedefs 
913
914 \par
915 The following constants and typedefs are required to properly use the File
916 Server RPC interface, both to provide values and to interpret information
917 returned by the calls. The constants appear first, followed by the list of
918 typedefs, which sometimes depend on the constants above. Items are alphabetized
919 within each group. 
920 \par
921 All of the constants appearing below whose names contain the XSTAT string are
922 used in conjuction with the extended data collection facility supported by the
923 File Server. The File Server defines some number of data collections, each of
924 which consists of an array of longword values computed by the File Server. 
925 \par
926 There are currently two data collections defined for the File Server. The first
927 is identified by the AFS XSTATSCOLL CALL INFO constant. This collection of
928 longwords relates the number of times each internal function within the File
929 Server code has been executed, thus providing profiling information. The second
930 File Server data collection is identified by the AFS XSTATSCOLL PERF INFO
931 constant. This set of longwords contains information related to the File
932 Server's performance. 
933
934 \par Section 5.1.2.1.1 AFS DISKNAMESIZE [Value = 32] 
935 Specifies the maximum length for an AFS disk partition, used directly in the
936 definition for the DiskName typedef. A DiskName appears as part of a struct
937 ViceDisk, a group of which appear inside a struct ViceStatistics, used for
938 carrying basic File Server statistics information. 
939
940 \par Section 5.1.2.1.2 AFS MAX XSTAT LONGS [Value = 1,024] 
941 Defines the maximum size for a File Server data collection, as exported via the
942 RXAFS GetXStats() RPC call. It is used directly in the AFS CollData typedef. 
943
944 \par Section 5.1.2.1.3 AFS XSTATSCOLL CALL INFO [Value = 0] 
945 This constant identifies the File Server's data collection containing profiling
946 information on the number of times each of its internal procedures has been
947 called. 
948 \par
949 Please note that this data collection is not supported by the File Server at
950 this time. A request for this data collection will result the return of a
951 zero-length array. 
952
953 \par Section 5.1.2.1.4 AFS XSTATSCOLL PERF INFO [Value = 1] 
954 This constant identifies the File Server's data collection containing
955 performance-related information. 
956
957 \par Section 5.1.2.1.5 AFS CollData [typedef long AFS CollData<AFS MAX XSTAT
958 LONGS>;] 
959 This typedef is used by Rxgen to create a structure used to pass File Server
960 data collections to the caller. It resolves into a C typedef statement defining
961 a structure of the same name with the following fields: 
962 \n \b Fields 
963 \li u int AFS CollData len - The number of longwords contained within the data
964 pointed to by the next field. 
965 \li long *AFS CollData val - A pointer to a sequence of AFS CollData len
966 long-words. 
967
968 \par Section 5.1.2.1.6 AFSBulkStats [typedef AFSFetchStatus
969 AFSBulkStats<AFSCBMAX>;] 
970 This typedef is used by Rxgen to create a structure used to pass a set of
971 statistics structures, as described in the RXAFS BulkStatus documentation in
972 Section 5.1.3.21. It resolves into a C typedef statement defining a structure
973 of the same name with the following fields: 
974 \n \b Fields 
975 \li u int AFSBulkStats len - The number of struct AFSFetchStatus units
976 contained within the data to which the next field points. 
977 \li AFSFetchStatus *AFSBulkStats val - This field houses pointer to a sequence
978 of AFSBulkStats len units of type struct AFSFetchStatus. 
979
980 \par Section 5.1.2.1.7 DiskName [typedef opaque DiskName[AFS DISKNAMESIZE];] 
981 The name of an AFS disk partition. This object appears as a field within a
982 struct ViceDisk,a group of which appear inside a struct ViceStatistics, used
983 for carrying basic File Server statistics information. The term opaque
984 appearing above inidcates that the object being defined will be treated as an
985 undifferentiated string of bytes. 
986
987 \par Section 5.1.2.1.8 ViceLockType [typedef long ViceLockType;] 
988 This defines the format of a lock used internally by the Cache Manager. The
989 content of these locks is accessible via the RXAFSCB GetLock() RPC function. An
990 isomorphic and more refined version of the lock structure used by the Cache
991 Manager, mapping directly to this definition, is struct AFSDBLockDesc, defined
992 in Section 4.3.1. 
993
994         \subsubsection sec5-1-2-2 Section 5.1.2.2: struct AFSVolSync 
995
996 \par
997 This structure conveys volume synchronization information across many of the
998 File Server RPC interface calls, allowing something akin to a "whole-volume
999 callback" on read-only volumes. 
1000 \n \b Fields 
1001 \li unsigned long spare1 ... spare6 - The first longword, spare1, contains the
1002 volume's creation date. The rest are currently unused. 
1003
1004         \subsubsection sec5-1-2-3 Section 5.1.2.3: struct AFSFetchStatus 
1005
1006 \par
1007 This structure defines the information returned when a file system object is
1008 fetched from a File Server. 
1009 \n \b Fields 
1010 \li unsigned long InterfaceVersion - RPC interface version, defined to be 1. 
1011 \li unsigned long FileType - Distinguishes the object as either a file,
1012 directory, symlink, or invalid. 
1013 \li unsigned long LinkCount - Number of links to this object. 
1014 \li unsigned long Length - Length in bytes. 
1015 \li unsigned long DataVersion - Object's data version number. 
1016 \li unsigned long Author - Identity of the object's author. 
1017 \li unsigned long Owner - Identity of the object's owner. 
1018 \li unsigned long CallerAccess - The set of access rights computed for the
1019 caller on this object. 
1020 \li unsigned long AnonymousAccess - The set of access rights computed for any
1021 completely unauthenticated principal. 
1022 \li unsigned long UnixModeBits - Contents of associated unix mode bits. 
1023 \li unsigned long ParentVnode - Vnode for the object's parent directory. 
1024 \li unsigned long ParentUnique - Uniquifier field for the parent object. 
1025 \li unsigned long SegSize - (Not implemented). 
1026 \li unsigned long ClientModTime - Time when the caller last modified the data
1027 within the object. 
1028 \li unsigned long ServerModTime - Time when the server last modified the data
1029 within the object. 
1030 \li unsigned long Group - (Not implemented). 
1031 \li unsigned long SyncCounter - (Not implemented). 
1032 \li unsigned long spare1 ... spare4 - Spares. 
1033
1034         \subsubsection sec5-1-2-4 Section 5.1.2.4: struct AFSStoreStatus 
1035
1036 \par
1037 This structure is used to convey which of a file system object's status fields
1038 should be set, and their new values. Several File Server RPC calls, including
1039 RXAFS StoreStatus(), RXAFS CreateFile(), RXAFS SymLink(), RXAFS MakeDir(), and
1040 the streamed call to store file data onto the File Server. 
1041 \n \b Fields 
1042 \li unsigned long Mask - Bit mask, specifying which of the following fields
1043 should be assigned into the File Server's status block on the object. 
1044 \li unsigned long ClientModTime - The time of day that the object was last
1045 modified. 
1046 \li unsigned long Owner - The principal identified as the owner of the file
1047 system object. 
1048 \li unsigned long Group - (Not implemented). 
1049 \li unsigned long UnixModeBits - The set of associated unix mode bits. 
1050 \li unsigned long SegSize - (Not implemented). 
1051
1052         \subsubsection sec5-1-2-5 Section 5.1.2.5: struct ViceDisk 
1053
1054 \par
1055 This structure occurs in struct ViceStatistics, and describes the
1056 characteristics and status of a disk partition used for AFS storage. 
1057 \n \b Fields 
1058 \li long BlocksAvailable - Number of 1 Kbyte disk blocks still available on the
1059 partition. 
1060 \li long TotalBlocks - Total number of disk blocks in the partition. 
1061 \li DiskName Name - The human-readable character string name of the disk
1062 partition (e.g., /vicepa). 
1063
1064         \subsubsection sec5-1-2-6 Section 5.1.2.6: struct ViceStatistics 
1065
1066 \par
1067 This is the File Server statistics structure returned by the RXAFS
1068 GetStatistics() RPC call. 
1069 \n \b Fields 
1070 \li unsigned long CurrentMsgNumber - Not used.
1071 \li unsigned long OldestMsgNumber - Not used.
1072 \li unsigned long CurrentTime - Time of day, as understood by the File Server. 
1073 \li unsigned long BootTime - Kernel's boot time. 
1074 \li unsigned long StartTime - Time when the File Server started up. 
1075 \li long CurrentConnections - Number of connections to Cache Manager instances. 
1076 \li unsigned long TotalViceCalls - Count of all calls made to the RPC
1077 interface. 
1078 \li unsigned long TotalFetchs - Total number of fetch operations, either status
1079 or data, performed. 
1080 \li unsigned long FetchDatas - Total number of data fetch operations
1081 exclusively. 
1082 \li unsigned long FetchedBytes - Total number of bytes fetched from the File
1083 Server since it started up. 
1084 \li long FetchDataRate - Result of dividing the FetchedBytes field by the
1085 number of seconds the File Server has been running. 
1086 \li unsigned long TotalStores - Total number of store operations, either status
1087 or data, performed. 
1088 \li unsigned long StoreDatas - Total number of data store operations
1089 exclusively. 
1090 \li unsigned long StoredBytes - Total number of bytes stored to the File Server
1091 since it started up. 
1092 \li long StoreDataRate - The result of dividing the StoredBytes field by the
1093 number of seconds the File Server has been running. 
1094 \li unsigned long TotalRPCBytesSent - Outdated 
1095 \li unsigned long TotalRPCBytesReceived - Outdated 
1096 \li unsigned long TotalRPCPacketsSent - Outdated 
1097 \li unsigned long TotalRPCPacketsReceived - Outdated 
1098 \li unsigned long TotalRPCPacketsLost - Outdated 
1099 \li unsigned long TotalRPCBogusPackets - Outdated 
1100 \li long SystemCPU - Result of reading from the kernel the usage times
1101 attributed to system activities. 
1102 \li long UserCPU - Result of reading from the kernel the usage times attributed
1103 to user-level activities. 
1104 \li long NiceCPU - Result of reading from the kernel the usage times attributed
1105 to File Server activities that have been nice()d (i.e., run at a lower
1106 priority). 
1107 \li long IdleCPU - Result of reading from the kernel the usage times attributed
1108 to idling activities. 
1109 \li long TotalIO - Summary of the number of bytes read/written from the disk. 
1110 \li long ActiveVM - Amount of virtual memory used by the File Server. 
1111 \li long TotalVM - Total space available on disk for virtual memory activities. 
1112 \li long EtherNetTotalErrors - Not used. 
1113 \li long EtherNetTotalWrites - Not used. 
1114 \li long EtherNetTotalInterupts - Not used. 
1115 \li long EtherNetGoodReads - Not used. 
1116 \li long EtherNetTotalBytesWritten - Not used. 
1117 \li long EtherNetTotalBytesRead - Not used. 
1118 \li long ProcessSize - The size of the File Server's data space in 1 Kbyte
1119 chunks. 
1120 \li long WorkStations - The total number of client Cache Managers
1121 (workstations) for which information is held by the File Server. 
1122 \li long ActiveWorkStations - The total number of client Cache Managers
1123 (workstations) that have recently interacted with the File Server. This number
1124 is strictly less than or equal to the WorkStations field. 
1125 \li long Spare1 ... Spare8 - Not used. 
1126 \li ViceDisk Disk1 ... Disk10 - Statistics concerning up to 10 disk partitions
1127 used by the File Server. These records keep information on all partitions, not
1128 just partitions reserved for AFS storage. 
1129
1130         \subsubsection sec5-1-2-7 Section 5.1.2.7: struct afs PerfStats 
1131
1132 \par
1133 This is the structure corresponding to the AFS XSTATSCOLL PERF INFO data
1134 collection that is defined by the File Server (see Section 5.1.2.1.4). It is
1135 accessible via the RXAFS GetXStats() interface routine, as defined in Section
1136 5.1.3.26. 
1137 The fields within this structure fall into the following classifications: 
1138 \li Number of requests for the structure. 
1139 \li Vnode cache information. 
1140 \li Directory package numbers. 
1141 \li Rx information. 
1142 \li Host module fields 
1143 \li Spares. 
1144
1145 \par
1146 Please note that the Rx fields represent the contents of the rx stats structure
1147 maintained by Rx RPC facility itself. Also, a full description of all the
1148 structure's fields is not possible here. For example, the reader is referred to
1149 the companion Rx document for further clarification on the Rx-related fields
1150 within afs PerfStats. 
1151 \n \b Fields
1152 \li long numPerfCalls - Number of performance collection calls received.
1153 \li long vcache L Entries - Number of entries in large (directory) vnode cache.
1154 \li long vcache L Allocs - Number of allocations for the large vnode cache.
1155 \li long vcache L Gets - Number of get operations for the large vnode cache.
1156 \li long vcache L Reads - Number of reads performed on the large vnode cache.
1157 \li long vcache L Writes - Number of writes executed on the large vnode.cache. 
1158 \li long vcache S Entries - Number of entries in the small (file) vnode cache. 
1159 \li long vcache S Allocs - Number of allocations for the small vnode cache. 
1160 \li long vcache S Gets - Number of get operations for the small vnode cache. 
1161 \li long vcache S Reads - Number of reads performed on the small vnode cache. 
1162 \li long vcache S Writes - Number of writes executed on the small vnode cache. 
1163 \li long vcache H Entries - Number of entries in the header of the vnode cache. 
1164 \li long vcache H Gets - Number of get operations on the header of the vnode
1165 cache. 
1166 \li long vcache H Replacements - Number of replacement operations on the header
1167 of the vnode cache. 
1168 \li long dir Buffers - Number of directory package buffers in use. 
1169 \li long dir Calls - Number of read calls made to the directory package. 
1170 \li long dir IOs - Number of directory I/O operations performed. 
1171 \li long rx packetRequests - Number of Rx packet allocation requests. 
1172 \li long rx noPackets RcvClass - Number of failed packet reception requests. 
1173 \li long rx noPackets SendClass - Number of failed packet transmission
1174 requests. 
1175 \li long rx noPackets SpecialClass - Number of 'special' Rx packet rquests. 
1176 \li long rx socketGreedy - Did setting the Rx socket to SO GREEDY succeed? 
1177 \li long rx bogusPacketOnRead - Number of short packets received. 
1178 \li long rx bogusHost - Latest host address from bogus packets. 
1179 \li long rx noPacketOnRead - Number of attempts to read a packet when one was
1180 not physically available. 
1181 \li long rx noPacketBuffersOnRead - Number of packets dropped due to buffer
1182 shortages. 
1183 \li long rx selects - Number of selects performed, waiting for a packet arrival
1184 or a timeout. 
1185 \li long rx sendSelects - Number of selects forced upon a send. 
1186 \li long rx packetsRead RcvClass - Number of packets read belonging to the
1187 'Rcv'  class. 
1188 \li long rx packetsRead SendClass - Number of packets read that belong to the
1189 'Send' class. 
1190 \li long rx packetsRead SpecialClass - Number of packets read belonging to the
1191 'Special' class. 
1192 \li long rx dataPacketsRead - Number of unique data packets read off the wire. 
1193 \li long rx ackPacketsRead - Number of acknowledgement packets read. 
1194 \li long rx dupPacketsRead - Number of duplicate data packets read. 
1195 \li long rx spuriousPacketsRead - Number of inappropriate packets read. 
1196 \li long rx packetsSent RcvClass - Number of packets sent belonging to the
1197 'Rcv'  class. 
1198 \li long rx packetsSent SendClass - Number of packets sent belonging to the
1199 'Send' class. 
1200 \li long rx packetsSent SpecialClass - Number of packets sent belonging to the
1201 'Special' class. 
1202 \li long rx ackPacketsSent - Number of acknowledgement packets sent. 
1203 \li long rx pingPacketsSent - Number of ping packets sent. 
1204 \li long rx abortPacketsSent - Number of abort packets sent. 
1205 \li long rx busyPacketsSent - Number of busy packets sent. 
1206 \li long rx dataPacketsSent - Number of unique data packets sent. 
1207 \li long rx dataPacketsReSent - Number of retransmissions sent. 
1208 \li long rx dataPacketsPushed - Number of retransmissions pushed by a NACK. 
1209 \li long rx ignoreAckedPacket - Number of packets whose acked flag was set at
1210 rxi Start() time. 
1211 \li long rx totalRtt Sec - Total round trip time in seconds. 
1212 \li long rx totalRtt Usec - Microsecond portion of the total round trip time, 
1213 \li long rx minRtt Sec - Minimum round trip time in seconds. 
1214 \li long rx minRtt Usec - Microsecond portion of minimal round trip time. 
1215 \li long rx maxRtt Sec - Maximum round trip time in seconds. 
1216 \li long rx maxRtt Usec - Microsecond portion of maximum round trip time. 
1217 \li long rx nRttSamples - Number of round trip samples. 
1218 \li long rx nServerConns - Total number of server connections. 
1219 \li long rx nClientConns - Total number of client connections. 
1220 \li long rx nPeerStructs - Total number of peer structures. 
1221 \li long rx nCallStructs - Total number of call structures. 
1222 \li long rx nFreeCallStructs - Total number of call structures residing on the
1223 free list. 
1224 \li long host NumHostEntries - Number of host entries. 
1225 \li long host HostBlocks - Number of blocks in use for host entries. 
1226 \li long host NonDeletedHosts - Number of non-deleted host entries. 
1227 \li long host HostsInSameNetOrSubnet - Number of host entries in the same
1228 [sub]net as the File Server. 
1229 \li long host HostsInDiffSubnet - Number of host entries in a different subnet
1230 as the File Server. 
1231 \li long host HostsInDiffNetwork - Number of host entries in a different
1232 network entirely as the File Server. 
1233 \li long host NumClients - Number of client entries. 
1234 \li long host ClientBlocks - Number of blocks in use for client entries. 
1235 \li long spare[32] - Spare fields, reserved for future use. 
1236
1237         \subsubsection sec5-1-2-8 Section 5.1.2.8: struct AFSFetchVolumeStatus 
1238
1239 \par
1240 The results of asking the File Server for status information concerning a
1241 particular volume it hosts. 
1242 \n \b Fields 
1243 \li long Vid - Volume ID. 
1244 \li long ParentId - Volume ID in which the given volume is 'primarily' mounted. 
1245 \li This is used to properly resolve pwd operations, as a volume may be mounted
1246 simultaneously at multiple locations. 
1247 \li char Online - Is the volume currently online and fully available? 
1248 \li char InService - This field records whether the volume is currently in
1249 service. It is indistinguishable from the Blessed field, 
1250 \li char Blessed - See the description of the InService field immediately
1251 above. 
1252 \li char NeedsSalvage -Should this volume be salvaged (run through a
1253 consistency- checking procedure)? 
1254 \li long Type - The classification of this volume, namely a read/write volume
1255 (RWVOL = 0), read-only volume (ROVOL = 1), or backup volume (BACKVOL = 2). 
1256 \li long MinQuota - Minimum number of 1 Kbyte disk blocks to be set aside for
1257 this volume. Note: this field is not currently set or accessed by any AFS
1258 agents. 
1259 \li long MaxQuota - Maximum number of 1 Kbyte disk blocks that may be occupied
1260 by this volume. 
1261 \li long BlocksInUse - Number of 1 Kbyte disk blocks currently in use by this
1262 volume. 
1263 \li long PartBlocksAvail - Number of available 1 Kbyte blocks currently unused
1264 in the volume's partition. 
1265 \li long PartMaxBlocks - Total number of blocks, in use or not, for the
1266 volume's partition. 
1267
1268         \subsubsection sec5-1-2-9 Section 5.1.2.9: struct AFSStoreVolumeStatus 
1269
1270 \par
1271 This structure is used to convey which of a file system object's status fields
1272 should be set, and their new values. The RXAFS SetVolumeStatus() RPC call is
1273 the only user of this structure. 
1274 \n \b Fields 
1275 \li long Mask - Bit mask to determine which of the following two fields should
1276 be stored in the centralized status for a given volume. 
1277 \li long MinQuota - Minimum number of 1 Kbyte disk blocks to be set aside for
1278 this volume. 
1279 \li long MaxQuota - Maximum number of 1 Kbyte disk blocks that may be occupied
1280 by this volume. 
1281
1282         \subsubsection sec5-1-2-10 Section 5.1.2.10: struct AFSVolumeInfo 
1283
1284 \par
1285 This field conveys information regarding a particular volume through certain
1286 File Server RPC interface calls. For information regarding the different volume
1287 types that exist, please consult the companion document, AFS-3 Programmer's
1288 Reference:Volume Server/Volume Location Server Interface. 
1289 \n \b Fields 
1290 \li unsigned long Vid - Volume ID. 
1291 \li long Type - Volume type (see struct AFSFetchVolumeStatus in Section 5.1.2.8
1292 above). 
1293 \li unsigned long Type0 ... Type4 - The volume IDs for the possible volume
1294 types in existance for this volume. 
1295 \li unsigned long ServerCount - The number of File Server machines on which an
1296 instance of this volume is located. 
1297 \li unsigned long Server0 ... Server7 - Up to 8 IP addresses of File Server
1298 machines hosting an instance on this volume. The first ServerCount of these
1299 fields hold valid server addresses. 
1300 \li unsigned short Port0 ... Port7 - Up to 8 UDP port numbers on which
1301 operations on this volume should be directed. The first ServerCount of these
1302 fields hold valid port identifiers. 
1303
1304         \subsection sec5-1-3 Section 5.1.3: Non-Streamed Function Calls 
1305
1306 \par
1307 The following is a description of the File Server RPC interface routines that
1308 utilize only parameters with fixed maximum lengths. The majority of the File
1309 Server calls fall into this suite, with only a handful using streaming
1310 techniques to pass objects of unbounded size between a File Server and Cache
1311 Manager. 
1312 \par
1313 Each function is labeled with an opcode number. This is the low-level numerical
1314 identifier for the function, and appears in the set of network packets
1315 constructed for the RPC call. 
1316
1317         \subsubsection sec5-1-3-1 Section 5.1.3.1: RXAFS FetchACL - Fetch the
1318 ACL associated with the given AFS file identifier 
1319
1320 \code
1321 int RXAFS FetchACL(IN struct rx connection *a rxConnP, 
1322                         IN AFSFid *a dirFidP, 
1323                         OUT AFSOpaque *a ACLP, 
1324                         OUT AFSFetchStatus *a dirNewStatP, 
1325                         OUT AFSVolSync *a volSyncP) 
1326 \endcode
1327 \par Description 
1328 [Opcode 131] Fetch the ACL for the directory identified by a dirFidP, placing
1329 it in the space described by the opaque structure to which a ACLP points. Also
1330 returned is the given directory's status, written to a dirNewStatP. An ACL may
1331 thus take up at most AFSOPAQUEMAX (1,024) bytes, since this is the maximum size
1332 of an AFSOpaque. 
1333 \par
1334 Rx connection information for the related File Server is contained in a
1335 rxConnP. Volume version information is returned for synchronization purposes in
1336 a volSyncP. 
1337 \par Error Codes 
1338 EACCES The caller is not permitted to perform this operation. EINVAL An
1339 internal error in looking up the client record was encountered, or an invalid
1340 fid was provided. VICETOKENDEAD Caller's authentication token has expired. 
1341
1342         \subsubsection sec5-1-3-2 Section 5.1.3.2: RXAFS FetchStatus - Fetch
1343 the status information regarding a given file system object 
1344
1345 \code
1346 int RXAFS FetchStatus(IN struct rx connection *a rxConnP, 
1347                         IN AFSFid *a fidToStatP, 
1348                         OUT AFSFetchStatus *a currStatP, 
1349                         OUT AFSCallBack *a callBackP, 
1350                         OUT AFSVolSync *a volSyncP) 
1351 \endcode
1352 \par Description 
1353 [Opcode 132] Fetch the current status information for the file or directory
1354 identified by a fidToStatP, placing it into the area to which a currStatP
1355 points. If the object resides in a read/write volume, then the related callback
1356 information is returned in a callBackP. 
1357 \par
1358 Rx connection information for the related File Server is contained in a
1359 rxConnP. Volume version information is returned for synchronization purposes in
1360 a volSyncP. 
1361 \par Error Codes 
1362 EACCES The caller is not permitted to perform this operation. EINVAL An
1363 internal error in looking up the client record was encountered, or an invalid
1364 fid was provided. VICETOKENDEAD Caller's authentication token has expired. 
1365
1366         \subsubsection sec5-1-3-3 Section 5.1.3.3: RXAFS StoreACL - Associate
1367 the given ACL with the named directory 
1368
1369 \code
1370 int RXAFS StoreACL(IN struct rx connection *a rxConnP, 
1371                         IN AFSOpaque *a ACLToStoreP, 
1372                         IN AFSFid *a dirFidP, 
1373                         OUT AFSFetchStatus *a dirNewStatP, 
1374                         OUT AFSVolSync *a volSyncP) 
1375 \endcode
1376 \par Description 
1377 [Opcode 134] Store the ACL information to which a ACLToStoreP points to the
1378 File Server, associating it with the directory identified by a dirFidP. The
1379 resulting status information for the a dirFidP directory is returned in a
1380 dirNewStatP. Note that the ACL supplied via a ACLToStoreP may be at most
1381 AFSOPAQUEMAX (1,024) bytes long, since this is the maximum size accommodated by
1382 an AFSOpaque. 
1383 \par
1384 Rx connection information for the related File Server is contained in a
1385 rxConnP. Volume version information is returned for synchronization purposes in
1386 a volSyncP. 
1387 \par Error Codes 
1388 EACCES The caller is not permitted to perform this operation. 
1389 \n E2BIG The given ACL is too large. 
1390 \n EINVAL The given ACL could not translated to its on-disk format. 
1391
1392         \subsubsection sec5-1-3-4 Section 5.1.3.4: RXAFS StoreStatus - Store
1393 the given status information for the specified file 
1394
1395 \code
1396 int RXAFS StoreStatus(IN struct rx connection *a rxConnP, 
1397                         IN AFSFid *a fidP, 
1398                         IN AFSStoreStatus *a currStatusP, 
1399                         OUT AFSFetchStatus *a srvStatusP, 
1400                         OUT AFSVolSync *a volSyncP) 
1401 \endcode
1402 \par Description 
1403 [Opcode 135] Store the status information to which a currStatusP points,
1404 associating it with the file identified by a fidP. All outstanding callbacks on
1405 this object are broken. The resulting status structure stored at the File
1406 Server is returned in a srvStatusP. 
1407 \par
1408 Rx connection information for the related File Server is contained in a
1409 rxConnP. Volume version information is returned for synchronization purposes in
1410 a volSyncP. 
1411 \par Error Codes 
1412 EACCES The caller is not permitted to perform this operation. 
1413 \n EINVAL An internal error in looking up the client record was encountered, or
1414 an invalid fid was provided, or an attempt was made to change the mode of a
1415 symbolic link. 
1416 \n VICETOKENDEAD Caller's authentication token has expired. 
1417
1418         \subsubsection sec5-1-3-5 Section 5.1.3.5: RXAFS RemoveFile - Delete
1419 the given file 
1420
1421 \code
1422 int RXAFS RemoveFile(IN struct rx connection *a rxConnP, 
1423                         IN AFSFid *a dirFidP, 
1424                         IN char *a name<AFSNAMEMAX>, 
1425                         OUT AFSFetchStatus *a srvStatusP, 
1426                         OUT AFSVolSync *a volSyncP) 
1427 \endcode
1428 \par Description 
1429 [Opcode 136] Destroy the file named a name within the directory identified by a
1430 dirFidP. All outstanding callbacks on this object are broken. The resulting
1431 status structure stored at the File Server is returned in a srvStatusP. 
1432 \par
1433 Rx connection information for the related File Server is contained in a
1434 rxConnP. Volume version information is returned for synchronization purposes in
1435 a volSyncP. 
1436 \par Error Codes 
1437 EACCES The caller is not permitted to perform this operation. 
1438 \n EINVAL An internal error in looking up the client record was encountered, or
1439 an invalid fid was provided, or an attempt was made to remove "." or "..". 
1440 \n EISDIR The target of the deletion was supposed to be a file, but it is
1441 really a directory. 
1442 \n ENOENT The named file was not found. 
1443 \n ENOTDIR The a dirFidP parameter references an object which is not a
1444 directory, or the deletion target is supposed to be a directory but is not. 
1445 \n ENOTEMPTY The target directory being deleted is not empty. 
1446 \n VICETOKENDEAD Caller's authentication token has expired. 
1447
1448         \subsubsection sec5-1-3-6 Section 5.1.3.6: RXAFS CreateFile - Create
1449 the given file 
1450
1451 \code
1452 int RXAFS CreateFile(IN struct rx connection *a rxConnP, 
1453                         IN AFSFid *DirFid, 
1454                         IN char *Name, 
1455                         IN AFSStoreStatus *InStatus, 
1456                         OUT AFSFid *OutFid, 
1457                         OUT AFSFetchStatus *OutFidStatus, 
1458                         OUT AFSFetchStatus *OutDirStatus, 
1459                         OUT AFSCallBack *CallBack, 
1460                         OUT AFSVolSync *a volSyncP) 
1461 /* associated with the new file. */
1462 \endcode
1463 \par Description 
1464 [Opcode 137] This call is used to create a file, but not for creating a
1465 directory or a symbolic link. If this call succeeds, it is the Cache Manager's
1466 responsibility to either create an entry locally in the directory specified by
1467 DirFid or to invalidate this directory's cache entry. 
1468 \par
1469 Rx connection information for the related File Server is contained in a
1470 rxConnP. Volume version information is returned for synchronization purposes in
1471 a volSyncP. 
1472 \par Error Codes 
1473 EACCES The caller is not permitted to perform this operation. 
1474 \n EINVAL An internal error in looking up the client record was encountered, or
1475 an invalid fid or name was provided. 
1476 \n ENOTDIR The DirFid parameter references an object which is not a directory. 
1477 \n VICETOKENDEAD Caller's authentication token has expired. 
1478
1479         \subsubsection sec5-1-3-7 Section 5.1.3.7: RXAFS Rename - Rename the
1480 specified file in the given directory 
1481
1482 \code
1483 int RXAFS Rename(IN struct rx connection *a rxConnP, 
1484                         IN AFSFid *a origDirFidP, 
1485                         IN char *a origNameP, 
1486                         IN AFSFid *a newDirFidP, 
1487                         IN char *a newNameP, 
1488                         OUT AFSFetchStatus *a origDirStatusP, 
1489                         OUT AFSFetchStatus *a newDirStatusP, 
1490                         OUT AFSVolSync *a volSyncP) 
1491 \endcode
1492 \par Description 
1493 [Opcode 138] Rename file a origNameP in the directory identified by a
1494 origDirFidP. Its new name is to be a newNameP, and it will reside in the
1495 directory identified by a newDirFidP. Each of these names must be no more than
1496 AFSNAMEMAX (256) characters long. The status of the original and new
1497 directories after the rename operation completes are deposited in a
1498 origDirStatusP and a newDirStatusP respectively. Existing callbacks are broken
1499 for all files and directories involved in the operation. 
1500 \par
1501 Rx connection information for the related File Server is contained in a
1502 rxConnP. Volume version information is returned for synchronization purposes in
1503 a volSyncP. 
1504 \par Error Codes 
1505 EACCES New file exists but user doesn't have Delete rights in the directory. 
1506 \n EINVAL Name provided is invalid. 
1507 \n EISDIR Original object is a file and new object is a directory. 
1508 \n ENOENT The object to be renamed doesn't exist in the parent directory. 
1509 \n ENOTDIR Original object is a directory and new object is a file. 
1510 \n EXDEV Rename attempted across a volume boundary, or create a pathname loop,
1511 or hard links exist to the file. 
1512
1513         \subsubsection sec5-1-3-8 Section 5.1.3.8: RXAFS Symlink - Create a
1514 symbolic link 
1515
1516 \code
1517 int RXAFS Symlink(IN struct rx connection *a rxConnP, 
1518                         IN AFSFid *a dirFidP, 
1519                         IN char *a nameP, 
1520                         IN char *a linkContentsP, 
1521                         IN AFSStoreStatus *a origDirStatP, 
1522                         OUT AFSFid *a newFidP, 
1523                         OUT AFSFetchStatus *a newFidStatP, 
1524                         OUT AFSFetchStatus *a newDirStatP, 
1525                         OUT AFSVolSync *a volSyncP) 
1526 \endcode
1527 \par Description 
1528 [Opcode 139] Create a symbolic link named a nameP in the directory identified
1529 by a dirFidP. The text of the symbolic link is provided in a linkContentsP, and
1530 the desired status fields for the symbolic link given by a origDirStatP. The
1531 name offered in a nameP must be less than AFSNAMEMAX (256) characters long, and
1532 the text of the link to which a linkContentsP points must be less than
1533 AFSPATHMAX (1,024) characters long. Once the symbolic link has been
1534 successfully created, its file identifier is returned in a newFidP. Existing
1535 callbacks to the a dirFidP directory are broken before the symbolic link
1536 creation completes. The status fields for the symbolic link itself and its
1537 parent's directory are returned in a newFidStatP and a newDirStatP
1538 respectively. 
1539 \par
1540 Rx connection information for the related File Server is contained in a
1541 rxConnP. Volume version information is returned for synchronization purposes in
1542 a volSyncP. 
1543 \par Error Codes 
1544 EACCES The caller does not have the necessary access rights. 
1545 \n EINVAL Illegal symbolic link name provided. 
1546
1547         \subsubsection sec5-1-3-9 Section 5.1.3.9: RXAFS Link - Create a hard
1548 link 
1549
1550 \code
1551 int RXAFS Link(IN struct rx connection *a rxConnP, 
1552                 IN AFSFid *a dirFidP, 
1553                 IN char *a nameP, 
1554                 IN AFSFid *a existingFidP, 
1555                 OUT AFSFetchStatus *a newFidStatP, 
1556                 OUT AFSFetchStatus *a newDirStatP, 
1557                 OUT AFSVolSync *a volSyncP) 
1558 \endcode
1559 \par Description 
1560 [Opcode 140] Create a hard link named a nameP in the directory identified by a
1561 dirFidP. The file serving as the basis for the hard link is identified by
1562 existingFidP. The name offered in a nameP must be less than AFSNAMEMAX (256)
1563 characters long. Existing callbacks to the a dirFidP directory are broken
1564 before the hard link creation completes. The status fields for the file itself
1565 and its parent's directory are returned in a newFidStatP and a newDirStatP
1566 respectively. 
1567 Rx connection information for the related File Server is contained in a
1568 rxConnP. Volume version information is returned for synchronization purposes in
1569 a volSyncP. 
1570 \par Error Codes 
1571 EACCES The caller does not have the necessary access rights. 
1572 \n EISDIR An attempt was made to create a hard link to a directory. 
1573 \n EXDEV Hard link attempted across directories. 
1574
1575         \subsubsection sec5-1-3-10 Section 5.1.3.10: RXAFS MakeDir - Create a
1576 directory 
1577
1578 \code
1579 int RXAFS MakeDir(IN struct rx connection *a rxConnP, 
1580                         IN AFSFid *a parentDirFid,P 
1581                         IN char *a newDirNameP, 
1582                         IN AFSStoreStatus *a currStatP, 
1583                         OUT AFSFid *a newDirFidP, 
1584                         OUT AFSFetchStatus *a dirFidStatP, 
1585                         OUT AFSFetchStatus *a parentDirStatP, 
1586                         OUT AFSCallBack *a newDirCallBackP, 
1587                         OUT AFSVolSync *a volSyncP) 
1588 \endcode
1589 \par Description 
1590 [Opcode 141] Create a directory named a newDirNameP within the directory
1591 identified by a parentDirFidP. The initial status fields for the new directory
1592 are provided in a currStatP. The new directory's name must be less than
1593 AFSNAMEMAX (256) characters long. The new directory's ACL is inherited from its
1594 parent. Existing callbacks on the parent directory are broken before the
1595 creation completes. Upon successful directory creation, the new directory's
1596 file identifier is returned in a newDirFidP, and the resulting status
1597 information for the new and parent directories are stored in a dirFidStatP and
1598 a parentDirStatP respectively. In addition, a callback for the new directory is
1599 returned in a newDirCallBackP. 
1600 \par
1601 Rx connection information for the related File Server is contained in a
1602 rxConnP. Volume version information is returned for synchronization purposes in
1603 a volSyncP. 
1604 \par Error Codes 
1605 EACCES The caller does not have the necessary access rights. 
1606 \n EINVAL The directory name provided is unacceptable. 
1607
1608         \subsubsection sec5-1-3-11 Section 5.1.3.11: RXAFS RemoveDir - Remove a
1609 directory 
1610
1611 \code
1612 int RXAFS RemoveDir(IN struct rx connection *a rxConnP, 
1613                         IN AFSFid *a parentDirFidP, 
1614                         IN char *a dirNameP, 
1615                         OUT AFSFetchStatus *a newParentDirStatP, 
1616                         OUT AFSVolSync *a volSyncP) 
1617 \endcode
1618 \par Description 
1619 [Opcode 142] Remove the directory named a dirNameP from within its parent
1620 directory, identified by a parentDirFid. The directory being removed must be
1621 empty, and its name must be less than AFSNAMEMAX (256) characters long.
1622 Existing callbacks to the directory being removed and its parent directory are
1623 broken before the deletion completes. Upon successful deletion, the status
1624 fields for the parent directory are returned in a newParentDirStatP. 
1625 \par
1626 Rx connection information for the related File Server is contained in a
1627 rxConnP. Volume version information is returned for synchronization purposes in
1628 a volSyncP. 
1629 \par Error Codes 
1630 EACCES The caller does not have the necessary access rights. 
1631
1632         \subsubsection sec5-1-3-12 Section 5.1.3.12: RXAFS GetStatistics - Get
1633 common File Server statistics 
1634
1635 \code
1636 int RXAFS GetStatistics(IN struct rx connection *a rxConnP, 
1637                         OUT ViceStatistics *a FSInfoP) 
1638 \endcode
1639 \par Description 
1640 [Opcode 146] Fetch the structure containing a set of common File Server
1641 statistics. These numbers represent accumulated readings since the time the
1642 File Server last restarted. For a full description of the individual fields
1643 contained in this structure, please see Section 5.1.2.6. 
1644 \par
1645 Rx connection information for the related File Server is contained in a
1646 rxConnP. 
1647 \par Error Codes 
1648 ---No error codes generated. 
1649
1650         \subsubsection sec5-1-3-13 Section 5.1.3.13: RXAFS GiveUpCallBacks -
1651 Ask the File Server to break the given set of callbacks on the corresponding
1652 set of file identifiers 
1653
1654 \code
1655 int RXAFS GiveUpCallBacks(IN struct rx connection *a rxConnP, 
1656                                 IN AFSCBFids *a fidArrayP, 
1657                                 IN AFSCBs *a callBackArrayP) 
1658 \endcode
1659 \par Description 
1660 [Opcode 147] Given an array of up to AFSCBMAX file identifiers in a fidArrayP
1661 and a corresponding number of callback structures in a callBackArrayP, ask the
1662 File Server to remove these callbacks from its register. Note that this routine
1663 only affects callbacks outstanding on the given set of files for the host
1664 issuing the RXAFS GiveUpCallBacks call. Callback promises made to other
1665 machines on any or all of these files are not affected. 
1666 \par
1667 Rx connection information for the related File Server is contained in a
1668 rxConnP. 
1669 \par Error Codes 
1670 EINVAL More file identifiers were provided in the a fidArrayP than callbacks in
1671 the a callBackArray. 
1672
1673         \subsubsection sec5-1-3-14 Section 5.1.3.14: RXAFS GetVolumeInfo - Get
1674 information about a volume given its name 
1675
1676 \code
1677 int RXAFS GetVolumeInfo(IN struct rx connection *a rxConnP, 
1678                         IN char *a volNameP, 
1679                         OUT VolumeInfo *a volInfoP) 
1680 \endcode
1681 \par Description 
1682 [Opcode 148] Ask the given File Server for information regarding a volume whose
1683 name is a volNameP. The volume name must be less than AFSNAMEMAX characters
1684 long, and the volume itself must reside on the File Server being probed. 
1685 \par
1686 Rx connection information for the related File Server is contained in a
1687 rxConnP. Please note that definitions for the error codes with VL prefixes may
1688 be found in the vlserver.h include file 
1689 \par Error Codes 
1690 Could not contact any of the corresponding Volume Location Servers. 
1691 VL BADNAME An improperly-formatted volume name provided. 
1692 \n VL ENTDELETED An entry was found for the volume, reporting that the volume
1693 has been deleted. 
1694 \n VL NOENT The given volume was not found. 
1695
1696         \subsubsection sec5-1-3-15 Section 5.1.3.15: RXAFS GetVolumeStatus -
1697 Get basic status information for the named volume 
1698
1699 \code
1700 int RXAFS GetVolumeStatus(IN struct rx connection *a rxConnP, 
1701                                 IN long a volIDP, 
1702                                 OUT AFSFetchVolumeStatus *a volFetchStatP, 
1703                                 OUT char *a volNameP, 
1704                                 OUT char *a offLineMsgP, 
1705                                 OUT char *a motdP) 
1706 \endcode
1707 \par Description 
1708 [Opcode 149] Given the numeric volume identifier contained in a volIDP, fetch
1709 the basic status information corresponding to that volume. This status
1710 information is stored into a volFetchStatP. A full description of this status
1711 structure is found in Section 5.1.2.8. In addition, three other facts about the
1712 volume are returned. The volume's character string name is placed into a
1713 volNameP. This name is guaranteed to be less than AFSNAMEMAX characters long.
1714 The volume's offline message, namely the string recording why the volume is
1715 off-line (if it is), is stored in a offLineMsgP . Finally, the volume's
1716 "Message of the Day" is placed in a motdP. Each of the character strings
1717 deposited into a offLineMsgP and a motdP is guaranteed to be less than
1718 AFSOPAQUEMAX (1,024) characters long. 
1719 \par
1720 Rx connection information for the related File Server is contained in a
1721 rxConnP. 
1722 \par Error Codes 
1723 EACCES The caller does not have the necessary access rights. 
1724 \n EINVAL A volume identifier of zero was specified. 
1725
1726         \subsubsection sec5-1-3-16 Section 5.1.3.16: RXAFS SetVolumeStatus -
1727 Set the basic status information for the named volume
1728
1729 \code
1730 int RXAFS SetVolumeStatus(struct rx connection *a rxConnP,
1731                                 long avolIDP, 
1732                                 AFSStoreVolumeStatus *a volStoreStatP, 
1733                                 char *a volNameP, 
1734                                 char *a offLineMsgP, 
1735                                 char *a motdP) 
1736 /* for the named volume */
1737 \endcode
1738 \par Description
1739 [Opcode 150] Given the numeric volume identifier contained in a volIDP, set
1740 that volume's basic status information to the values contained in a
1741 volStoreStatP. A full description of the fields settable by this call,
1742 including the necessary masking, is found in Section 5.1.2.9. In addition,
1743 three other items relating to the volume may be set. Non-null character strings
1744 found in a volNameP, a offLineMsgP, and a motdP will be stored in the volume's
1745 printable name, off-line message, and "Message of the Day" fields respectively.
1746 The volume name provided must be less than AFSNAMEMAX (256) characters long,
1747 and the other two strings must be less than AFSOPAQUEMAX (1,024) characters
1748 long each. 
1749 \par
1750 Rx connection information for the related File Server is contained in a
1751 rxConnP. 
1752 \par Error Codes 
1753 EACCES The caller does not have the necessary access rights. 
1754 \n EINVAL A volume identifier of zero was specified. 
1755
1756         \subsubsection sec5-1-3-17 Section 5.1.3.17: RXAFS GetRootVolume -
1757 Return the name of the root volume for the file system 
1758
1759 \code
1760 int RXAFS GetRootVolume(IN struct rx connection *a rxConnP, 
1761                         OUT char *a rootVolNameP) 
1762 \endcode
1763 \par Description 
1764 [Opcode 151] Fetch the name of the volume which serves as the root of the AFS
1765 file system and place it into a rootVolNameP. This name will always be less
1766 than AFSNAMEMAX characters long. Any File Server will respond to this call, not
1767 just the one hosting the root volume. The queried File Server first tries to
1768 discover the name of the root volume by reading from the
1769 /usr/afs/etc/RootVolume file on its local disks. If that file doesn't exist,
1770 then it will return the default value, namely "root.afs". 
1771 \par
1772 Rx connection information for the related File Server is contained in a
1773 rxConnP. Volume version information is returned for synchronization purposes in
1774 a volSyncP. 
1775 \par Error Codes 
1776 ---No error codes generated. 
1777
1778         \subsubsection sec5-1-3-18 5.1.3.18: RXAFS CheckToken - (Obsolete)
1779 Check that the given user identifier matches the one in the supplied
1780 authentication token 
1781
1782 \code
1783 int RXAFS CheckToken(IN struct rx connection *a rxConnP, 
1784                         IN long ViceId, 
1785                         IN AFSOpaque *token) 
1786 \endcode
1787 \par Description 
1788 [Opcode 152] This function only works for the now-obsolete RPC facility used by
1789 AFS, R. For modern systems using the Rx RPC mechanism, we always get an error
1790 return from this routine. 
1791 \par
1792 Rx connection information for the related File Server is contained in a
1793 rxConnP. 
1794 \par Error Codes 
1795 ECONNREFUSED Always returned on Rx connections. 
1796
1797         \subsubsection sec5-1-3-19 Section 5.1.3.19: RXAFS GetTime - Get the
1798 File Server's time of day 
1799
1800 \code
1801 int RXAFS GetTime(IN struct rx connection *a rxConnP, 
1802                         OUT unsigned long *a secondsP, 
1803                         OUT unsigned long *a uSecondsP) 
1804 \endcode
1805 \par Description 
1806 [Opcode 153] Get the current time of day from the File Server specified in the
1807 Rx connection information contained in a rxConnP. The time is returned in
1808 elapsed seconds (a secondsP) and microseconds (a uSecondsP) since that standard
1809 unix "start of the world". 
1810 \par Error Codes 
1811 ---No error codes generated. 
1812
1813         \subsubsection sec5-1-3-20 Section 5.1.3.20: RXAFS NGetVolumeInfo - Get
1814 information about a volume given its name 
1815
1816 \code
1817 int RXAFS NGetVolumeInfo(IN struct rx connection *a rxConnP, 
1818                                 IN char *a volNameP, 
1819                                 OUT AFSVolumeInfo *a volInfoP) 
1820 \endcode
1821 \par Description 
1822 [Opcode 154] This function is identical to RXAFS GetVolumeInfo() (see Section
1823 5.1.3.14), except that it returns a struct AFSVolumeInfo instead of a struct
1824 VolumeInfo. The basic difference is that struct AFSVolumeInfo also carries an
1825 accompanying UDP port value for each File Server listed in the record. 
1826
1827         \subsubsection sec5-1-3-21 Section 5.1.3.21: RXAFS BulkStatus - Fetch
1828 the status information regarding a set of given file system objects 
1829
1830 \code
1831 int RXAFS BulkStatus(IN struct rx connection *a rxConnP, 
1832                         IN AFSCBFids *a fidToStatArrayP, 
1833                         OUT AFSBulkStats *a currStatArrayP, 
1834                         OUT AFSCBs *a callBackArrayP, 
1835                         OUT AFSVolSync *a volSyncP) 
1836 \endcode
1837 \par Description 
1838 [Opcode 155] This routine is identical to RXAFS FetchStatus() as described in
1839 Section 5.1.3.2, except for the fact that it allows the caller to ask for the
1840 current status fields for a set of up to AFSCBMAX (50) file identifiers at
1841 once. 
1842 \par
1843 Rx connection information for the related File Server is contained in a
1844 rxConnP. Volume version information is returned for synchronization purposes in
1845 a volSyncP. 
1846 \par Error Codes 
1847 EACCES The caller does not have the necessary access rights. 
1848 \n EINVAL The number of file descriptors for which status information was
1849 requested is illegal. 
1850
1851         \subsubsection sec5-1-3-22 Section 5.1.3.22: RXAFS SetLock - Set an
1852 advisory lock on the given file identifier 
1853
1854 \code
1855 int RXAFS SetLock(IN struct rx connection *a rxConnP, 
1856                         IN AFSFid *a fidToLockP, 
1857                         IN ViceLockType a lockType, 
1858                         OUT AFSVolSync *a volSyncP) 
1859 \endcode
1860 \par Description 
1861 [Opcode 156] Set an advisory lock on the file identified by a fidToLockP. There
1862 are two types of locks that may be specified via a lockType: LockRead and
1863 LockWrite. An advisory lock times out after AFS LOCKWAIT (5) minutes, and must
1864 be extended in order to stay in force (see RXAFS ExtendLock(), Section
1865 5.1.3.23). 
1866 \par
1867 Rx connection information for the related File Server is contained in a
1868 rxConnP. Volume version information is returned for synchronization purposes in
1869 a volSyncP. 
1870 \par Error Codes 
1871 EACCES The caller does not have the necessary access rights. 
1872 \n EINVAL An illegal lock type was specified. 
1873 \n EWOULDBLOCK The lock was already incompatibly granted to another party. 
1874
1875         \subsubsection sec5-1-3-23 Section 5.1.3.23: RXAFS ExtendLock - Extend
1876 an advisory lock on a file 
1877
1878 \code
1879 int RXAFS ExtendLock(IN struct rx connection *a rxConnP, 
1880                         IN AFSFid *a fidToBeExtendedP, 
1881                         OUT AFSVolSync *a volSyncP) 
1882 \endcode
1883 \par Description 
1884 [Opcode 157] Extend the advisory lock that has already been granted to the
1885 caller on the file identified by a fidToBeExtendedP. 
1886 \par
1887 Rx connection information for the related File Server is contained in a
1888 rxConnP. Volume version information is returned for synchronization purposes in
1889 a volSyncP. 
1890 \par Error Codes 
1891 EINVAL The caller does not already have the given file locked. 
1892
1893         \subsubsection sec5-1-3-24 Section 5.1.3.24: RXAFS ReleaseLock -
1894 Release the advisory lock on a file 
1895
1896 \code
1897 int RXAFS ReleaseLock(IN struct rx connection *a rxConnP, 
1898                         IN AFSFid *a fidToUnlockP, 
1899                         OUT AFSVolSync *a volSyncP) 
1900 \endcode
1901 \par Description 
1902 [Opcode 158] Release the advisory lock held on the file identified by a
1903 fidToUnlockP. If this was the last lock on this file, the File Server will
1904 break all existing callbacks to this file. 
1905 \par 
1906 Rx connection information for the related File Server is contained in a
1907 rxConnP. Volume version information is returned for synchronization purposes in
1908 a volSyncP. 
1909 \par Error Codes 
1910 EACCES The caller does not have the necessary access rights. 
1911
1912         \subsubsection sec5-1-3-25 Section 5.1.3.25: RXAFS XStatsVersion - Get
1913 the version number associated with the File Server's extended statistics
1914 structure 
1915
1916 \code
1917 int RXAFS XStatsVersion(IN struct rx connection *a rxConnP, 
1918                         OUT long *a versionNumberP) 
1919 \endcode
1920 \par Description 
1921 [Opcode 159] This call asks the File Server for the current version number of
1922 the extended statistics structures it exports (see RXAFS GetXStats(), Section
1923 5.1.3.26). The version number is placed into a versionNumberP. 
1924 \par
1925 Rx connection information for the related File Server is contained in a
1926 rxConnP. 
1927 \par Error Codes 
1928 ---No error codes generated. 
1929
1930         \subsubsection sec5-1-3-26 Section 5.1.3.26: RXAFS GetXStats - Get the
1931 current contents of the specified extended statistics structure 
1932
1933 \code
1934 int RXAFS GetXStats(IN struct rx connection *a rxConnP, 
1935                         IN long a clientVersionNumber, 
1936                         IN long a collectionNumber, 
1937                         OUT long *a srvVersionNumberP, 
1938                         OUT long *a timeP, 
1939                         OUT AFS CollData *a dataP) 
1940 \endcode
1941 \par Description 
1942 [Opcode 160] This function fetches the contents of the specified File Server
1943 extended statistics structure. The caller provides the version number of the
1944 data it expects to receive in a clientVersionNumber. Also provided in a
1945 collectionNumber is the numerical identifier for the desired data collection.
1946 There are currently two of these data collections defined: AFS XSTATSCOLL CALL
1947 INFO, which is the list of tallies of the number of invocations of internal
1948 File Server procedure calls, and AFS XSTATSCOLL PERF INFO, which is a list of
1949 performance-related numbers. The precise contents of these collections are
1950 described in Sections 5.1.2.7. The current version number of the File Server
1951 collections is returned in a srvVersionNumberP, and is always set upon return,
1952 even if the caller has asked for a difierent version. If the correct version
1953 number has been specified, and a supported collection number given, then the
1954 collection data is returned in a dataP. The time of collection is also
1955 returned, being placed in a timeP. 
1956 \par
1957 Rx connection information for the related File Server is contained in a
1958 rxConnP. 
1959 \par Error Codes 
1960 ---No error codes are generated. 
1961
1962         \subsection sec5-1-4 Section 5.1.4: Streamed Function Calls 
1963
1964 \par
1965 There are two streamed functions in the File Server RPC interface, used to
1966 fetch and store arbitrary amounts of data from a file. While some non-streamed
1967 calls pass such variable-length objects as struct AFSCBFids, these objects have
1968 a pre-determined maximum size. 
1969 \par
1970 The two streamed RPC functions are also distinctive in that their single Rxgen
1971 declarations generate not one but two client-side stub routines. The first is
1972 used to ship the IN parameters off to the designated File Server, and the
1973 second to gather the OUT parameters and the error code. If a streamed
1974 definition declares a routine named X YZ(), the two resulting stubs will be
1975 named StartX YZ() and EndX YZ(). It is the application programmer's job to
1976 first invoke StartX YZ(), then manage the unbounded data transfer, then finish
1977 up by calling EndX YZ(). The first longword in the unbounded data stream being
1978 fetched from a File Server contains the number of data bytes to follow. The
1979 application then reads the specified number of bytes from the stream. 
1980 \par
1981 The following sections describe the four client-side functions resulting from
1982 the Fetch-Data() and StoreData() declarations in the Rxgen interface definition
1983 file. These are the actual routines the application programmer will include in
1984 the client code. For reference, here are the interface definitions that
1985 generate these functions. Note that the split keyword is what causes Rxgen to
1986 generate the separate start and end routines. In each case, the number after
1987 the equal sign specifies the function's identifying opcode number. The opcode
1988 is passed to the File Server by the StartRXAFS FetchData() and StartRXAFS
1989 StoreData() stub routines. 
1990
1991 \code
1992 FetchData(IN AFSFid *a_fidToFetchP, 
1993                 IN long a_offset, 
1994                 IN long a_lenInBytes, 
1995                 OUT AFSFetchStatus *a_fidStatP, 
1996                 OUT AFSCallBack *a_callBackP, 
1997                 OUT AFSVolSync *a_volSyncP) split = 130; 
1998
1999 StoreData(IN AFSFid *Fid, 
2000                 IN AFSStoreStatus *InStatus, 
2001                 IN long Pos, 
2002                 IN long Length, 
2003                 IN long FileLength, 
2004                 OUT AFSFetchStatus *OutStatus, 
2005                 OUT AFSVolSync *a_volSyncP) split = 133; 
2006 \endcode
2007
2008         \subsubsection sec5-1-4-1 Section 5.1.4.1: StartRXAFS FetchData - Begin
2009 a request to fetch file data 
2010
2011 \code
2012 int StartRXAFS FetchData(IN struct rx call *a rxCallP, 
2013                                 IN AFSFid *a fidToFetchP, 
2014                                 IN long a offset, 
2015                                 IN long a lenInBytes) 
2016 \endcode
2017
2018 \par Description
2019 Begin a request for a lenInBytes bytes of data starting at byte offset a offset
2020 from the file identified by a fidToFetchP. After successful completion of this
2021 call, the data stream will make the desired bytes accessible. The first
2022 longword in the stream contains the number of bytes to actually follow. 
2023 \par
2024 Rx call information to the related File Server is contained in a rxCallP. 
2025 \par Error Codes 
2026 ---No error codes generated. 
2027
2028         \subsubsection sec5-1-4-2 Section 5.1.4.2: EndRXAFS FetchData -
2029 Conclude a request to fetch file data 
2030
2031 \code
2032 int EndRXAFS FetchData(IN struct rx call *a rxCallP, 
2033                         OUT AFSFetchStatus *a fidStatP, 
2034                         OUT AFSCallBack *a callBackP, 
2035                         OUT AFSVolSync *a volSyncP) 
2036 \endcode
2037 \par Description
2038 Conclude a request to fetch file data, as commenced by an StartRXAFS
2039 FetchData() invocation. By the time this routine has been called, all of the
2040 desired data has been read off the data stream. The status fields for the file
2041 from which the data was read are stored in a fidStatP. If the file was from a
2042 read/write volume, its callback information is placed in a callBackP. 
2043 \par
2044 Rx call information to the related File Server is contained in a rxCallP.
2045 Volume version information is returned for synchronization purposes in a
2046 volSyncP. 
2047 \par Error Codes 
2048 EACCES The caller does not have the necessary access rights. EIO Given file
2049 could not be opened or statted on the File Server, or there was an error
2050 reading the given data off the File Server's disk. 
2051 \n -31 An Rx write into the stream ended prematurely. 
2052
2053         \subsubsection sec5-1-4-3 Section 5.1.4.3: StartRXAFS StoreData - Begin
2054 a request to store file data 
2055
2056 \code
2057 int StartRXAFS StoreData(IN struct rx call *a rxCallP, 
2058                                 IN AFSFid *a fidToStoreP, 
2059                                 IN reStatus *a fidStatusP, 
2060                                 IN AFSStolong a offset, 
2061                                 IN long a lenInBytes, 
2062                                 IN long a fileLenInBytes) 
2063 \endcode
2064 \par Description
2065 Begin a request to write a lenInBytes of data starting at byte offset a offset
2066 to the file identified by a fidToStoreP, causing that file's length to become a
2067 fileLenInBytes bytes. After successful completion of this call, the data stream
2068 will be ready to begin accepting the actual data being written. 
2069 \par
2070 Rx call information to the related File Server is contained in a rxCallP. 
2071 \par Error Codes 
2072 ---No error codes generated. 
2073
2074         \subsubsection sec5-1-4-4 Section 5.1.4.4: EndRXAFS StoreData -
2075 Conclude a request to store file data 
2076
2077 \code
2078 int EndRXAFS StoreData(IN struct rx call *a rxCallP, 
2079                         OUT AFSFetchStatus *a fidStatP, 
2080                         OUT AFSCallBack *a callBackP, 
2081                         OUT AFSVolSync *a volSyncP) 
2082 \endcode
2083 \par Description 
2084 Conclude a request to store file data, as commenced by a StartRXAFS StoreData()
2085 invocation. By the time this routine has been called, all of the file data has
2086 been inserted into the data stream. The status fields for the file to which the
2087 data was written are stored in a fidStatP. All existing callbacks to the given
2088 file are broken before the store concludes. 
2089 \par
2090 Rx call information to the related File Server is contained in a rxCallP.
2091 Volume version information is returned for synchronization purposes in a
2092 volSyncP. 
2093 \par Error Codes 
2094 EACCES The caller does not have the necessary access rights. 
2095 \n EISDIR The file being written to is a symbolic link. 
2096 \n ENOSPEC A write to the File Server's file on local disk failed. 
2097 \n -32 A short read was encountered by the File Server on the data stream. 
2098
2099         \subsection sec5-1-5 Section 5.1.5: Example of Streamed Function Call
2100 Usage 
2101
2102         \subsubsection sec5-1-5-1 Section 5.1.5.1: Preface 
2103
2104 \par
2105 The following code fragment is offered as an example of how to use the streamed
2106 File Server RPC calls. In this case, a client fetches some amount of data from
2107 the given File Server and writes it to a local file it uses to cache the
2108 information. For simplicity, many issues faced by a true application programmer
2109 are not addressed here. These issues include locking, managing file chunking,
2110 data version number mismatches, volume location, Rx connection management,
2111 defensive programming (e.g., checking parameters before using them),
2112 client-side cache management algorithms, callback management, and full error
2113 detection and recovery. Pseudocode is incorporated when appropriate to keep the
2114 level of detail reasonable. For further descriptions of some of these details
2115 and issues, the reader is referred to such companion documents as AFS-3
2116 Programmer's Reference: Specification for the Rx Remote Procedure Call
2117 Facility, AFS-3 Programmer's Reference:Volume Server/Volume Location Server
2118 Interface, and AFS-3 Programmer's Reference: Architectural Overview. 
2119 \par
2120 A discussion of the methods used within the example code fragment follows
2121 immediately afterwards in Section 5.1.5.3. 
2122
2123         \subsubsection sec5-1-5-2 Section 5.1.5.2: Code Fragment Illustrating
2124 Fetch Operation 
2125
2126 \code
2127 int code; /*Return code*/ 
2128 long bytesRead; /*Num bytes read from Rx*/ 
2129 struct myConnInfo *connP; /*Includes Rx conn info*/ 
2130 struct rx_call *rxCallP; /*Rx call ptr*/ 
2131 struct AFSFid *afsFidP; /*Fid for file to fetch*/ 
2132 int lclFid; /*Fid for local cache file*/ 
2133 long offsetBytes; /*Starting fetch offset*/ 
2134 long bytesToFetch; /*Num bytes to fetch*/ 
2135 long bytesFromFS; /*Num bytes FileServer returns*/ 
2136 char *fetchBuffP; /*Buffer to hold stream data*/ 
2137 int currReadBytes; /*Num bytes for current read*/ 
2138 /* 
2139 * Assume that connP, afsFidP, offsetBytes, lclFid,and 
2140 * bytesToFetch have all been given their desired values. 
2141 */ . . . 
2142 rxCallP = rx_NewCall(connP->rxConnP); 
2143 code = StartRXAFS_FetchData( rxCallP, /*Rx call to use*/ 
2144                         afsFidP, /*Fid being fetched from*/ 
2145                         offsetBytes, /*Offset in bytes*/ 
2146                         bytesToFetch); /*Num bytes wanted*/ 
2147 if (code == 0) 
2148
2149         bytesRead = rx_Read(rxCallP, &bytesFromFS, sizeof(long)); 
2150         if (bytesRead != sizeof(long)) ExitWithError(SHORT_RX_READ); 
2151         bytesFromFS = ntohl(bytesFromFS); 
2152         xmitBuffer = malloc(FETCH_BUFF_BYTES); 
2153         lclFid = open(CacheFileName, O_RDWR, mode); 
2154         pos = lseek(lclFid, offsetBytes, L_SET); 
2155         while (bytesToFetch > 0) { 
2156                 currReadBytes = (bytesToFetch > FETCH_BUFF_BYTES) ?  
2157                                 FETCH_BUFF_BYTES : bytesToFetch; 
2158                 bytesRead = rx_Read(rxCallP, fetchBuffP, currReadBytes); 
2159                 if (bytesRead != currReadBytes) ExitWithError(SHORT_RX_READ); 
2160                 code = write(lclFid, fetchBuffP, currReadBytes); 
2161                 if (code) ExitWithError(LCL_WRITE_FAILED); 
2162                 bytesToFetch -= bytesRead; 
2163         } /*Read from the Rx stream*/ 
2164         close(lclFid); 
2165 } else ExitWithError(code); 
2166 code = EndRXAFS_FetchData( rxCallP, /*Rx call to use*/ 
2167                                 fidStatP, /*Resulting stat fields*/ 
2168                                 fidCallBackP, /*Resulting callback info*/ 
2169                                 volSynchP); /*Resulting volume sync info*/ 
2170                                 code = rx_EndCall(rxCallP, code); 
2171 return(code); . . . 
2172 \endcode
2173
2174         \subsubsection sec5-1-5-3 Section 5.1.5.3: Discussion and Analysis 
2175
2176 \par
2177 The opening assumption in this discussion is that all the information required
2178 to do the fetch has already been set up. These mandatory variables are the
2179 client-side connection information for the File Server hosting the desired
2180 file, the corresponding AFS file identifier, the byte offset into the file, the
2181 number of bytes to fetch, and the identifier for the local file serving as a
2182 cached copy. 
2183 \par
2184 Given the Rx connection information stored in the client's connP record, rx
2185 NewCall() is used to create a new Rx call to handle this fetch operation. The
2186 structure containing this call handle is placed into rxCallP. This call handle
2187 is used immediately in the invocation of StartRXAFS FetchData(). If this setup
2188 call fails, the fragment exits. Upon success, though, the File Server will
2189 commence writing the desired data into the Rx data stream. The File Server
2190 first writes a single longword onto the stream announcing to the client how
2191 many bytes of data will actually follow. The fragment reads this number with
2192 its first rx Read() call. Since all Rx stream data is written in network byte
2193 order, the fragment translates the byte count to its own host byte order first
2194 to properly interpret it. Once the number of bytes to appear on the stream is
2195 known, the client code proceeds to open the appropriate cache file on its own
2196 local disk and seeks to the appropriate spot within it. A buffer into which the
2197 stream data will be placed is also created at this time. 
2198 \par
2199 The example code then falls into a loop where it reads all of the data from the
2200 File Server and stores it in the corresponding place in the local cache file.
2201 For each iteration, the code decides whether to read a full buffer's worth or
2202 the remaining number of bytes, whichever is smaller. After all the data is
2203 pulled off the Rx stream, the local cache file is closed. At this point, the
2204 example finishes off the RPC by calling EndRXAFS FetchData(). This gathers in
2205 the required set of OUT parameters, namely the status fields for the file just
2206 fetched, callback and volume synchronization information, and the overall error
2207 code for the streamed routine. The Rx call created to perform the fetch is then
2208 terminated and cleaned up by invoking rx EndCall(). 
2209
2210         \subsection sec5-1-6 Section 5.1.6: Required Caller Functionality 
2211
2212 \par
2213 The AFS File Server RPC interface was originally designed to interact only with
2214 Cache Manager agents, and thus made some assumptions about its callers. In
2215 particular, the File Server expected that the agents calling it would
2216 potentially have stored callback state on file system objects, and would have
2217 to be periodically pinged in order to garbage-collect its records, removing
2218 information on dead client machines. Thus, any entity making direct calls to
2219 this interface must mimic certain Cache Manager actions, and respond to certain
2220 Cache Manager RPC interface calls. 
2221 \par
2222 To be safe, any application calling the File Server RPC interface directly
2223 should export the entire Cache Manager RPC interface. Realistically, though, it
2224 will only need to provide stubs for the three calls from this interface that
2225 File Servers know how to make: RXAFSCB InitCallBackState(), RXAFSCB Probe() and
2226 RXAFSCB CallBack(). The very first File Server call made by this application
2227 will prompt the given File Server to call RXAFSCB InitCallBackState(). This
2228 informs the application that the File Server has no record of its existence and
2229 hence this "Cache Manager" should clear all callback information for that
2230 server. Once the application responds positively to the inital RXAFSCB
2231 InitCallBackState(), the File Server will treat it as a bona fide,
2232 fully-fledged Cache Manager, and probe it every so often with RXAFSCB Probe()
2233 calls to make sure it is still alive. 
2234
2235         \section sec5-2 Section 5.2: Signal Interface 
2236
2237 \par
2238 While the majority of communication with AFS File Servers occurs over the RPC
2239 interface, some important operations are invoked by sending unix signals to the
2240 process. This section describes the set of signals recognized by the File
2241 Server and the actions they trigger upon receipt, as summarized below: 
2242 \li SIGQUIT: Shut down a File Server. 
2243 \li SIGTSTP: Upgrade debugging output level. 
2244 \li SIGHUP: Reset debugging output level. 
2245 \li SIGTERM: Generate debugging output specifically concerning open files
2246 within the File Server process. 
2247
2248         \subsection sec5-2-1 Section 5.2.1: SIGQUIT: Server Shutdown 
2249
2250 \par
2251 Upon receipt of this signal, the File Server shuts itself down in an orderly
2252 fashion. It first writes a message to the console and to its log file
2253 (/usr/afs/logs/FileLog) stating that a shutdown has commenced. The File Server
2254 then flushes all modified buffers and prints out a set of internal statistics,
2255 including cache and disk numbers. Finally, each attached volume is taken
2256 offline, which means the volume header is written to disk with the appropriate
2257 bits set. 
2258 \par
2259 In typical usage, human operators do not send the SIGQUIT signal directly to
2260 the File Server in order to affect an orderly shutdown. Rather, the BOS Server
2261 managing the server processes on that machine issues the signal upon receipt of
2262 a properly-authorized shutdown RPC request. 
2263
2264         \subsection sec5-2-2 Section 5.2.2: SIGTSTP: Upgrade Debugging Level 
2265
2266 \par
2267 Arrival of a SIGTSTP signal results in an increase of the debugging level used
2268 by the File Server. The routines used for writing to log files are sensitive to
2269 this debugging level, as recorded in the global LogLevel variable.
2270 Specifically, these routines will only generate output if the value of LogLevel
2271 is greater than or equal to the value of its threshold parameter. By default,
2272 the File Server sets LogLevel to zero upon startup. If a SIGTSTP signal is
2273 received when the debugging level is zero, it will be bumped to 1. If the
2274 signal arrives when the debugging level is positive, its value will be
2275 multiplied by 5. Thus, as more SIGTSTPs are received, the set of debugging
2276 messages eligible to be delivered to log files grows. 
2277 \par
2278 Since the SIGTSTP signal is not supported under IBM's AIX 2.2.1 operating
2279 system, this form of debugging output manipulation is not possible on those
2280 platforms. 
2281
2282         \subsection sec5-2-3 Section 5.2.3: SIGHUP: Reset Debugging Level 
2283
2284 \par
2285 Receiving a SIGHUP signal causes a File Server to reset its debugging level to
2286 zero. This effectively reduces the set of debugging messages eligible for
2287 delivery to log files to a bare minimum. This signal is used in conjunction
2288 with SIGTSTP to manage the verbosity of log information. 
2289 \par
2290 Since the SIGHUP signal is not supported under IBM's AIX 2.2.1 operating
2291 system, this form of debugging output manipulation is not possible on those
2292 platforms. 
2293
2294         \subsection sec5-2-4 Section 5.2.4: SIGTERM: File Descriptor Check 
2295
2296 \par
2297 Receipt of a SIGTERM signal triggers a routine which sweeps through the given
2298 File Server's unix file descriptors. For each possible unix fid slot, an
2299 fstat() is performed on that descriptor, and the particulars of each open file
2300 are printed out. This action is designed solely for debugging purposes. 
2301
2302         \section sec5-3 Section 5.3: Command Line Interface 
2303
2304 \par
2305 Another interface exported by the File Server is the set of command line
2306 switches it accepts. Using these switches, many server parameters and actions
2307 can be set. Under normal conditions, the File Server process is started up by
2308 the BOS Server on that machine, as described in AFS-3 Programmer's Reference:
2309 BOS Server Interface. So, in order to utilize any combination of these
2310 command-line options, the system administrator must define the File Server
2311 bnode in such a way that these parameters are properly included. Note that the
2312 switch names must be typed exactly as listed, and that abbreviations are not
2313 allowed. Thus, specifying -b 300 on the command line is unambiguous, directing
2314 that 300 buffers are to be allocated. It is not an abbreviation for the -banner
2315 switch, asking that a message is to be printed to the console periodically. 
2316 \par
2317 A description of the set of currently-supported command line switches follows. 
2318 \li -b <# buffers> Choose the number of 2,048-byte data buffers to allocate at
2319 system startup. If this switch is not provided, the File Server will operate
2320 with 70 such buffers by default. 
2321 \li -banner This switch instructs the File Server to print messages to the
2322 console every 10 minutes to demonstrate it is still running correctly. The text
2323 of the printed message is: File Server is running at <time>. 
2324 \li -cb <# callbacks stored> Specify the maximum number of callback records
2325 stored simultaneously by the File Server. The default pool size is 20,000
2326 records. 
2327 \li -d <debug level> Set the debugging output level at which File Server runs
2328 to the value provided. Specifically, the LogLevel global variable is set to the
2329 given value (See Section 5.2.2). If this switch is not provided, the default
2330 initial File Server debugging level is set to zero, producing the minimal
2331 debugging output to the log files. 
2332 \li -k <stack size> Set the stack size to provide server LWPs upon creation,
2333 measured in 1,024-byte blocks. The default LWP stack size is 24 blocks, or
2334 24,576 bytes. 
2335 \li -l <large (directory) vnodes> Select the number of "large" vnodes the File
2336 Server will cache. These vnodes are suitable for recording information about
2337 AFS directories. The extra space in the vnode allows ACL information to be
2338 stored along with the directory. The default allocation value is 200 directory
2339 vnodes. 
2340 \li -pctspare <percent overrun blocks past quota> Similar to the -spare switch,
2341 except that the number of allowable overrun blocks is expressed as a percentage
2342 of the given volume's quota. Note: this switch cannot be used in combination
2343 with the -spare switch. 
2344 \li -rxdbg Instruct the File Server to open a file named rx dbg in the current
2345 directory, into which the Rx package will write general debugging information.
2346 If the file is already open (due to the appearance of the -rxdbge switch
2347 earlier in the command line), this results in a no-op. 
2348 \li -rxdbge Instruct the File Server to open a file named rx dbg in the current
2349 directory, into which the Rx package will write debugging information related
2350 to its event-scheduling activities. If the file is already open (due to the
2351 appearance of the -rxdbg switch earlier in the command line), this results in a
2352 no-op. 
2353 \li -rxpck <# packets> Set the number of extra Rx packet buffers to hold in
2354 reserve. These pre-allocated buffers assist in responding to spikes in network
2355 traffic demands. By default, 100 such packet buffers are maintained. 
2356 \li -s <small (file) vnodes> Select the number of "small" vnodes the File
2357 Server will cache. These vnodes are suitable for recording information about
2358 non-directory files. As with directory vnodes, the File Server will allocate
2359 200 small vnodes by default. 
2360 \li -spare <# overrun blocks to allow> Tell the File Server to allow users
2361 performing a store operation to overrun the host volume's disk quota by a
2362 certain number of (1,024-byte) blocks. In other words, the first store
2363 resulting in a quota overrun will be allowed to succeed if and only if it uses
2364 no more than these many blocks beyond the quota. Further store operations will
2365 be rejected until the volume's storage is once again reduced below quota. By
2366 default, overruns of 1,024 blocks of 1,024 bytes each (1 megabyte total) are
2367 tolerated. Note: this switch cannot be used in combination with the -pctspare
2368 switch. 
2369 \li -w <callback wait interval in seconds> This switch determines how often the
2370 File Server periodic daemon lightweight processes run. Among other things,
2371 these daemon LWPs check on the validity of callback records, keep disk usage
2372 statistics up to date, and check the health of the various client machines that
2373 have previously interacted with the File Server. For a full description of
2374 these daemon LWPs, consult Section 2.3. The associated argument specifies the
2375 number of seconds to sleep between daemon invocations. By default, these
2376 periodic daemons run every 300 seconds (5 minutes). 
2377
2378         \page chap6 Chapter 6: Cache Manager Interfaces 
2379
2380         \section sec6-1 Section 6.1: Overview 
2381
2382 \par
2383 There are several interfaces offered by the Cache Manager, allowing clients to
2384 access the files stored by the community of AFS File Servers, to configure the
2385 Cache Manager's behavior and resources, to store and retrieve authentication
2386 information, to specify the location of community Authentication Server and
2387 Volume Location Server services, and to observe and debug the Cache Manager's
2388 state and actions. This chapter will cover the following five interfaces to the
2389 Cache Manager: 
2390 \li     ioctl(): The standard unix ioctl() system call has been extended to
2391 include more operations, namely waiting until data stores to a File Server
2392 complete before returning to the caller (VIOCCLOSEWAIT) and getting the name of
2393 the cell in which an open file resides (VIOCIGETCELL). 
2394 \li     pioctl(): An additional system call is provided through which
2395 applications can access operations specific to AFS, which are often tied to a
2396 particular pathname. These operations include Access Control List (ACL) and
2397 mount point management, Kerberos ticket management, cache configuration, cell
2398 configuration, and status of File Servers. 
2399 \li     RPC: Interface by which outside servers and investigators can
2400 manipulate the Cache Manager. There are two main categories of routines:
2401 callback management, typically called by the File Server, and
2402 debugging/statistics, called by programs such as cmdebug and via the xstat
2403 user-level library for collection of extended statistics. 
2404 \li     Files: Much of the Cache Manager's configuration information, as well
2405 as its view of the AFS services available from the outside world, is obtained
2406 from parsing various files. One set of these files is typically located in
2407 /usr/vice/etc, and includes CellServDB, ThisCell, and cacheinfo. Another set is
2408 usually found in /usr/vice/cache, namely CacheItems, VolumeItems, and AFSLog. 
2409 \li     Mariner: This is the interface by which file transfer activity between
2410 the Cache Manager and File Servers may be monitored. Specifically, it is used
2411 to monitor the names of the files and directories being fetched and/or stored
2412 over the network. 
2413 \par
2414 Another important component not described in this document is the afsd program.
2415 It is afsd's job to initialize the Cache Manager on a given machine and to
2416 start up its related daemon threads. It accepts a host of configuration
2417 decisions via its command-line interface. In addition, it parses some of the
2418 information kept in the configuration files mentioned above and passes that
2419 information to the Cache Manager. The reader may find a full description of
2420 afsd in the AFS 3.0 Command Reference Manual[2]. 
2421
2422         \section sec6-2 Section 6.2: Definitions 
2423
2424 \par
2425 This section defines data structures that are used by the pioctl() calls. 
2426
2427         \subsection sec6-2-1 Section 6.2.1: struct VenusFid 
2428
2429 \par
2430 The Cache Manager is the sole active AFS agent aware of the cellular
2431 architecture of the system. Since AFS file identifiers are not guaranteed to be
2432 unique across cell boundaries, it must further qualify them for its own
2433 internal bookkeeping. The struct VenusFid provides just such additional
2434 qualification, attaching the Cache Manager's internal cell identifier to the
2435 standard AFS fid. 
2436 \n \b Fields 
2437 \li long Cell - The internal identifier for the cell in which the file resides. 
2438 \li struct ViceFid Fid - The AFS file identifier within the above cell. 
2439
2440         \subsection sec6-2-2 Section 6.2.2: struct ClearToken 
2441
2442 \par
2443 This is the clear-text version of an AFS token of identity. Its fields are
2444 encrypted into the secret token format, and are made easily available to the
2445 Cache Manager in this structure. 
2446 \n \b Fields 
2447 \li long AuthHandle - Key version number. 
2448 \li char HandShakeKey[8] - Session key. 
2449 \li long ViceId - Identifier for the AFS principal represented by this token. 
2450 \li long BeginTimestamp - Timestamp of when this token was minted, and hence
2451 came into effect. 
2452 \li long EndTimestamp - Timestamp of when this token is considered to be
2453 expired, and thus disregarded. 
2454
2455         \section sec6-3 Section 6.3: ioctl() Interface 
2456
2457 \par
2458 The standard unix ioctl() system call performs operations on file system
2459 objects referenced with an open file descriptor. AFS has augmented this system
2460 call with two additional operations, one to perform "safe stores", and one to
2461 get the name of the cell in which a file resides. A third ioctl() extension is
2462 now obsolete, namely aborting a store operation currently in progress. 
2463
2464         \subsection sec6-3-1 Section 6.3.1: VIOCCLOSEWAIT 
2465
2466 \par
2467 [Opcode 1] Normally, a client performing a unix close() call on an AFS file
2468 resumes once the store operation on the given file data to the host File Server
2469 has commenced but before it has completed. Thus, it is possible that the store
2470 could actually fail (say, because of network partition or server crashes)
2471 without the client's knowledge. This new ioctl opcode specifies to the Cache
2472 Manager that all future close() operations will wait until the associated store
2473 operation to the File Server has completed fully before returning. 
2474
2475         \subsection sec6-3-2 Section 6.3.2: VIOCABORT 
2476
2477 \par
2478 [Opcode 2] This ioctl() extension is now obsolete. This call results in a noop.
2479 The original intention of this call was to allow a store operation currently in
2480 progress to a File Server on the named fid to be aborted. 
2481
2482         \subsection sec6-3-3 Section 6.3.3: VIOIGETCELL 
2483
2484 \par
2485 [Opcode 3] Get the name of the cell in which the given fid resides. If the file
2486 is not an AFS file, then ENOTTY is returned. The output buffer specified in the
2487 data area must be large enough to hold the null-terminated string representing
2488 the file's cell, otherwise EFAULT is returned. However, an out size value of
2489 zero specifies that the cell name is not to be copied into the output buffer.
2490 In this case, the caller is simply interested in whether the file is in AFS,
2491 and not its exact cell of residence. 
2492
2493         \section sec6-4 Section 6.4: pioctl() Interface 
2494
2495         \subsection sec6-4-1 Section 6.4.1: Introduction 
2496
2497 \par
2498 There is a new unix system call, pioctl(), which has been defined especially to
2499 support the AFS Cache Manager. Its functional definition is as follows: 
2500 \code
2501 int afs syscall pioctl(IN char *a pathP, 
2502                         IN int a opcode, 
2503                         IN struct ViceIoctl *a paramsP, 
2504                         IN int a followSymLinks) 
2505 \endcode
2506 \par
2507 This new call is much like the standard ioctl() call, but differs in that the
2508 affected file (when applicable) is specified by its path, not by a file
2509 descriptor. Another difference is the fourth parameter, a followSymLinks,
2510 determines which file should be used should a pathP be a symbolic link. If a
2511 followSymLinks be set to 1, then the symbolic link is followed to its target,
2512 and the pioctl() is applied to that resulting file. If a followSymLinks is set
2513 to 0, then the pioctl() applies to the symbolic link itself. 
2514 \par
2515 Not all pioctl() calls affect files. In those cases, the a pathP parameter
2516 should be set to a null pointer. The second parameter to pioctl(), a opcode,
2517 specifies which operation is to be performed. The opcode for each of these
2518 operations is included in the text of the description. Note that not all
2519 pioctl() opcodes are in use. These unused values correspond to obsolete
2520 operations. 
2521 \par
2522 The descriptions that follow identify some of the possible error codes for each
2523 pioctl() opcode, but do not offer a comprehensive lists. All pioctl() calls
2524 return 0 upon success. 
2525 \par
2526 The rest of this section proceeds to describe the individual opcodes available.
2527 First, though, one asymmetry in this opcode set is pointed out, namely that
2528 while various operations are defined on AFS mount points, there is no direct
2529 way to create a mount point. 
2530 \par
2531 This documentation partitions the pioctl() into several groups: 
2532 \li Volume operations 
2533 \li File Server operations 
2534 \li Cell Operations 
2535 \li Authentication Operations 
2536 \li ACL Operations 
2537 \li Cache operations 
2538 \li Miscellaneous operations 
2539
2540 \par
2541 For all pioctl()s, the fields within the a paramsP parameter will be referred
2542 to directly. Thus, the values of in, in size, out, and out size are discussed,
2543 rather than the settings for a paramsP->in, a paramsP->in size, a paramsP->out,
2544 and a paramsP->out size. 
2545 \par
2546 For convenience of reference, a list of the actively-supported pioctl()s, their
2547 opcodes, and brief description appears (in opcode order) below. 
2548 \li [1] VIOCSETAL : Set the ACL on a directory 
2549 \li [2] VIOCGETAL : Get the ACL for a directory 
2550 \li [3] VIOCSETTOK : Set the caller's token for a cell 
2551 \li [4] VIOCGETVOLSTAT : Get volume status 
2552 \li [5] VIOCSETVOLSTAT : Set volume status 
2553 \li [6] VIOCFLUSH : Flush an object from the cache 
2554 \li [8] VIOCGETTOK : Get the caller's token for a cell 
2555 \li [9] VIOCUNLOG : Discard authentication information 
2556 \li [10] VIOCCKSERV : Check the status of one or more File Servers 
2557 \li [11] VIOCCKBACK : Mark cached volume info as stale 
2558 \li [12] VIOCCKCONN : Check caller's tokens/connections 
2559 \li [14] VIOCWHEREIS : Find host(s) for a volume 
2560 \li [20] VIOCACCESS : Check caller's access on object 
2561 \li [21] VIOCUNPAG : See [9] VIOCUNLOG 
2562 \li [22] VIOCGETFID : Get fid for named object 
2563 \li [24] VIOCSETCACHESIZE : Set maximum cache size in blocks 
2564 \li [25] VIOCFLUSHCB : Unilaterally drop a callback 
2565 \li [26] VIOCNEWCELL : Set cell service information 
2566 \li [27] VIOCGETCELL : Get cell configuration entry 
2567 \li [28] VIOCAFS DELETE MT PT : Delete a mount point 
2568 \li [29] VIOC AFS STAT MT PT : Get the contents of a mount point 
2569 \li [30] VIOC FILE CELL NAME : Get cell hosting a given object 
2570 \li [31] VIOC GET WS CELL : Get caller's home cell name 
2571 \li [32] VIOC AFS MARINER HOST : Get/set file transfer monitoring output 
2572 \li [33] VIOC GET PRIMARY CELL : Get the caller's primary cell 
2573 \li [34] VIOC VENUSLOG : Enable/disable Cache Manager logging 
2574 \li [35] VIOC GETCELLSTATUS : Get status info for a cell entry 
2575 \li [36] VIOC SETCELLSTATUS : Set status info for a cell entry 
2576 \li [37] VIOC FLUSHVOLUME : Flush cached data from a volume 
2577 \li [38] VIOC AFS SYSNAME : Get/set the @sys mapping 
2578 \li [39] VIOC EXPORTAFS : Enable/disable NFS/AFS translation 
2579 \li [40] VIOCGETCACHEPARAMS : Get current cache parameter values 
2580
2581         \subsection sec6-4-2 Section 6.4.2: Mount Point Asymmetry 
2582
2583 \par
2584 There is an irregularity which deserves to be mentioned regarding the pioctl()
2585 interface. There are pioctl() operations for getting information about a mount
2586 point (VIOC AFS STAT MT PT) and for deleting a mount point (VIOC AFS DELETE MT
2587 PT), but no operation for creating mount points. To create a mount point, a
2588 symbolic link obeying a particular format must be created. The first character
2589 must be either a "%" or a "#", depending on the type of mount point being
2590 created (see the discussion in Section 6.4.4.4). If the mount point carries the
2591 name of the cell explicitly, the full cell name will appear next, followed by a
2592 colon. In all cases, the next portion of the mount point is the volume name. By
2593 convention, the last character of a mount point must always be a period (".").
2594 This trailing period is not visible in the output from fs lsmount. 
2595
2596         \subsection sec6-4-3 Section 6.4.3: Volume Operations 
2597
2598 \par
2599 There are several pioctl() opcodes dealing with AFS volumes. It is possible to
2600 get and set volume information (VIOCGETVOLSTAT, VIOCSETVOLSTAT), discover which
2601 volume hosts a particular file system object (VIOCWHEREIS), remove all objects
2602 cached from a given volume (VIOC FLUSHVOLUME), and revalidate cached volume
2603 information (VIOCCKBACK). 
2604
2605         \subsubsection sec6-4-3-1 Section 6.4.3.1: VIOCGETVOLSTAT: Get volume
2606 status for pathname 
2607
2608 \par
2609 [Opcode 4] Fetch information concerning the volume that contains the file
2610 system object named by a pathP. There is no other input for this call, so in
2611 size should be set to zero. The status information is placed into the buffer
2612 named by out, if out size is set to a value of sizeof(struct VolumeStatus) or
2613 larger. Included in the volume information are the volume's ID, quota, and
2614 number of blocks used in the volume as well as the disk partition on which it
2615 resides. Internally, the Cache Manager calls the RXAFS GetVolumeInfo() RPC (See
2616 Section 5.1.3.14) to fetch the volume status. 
2617 \par
2618 Among the possible error returns, EINVAL indicates that the object named by a
2619 pathP could not be found. 
2620
2621         \subsubsection sec6-4-3-2 Section 6.4.3.2: VIOCSETVOLSTAT: Set volume
2622 status for pathname 
2623
2624 \par
2625 [Opcode 5] Set the status fields for the volume hosting the file system object
2626 named by a pathP. The first object placed into the input buffer in is the new
2627 status image. Only those fields that may change, namely MinQuota and MaxQuota
2628 fields, are interpreted upon receipt by the File Server, and are set to the
2629 desired values. Immediately after the struct VolumeStatus image, the caller
2630 must place the null-terminated string name of the volume involved in the input
2631 buffer. New settings for the offline message and MOTD (Message of the Day)
2632 strings may appear after the volume name. If there are no changes in the
2633 offline and/or MOTD messages, a null string must appear for that item. The in
2634 size parameter must be set to the total number of bytes so inserted, including
2635 the nulls after each string. Internally, the Cache Manager calls the RXAFS
2636 SetVolumeStatus() RPC (See Section 5.1.3.16) to store the new volume status. 
2637 \par
2638 Among the possible error returns, EINVAL indicates that the object named by a
2639 pathP could not be found. 
2640
2641         \subsubsection sec6-4-3-3 Section 6.4.3.3: VIOCWHEREIS: Find the
2642 server(s) hosting the pathname's volume 
2643
2644 \par
2645 [Opcode 14] Find the set of machines that host the volume in which the file
2646 system object named by a pathP resides. The input buffer in is not used by this
2647 call, so in size should be set to zero. The output buffer indicated by out is
2648 filled with up to 8 IP addresses, one for each File Server hosting the
2649 indicated volume. Thus, out size should be set to at least (8*sizeof(long)).
2650 This group of hosts is terminated by the first zeroed IP address that appears
2651 in the list, but under no circumstances are more than 8 host IP addresses
2652 returned. 
2653 \par
2654 Among the possible error returns is EINVAL, indicating that the pathname is not
2655 in AFS, hence is not contained within a volume. If ENODEV is returned, the
2656 associated volume information could not be obtained. 
2657
2658         \subsubsection sec6-4-3-4 Section 6.4.3.4: VIOC FLUSHVOLUME: Flush all
2659 data cached from the pathname's volume 
2660
2661 \par
2662 [Opcode 37] Determine the volume in which the file system object named by a
2663 pathP resides, and then throw away all currently cached copies of files that
2664 the Cache Manager has obtained from that volume. This call is typically used
2665 should a user suspect there is some cache corruption associated with the files
2666 from a given volume. 
2667
2668         \subsubsection sec6-4-3-5 Section 6.4.3.5: VIOCCKBACK: Check validity
2669 of all cached volume information 
2670
2671 \par
2672 [Opcode 11] Ask the Cache Manager to check the validity of all cached volume
2673 information. None of the call's parameters are referenced in this call, so a
2674 pathP and in should be set to the null pointer, and in size and out size should
2675 be set to zero. 
2676 \par
2677 This operation is performed in two steps: 
2678 \li 1 The Cache Manager first refreshes its knowledge of the root volume,
2679 usually named root.afs. On success, it wakes up any of its own threads waiting
2680 on the arrival of this information, should it have been previously unreachable.
2681 This typically happens should the Cache Manager discover in its startup
2682 sequence that information on the root volume is unavailable. Lacking this
2683 knowledge at startup time, the Cache Manager settles into a semi-quiescent
2684 state, checking every so often to see if volume service is available and thus
2685 may complete its own initialization. 
2686 \li 2 Each cached volume record is flagged as being stale. Any future attempt
2687 to access information from these volumes will result in the volume record's
2688 data first being refreshed from the Volume Location Server. 
2689
2690         \subsection sec6-4-4 Section 6.4.4: File Server Operations 
2691
2692 \par
2693 One group of pioctl() opcodes is aimed at performing operations against one or
2694 more File Servers directly. Specifically, a caller may translate a pathname
2695 into the corresponding AFS fid (VIOCGETFID), unilaterally discard a set of
2696 callback promises (VIOCFLUSHCB), get status on mount points (VIOC AFS STAT MT
2697 PT), delete unwanted mount points (VIOC AFS DELETE MT PT), and check the health
2698 of a group of File Servers(VIOCCKSERV). 
2699
2700         \subsubsection sec6-4-4-1 Section 6.4.4.1: VIOCGETFID: Get augmented
2701 fid for named file system object 
2702
2703 \par
2704 [Opcode 22] Return the augmented file identifier for the file system object
2705 named by a pathP. The desired struct VenusFid is placed in the output buffer
2706 specified by out. The output buffer size, as indicated by the out size
2707 parameter, must be set to the value of sizeof(struct VenusFid) or greater. The
2708 input buffer is not referenced in this call, so in should be set to the null
2709 pointer and in size set to zero. 
2710 \par
2711 Among the possible error returns, EINVAL indicates that the object named by a
2712 pathP was not found. 
2713
2714         \subsubsection sec6-4-4-2 Section 6.4.4.2: VIOCFLUSHCB: Unilaterally
2715 drop a callback 
2716
2717 \par
2718 [Opcode 25] Remove any callback information kept by the Cache Manager on the
2719 file system object named by a pathP. Internally, the Cache Manager executes a
2720 call to the RXAFS GiveUpCallBacks() RPC (See Section 5.1.3.13) to inform the
2721 appropriate File Server that it is being released from its particular callback
2722 promise. Note that if the named file resides on a read-only volume, then the
2723 above call is not made, and success is returned immediately. This optimization
2724 is possible because AFS File Servers do not grant callbacks on files from
2725 read-only volumes. 
2726 \par
2727 Among the possible error returns is EINVAL, which indicates that the object
2728 named by a pathP was not found. 
2729
2730         \subsubsection sec6-4-4-3 Section 6.4.4.3: VIOC AFS DELETE MT PT:
2731 Delete a mount point 
2732
2733 \par
2734 [Opcode 28] Remove an AFS mount point. The name of the directory in which the
2735 mount point exists is specified by a pathP, and the string name of the mount
2736 point within this directory is provided through the in parameter. The input
2737 buffer length, in size, is set to the length of the mount point name itself,
2738 including the trailing null. The output buffer is not accessed by this call, so
2739 out should be set to the null pointer and out size to zero. 
2740 \par
2741 One important note is that the a followSymLinks argument must be set to zero
2742 for correct operation. This is counter-intuitive, since at first glance it
2743 seems that a symbolic link that resolves to a directory should be a valid
2744 pathname parameter. However, recall that mount points are implemented as
2745 symbolic links that do not actually point to another file system object, but
2746 rather simply contain cell and volume information (see the description in
2747 Section 6.4.2). This "special" symbolic link must not be resolved by the
2748 pioctl(), but rather presented as-is to the Cache Manager, which then properly
2749 interprets it and generates a reference to the given volume's root directory.
2750 As an unfortunate side-effect, a perfectly valid symbolic link referring to a
2751 directory will be rejected out of hand by this operation as a value for the a
2752 pathP parameter. 
2753 \par
2754 Among the possible error returns, EINVAL reports that the named directory was
2755 not found, and ENOTDIR indicates that the pathname contained within a pathP is
2756 not a directory. 
2757
2758         \subsubsection sec6-4-4-4 Section 6.4.4.4: VIOC AFS STAT MT PT: Get the
2759 contents of a mount point 
2760
2761 \par
2762 [Opcode 29] Return the contents of the given mount point. The directory in
2763 which the mount point in question resides is provided via the a pathP argument,
2764 and the in buffer contains the name of the mount point object within this
2765 directory. As usual, in size is set to the length of the input buffer,
2766 including the trailing null. If the given object is truly a mount point and the
2767 out buffer is large enough (its length appears in out size), the mount point's
2768 contents are stored into out. 
2769 \par
2770 The mount point string returned obeys a stylized format, as fully described in
2771 Section 5.6.2 of the AFS 3.0 System Administrator's Guide[1]. Briefly, a
2772 leading pound sign ("#") indicates a standard mount point, inheriting the
2773 read-only or read-write preferences of the mount point's containing volume. On
2774 the other hand, a leading percent sign ("%") advises the Cache Manager to cross
2775 into the read-write version of the volume, regardless of the existence of
2776 read-only clones. If a colon (":") separator occurs, the portion up to the
2777 colon itself denotes the fully-qualified cell name hosting the volume. The rest
2778 of the string is the volume name itself. 
2779 \par
2780 Among the possible error codes is EINVAL, indicating that the named object is
2781 not an AFS mount point. Should the name passed in a pathP be something other
2782 than a directory, then ENOTDIR is returned. 
2783
2784         \subsubsection sec6-4-4-5 Section 6.4.4.5: VIOCCKSERV: Check the status
2785 of one or more File Servers 
2786
2787 \par
2788 [Opcode 10] Check the status of the File Servers that have been contacted over
2789 the lifetime of the Cache Manager. The a pathP parameter is ignored by this
2790 call, so it should be set to the null pointer. The input parameters as
2791 specified by in are completely optional. If something is placed in the input
2792 buffer, namely in size is not zero, then the first item stored there is a
2793 longword used as a bit array of flags. These flags carry instructions as to the
2794 domain and the "thoroughness" of this check. 
2795 \par
2796 Only the settings of the least-significant two bits are recognized. Enabling
2797 the lowest bit tells the Cache Manager not to ping its list of servers, but
2798 simply report their status as contained in the internal server records.
2799 Enabling the next-higher bit limits the search to only those File Servers in a
2800 given cell. If in size is greater than sizeof(long),a null-terminated cell name
2801 string follows the initial flag array, specifying the cell to check. If this
2802 search bit is set but no cell name string follows the longword of flags, then
2803 the search is restricted to those servers contacted from the same cell as the
2804 caller. 
2805 \par
2806 This call returns at least one longword into the output buffer out, specifying
2807 the number of hosts it discovered to be down. If this number is not zero, then
2808 the longword IP address for each dead (or unreachable) host follows in the
2809 output buffer. At most 16 server addresses will be returned, as this is the
2810 maximum number of servers for which the Cache Manager keeps information. 
2811 \par
2812 Among the possible error returns is ENOENT, indicating that the optional cell
2813 name string input value is not known to the Cache Manager. 
2814
2815         \subsection sec6-4-5 Section 6.4.5: Cell Operations 
2816
2817 \par
2818 The Cache Manager is the only active AFS agent that understands the system's
2819 cellular architecture. Thus, it keeps important information concerning the
2820 identities of the cells in the community, which cell is in direct
2821 administrative control of the machine upon which it is running, status and
2822 configuration of its own cell, and what cell-specific operations may be legally
2823 executed. The following pioctl()s allow client processes to access and update
2824 this cellular information. Supported operations include adding or updating
2825 knowledge of a cell, including the cell overseeing the caller's machine
2826 (VIOCNEWCELL), fetching the contents of a cell configuration entry
2827 (VIOCGETCELL), finding out which cell hosts a given file system object (VIOC
2828 FILE CELL NAME), discovering the cell to which the machine belongs (VIOC GET WS
2829 CELL), finding out the caller's "primary" cell (VIOC GET PRIMARY CELL), and
2830 getting/setting certain other per-cell system parameters (VIOC GETCELLSTATUS,
2831 VIOC SETCELLSTATUS). 
2832
2833         \subsubsection sec6-4-5-1 Section 6.4.5.1: VIOCNEWCELL: Set cell
2834 service information 
2835
2836 \par
2837 [Opcode 26] Give the Cache Manager all the information it needs to access an
2838 AFS cell. Exactly eight longwords are placed at the beginning of the in input
2839 buffer. These specify the IP addresses for the machine providing AFS
2840 authentication and volume location authentication services. The first such
2841 longword set to zero will signal the end of the list of server IP addresses.
2842 After these addresses, the input buffer hosts the null-terminated name of the
2843 cell to which the above servers belong. The a pathP parameter is not used, and
2844 so should be set to the null pointer. 
2845 \par
2846 Among the possible error returns is EACCES, indicating that the caller does not
2847 have the necessary rights to perform the operation. Only root is allowed to set
2848 cell server information. If either the IP address array or the server name is
2849 unacceptable, EINVAL will be returned. 
2850
2851         \subsubsection sec6-4-5-2 Section 6.4.5.2: VIOCGETCELL: Get cell
2852 configuration entry 
2853
2854 \par
2855 [Opcode 27] Get the i'th cell configuration entry known to the Cache Manager.
2856 The index of the desired entry is placed into the in input buffer as a
2857 longword, with the first legal value being zero. If there is a cell associated
2858 with the given index, the output buffer will be filled with an array of 8
2859 longwords, followed by a null-terminated string. 
2860 \par
2861 The longwords correspond to the list of IP addresses of the machines providing
2862 AFS authentication and volume location services. The string reflects the name
2863 of the cell for which the given machines are operating. There is no explicit
2864 count returned of the number of valid IP addresses in the longword array.
2865 Rather, the list is terminated by the first zero value encountered, or when the
2866 eighth slot is filled. 
2867 \par
2868 This routine is intended to be called repeatedly, with the index starting at
2869 zero and increasing each time. The array of cell information records is kept
2870 compactly, without holes. A return value of EDOM indicates that the given index
2871 does not map to a valid entry, and thus may be used as the terminating
2872 condition for the iteration. 
2873
2874         \subsubsection sec6-4-5-3 Section 6.4.5.3: VIOC FILE CELL NAME: Get
2875 cell hosting a given object 
2876
2877 \par
2878 [Opcode 30] Ask the Cache Manager to return the name of the cell in which the
2879 file system object named by a pathP resides. The input arguments are not used,
2880 so in should be set to the null pointer and in size should be set to zero. The
2881 null-terminated cell name string is returned in the out output buffer. 
2882 \par
2883 Among the possible error values, EINVAL indicates that the pathname provided in
2884 a pathP is illegal.  If there is no cell information associated with the given
2885 object, ESRCH is returned.
2886
2887         \subsubsection sec6-4-5-4 Section 6.4.5.4: VIOC GET WS CELL: Get
2888 caller's home cell name 
2889
2890 \par
2891 [Opcode 31] Return the name of the cell to which the caller's machine belongs.
2892 This cell name is returned as a null-terminated string in the output buffer.
2893 The input arguments are not used, so in should be set to the null pointer and
2894 in size should be set to zero. 
2895 \par
2896 Among the possible error returns is ESRCH, stating that the caller's home cell
2897 information was not available. 
2898
2899         \subsubsection sec6-4-5-5 Section 6.4.5.5: VIOC GET PRIMARY CELL: Get
2900 the caller's primary cell 
2901
2902 \par
2903 [Opcode 33] Ask the Cache Manager to return the name of the caller's primary
2904 cell. Internally, the Cache Manager scans its user records, and the cell
2905 information referenced by that record is used to extract the cell's string
2906 name. The input arguments are not used, so in should be set to the null pointer
2907 and in size should be set to zero. The a pathP pathname argument is not used
2908 either, and should similarly be set to the null pointer. The null-terminated
2909 cell name string is placed into the output buffer pointed to by out if it has
2910 suffcient room. 
2911 \par
2912 Among the possible error returns is ESRCH, stating that the caller's primary
2913 cell information was not available. 
2914
2915         \subsubsection sec6-4-5-6 Section 6.4.5.6: VIOC GETCELLSTATUS: Get
2916 status info for a cell entry 
2917
2918 \par
2919 [Opcode 35] Given a cell name, return a single longword of status flags from
2920 the Cache Manager's entry for that cell. The null-terminated cell name string
2921 is expected to be in the in parameter, with in size set to its length plus one
2922 for the trailing null. The status flags are returned in the out buffer, which
2923 must have out size set to sizeof(long) or larger. 
2924 \par
2925 The Cache Manager defines the following output flag values for this operation: 
2926 \li 0x1 This entry is considered the caller's primary cell. 
2927 \li 0x2 The unix setuid() operation is not honored. 
2928 \li 0x4 An obsolete version of the Volume Location Server's database is being
2929 used. While defined, this flag should no longer be set in modern systems. 
2930
2931 \par
2932 Among the possible error returns is ENOENT, informing the caller that the Cache
2933 Manager has no knowledge of the given cell name. 
2934
2935         \subsubsection sec6-4-5-7 Section 6.4.5.7: VIOC SETCELLSTATUS: Set
2936 status info for a cell entry 
2937
2938 \par
2939 [Opcode 36] Given a cell name and an image of the cell status bits that should
2940 be set, record the association in the Cache Manager. The input buffer in must
2941 be set up as follows. The first entry is the longword containing the cell
2942 status bits to be set (see the VIOC GETCELLSTATUS description above for valid
2943 flag definitions). The next entry is another longword, ignored by the Cache
2944 Manager. The third and final entry in the input buffer is a null-terminated
2945 string containing the name of the cell for which the status flags are to be
2946 applied. 
2947 \par
2948 Among the possible error returns is ENOENT, reflecting the Cache Manager's
2949 inability to locate its record for the given cell. Only root is allowed to
2950 execute this operation, and an EACCES return indicates the caller was not
2951 effectively root when the call took place. 
2952
2953         \subsection sec6-4-6 Section 6.4.6: Authentication Operations 
2954
2955 \par
2956 The Cache Manager serves as the repository for authentication information for
2957 AFS clients. Each client process belongs to a single Process Authentication
2958 Group (PAG). Each process in a given PAG shares authentication information with
2959 the other members, and thus has the identical rights with respect to AFS Access
2960 Control Lists (ACLs) as all other processes in the PAG. As the Cache Manager
2961 interacts with File Servers as a client process' agent, it automatically and
2962 transparently presents the appropriate authentication information as required
2963 in order to gain the access to which the caller is entitled. Each PAG can host
2964 exactly one token per cell. These tokens are objects that unequivocally codify
2965 the principal's identity, and are encrypted for security. Token operations
2966 between a Cache Manager and File Server are also encrypted, as are the
2967 interchanges between clients and the Authentication Servers that generate these
2968 tokens. 
2969 \par
2970 There are actually two different flavors of tokens, namely clear and secret.
2971 The data structure representing clear tokens is described in Section 6.2.2, and
2972 the secret token appears as an undifferentiated byte stream. 
2973 \par
2974 This section describes the operations involving these tokens, namely getting
2975 and setting the caller's token for a particular cell (VIOCGETTOK, VIOCSETTOK),
2976 checking a caller's access on a specified file system object (VIOCACCESS),
2977 checking the status of caller's tokens associated with the set of File Server
2978 connections maintained on its behalf (VIOCCKCONN), and discarding tokens
2979 entirely (VIOCUNLOG, VIOCUNPAG). These abilities are used by such programs as
2980 login, klog, unlog, and tokens, which must generate, manipulate, and/or destroy
2981 AFS tokens. 
2982
2983         \subsubsection sec6-4-6-1 Section 6.4.6.1: VIOCSETTOK: Set the caller's
2984 token for a cell 
2985
2986 \par
2987 [Opcode 3] Store the caller's secret and clear tokens within the Cache Manager.
2988 The input buffer is used to hold the following quantities, laid out end to end.
2989 The first item placed in the buffer is a longword, specifying the length in
2990 bytes of the secret token, followed by the body of the secret token itself. The
2991 next field is another longword, this time describing the length in bytes of the
2992 struct ClearToken, followed by the structure. These are all required fields.
2993 The caller may optionally include two additional fields, following directly
2994 after the required ones. The first optional field is a longword which is set to
2995 a non-zero value if the cell in which these tokens were generated is to be
2996 marked as the caller's primary cell. The second optional argument is a
2997 null-terminated string specifying the cell in which these tokens apply. If
2998 these two optional arguments do not appear, the Cache Manager will default to
2999 using its home cell and marking the entry as non-primary. The a pathP pathname
3000 parameter is not used, and thus should be set to the null pointer. 
3001 \par
3002 If the caller does not have any tokens registered for the cell, the Cache
3003 Manager will store them. If the caller already has tokens for the cell, the new
3004 values will overwrite their old values. Because these are stored per PAG, the
3005 new tokens will thus determine the access rights of all other processes
3006 belonging to the PAG. 
3007 \par
3008 Among the possible error returns is ESRCH, indicating the named cell is not
3009 recognized, and EIO, if information on the local cell is not available. 
3010
3011         \subsubsection sec6-4-6-2 Section 6.4.6.2: VIOCGETTOK: Get the caller's
3012 token for a cell 
3013
3014 \par
3015 [Opcode 8] Get the specified authentication tokens associated with the caller.
3016 The a pathP parameter is not used, so it should be set to the null pointer.
3017 Should the input parameter in be set to a null pointer, then this call will
3018 place the user's tokens for the machine's home cell in the out output buffer,
3019 if such tokens exist. In this case, the following objects are placed in the
3020 output buffer. First, a longword specifying the number of bytes in the body of
3021 the secret token is delivered, followed immediately by the secret token itself.
3022 Next is a longword indicating the length in bytes of the clear token, followed
3023 by the clear token. The input parameter may also consist of a single longword,
3024 indicating the index of the token desired. Since the Cache Manager is capable
3025 of storing multiple tokens per principal, this allows the caller to iteratively
3026 extract the full set of tokens stored for the PAG. The first valid index value
3027 is zero. The list of tokens is kept compactly, without holes. A return value of
3028 EDOM indicates that the given index does not map to a valid token entry, and
3029 thus may be used as the terminating condition for the iteration. 
3030 \par
3031 Other than EDOM, another possible error return is ENOTCONN, specifying that the
3032 caller does not have any AFS tokens whatsoever. 
3033
3034         \subsubsection sec6-4-6-3 Section 6.4.6.3: VIOCACCESS: Check caller's
3035 access on object 
3036
3037 \par
3038 [Opcode 20] This operation is used to determine whether the caller has specific
3039 access rights on a particular file system object. A single longword is placed
3040 into the input buffer, in, representing the set of rights in question. The
3041 acceptable values for these access rights are listen in Section 6.4.5. The
3042 object to check is named by the a pathP parameter. The output parameters are
3043 not accessed, so out should be set to the null pointer, and out size set to
3044 zero. 
3045 If the call returns successfully, the caller has at least the set of rights
3046 denoted by the bits set in the input buffer. Otherwise, EACCESS is returned. 
3047
3048         \subsubsection sec6-4-6-4 Section 6.4.6.4: VIOCCKCONN: Check status of
3049 caller's tokens/connections 
3050
3051 \par
3052 [Opcode 12] Check whether the suite of File Server connections maintained on
3053 behalf of the caller by the Cache Manager has valid authentication tokens. This
3054 function always returns successfully, communicating the health of said
3055 connections by writing a single longword value to the specified output buffer
3056 in out. If zero is returned to the output buffer, then two things are true.
3057 First, the caller has tokens for at least one cell. Second, all tokens
3058 encountered upon a review of the caller's connections have been properly minted
3059 (i.e., have not been generated fraudulently), and, in addition, have not yet
3060 expired. If these conditions do not currently hold for the caller, then the
3061 output buffer value will be set to EACCES. Neither the a pathP nor input
3062 parameters are used by this call. 
3063
3064         \subsubsection sec6-4-6-5 Section 6.4.6.5: VIOCUNLOG: Discard
3065 authentication information 
3066
3067 \par
3068 [Opcode 9] Discard all authentication information held in trust for the caller.
3069 The Cache Manager sweeps through its user records, destroying all of the
3070 caller's associated token information. This results in reducing the rights of
3071 all processes within the caller's PAG to the level of file system access
3072 granted to the special system:anyuser group. 
3073 \par
3074 This operation always returns successfully. None of the parameters are
3075 referenced, so they should all be set to null pointers and zeroes as
3076 appropriate. 
3077
3078         \subsubsection sec6-4-6-6 Section 6.4.6.6: VIOCUNPAG: Discard
3079 authentication information 
3080
3081 \par
3082 [Opcode 21] This call is essentially identical to the VIOCUNLOG operation, and
3083 is in fact implemented internally by the same code for VIOCUNLOG. 
3084
3085         \subsection sec6-4-7 Section 6.4.7: ACL Operations 
3086
3087 \par
3088 This set of opcodes allows manipulation of AFS Access Control Lists (ACLs).
3089 Callers are allowed to fetch the ACL on a given directory, or to set the ACL on
3090 a directory. In AFS-3, ACLs are only maintained on directories, not on
3091 individual files. Thus, a directory ACL determines the allowable accesses on
3092 all objects within that directory in conjunction with their normal unix mode
3093 (owner) bits. Should the a pathP parameter specify a file instead of a
3094 directory, the ACL operation will be performed on the directory in which the
3095 given file resides. 
3096 \par
3097 These pioctl() opcodes deal only in external formats for ACLs, namely the
3098 actual text stored in an AFS ACL container. This external format is a character
3099 string, composed of a descriptive header followed by some number of individual
3100 principal-rights pairs. AFS ACLs actually specify two sublists, namely the
3101 positive and negative rights lists. The positive list catalogues the set of
3102 rights that certain principals (individual users or groups of users) have,
3103 while the negative list contains the set of rights specifically denied to the
3104 named parties. 
3105 \par
3106 These external ACL representations differ from the internal format generated by
3107 the Cache Manager after a parsing pass. The external format may be easily
3108 generated from the internal format as follows. The header format is expressed
3109 with the following printf() statement: 
3110 \code
3111 printf("%d\n%d\n", NumPositiveEntries, NumNegativeEntries); 
3112 \endcode
3113 \par
3114 The header first specifies the number of entries on the positive rights list,
3115 which appear first in the ACL body. The number of entries on the negative list
3116 is the second item in the header. The negative entries appear after the last
3117 positive entry. 
3118 \par
3119 Each entry in the ACL proper obeys the format imposed by the following printf()
3120 statement: 
3121 \code
3122 printf("%s\t%d\n", UserOrGroupName, RightsMask); 
3123 \endcode
3124 \par
3125 Note that the string name for the user or group is stored in an externalized
3126 ACL entry. The Protection Server stores the mappings between the numerical
3127 identifiers for AFS principals and their character string representations.
3128 There are cases where there is no mapping from the numerical identifier to a
3129 string name. For example, a user or group may have been deleted sometime after
3130 they were added to the ACL and before the Cache Manager externalized the ACL
3131 for storage. In this case, the Cache Manager sets UserOrGroupName to the string
3132 version of the principal's integer identifier. Should the erz principal be
3133 deleted from the Protection Server's database in the above scenario, then the
3134 string '1019' will be stored, since it corresponded to erz's former numerical
3135 identifier. 
3136 \par
3137 The RightsMask parameter to the above call represents the set of rights the
3138 named principal may exercise on the objects covered by the ACL. The following
3139 flags may be OR'ed together to construct the desired access rights placed in
3140 RightsMask: 
3141 \code
3142 #define PRSFS_READ 1 /*Read files*/ 
3143 #define PRSFS_WRITE 2 /*Write & write-lock existing files*/ 
3144 #define PRSFS_INSERT 4 /*Insert & write-lock new files*/ 
3145 #define PRSFS_LOOKUP 8 /*Enumerate files and examine ACL*/ 
3146 #define PRSFS_DELETE 16 /*Remove files*/ 
3147 #define PRSFS_LOCK 32 /*Read-lock files*/ 
3148 #define PRSFS_ADMINISTER 64 /*Set access list of directory*/ 
3149 \endcode
3150
3151         \subsubsection sec6-4-7-1 Section 6.4.7.1: VIOCSETAL: Set the ACL on a
3152 directory 
3153
3154 \par
3155 [Opcode 1] Set the contents of the ACL associated with the file system object
3156 named by a pathP. Should this pathname indicate a file and not a directory, the
3157 Cache Manager will apply this operation to the file's parent directory. The new
3158 ACL contents, expressed in their externalized form, are made available in in,
3159 with in size set to its length in characters, including the trailing null.
3160 There is no output from this call, so out size should be set to zero.
3161 Internally, the Cache Manager will call the RXAFS StoreACL() RPC (see Section
3162 5.1.3.3 to store the new ACL on the proper File Server. 
3163 \par
3164 Possible error codes include EINVAL, indicating that one of three things may be
3165 true: the named path is not in AFS, there are too many entries in the specified
3166 ACL, or a non-existent user or group appears on the ACL. 
3167
3168         \subsubsection sec6-4-7-2 Section 6.4.7.2: VIOCGETAL: Get the ACL for a
3169 directory 
3170
3171 \par
3172 [Opcode 2] Get the contents of the ACL associated with the file system object
3173 named by a pathP. Should this pathname indicate a file and not a directory, the
3174 Cache Manager will apply this operation to the file's parent directory. The ACL
3175 contents, expressed in their externalized form, are delivered into the out
3176 buffer if out size has been set to a value which indicates that there is enough
3177 room for the specified ACL. This ACL string will be null-terminated. There is
3178 no input to this call, so in size should be set to zero. Internally, the Cache
3179 Manager will call the RXAFS FetchACL() RPC (see Section 5.1.3.1) to fetch the
3180 ACL from the proper File Server. 
3181 \par
3182 Possible error codes include EINVAL, indicating that the named path is not in
3183 AFS. 
3184
3185         \subsection sec6-4-8 Section 6.4.8: Cache Operations 
3186
3187 \par
3188 It is possible to inquire about and affect various aspects of the cache
3189 maintained locally by the Cache Manager through the group of pioctl()s
3190 described below. Specifically, one may force certain file system objects to be
3191 removed from the cache (VIOCFLUSH), set the maximum number of blocks usable by
3192 the cache (VIOCSETCACHESIZE), and ask for information about the cache's current
3193 state (VIOCGETCACHEPARAMS). 
3194
3195         \subsubsection sec6-4-8-1 Section 6.4.8.1: VIOCFLUSH: Flush an object
3196 from the cache 
3197
3198 \par
3199 [Opcode 6] Flush the file system object specified by a pathP out of the local
3200 cache. The other parameters are not referenced, so they should be set to the
3201 proper combination of null pointers and zeroes. 
3202 \par
3203 Among the possible error returns is EINVAL, indicating that the value supplied
3204 in the a pathP parameter is not acceptable. 
3205
3206         \subsubsection sec6-4-8-2 Section 6.4.8.2: VIOCSETCACHESIZE: Set
3207 maximum cache size in blocks 
3208
3209 \par
3210 [Opcode 24] Instructs the Cache Manager to set a new maximum size (in 1 Kbyte
3211 blocks) for its local cache. The input buffer located at in contains the new
3212 maximum block count. If zero is supplied for this value, the Cache Manager will
3213 revert its cache limit to its value at startup time. Neither the a pathP nor
3214 output buffer parameters is referenced by this operation. The Cache Manager
3215 recomputes its other cache parameters based on this new value, including the
3216 number of cache files allowed to be dirty at once and the total amount of space
3217 filled with dirty chunks. Should the new setting be smaller than the number of
3218 blocks currently being used, the Cache Manager will throw things out of the
3219 cache until it obeys the new limit. 
3220 \par
3221 The caller is required to be effectively running as root, or this call will
3222 fail, returning EACCES. If the Cache Manager is configured to run with a memory
3223 cache instead of a disk cache, this operation will also fail, returning EROF. 
3224
3225         \subsubsection sec6-4-8-3 Section 6.4.8.3: VIOCGETCACHEPARAMS: Get
3226 current cache parameter values 
3227
3228 \par
3229 [Opcode 40] Fetch the current values being used for the cache parameters. The
3230 output buffer is filled with MAXGCSTATS (16) longwords, describing these
3231 parameters. Only the first two longwords in this array are currently set. The
3232 first contains the value of afs cacheBlocks, or the maximum number of 1 Kbyte
3233 blocks which may be used in the cache (see Section 6.4.8.2 for how this value
3234 may be set). The second longword contains the value of the Cache Manager's
3235 internal afs blocksUsed variable, or the number of these cache blocks currently
3236 in use. All other longwords in the array are set to zero. Neither the a pathP
3237 nor input buffer arguments are referenced by this call. 
3238 \par
3239 This routine always returns successfully. 
3240
3241         \subsection sec6-4-9 Section 6.4.9: Miscellaneous Operations 
3242
3243 \par
3244 There are several other AFS-specific operations accessible via the pioctl()
3245 interface that don't fit cleanly into the above categories. They are described
3246 in this section, and include manipulation of the socket-based Mariner file
3247 trace interface (VIOC AFS MARINER HOST), enabling and disabling of the
3248 file-based AFSLog output interface for debugging (VIOC VENUSLOG), getting and
3249 setting the value of the special @sys pathname component mapping (VIOC AFS
3250 SYSNAME), and turning the NFS-AFS translator service on and off (VIOC
3251 EXPORTAFS). 
3252
3253         \subsubsection sec6-4-9-1 Section 6.4.9.1: VIOC AFS MARINER HOST:
3254 Get/set file transfer monitoring output 
3255
3256 \par
3257 [Opcode 32] This operation is used to get or set the IP address of the host
3258 destined to receive Mariner output. A detailed description of the Cache Manager
3259 Mariner interface may be found in Section 6.7. 
3260 \par
3261 The input buffer located at in is used to pass a single longword containing the
3262 IP address of the machine to receive output regarding file transfers between
3263 the Cache Manager and any File Server. If the chosen host IP address is
3264 0xffffffff, the Cache Manager is prompted to turn off generation of Mariner
3265 output entirely. If the chosen host IP address is zero, then the Cache Manager
3266 will not set the Mariner host, but rather return the current Mariner host as a
3267 single longword written to the out output buffer. Any other value chosen for
3268 the host IP address enables Mariner output (if it was not already enabled) and
3269 causes all further traffic to be directed to the given machine. 
3270 \par
3271 This function always returns successfully. 
3272
3273         \subsubsection sec6-4-9-2 Section 6.4.9.2: VIOC VENUSLOG:
3274 Enable/disable Cache Manager logging 
3275
3276 \par
3277 [Opcode 34] Tell the Cache Manager whether to generate debugging information,
3278 and what kind of debugging output to enable. The input buffer located at in is
3279 used to transmit a single longword to the Cache Manager, expressing the
3280 caller's wishes. Of the four bytes making up the longword, the highest byte
3281 indicates the desired value for the internal afsDebug variable, enabling or
3282 disabling general trace output. The next highest byte indicates the desired
3283 value for the internal netDebug variable, enabling or disabling network-level
3284 debugging traces. The third byte is unused, and the low-order byte represents
3285 an overall on/off value for the functionality. There is a special value for the
3286 low-order byte, 99, which instructs the Cache Manager to return the current
3287 debugging setting as a single longword placed into the output buffer pointed to
3288 by out. The a pathP parameter is not referenced by this routine. 
3289 \par
3290 Trace output is delivered to the AFSLog file, typically located in the
3291 /usr/vice/etc directory. When this form of debugging output is enabled, the
3292 existing AFSLog file is truncated, and its file descriptor is stored for future
3293 use. When this debugging is disabled, a close() is done on the file, forcing
3294 all its data to disk. For additional information on the AFSLog file for
3295 collecting Cache Manager traces, please see the description in Section 6.6.2.1. 
3296 \par
3297 This call will only succeed if the caller is effectively running as root. If
3298 this is not the case, an error code of EACCES is returned. 
3299
3300         \subsubsection sec6-4-9-3 Section 6.4.9.3: VIOC AFS SYSNAME: Get/set
3301 the @sys mapping 
3302
3303 \par
3304 [Opcode 38] Get or set the value of the special @sys pathname component
3305 understood by the Cache Manager. The input buffer pointed to by in is used to
3306 house a longword whose value determines whether the @sys value is being set (1)
3307 or whether the current value is being fetched (0). If it is being set, then a
3308 null-terminated string is expected to follow in the input buffer, specifying
3309 the new value of @sys. Otherwise, if we are asking the Cache Manager for the
3310 current @sys setting, a null-terminated string bearing that value will be
3311 placed in the out output buffer. The a pathP parameter is not used by this
3312 call, and thus should be set to a null pointer. 
3313 \par
3314 There are no special privileges required of the caller to fetch the value of
3315 the current @sys mapping. However, a native caller must be running effectively
3316 as root in order to successfully alter the mapping. An unauthorized attempt to
3317 change the @sys setting will be ignored, and cause this routine to return
3318 EACCES. This requirement is relaxed for VIOC AFS SYSNAME pioctl() calls
3319 emanating from foreign file systems such as NFS and accessing AFS files through
3320 the NFS-AFS translator. Each such remote caller may set its own notion of what
3321 the @sys mapping is without affecting native AFS clients. Since the uid values
3322 received in calls from NFS machines are inherently insecure, it is impossible
3323 to enforce the fact that the caller is truly root on the NFS machine. This,
3324 while any principal running on an NFS machine may change that foreign machine's
3325 perception of @sys, it does not impact native AFS users in any way. 
3326
3327         \subsubsection sec6-4-9-4 Section 6.4.9.4: VIOC EXPORTAFS:
3328 Enable/disable NFS/AFS translation 
3329
3330 \par
3331 [Opcode 39] Enable or disable the ability of an AFS-capable machine to export
3332 AFS access to NFS clients. Actually, this is a general facility allowing
3333 exportation of AFS service to any number of other file systems, but the only
3334 support currently in place is for NFS client machines. A single longword is
3335 expected in the input buffer in. This input longword is partitioned into
3336 individual bytes, organized as follows. The high-order byte communicates the
3337 type of foreign client to receive AFS file services. There are currently two
3338 legal values for this field, namely 0 for the null foreign file system and 1
3339 for NFS. The next byte determines whether the Cache Manager is being asked to
3340 get or set this information. A non-zero value here is interpreted as a command
3341 to set the export information according to what's in the input longword, and a
3342 zero-valued byte in this position instructs the Cache Manager to place a
3343 longword in the output buffer out, which contains the current export settings
3344 for the foreign system type specified in the high-order byte. The third input
3345 byte is not used, and the lowest-order input buffer byte determines whether
3346 export services for the specified system are being enabled or disabled. A
3347 non-zero value will turn on the services, and a zero value will shut them down.
3348 The a pathP pathname parameter is not used by this call, and the routine
3349 generates output only if the export information is being requested instead of
3350 being set. 
3351 \par
3352 The caller must be effectively running as root in order for this operation to
3353 succeed. The call returns EACCES if the caller is not so authorized. If the
3354 caller specifies an illegal foreign system type in the high-order byte of the
3355 input longword, then ENODEV is returned. Again, NFS is the only foreign file
3356 system currently supported. 
3357 \par
3358 Practically speaking, the machine providing NFS-AFS translation services must
3359 enable this service with this pioctl() before any NFS client machines may begin
3360 accessing AFS files. Conversely, if an administrator turns off this export
3361 facility, the export code on the translator machine will immediately stop
3362 responding to traffic from its active NFS clients. 
3363
3364         \section sec6-5 Section 6.5: RPC Interface 
3365
3366         \subsection sec6-5-1 Section 6.5.1: Introduction 
3367
3368 \par
3369 Thi