idnits 2.17.1 draft-mbenjamin-afs-file-locking-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == The page length should not exceed 58 lines per page, but there was 4 longer pages, the longest (page 3) being 152 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 27, 2011) is 4748 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 N/A 3 Internet-Draft 5 Intended status: Informational 7 Expires: November 27, 2011 9 Matt Benjamin 11 Linux Box Corporation 13 April 27, 2011 15 AFS Byte-Range Locking 17 draft-mbenjamin-afs-file-locking-06 19 Status of this Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet 25 Engineering Task Force (IETF), its areas, and its working 26 groups. Note that other groups may also distribute working 27 documents as Internet-Drafts. 29 Internet-Drafts are draft documents valid for a maximum of six 30 months and may be updated, replaced, or obsoleted by other 31 documents at any time. It is inappropriate to use 32 Internet-Drafts as reference material or to cite them other 33 than as "work in progress." 35 The list of current Internet-Drafts can be accessed at 36 http://www.ietf.org/1id-abstracts.html 38 The list of Internet-Draft Shadow Directories can be accessed 39 at http://www.ietf.org/shadow.html 41 Copyright Notice 43 Copyright (c) 2011 IETF Trust and the persons identified as the 44 document authors. All rights reserved. 46 This document is subject to BCP 78 and the IETF Trust's Legal 47 Provisions Relating to IETF Documents 48 (http://trustee.ietf.org/license-info) in effect on the date of 49 publication of this document. Please review these documents 50 carefully, as they describe your rights and restrictions with 51 respect to this document. 53 Abstract 55 The AFS-3 protocol supports file locks, but only on whole 56 files, only in advisory mode. Efficient support for byte-range 57 file locking, together with the stronger semantics with which 58 they are associated, are required to improve the suitability of 59 AFS as a LAN file-sharing protocol for both Unix and Windows 60 clients. Applications on the Windows platform, in particular 61 (e.g., Microsoft Office), actually require byte-range locking 62 to function correctly. Emulation in the client has alleviated 63 most serious problems, albeit, with reduced semantics. We 64 propose protocol enhancements facilitating server-coordinated 65 byte-range locks, atomic lock up/down-grade support, improved 66 semantics for files under byte-range lock control, protocol 67 support for wait-on-lock with fairness, and mandatory lock 68 enforcement for clients on request. The delegation proposal, 69 included within this document in previous drafts, has been 70 split out into a separate proposal, based on feedback from 71 reviewers. 73 Table of Contents 75 Status of this Memo 76 Copyright Notice 77 Abstract 78 1 Introduction 79 2 Conventions Used in this Document 80 3 Byte-Range Locking Interfaces 81 3.1 Dependencies 82 3.2 Backward Compatibility 83 3.3 Concepts 84 3.3.1 General 85 3.3.2 Lock Management 86 3.3.3 Share Reservations 87 3.3.4 POSIX Conventions 88 3.3.5 Deferred Locks 89 3.3.6 Server Restarts 90 3.4 Constants 91 3.4.1 Lock Type 92 3.4.2 Lock Flags 93 AFSLock_Flag_Mand 94 AFS_Lock_Flag_Wait 95 AFSLock_Flag_TestLock 96 AFS_Lock_Flag_EReturn 97 3.4.3 Lock Flags for Share Reservation 98 AFSLock_Flag_Share_Read 99 AFSLock_Flag_Share_Write 100 AFSLock_Flag_Share_Exclusive 101 3.4.4 Lock Status 102 AFSLock_Flag_Extend 103 AFSLock_Flag_Discard 104 3.4.5 Extended Callback Constants 105 3.4.6 Extended Callback Extra Flags 106 AFSCB_Lock_Flag_All 107 AFSCB_Cancel_ExtendLocks 108 AFSCB_Cancel_RevokeLocks 109 AFSCB_Flag_ExtendLocks 110 AFSCB_Flag_RevokeLocks 111 3.5 Data Types 112 3.5.1 AFSByteRangeLock 113 Fid 114 Type 115 Owner 116 Uniq 117 Offset 118 Length 119 Expiration 120 Txid 121 Token 122 3.5.2 AFSByteRangeLockSeq 123 3.5.3 AFSByteRangeLockPointer 124 3.5.4 AFSByteRangeLockPointerSeq 125 3.5.5 AFSLockHostIdentifierSeq 126 3.5.6 AFSCB_NotificationData Redefinition 127 AFSCB_Data_Flock 128 3.6 Procedures 129 3.6.1 SetByteRangeLock 130 Notes 131 Async Lock Issue vs Polling 132 POSIX Semantics 133 Share Reservations 134 Error Codes 135 EACCES 136 EAGAIN (EWOULDBLOCK) 137 EDEADLK 138 EINVAL 139 ENAVAIL 140 ENOLCK 141 3.6.2 ReleaseByteRangeLock 142 Notes 143 POSIX Semantics 144 Error Codes 145 EINVAL 146 3.6.3 UpgradeByteRangeLock 147 Error Codes 148 EINVAL 149 EWOULBLOCK 150 EDEADLK 151 3.6.4 DowngradeByteRangeLock 152 Notes 153 Error Codes 154 EINVAL 155 3.6.5 AssertExtendLocks 156 3.6.6 GetByteRangeLockStatus 157 Error Codes 158 EACCES 159 3.6.7 CancelByteRangeLock 160 3.6.8 CreateFileLocked 161 Error Codes 162 3.7 Windows File Locking Semantics 163 3.7.1 Byte-Range Locking vs. Byte-Range Lock Emulation 164 3.7.2 Atomic Lock Open 165 3.8 Lock Enforcement 166 3.8.1 Governing Ideas 167 3.8.2 Enforcement Rules 168 3.8.3 Implementation Note 169 4 Security Considerations 170 5 IANA Considerations 171 6 Appendix A: XDR Grammar (afsint.xg) 172 7 Appendix A: XDR Grammar (afscbint.xg) 173 Author's Address 175 1 Introduction 177 While AFS-3 does support file locking, it permits locking of 178 whole-files only, and provides this support inefficiently. AFS 179 clients can take locks on any file object, with the granularity 180 of an entire file, using the RXAFS_SetLock procedure, and 181 release them with the RXAFS_ReleaseLock procedure. AFS uses a 182 poll-based locking model. AFS file locks, once issued, are 183 considered to persist only for 5 minutes, unless extended by 184 the requesting client using the RXAFS_ExtendLock procedure. The 185 OpenAFS file server implementaion, based on the original 186 Transarc AFS file server, tracks locks directly in its on-disk 187 volume structures. The disk package tracks lock type (LockRead 188 or LockWrite), numbers of clients holding locks, and a 189 timestamp. Lock ownership, which in many cases may be reliably 190 inferred, is not recorded. Hence, a broken or malicious client 191 might release locks it never set (i.e., locks set by other 192 clients). The AFS protocol also does not permit atomic lock 193 upgrades (or downgrades). 195 2 Conventions Used in this Document 197 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 198 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and 199 "OPTIONAL" in this document are to be interpreted as described 200 in RFC 2119. 202 3 Byte-Range Locking Interfaces 204 3.1 Dependencies 206 The byte-range lock feature depends on support for extended 207 callback notifications and extended host tracking support in 208 client and server. 210 3.2 Backward Compatibility 212 AFS clients and servers will indicate their support for 213 byte-range locking through new client and file server 214 capability flags: 216 const CLIENT_CAPABILITY_BYTE_RANGE_LOCK = 0x0008; 218 const VICED_CAPABILITY_BYTE_RANGE_LOCK = 0x0010; 220 Additionally, a client capability flag is provided to indicate 221 when a client is prepared to accept async lock issue 222 notifications, as a substitute for polling: 224 const VICED_CAPABILITY_ASYNC_LOCK_ISSUE = 0x0020; 226 3.3 Concepts 228 3.3.1 General 230 An AFS file server is responsible to coordinate byte-range 231 locking requests and, optionally, enforce mandatory locking 232 semantics relative to file operations, initiated at different 233 clients. By contrast with the traditional AFS file locking 234 protocol, the proposed byte-range locking protocol makes an 235 attempt to associate locks with a unique subject, specifically, 236 a ViceID and unique identifier which could correspond to a 237 unique session or process executing on the client machine. 239 Clients (cache-manager processes not co-located in memory) 240 request and release byte-range locks through a pair of 241 interfaces (RequestByteRangeLock, ReleaseByteRangeLock) similar 242 to those provided by the traditional AFS locking 243 implementation. Two base lock types (read and write, in general 244 regarded as "shared" or "exclusive") locks, plus a new share 245 reservation lock type, are defined. Additional arguments and 246 flags are provided to permit selection of desired lock ranges, 247 intention to "wait" on the lock (i.e., willing to accept a 248 deferred issue of the lock at such time as the file server can 249 grant the lock, if it cannot be granted immediately), and 250 desired special semantics--currently, the client may request 251 mandatory enforcement. Clients already holding a read or write 252 lock on a range may atomically upgrade or downgrade the lock to 253 the orthogonal type, i.e., they need not release a lock of one 254 type before requesting the other type, avoiding the race 255 condition present in the traditional AFS locking protocol. 256 Byte-range locks are permanently associated with an owner, the 257 client which requested the lock. A lock may not be released by 258 a client which never owned it. 260 A file server may revoke locks granted to any client, for any 261 reason. The file server may also request clients to re-assert 262 their interest in outstanding locks, at any time--in 263 particular, if a client holding locks has not been heard from 264 for a long period (e.g., 10 minutes). Provision is made for 265 re-establishment of state after server restarts or other 266 service interruptions. 268 Administrative users may under various circumstances have need 269 to identify the owner and state of locks on a locked file, and 270 to revoke file locks administratively. This proposal includes 271 RPCs allowing administrative users to perform these operations, 272 and suggests exposure through new AFS pioctls and the fs 273 command. 275 3.3.2 Lock Management 277 Lock management in the proposed interface is completely 278 redefined relative to the file locking in AFS-3. Concepts are 279 borrowed from AFS cache management, including the callback 280 concept. A byte-range lock may be regarded as a special-purpose 281 callback. A file server may use the ExtendedCallBack interface 282 to request re-assertion of existing locks or revoke (cancel) 283 locks completely. These indications re-use the existing 284 AFSCB_Event_Cancel extended callback notification, adding new 285 cancellation types defined below. 287 3.3.3 Share Reservations 289 To support platforms in which use mandatory locking and other 290 enhanced sharing semantics, in particular, to support Microsoft 291 Windows sharing semantics, a new share reservation mechanism is 292 proposed. AFS-3 share reservations serve a purpose similar to 293 the correspondingly named facility in NFSv4. Share reservations 294 provide a means by which clients can reserve, in advance of any 295 I/O or ordinary locking operations, a specific set of sharing 296 semantics. For example, a client would use a share reservation 297 to request mandatory enforcement semantics, or to request a 298 specific share mode. AFS-3 share reservations are locks 299 acquired and released by clients using the SetByteRangeLock and 300 ReleaseByteRangeLock procedures defined in this document, with 301 special meaning. A share reservation may be taken only at 302 whole-file granularity. 304 3.3.4 POSIX Conventions 306 In addition to having (as presently standardized) advisory 307 semantics, the application interfaces for file locking on 308 Unix-like platforms are not entirely uniform (cf. fcntl, flock, 309 lockf) and not uniformly compatible with those on Windows 310 operating systems. In particular, a POSIX file locking 311 implementation may consolidate adjacent lock ranges taken in 312 different lock requests. In addition, POSIX permits unlocking 313 of potentially non-overlapping locked ranges (including locks 314 of different types) in a range in a single operation and 315 permits splitting of a locked range by unlocking an intervening 316 range. A POSIX client may request a lock spanning any future 317 end-of-file by setting a lock length of 0. None of these 318 behaviors is permitted using Windows file locking interfaces. 319 Consolidation of adjacent locked ranges, in particular, would 320 be unexpected and incorrect behavior for a Windows file locking 321 client. ("Two adjacent regions of a file cannot be locked 322 separately and then unlocked using a single region that spans 323 both locked regions.") The listed behaviors are not visible to 324 other (possibly non-Unix) clients independently operating on 325 the same file, however, and each is bounded by the scope of a 326 specific operation (e.g., SetByteRangeLock or 327 ReleaseByteRangeLock). Hence a per-call flag is sufficient to 328 allow a cache manager to select appropriate semantics for its 329 platform. The present document attempts to provide a uniform 330 interface for a superset of POSIX file locking facilities. For 331 each operation where a choice of operational semantics is 332 available, the client may specify POSIX semantics, defined as 333 supporting the above-listed behaviors for both shared and 334 exclusive locks, using the AFSLock_Flag_Posix flag. The 335 unmarked semantics are those of the corresponding Windows file 336 locking operation. 338 3.3.5 Deferred Locks 340 Where possible, locks are granted immediately with the 341 completion of the SetByteRangeLock request. A file server MAY, 342 on explicit request and subject to client capability, agree to 343 prospectively issue a lock to an interested client at a future 344 time, when the requested lock becomes available. Such deferred 345 locks constitute a promise to issue the lock with best-effort 346 consideration of fairness. A new extended callback notification 347 (AFSCB_Event_Flock) is provided to effect asynchronous issue of 348 a deferred lock to a waiting client, for clients configured to 349 accept it. Clients not configured for async issue processing 350 must alternatively poll for desired locks. Deferred locks may 351 themselves be canceled. 353 3.3.6 Server Restarts 355 When a byte-range locking capable client receives one of the 356 InitCallBackState RPCs from a byte-range locking capable file 357 server, it must assume that any byte-range locks it held prior 358 to receipt must be re-asserted or bulk-released at the file 359 server, using the server's AssertExtendLocks RPC. A conformant 360 file server may, but need not, be prepared to validate locks 361 previously issued to clients, across server restarts. In future 362 revisions, the Token attribute of AFSByteRangeLock may allow 363 file servers to reliably recognize locks they issued in these 364 circumstances, using cryptographic or other mechanisms. 366 3.4 Constants 368 3.4.1 Lock Type 370 AFS-3 defines the following lock types: 372 %#define LockRead 0 374 %#define LockWrite 1 376 %#define LockExtend 2 378 %#define LockRelease 3 380 The current draft adds the following new lock type: 382 const LockShareReservation = 4; 384 3.4.2 Lock Flags 386 The following flag constants are defined for use in the Flags 387 member of the AFSByteRangeLock structure and equivalently in 388 the Flags argument of the SetByteRangeLock procedure, with the 389 same semantics: 391 const AFSLock_Flag_Mand = 0x0001; /* Request mandatory 392 enforcement */ 394 const AFSLock_Flag_Wait = 0x0002; /* Request async wait on 395 lock */ 397 const AFSLock_Flag_Posix = 0x0004; /* Request posix semantics 398 */ 400 const AFSLock_Flag_TestLock = 0x0100; /* test for conflicts 401 only */ 403 const AFSLock_Flag_EReturn = 0x1000; /* error return flag */ 405 AFSLock_Flag_Mand 407 Requests mandatory enforcement when sent with a 408 SetByteRangeLock request or in a deferred AFSByteRangeLock 409 instance. Asserts mandatory enforcement in an AFSByteRangeLock 410 instance. 412 AFS_Lock_Flag_Wait 414 Requests deferred lock if immediate lock cannot be granted when 415 sent with a SetByteRangeLock request. Indicates deferred lock 416 in an AFSByteRangeLock instance. The SetByteRangeLock procedure 417 may return locks in this state, subject to client capability 418 and if so requested in the Flags argument. 420 AFSLock_Flag_TestLock 422 Requests that the current lock request be evalutated only for 423 conflict information. 425 AFS_Lock_Flag_EReturn 427 When set on return from a lock request, coincides with an error 428 return and non-zero members in Lock describe a conflicting lock 429 which was in effect at the time of the request and obstructed 430 it. 432 3.4.3 Lock Flags for Share Reservation 434 The following flag constants are defined for use in the Flags 435 member of the AFSByteRangeLock structure and equivalently in 436 the Flags argument of the SetByteRangeLock procedure, and 437 specifcally, identify share reservations: 439 const AFSLock_Flag_Share_Read = 0x0008; /* Allow Share 440 mode READ (Share Reservation) */ 441 const AFSLock_Flag_Share_Write = 0x0010; /* Allow Share 442 mode WRITE (Share Reservation) */ 444 const AFSLock_Flag_Share_Exclusive = 0x0020; /* Assert 445 EXCLUSIVE sharing (Share Reservation) */ 447 AFSLock_Flag_Share_Read 449 Share reservation. Allow future clients to open this file for 450 reading. Opens for writing mode and requests for write locks 451 will fail unless the AFSLock_Flag_Share_Write flag is set. 453 AFSLock_Flag_Share_Write 455 Share reservation. Allow future clients to open this file for 456 writing. Opens for reading mode and requests for read locks 457 will fail unless the AFSLock_Flag_Share_Read flag is set. 459 AFSLock_Flag_Share_Exclusive 461 Share Reservation. Requests exclusive access to the file by the 462 requesting process at the requesting client. 464 3.4.4 Lock Status 466 The following flag constants are provided to coordinate 467 advanced lock-management operations: 469 const AFSLock_Flag_Extend = 4; /* request extension, or server 470 ack extended */ 472 const AFSLock_Flag_Discard = 8; /* discard lock, or server ack 473 discarded */ 475 AFSLock_Flag_Extend 477 Sent with AssertExtendLocks indicates request to assert/extend 478 the corresponding lock. Returned from AssertExtendLocks in 479 OutStatus array, indicates lock confirmation. 481 AFSLock_Flag_Discard 483 Sent with AssertExtendLocks indicates intention to discard the 484 corresponding lock. Returned from AssertExtendLocks in 485 OutStatus array, acknowleges lock discard. 487 3.4.5 Extended Callback Constants 489 The following extended callback cancellation types and flags 490 are provided, to facilitate lock management through the 491 ExtendedCallback interface: 493 const AFSCB_Cancel_ExtendLocks = 7; /* re-assert locks, or lose 494 them */ 496 const AFSCB_Cancel_RevokeLocks = 8; /* locks on Fid revoked */ 498 These cancellation types are intended to be sent with 499 notifications of the existing AFSCB_Event_Cancel type. 501 3.4.6 Extended Callback Extra Flags 503 AFSCB_Lock_Flag_All 505 Sent as the value of ExtraFlags when the notification type is 506 AFSCB_Cancel_ExtendLocks or AFSCB_Cancel_RevokeLocks, the 507 notification shall apply to all eligible objects, in which a 0 508 value has also been set for one or more of Volume, Fid, Uniq in 509 the corresponding callback, with the following intepretation: 511 - If Volume is non-zero, and is published from the sending file 512 server, while Fid and Uniq are 0, then all outstanding locks 513 on files in the volume are requested to be re-asserted or 514 revoked, depending on the value of the corresponding 515 notification 517 - If the notification type is AFSCB_Cancel_ExtendLocks, all 518 corresponding locks are requested to be extended 520 - If the notification type is AFSCB_Cancel_RevokeLocks, all 521 corresponding locks are revoked 523 - If all of Volume, Fid, and Uniq are 0, then all outstanding 524 locks on files published from this server are requested to be 525 re-asserted or revoked, depending on the value of the 526 corresponding notification 528 - If the notification type is AFSCB_Cancel_ExtendLocks, all 529 corresponding locks are requested to be extended 531 - If the notification type is AFSCB_Cancel_RevokeLocks, all 532 corresponding locks are revoked 534 AFSCB_Cancel_ExtendLocks 536 When sent as the reason for cancellation in an ExtendedCallback 537 notification, indicates the server requires re-assertion of all 538 locks on FID using the file server's AssertExtendLocks 539 procedure. The client MUST execute the procedure for all locks 540 it asserts on FID prior to the Expiration in the callback, else 541 it MUST consider any locks it held on FID to be canceled. 543 AFSCB_Cancel_RevokeLocks 545 When sent as the reason for cancellation in an ExtendedCallback 546 notification, indicates administrative cancellation of all 547 locks on FID. 549 const AFSCB_Flag_AssertLocks = 4; /* request ExtendLock */ 551 const AFSCB_Flag_RevokeLocks = 8; /* locks cancelled */ 553 AFSCB_Flag_ExtendLocks 555 Has the same meaning and effect as AFSCB_Cancel_ExtendLocks, 556 but may be sent with an arbitrary extended callback message. 558 AFSCB_Flag_RevokeLocks 560 Has the same meaning and effect as AFSCB_Cancel_RevokeLocks, 561 but may be sent with an arbitrary extended callback message. 563 3.5 Data Types 565 3.5.1 AFSByteRangeLock 567 The AFSByteRangeLock data type represents a byte-range lock 568 issued by an AFS file server: 570 struct AFSByteRangeLock { 572 AFSFid Fid; 574 afs_uint32 Type; 576 afs_uint32 Owner; 578 afs_uint64 Uniq; 580 afs_uint32 Flags; 582 afs_uint64 Offset; 584 afs_uint64 Length; 586 afs_uint64 Expiration; 588 AFSOpaque Txid; 590 AFSOpaque Token; 591 }; 593 Fid 595 The Fid on which the lock is held. 597 Type 599 The type of lock requested, LockRead or LockWrite. A byte-range 600 read lock is a non-exclusive read assertion on the stated 601 range, which may be shared by any number of readers and no 602 writers. A byte-range lock is an exclusive write assertion on 603 the stated range. 605 Owner 607 The ViceID in use by the client requesting the lock. 609 Uniq 611 Value uniquely identifying a session or process context at the 612 client. The representation of Uniq is intended to be able to 613 uniquely represent the most relevant process or thread context 614 on modern platforms. 616 Offset 618 The distance in bytes from beginning-of-file to the start of 619 the locked range. 621 Length 623 Length in bytes of the locked range. 625 Expiration 627 AFSByteRangeLock instances may be regarded as a special-purpose 628 callback. Instances persist until canceled, or until Expiration 629 is reached. 631 Txid 633 An arbitrary counted bytestring originating at the client with 634 the original request granting a lock. Defined for this revision 635 of the specification to have a maximum length of 0. 637 Token 639 An arbitrary counted bytestring originating at the server when 640 the lock is issued. Defined for this revision of the 641 specification to have a maximum length of 0. In future 642 revisions it may be used to store an "irrefutable" 643 cryptographic object which may be used to re-assert locks after 644 server restart, or similar scenarios. 646 3.5.2 AFSByteRangeLockSeq 648 A variable-length array of type AFSByteRangeLock used for bulk 649 calls for asserting and locks. 651 const AFSFLOCKMAX = 512; 653 typedef AFSByteRangeLock AFSByteRangeLockSeq; 655 3.5.3 AFSByteRangeLockPointer 657 A convenience typedef for a pointer to an AFSByteRangeLock 658 object. 660 3.5.4 AFSByteRangeLockPointerSeq 662 An array of pointers to objects of type AFSByteRangeLock, used 663 by AssertExtendLocks to return locks with updated expiration 664 time. 666 typedef AFSByteRangeLockPointer 667 AFSByteRangeLockPointerSeq; 669 3.5.5 AFSLockHostIdentifierSeq 671 typedef HostIdentifier AFSLockHostIdentifierSeq; 673 An array of HostIdentifier structures used by the 674 GetByteRangeLockStatus procedure to report client machines 675 holding locks. 677 3.5.6 AFSCB_NotificationData Redefinition 679 The AFSCB_NotificationData union defined in the Callback 680 Extended Information draft is redefined (upward compatibly), as 681 the following: 683 const AFSCB_Event_Flock = 14; 685 ext-union AFSCB_NotificationData switch (afs_uint32 Event_Type) 686 { 688 ... 690 case AFSCB_Event_Flock: 692 AFSCB_Data_Flock u_xlock; 694 }; 696 AFSCB_Data_Flock 698 A struct AFSCB_Data_Flock is defined to be the type of 699 AFSCB_NotificationData at AFSCB_Event_Flock. The structure is 700 equivalent to an AFSByteRangeLock except it omits Fid. 702 struct AFSCB_Data_Flock { 704 afs_uint32 Type; 706 afs_uint32 Owner; 708 afs_uint64 Uniq; 710 afs_uint32 Flags; 712 afs_uint64 Offset; 714 afs_uint64 Length; 716 afs_uint64 Expiration; 718 AFSOpaque Txid; 720 AFSOpaque Token; 722 }; 724 3.6 Procedures 726 3.6.1 SetByteRangeLock 728 Requests a lock of type Lock.Type on Fid, on the range 729 [Lock.Offset, Lock.Offset+Lock.Length). Lock.Type must be one 730 of LockRead or LockWrite. Lock.Owner shall be set to the ViceID 731 corresponding to the requesting process or equivalent, or to 0 732 if this is not known. Lock.Uniq shall be set to a value 733 uniquely identifying the requesting process or equivalent. On 734 Unix-like systems, Lock.Uniq could be set to the PID of the 735 requesting process. Lock.Txid shall be a counted bytestring 736 corresponding to the AFSByteRangeLock attribute of the same 737 name. Lock.Txid is defined at this revision to have length 0. 739 proc SetByteRangeLock( 741 IN AFSFid *Fid, 743 INOUT AFSByteRangeLock *Lock 745 ) = 65601; 747 Notes 749 On successful return the file server has granted the requested 750 lock, and Lock points to the server's asserted AFSByteRangeLock 751 structure. If the client has requested and the server agrees to 752 issue a deferred lock, Lock points to the server's asserted 753 deferred AFSByteRangeLock structure. The client may safely 754 determine if it has been granted a deferred lock by inspecting 755 the value of Lock->Flags. 757 The returned Lock structure MAY differ from request with 758 respect to Flags. The returned Lock structure MUST NOT differ 759 from the request with respect to range, unless 760 AFSLock_Flag_EReturn is to be returned (below), or unless POSIX 761 semantics are in effect. 763 If a SetByteRange lock request would fail due to conflict, or 764 if AFSLock_Flag_Test is set in the request and the request 765 would have failed due to conflict, the server MAY provide 766 conflict information. To do so, the server returns EAGAIN, 767 setting flag AFSLock_Flag_EReturn. Non-zero members in the 768 returned Lock, less Expiration, describe a conflicting lock 769 which was in effect at the time of the request and obstructed 770 it. The returned value for Lock->Expiration indicates the 771 earliest time the client should resend the lock request (see 772 polling, below). 774 The value of the Flags argument may alter the semantics and/or 775 processing of the call: 777 - if (Flags & AFSLock_Flag_Mand), file server is requested to 778 provide mandatory locking semantics as defined below--if the 779 file server is willing to provide mandatory enforcement, it 780 MAY set the corresponding flag in Lock, and if so MUST 781 restrict writes on the asserted range to the holding client 782 for the duration of the lock. It is expected that clients 783 will request mandatory enforcement in a share reservation 784 request. 786 - if (Flags & AFSLock_Flag_Wait), file server is requested to 787 issue a deferred lock if the requested lock may not be 788 immediately granted--the file server MAY grant a deferred 789 lock in response to this request, indicating its agreement by 790 setting the corresponding flag in Lock. Lock is in this 791 instance an indicator only of the deferred lock promise 792 - if (Flags & AFSLock_Flag_Posix), POSIX lock semantics for 793 byte range locks will be observed for the current request 795 Async Lock Issue vs Polling 797 A file server MUST be prepared to support clients unable to use 798 the async lock issue mechanism. That is, it publishes the 799 VICED_CAPABILITY_BYTE_RANGE_LOCK capabilty, but not 800 VICED_CAPABILITY_ASYNC_LOCK_ISSUE. This situation may arise 801 when a client is operating in an unsecured environment and also 802 lacks a secured callback channel. 804 A file server MUST distingush clients not eligible for async 805 issue, and for these clients: 807 1. send the AFSCB_Event_ReleaseLock extended call back 808 notification to such clients when the client would be 809 eligible to acquire a lock it has previously requested, under 810 specific conditions 812 2. notify clients selectively in the presence of contention, so 813 as to achieve a best-effort degree of fairness 815 3. in consideration of read/write semantics, notify potentially 816 multiple clients with compatible shared lock requests 818 To improve the efficiency of polling, clients are provided with 819 a lock expiration hinting mechanism, as follows: 821 1. when a client SetByteRangeLock (UpgradeByteRangeLock) cannot 822 be granted, the value for Expiration in the returned Lock 823 object indicates 825 (a) the expiration time of the corresponding deferred lock 827 i. if the client had sent AFSLock_Flag_Wait, and a deferred 828 lock was successfully issued by the server, and the 829 client has published the capability to accept 830 AFSCB_Event_Flock (async lock issue) notifications 832 (b) the minimum interval which the client MUST delay polling 833 for the requested lock, 835 i. if the client as not published the capability to accept 836 AFSCB_Event_Flock (async lock issue) notifications 838 2. if a client is unable to to accept async lock issue 839 notifications but expresses willingness to wait for a 840 SetByteRangeLock (UpgradeByteRangeLock) to complete, the 841 server MUST 842 (a) send an AFSCB_Event_ReleaseLock notification when it 843 believes the client would be eligible to receive the lock 844 if such a condition arises prior to the Expiration it sent 845 with the corresponding lock request, or 847 (b) send an AFSCB_Event_Cancel notification for the 848 corresponding Fid, to inform the client that its pending 849 notification is cancelled 851 POSIX Semantics 853 The following behaviors are specified only when POSIX file lock 854 semantics are in effect: 856 - If a process has existing locks on a file F and requests a 857 new lock in a range overlapping existing locks and the type 858 of each existing lock is LockRead or LockWrite, the type of 859 the existing lock(s) shall be replaced by the new lock type 861 - If a process requests a lock adjacent to an existing lock of 862 the same type it already holds, the locks SHOULD be 863 consolidated into a single lock, this will be indicated in 864 the returned structure 866 - If a process requests a lock with a length of 0, the lock, if 867 granted, extends through any future end-of-file 869 Share Reservations 871 A share reservation is a file lock which is logically and 872 operationally distinct from traditional read and write locks, 873 but interact with lock requests of these types according to the 874 following rules, (as noted, share reservations are only issued 875 at whole-file granularity): 877 - if a client holds an exclusive share reservation on a file F, 878 the following assertions hold for the duration of the 879 reservation: 881 - no other client, nor the same client, may be granted a 882 share reservation of any type on F 884 - no other client may be granted a byte-range or whole-file 885 lock of any type on F 887 - the same client may be granted byte-range or whole-file 888 locks on F, according to ordinary rules 890 - if a client holds a read share reservation (but no write 891 share reservation) on a file F, we assert: 893 - other clients may be granted a read share reservation on F 895 - other clients may be granted byte-range or whole-file read 896 locks on F, according to ordinary rules 898 - no other client may be granted a byte-range or whole-file 899 write lock on F 901 - no other client may be granted an exclusive share 902 reservation on F 904 - no other client may be granted a write share reservation on 905 F 907 * the same client may be granted such a reservation, 908 provided its read share reservation is the only existing 909 on F 911 - if a client holds a write share reservation (but no read 912 share reservation) on a file F, we assert: 914 - other clients may be granted a write share reservation on F 916 - other clients may be granted byte-range or whole-file write 917 locks on F, according to ordinary rules 919 - no other client may be granted a byte-range or whole-file 920 read lock on F 922 - no other client may be granted a read share reservation on 923 F (but the same client may be granted such a reservation) 925 - no other client may be granted an exclusive share 926 reservation on F 928 - if a client holds a read and write (AFSLock_Share_Read | 929 AFSLock_Share_Write) share reservation on a file F, we assert 931 - other clients may be granted read or write or (read | 932 write) share reservations on F 934 - other clients may be granted read or write locks on F, 935 according to ordinary rules 937 - no other client may be granted an exclusive share 938 reservation on F 940 - a client which holds a read or write byte-range or whole-file 941 lock on F but holds no share reservation on F, may be 942 following POSIX semantics (although such a client could also 943 have requested a read and write share reservation) 944 - in such a case, no other client may be granted a share 945 reservation of any type on F 947 In addition, the AFSLock_Share_Mand flag may be included in a 948 share reservation to request mandatory enforcement of 949 byte-range locks, as described in this document. Clients which 950 prefer mandatory enforcement are expected to take a 951 corresponding share reservation to assert this preference 952 whenever appropriate. It is believed that the above rules 953 permit a correct client implementation to achieve Windows file 954 sharing semantics, by taking/releasing appropriate share 955 reservations when files are opened/closed by applications at 956 the client. As noted, the share reservation may be used by any 957 client implementation. 959 Error Codes 961 EACCES 963 The caller does not have the necessary rights. 965 EAGAIN (EWOULDBLOCK) 967 The server is unable to grant the request due to conflicting 968 locks. If a deferred lock was requested, a Flags value of 969 AFSLock_Flag_Wait indicates the deferred lock is granted. 971 EDEADLK 973 The server declines to grant the requested lock (or deferred 974 lock) because granting it would cause a deadlock. 976 EINVAL 978 An illegal lock type was specified. 980 ENAVAIL 982 The server unable to grant the request due to a conflicting 983 share reservation. If a deferred lock was requested, a Flags 984 value of AFSLock_Flag_Wait indicates a deferred lock is 985 granted. 987 ENOLCK 989 The server has insufficient resources to grant the lock, or the 990 requesting client or file has too many locks outstanding. (No 991 specific limits are mandated or suggested by this document.) 992 3.6.2 ReleaseByteRangeLock 994 Releases the byte-range lock represented in Lock. 996 proc ReleaseByteRangeLock( 998 IN AFSByteRangeLock *Lock 1000 ) = 65602; 1002 Notes 1004 When an AFS client intends to release a byte-range write lock, 1005 it MUST ensure that any changed data in the effected range has 1006 been sent to the file server with the appropriate StoreData 1007 RPC, and that the RPC completed successfully. This requirement 1008 is based on an implied assertion that holding a lock on some 1009 region of a file implies, invariantly, an up-to-date view on 1010 the locked region. 1012 The value of the Flags argument may alter the semantics and/or 1013 processing of the call: 1015 - if (Flags & AFSLock_Flag_Posix), POSIX lock semantics for 1016 byte range locks will be observed for the current request 1018 POSIX Semantics 1020 The following behaviors are specified only when POSIX file lock 1021 semantics are in effect: 1023 - an arbitrary number of previously-locked ranges, of type 1024 LockRead or LockWrite, may be released with a single 1025 ReleaseByteRangeLock request 1027 - if Lock.Length is 0, the released range extends to the 1028 current end-of-file 1030 By contrast, when default file locking semantics are in effect, 1031 the range is asserted to be held by the calling client with the 1032 supplied lock type. 1034 Error Codes 1036 EINVAL 1038 The caller does not own the corresponding lock. 1040 3.6.3 UpgradeByteRangeLock 1041 Upgrades the byte-range lock represented in Lock, asserted to 1042 be held by the calling client, from its current type (which 1043 should be LockRead) to LockWrite. The upgrade is executed 1044 atomically (no opportunity exists for another client to set a 1045 conflicting lock in the upgraded range while the upgrade is 1046 being executed). 1048 On unsuccessful return the file server MAY set flag 1049 AFSLock_Flag_EReturn. In this case, non-zero members in Lock 1050 describe a conflicting lock which was in effect at the time of 1051 the request and obstructed it. 1053 proc UpgradeByteRangeLock( 1055 IN AFSByteRangeLock *Lock, 1057 afs_uint32 Type 1059 ) = 65603; 1061 Error Codes 1063 EINVAL 1065 The caller does not own the corresponding lock or it is not of 1066 the correct type. 1068 EWOULBLOCK 1070 The lock could not be granted due to conflicting locks. 1072 EDEADLK 1074 The lock could not be granted because granting it would cause 1075 deadlock. 1077 3.6.4 DowngradeByteRangeLock 1079 Downgrades the byte-range lock represented in Lock, asserted to 1080 be held by the calling client, from its current type (which 1081 should be LockWrite) to LockRead. The downgrade is executed 1082 atomically (no opportunity exists for another client to set a 1083 conflicting lock in the downgraded range while the downgrade is 1084 being executed). 1086 proc DowngradeByteRangeLock( 1088 IN AFSByteRangeLock *Lock, 1089 afs_uint32 Type 1091 ) = 65604; 1093 Notes 1095 When an AFS client intends to downgrade a byte-range write 1096 lock, it MUST ensure that any changed data in the effected 1097 range has been sent to the file server with the appropriate 1098 StoreData RPC, and that the RPC completed successfully. This 1099 requirement is based on an implied assertion that holding a 1100 lock on some region of a file implies, invariantly, an 1101 up-to-date view on the locked region. 1103 Error Codes 1105 EINVAL 1107 The caller does not own the corresponding lock or it is not of 1108 the correct type. 1110 3.6.5 AssertExtendLocks 1112 A file server may, at any time, request a client to re-assert 1113 its interest in oustanding locks, or revoke those locks 1114 altogether. It is expected that clients not heard from for a 1115 long period (e.g., 10 minutes) would be requested to re-assert 1116 any outstanding locks they hold. To request re-assertion of 1117 outstanding locks, the file server may send the client an 1118 extended callback notification on the corresponding Fids of 1119 type AFSCB_Cancel_ExtendLocks, or it may set the flag 1120 AFSCB_Flag_ExtendLocks on a notification of another type it was 1121 already intending to send. 1123 On receipt of an AFSCB_Cancel_ExtendLocks or 1124 AFSCB_Flag_ExtendLocks notification through the extended 1125 callback interface, a client MUST either: 1127 - return any locks it asserts in AssertedLocks_Array, the type 1128 of union AFSCB_ResultData for these calls 1130 - if the server rejects any locks asserted by the client, it 1131 will so notify client in a subsequent cancellation message 1133 - set a result of AFSCB_Result_ResponseDeferred, and execute 1134 the AssertExtendLocks bulk call before the Expiration in the 1135 AFSExtendedCallback structure sent with the callback 1137 Fid is the file for which locks are being extended. Flags 1138 contains indication of special semantics (e.g., mandatory 1139 enforcement) being asserted, if any. AssertedLocks_Array points 1140 to a variable length array of AFSByteRangeLock structures the 1141 client asserts to hold. At the completion of the call, the 1142 parallel array OutResult indicates the server's confirmation 1143 (or refusal) to extend each asserted lock--a value of (Flags & 1144 AFSLock_Flag_Extend_Ok) indicates confirmation. 1146 /* Assert locks on Fid, on request */ 1148 proc AssertExtendLocks ( 1150 IN afs_uint32 Flags, 1152 AFSByteRangeLockSeq *AssertedLocks_Array, 1154 OUT AFSByteRangeLockPointerSeq *ConfirmedLocks_Array, 1156 AFSLockCodeRSeq *Result_Array 1158 ) = 65607; 1160 3.6.6 GetByteRangeLockStatus 1162 This is a diagnostic procedure provided to permit system 1163 administrators to identify client machines and software running 1164 on those clients that are currently holding locks on a file. 1165 Fid is the file to report on. The call returns parallel 1166 variable-length arrays of locks and their associated hosts. The 1167 procedure may only be executed by the AFS super user or members 1168 of the system:administrators group. 1170 proc GetByteRangeLockStatus( 1172 IN AFSFid Fid, 1174 OUT AFSByteRangeLockSeq *AssertedLocks_Array, 1176 AFSLockHostIdentifierSeq *Clients_Array 1178 ) = 65605; 1180 Error Codes 1182 EACCES 1184 The caller does not have the necessary rights. 1186 3.6.7 CancelByteRangeLock 1188 The CancelByteRangeLock procedure permits system administrators 1189 to revoke active locks that may be obstructing normal 1190 operations, perhaps due to a system or network problem. Fid is 1191 the file on which to revoke locks. If successful, all locks in 1192 range [Offset, Offset+Length) are canceled If a value of 0 is 1193 given for Offset and Length the range is taken to span the 1194 entire file. The procedure may only be executed by the AFS 1195 super user or members of the system:administrators group. 1197 proc CancelByteRangeLocks( 1199 IN AFSFid *Fid, 1201 afs_uint64 Offset, 1203 afs_uint64 Length 1205 ) = 65606; 1207 3.6.8 CreateFileLocked 1209 The CreateFileLocked procedure is to be regarded as if it 1210 consisted of of two actions, an initial CreateFile action, and 1211 a subsequent SetByteRangeLock action, taken atomically. The 1212 CreateFile action is taken first, and if the request succeeds, 1213 then the AFSByteRangeLock INOUT parameter (ignoring any 1214 supplied value for Expiration, Txid, or Token) is evaluated by 1215 the server as a byte-range lock request. The creating client is 1216 assured that no other client can be granted a conflicting lock 1217 on the file during the execution of the procedure. It is 1218 expected that clients will typically request a lock of the 1219 LockShareReservation type, and use a valid combination of 1220 AFSLock_Share_Exclusive, AFSLock_Share_Read, 1221 AFSLock_Share_Write, and AFSLock_Share_Mand flags to specify 1222 desired sharing semantics. In particular, the CreateFileLocked 1223 procedure provides a way to support Windows share mode opens 1224 including atomic open and lock semantics assumed by the Windows 1225 CreateFile() function. However, a client may request a lock of 1226 any valid type and range. 1228 proc CreateFileLocked( 1230 IN AFSFid *Fid, 1232 string Name, 1234 AFSStoreStatus *InStatus, 1236 OUT AFSFid *OutFid, 1238 AFSFetchStatus *OutFidStatus, 1240 AFSFetchStatus *OutDirStatus, 1242 AFSCallBack *CallBack, 1244 AFSVolSync *Sync, 1245 INOUT 1247 AFSByteRangeLock *Lock, 1249 ) = 65607; 1251 Error Codes 1253 The CreateFileLocked procedure shall return error codes 1254 corresponding to those of an equivalent CreateFile request. If 1255 the CreateFile is successful, and if Lock->Fid != OutFid, then 1256 Lock->Fid.Uniq is an error return for the requested lock 1257 operation, and may be any valid return from SetByteRangeLock. 1258 Otherwise OutFid is locked and Lock describes the lock. 1260 3.7 Windows File Locking Semantics 1262 Implementation of interoperable locking behavior presents 1263 challenges for a distributed file system like AFS, which must 1264 support clients on platforms which do not agree precisely on 1265 the semantics desirable or possible to enforce. 1267 3.7.1 Byte-Range Locking vs. Byte-Range Lock Emulation 1269 As byte-range locking is effectively required for correct 1270 behavior of Windows applications, the OpenAFS for Windows 1271 client has been forced to implement a locally-enforced 1272 byte-range locking mechanism. In the Windows client today, 1273 local byte-range are shadowed by a whole-file lock in AFS. With 1274 the introduction of server-coordinated byte-range locking, the 1275 Windows client is expected to use server byte-range locks when 1276 possible. 1278 3.7.2 Atomic Lock Open 1280 Windows provides applications with the ability to open and lock 1281 a file in a single operation. As noted elsewhere in this 1282 document, the correct use of share reservations and byte-range 1283 (or whole-file) lock facilities at clients permits correct 1284 implementation of this behavior. The CreateFileLocked procedure 1285 is used by clients seeking to atomically create and lock a file 1286 in a single operation. 1288 3.8 Lock Enforcement 1290 Mandatory enforcement of file locks is considered a requirement 1291 for Windows interoperation. Lock enforcement on Unix-like 1292 platforms generally is advisory. The rules proposed here 1293 reflect some consideration and discussion of unique features in 1294 AFS, and also compromises made in competing systems intended to 1295 support mixed Windows and Unix clients, particularly NFSv4. 1297 3.8.1 Governing Ideas 1299 - Byte-range locks may be taken out on a file under the same 1300 circumstances under which a whole file might be taken out in 1301 traditional AFS 1303 - The mechanism of lock enforcement is to fail the operation 1304 being attempted, a hint shall be sent in the return code of 1305 the reason for failure 1307 - An operation which fails due to conflict with an existing 1308 lock fails completely 1310 - When mandatory enforcement is in effect, attempts by other 1311 than owner to write within a range protected by a byte-range 1312 or whole-file lock, are asserted to fail 1314 - When mandatory enforcement is in effect, attempts by other 1315 than owner to truncate a file such that the truncation 1316 overlaps a range protected by a byte-range or whole-file read 1317 or write lock, or by a read or exclusive share reservation, 1318 are asserted to fail 1320 - Attempts to write outside any conflicting locked range on a 1321 file F with at least one mandatory locked range and not 1322 conflicting with any share reservation on F, considering the 1323 view of locks on the file at the fileserver when the write 1324 request is processed, are considered valid (this is the 1325 documented behavior on Windows platforms) 1327 - Since applications exist, particularly for the command line 1328 (e.g., tar) which know nothing about locks, and may have 1329 legitimate reason to read (though not write) data protected 1330 by mandatory locks, relaxed semantics are enforced for reads 1331 by clients reading outside any range they have themselves 1332 locked--such reads never conflict with lock enforcement, nor 1333 with conflicting share reservations. The view of data 1334 provided to such a client shall be whatever is available, 1335 conforming to regular AFS semantics 1337 - Mandatory enforcement of a read or write lock is asserted to 1338 govern only the StoreData operation (by other clients), and 1339 not, e.g., the various directory change operations or 1340 FetchData[footnote: 1341 Mandatory read lock enforcement is silly, Eisler 2006. More 1342 importantly, it causes difficulties for the AFS cache 1343 consistency model. 1344 ] 1346 3.8.2 Enforcement Rules 1347 - If a client A has a mandatory lock of any type on a range R 1348 in a file F, then StoreData operations by any other client B 1349 which would alter data in any overlapping range or truncate F 1350 such as to reduce or eliminate R, the conflicting operation 1351 (initiated by B) fails 1353 3.8.3 Implementation Note 1355 An AFS implementation MAY provide mechanisms, in addition to 1356 share reservations, by which administrators or users could 1357 specify that files or groups of files in a volume require 1358 mandatory enforcement semantics. 1360 4 Security Considerations 1362 Unless explicitly requested by a client, a sever implementation 1363 MUST send AFSCB_Event_Flock notifications only over a secured 1364 callback channel. By contrast, AFSCB_Event_Release Lock 1365 notifications may be sent over any channel. 1367 5 IANA Considerations 1369 This document makes no request of the IANA. 1371 6 Appendix A: XDR Grammar (afsint.xg) 1373 const VICED_CAPABILITY_BYTE_RANGE_LOCK = 0x0010; 1375 const VICED_CAPABILITY_ASYNC_LOCK_ISSUE = 0x0020; 1377 const LockShareReservation = 4; 1379 const AFSLock_Flag_None = 0x0000; 1381 const AFSLock_Flag_Mand = 0x0001; /* request mandatory 1382 enforcement */ 1384 const AFSLock_Flag_Wait = 0x0002; /* request wait on lock */ 1386 const AFSLock_Flag_Posix = 0x0004; /* request posix semantics 1387 */ 1389 const AFSLock_Flag_Share_Read = 0x0008; /* allow Share 1390 mode READ (Share Reservation) */ 1391 const AFSLock_Flag_Share_Write = 0x0010; /* allow Share 1392 mode WRITE (Share Reservation) */ 1394 const AFSLock_Flag_Share_Exclusive = 0x0020; /* assert 1395 exclusive sharing (Share Reservation) */ 1397 const AFSLock_Flag_Assert_Read = 0x0040; /* assert intention to 1398 READ */ 1400 const AFSLock_Flag_Assert_Write = 0x0080; /* assert intention 1401 to WRITE */ 1403 const AFSLock_Flag_TestLock = 0x0100; /* test for conflicts 1404 only */ 1406 const AFSLock_Flag_EReturn = 0x1000; /* error return 1407 flag */ 1409 struct AFSByteRangeLock { 1411 AFSFid Fid; 1413 afs_uint32 Type; 1415 afs_uint32 Owner; 1417 afs_uint64 Uniq; 1419 afs_uint32 Flags; 1421 afs_uint64 Offset; 1423 afs_uint64 Length; 1425 afs_uint64 Expiration; 1427 AFSOpaque Txid; 1429 AFSOpaque Token; 1431 }; 1432 /* Request byte-range file lock */ 1434 proc SetByteRangeLock( 1436 IN AFSFid *Fid, 1438 INOUT AFSByteRangeLock *Lock 1440 ) = 65601; 1442 /* Release byte-range file lock */ 1444 proc ReleaseByteRangeLock( 1446 IN AFSByteRangeLock *Lock 1448 ) = 65602; 1450 /* Upgrade byte-range file lock (i.e., from Read to Write) */ 1452 proc UpgradeByteRangeLock( 1454 IN AFSByteRangeLock *Lock, 1456 afs_uint32 Type 1458 ) = 65603; 1460 /* Downgrade byte-range file lock (i.e., from Write to Read) */ 1462 proc DowngradeByteRangeLock( 1464 IN AFSByteRangeLock *Lock, 1466 afs_uint32 Type 1468 ) = 65604; 1470 /* Request lock status report (system:administrators) */ 1472 proc GetByteRangeLockStatus( 1473 IN Fid, 1475 OUT AFSByteRangeLockSeq *AssertedLocks_Array, 1477 AFSLockHostIdentifierSeq *Clients_Array 1479 ) = 65605; 1481 /* administratively cancel locks (system:administrators) */ 1483 proc CancelByteRangeLocks( 1485 IN Fid, 1487 afs_uint64 Offset, 1489 afs_uint64 Length 1491 ) = 65606; 1493 const AFS_LOCK_SEQ_MAX = 10000; 1495 typedef AFSByteRangeLock AFSByteRangeLockSeq 1496 ; 1498 typedef AFSLockFlagsSeq ; 1500 const AFSLock_Flag_Extend = 4; /* client request extend, server 1501 ack extended */ 1503 const AFSLock_Flag_Discard = 8; /* client request disard, 1504 server ack discarded */ 1506 /* Assert locks on Fid, on request */ 1508 proc AssertExtendLocks ( 1510 IN afs_uint32 Flags, 1512 AFSByteRangeLockSeq *AssertedLocks_Array, 1513 OUT AFSByteRangeLockPointerSeq *ConfirmedLocks_Array, 1515 AFSLockCodeRSeq *Result_Array 1517 ) = 65607; 1519 7 Appendix A: XDR Grammar (afscbint.xg) 1521 const CLIENT_CAPABILITY_BYTE_RANGE_LOCK = 0x0008; 1523 const AFSCB_Result_ResponseDeferred = 2; 1525 const AFSCB_Result_ReturnLocks = 3; 1527 /* Byte-Range Locking Cancellation Types */ 1529 const AFSCB_Cancel_ExtendLocks = 7; /* re-assert locks, or lose 1530 them */ 1532 const AFSCB_Cancel_RevokeLocks = 8; /* locks on Fid revoked */ 1534 /* Cancellation Flags */ 1536 const AFSCB_Flag_AssertLocks = 4; /* request ExtendLock */ 1538 const AFSCB_Flag_RevokeLocks = 8; /* locks cancelled, sorry */ 1540 const AFSCB_Flock_IssueLocks = 1; /* locks issued on Fid */ 1542 const AFSCB_Flock_RevokeLocks = 2; /* locks on Fid revoked */ 1544 const AFSCB_Flock_ExpireLocks = 3; /* locks expired */ 1546 /* confirm issue of deferred lock requests */ 1548 proc AssertExtendLocks ( 1550 IN afs_uint32 Flags, 1551 AFSByteRangeLockSeq *AssertedLocks_Array, 1553 OUT AFSByteRangeLockPointerSeq *ConfirmedLocks_Array, 1555 AFSLockCodeRSeq *Result_Array 1557 ) = 65607; 1559 Author's Address 1561 Matt Benjamin 1563 Linux Box Corporation 1565 206 S. Fifth Ave, Ste 150 1567 Ann Arbor, MI 48104 USA 1569 Phone: +1 734 761 4689 1571 Email: matt@linuxbox.com