idnits 2.17.1 draft-deason-afs3-type-time-03.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: ---------------------------------------------------------------------------- No issues found here. 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 (August 26, 2011) is 4621 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 ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 3530 (Obsoleted by RFC 7530) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 N/A A. Deason 3 Internet-Draft Sine Nomine 4 Intended status: Informational August 26, 2011 5 Expires: February 27, 2012 7 Base Types for Time in AFS-3 8 draft-deason-afs3-type-time-03 10 Abstract 12 This document defines three types to be used in future AFS-3 Rx 13 Remote Procedure Calls (RPCs) to represent time. Current AFS-3 RPCs 14 represent time as 32-bit integers representing seconds. This is 15 insufficient in both granularity and range, so new types to represent 16 time are defined in this document to overcome these limitations. 18 Internet Draft Comments 20 Comments regarding this draft are solicited. Please include the 21 AFS-3 protocol standardization mailing list 22 (afs3-standardization@openafs.org) as a recipient of any comments. 24 Status of this Memo 26 This Internet-Draft is submitted in full conformance with the 27 provisions of BCP 78 and BCP 79. 29 Internet-Drafts are working documents of the Internet Engineering 30 Task Force (IETF). Note that other groups may also distribute 31 working documents as Internet-Drafts. The list of current Internet- 32 Drafts is at http://datatracker.ietf.org/drafts/current/. 34 Internet-Drafts are draft documents valid for a maximum of six months 35 and may be updated, replaced, or obsoleted by other documents at any 36 time. It is inappropriate to use Internet-Drafts as reference 37 material or to cite them other than as "work in progress." 39 This Internet-Draft will expire on February 27, 2012. 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 respect 51 to this document. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Conventions Used in this Document . . . . . . . . . . . . . . 3 57 3. Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3.1. AFSAbsTime64 . . . . . . . . . . . . . . . . . . . . . . . 4 59 3.2. AFSRelTime64 . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.3. AFSAbsTime64Res . . . . . . . . . . . . . . . . . . . . . 5 61 3.3.1. Resolution Assumptions . . . . . . . . . . . . . . . . 6 62 4. Time Resolution . . . . . . . . . . . . . . . . . . . . . . . 6 63 4.1. Sources of Differing Time Resolutions . . . . . . . . . . 6 64 4.2. Relevance to AFS-3 . . . . . . . . . . . . . . . . . . . . 7 65 4.3. When to Include Resolution Information . . . . . . . . . . 7 66 5. Resolution Limitations . . . . . . . . . . . . . . . . . . . . 8 67 6. Times Before UTC . . . . . . . . . . . . . . . . . . . . . . . 9 68 7. Converting Time Types . . . . . . . . . . . . . . . . . . . . 9 69 7.1. Special Cases . . . . . . . . . . . . . . . . . . . . . . 10 70 7.2. Sample Code . . . . . . . . . . . . . . . . . . . . . . . 10 71 8. Security Considerations . . . . . . . . . . . . . . . . . . . 13 72 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 73 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 74 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 75 11.1. Normative References . . . . . . . . . . . . . . . . . . . 13 76 11.2. Informative References . . . . . . . . . . . . . . . . . . 13 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 14 79 1. Introduction 81 All extant AFS-3 RPCs represent time as a 32-bit integer, as encoded 82 by XDR in [RFC4506], which represents a number of seconds. For RPCs 83 that specify an absolute time, this is the number of seconds that 84 have passed since since midnight or 0 hour January 1, 1970 85 Coordinated Universal Time (UTC), not counting leap seconds. These 86 time structures will be unusable after January 2038, and are already 87 insufficient to represent time with more granularity than one second. 89 This limited granularity creates inefficiencies in various parts of 90 the AFS-3 protocol when it must be determined in what order two 91 events have occurred (for example, whether or not a file was changed 92 since the last time a volume has been backed up). When those two 93 events have occurred during the same second, implementations must 94 take a conservative assumption about which event occurred first, 95 often resulting in unnecessary duplication or retransmission of data. 96 In addition, metadata can be lost when files are copied to AFS from 97 other filesystems that store file modification times with finer 98 granularity than one second. 100 This document defines three new types to represent time to overcome 101 these limitations: AFSAbsTime64, AFSRelTime64, and AFSAbsTime64Res. 102 All of these support a much wider time range at a much higher 103 granularity than the current time representations. AFSRelTime64 is 104 to be used to represent times relative to some other event, and 105 AFSAbsTime64 is to be used to represent absolute time stamps. 106 AFSAbsTime64Res is to be used to represent a small range of absolute 107 time, which is necessary for determining relative ordering of events, 108 as described in Section 4. 110 All of these new types also have the additional benefit of providing 111 standard type identifiers to be used when specifying absolute or 112 relative time in AFS-3 RPC arguments and structures. Currently, all 113 time values are just defined as "afs_int32" types in the XDR language 114 definitions. This can make it confusing whether or not a field is an 115 absolute time, relative time, or something else completely. Using 116 the new standard time types will make this clear and unambiguous. 118 2. Conventions Used in this Document 120 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 121 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 122 document are to be interpreted as described in [RFC2119]. 124 3. Data Types 126 This document defines three new data types: AFSAbsTime64, 127 AFSRelTime64, and AFSAbsTime64Res. All of these are encoded on the 128 wire using the XDR standard described in [RFC4506], and are described 129 using the XDR language specification therein. 131 3.1. AFSAbsTime64 133 The new AFSAbsTime64 type is represented as an XDR-encoded 64-bit 134 signed integer representing the timestamp. It is defined as thus in 135 XDR: 137 typedef hyper AFSAbsTime64; 139 The AFSAbsTime64 type represents time relative to midnight or 0 hour 140 January 1, 1970 Coordinated Universal Time (UTC), represented in 141 increments of 100 nanoseconds (ns). If the value is greater than 142 zero, the value represents the amount of time that has passed since 143 midnight January 1, 1970 UTC, excluding any leap seconds. If the 144 value is less than zero, the value represents the amount of time 145 before midnight January 1, 1970 UTC. 147 For example, to represent the time 60 seconds after midnight on 148 January 1, 1970 UTC, the value of the field would be 600000000 (600 149 million). To represent the time 60 seconds before midnight January, 150 1970 UTC, the value of the field would be -600000000 (negative 600 151 million). 153 This type can represent any time in the year 27258 BCE through any 154 time in the year 31196 CE with 100-ns granularity. For timestamps 155 before 1972, see the notes in Section 6. 157 3.2. AFSRelTime64 159 The new AFSRelTime64 type has same representation on the wire as 160 AFSAbsTime64 in Section 3.1: 162 typedef hyper AFSRelTime64; 164 The AFSRelTime64 type represents an amount of time that has passed 165 since some other event, represented in increments of 100 nanoseconds 166 (ns). The event to which this time is relative is unspecified, and 167 can be anything; it must be specified by the RPC or structure that 168 defines a field of the AFSRelTime type. 170 Values greater than 0 represent dates that occur after the relative 171 event, and values less than 0 represent dates that occur before the 172 relative event. 174 For example, to represent the time 5 seconds before some other event, 175 the value of the timestamp field would be -50000000 (negative 50 176 million). 178 3.3. AFSAbsTime64Res 180 The new AFSAbsTime64Res type is represented as an XDR-encoded 181 structure on the wire, containing an AFSAbsTime64 and a 32-bit 182 unsigned integer representing the resolution. It is defined as thus 183 in XDR: 185 struct AFSAbsTime64Res { 186 AFSAbsTime64 timestamp; 187 unsigned int resolution; 188 }; 190 The AFSAbsTime64Res structure represents the amount of time that has 191 passed since midnight or 0 hour January 1, 1970 Coordinated Universal 192 Time (UTC), excluding any leap seconds. The value of the timestamp 193 field is this amount of time represented as described in Section 3.1. 195 The resolution field represents the resolution of the time source 196 from which the timestamp was obtained. The value of the resolution 197 field is the difference between the represented time, and another 198 time after the represented time that is guaranteed to be after the 199 actual time at which the event in question occurred. 201 In other words, let X be the time that some event occurred, Y be the 202 value of the timestamp field in an AFSAbsTime64Res structure, and Z 203 be the value of the resolution field. To construct an 204 AFSAbsTime64Res structure that represents X, the values of the 205 timestamp and resolution field MUST be specified such that Y <= X < Y 206 + Z. Typically the value of the resolution field will just be the 207 resolution of the time source from which the timestamp was obtained, 208 if the resolution of the time source is constant. 210 For example, to represent the time 60 seconds after midnight on 211 January 1, 1970, the value of the timestamp field would be 600000000 212 (600 million) as described in Section 3.1. If this time stamp was 213 obtained from a source that only represents time in seconds, the next 214 representable time is 61 seconds after midnight on January 1, 1970, 215 so it is guaranteed that the event in question occurred before that 216 time (otherwise the time source would give us a time of 61 seconds). 217 So the value of the resolution field should be 10000000 (10 million). 218 In effect, this AFSAbsTime64Res structure represents an event that 219 occurred at or after 60 seconds after January 1, 1970, but occurred 220 before 61 seconds after January 1, 1970. 222 For more details about the resolution field (including the motivation 223 for its existence), see Section 4. 225 3.3.1. Resolution Assumptions 227 If the resolution field has the value of 0, the resolution of the 228 specified timestamp is unknown. If an implementation has absolutely 229 no mechanism to determine the resolution of a time source when 230 creating a time stamp, it MUST specify a resolution of 0. If an 231 implementation needs to use an AFSAbsTime64Res value for calculating 232 event ordering, and the resolution is 0, it SHOULD assume a 233 resolution of 1 second, and round the timestamp down to the nearest 234 second. 236 An AFS-3 implementation MUST NOT ever specify a resolution greater 237 than 1 second (10000000 100-ns increments). Implementations of the 238 AFS-3 protocol that exist prior to the introduction of the new time 239 types in this document assume that the time resolution is 1 second, 240 and may not behave correctly with time sources that are less granular 241 than 1 second. No systems nor file formats that are related to any 242 AFS-3 implementation are known that do not have at least 1-second 243 granularity, so adhering to this should not be a problem. 245 If an implementation receives an AFSAbsTime64Res structure with a 246 granularity coarser than 1 second, it MUST treat it as an invalid 247 time representation. What that entails depends on the context, but 248 the AFSAbsTime64Res value MUST NOT be used for any calculations and 249 SHOULD be immediately discarded. Typically an RPC will raise some 250 kind of error in this condition, but the exact behavior is up to the 251 relevant RPC or other operation. 253 4. Time Resolution 255 The new type AFSAbsTime64Res includes information about the 256 resolution or granularity of the time it represents. The reason for 257 including this information may not be immediately clear, so this 258 section provides some information on why this information is 259 beneficial. 261 4.1. Sources of Differing Time Resolutions 263 All current AFS-3 implementations represent time as a 32-bit integer 264 on the wire, and so it is common for implementations to internally 265 represent time as 32-bit integers, with 1-second granularity. As 266 such, when implementations support the time types defined in this 267 document, it is likely that there will be a period of time where 268 implementations cannot store or represent time with greater 269 granularity than 1-second, even though the protocol allows them to do 270 so. 272 In addition, due to technical restrictions of various platforms, or 273 other sources of time (such as file formats), implementations may be 274 only able to transmit time information in certain granularities. For 275 example, the operating system that an AFS-3 Volume Server 276 implementation runs on may only be able to retrieve the current time 277 in increments of 1 millisecond. Or, an AFS-3 Volume Server 278 implementation may be reading the time information from a file, and 279 the file only represents time in increments of 1 second. 281 From this, it is clear that implementations will send time of various 282 granularity when communicating with other services and clients in 283 AFS-3, and the granularity of time may vary even within the same 284 implementation process (depending on from where it is obtaining the 285 time). 287 4.2. Relevance to AFS-3 289 Timestamps are sometimes used in AFS-3 to establish a relative non- 290 strict total ordering of events. That is, given the events X and Y, 291 we must determine whether X or Y occurred first, or if they occurred 292 at approximately the same time. This primarily occurs in volume 293 operations when incremental data is sent, and exactly what 294 incremental data is sent is determined by the timestamps of other 295 volumes. If we get the ordering wrong, problems with data 296 inconsistency can occur. If we conservatively determine that two 297 events occurred at the same time when we could have correctly made 298 the determination that one occurred before the other, inefficiencies 299 arise. 301 In order to be able to order such events, then, we must know the 302 resolution of the time value that is stored. This is so we know the 303 earliest possible time that the event occurred, and the latest 304 possible time that the event occurred. 306 4.3. When to Include Resolution Information 308 There are two time types defined in this document to represent an 309 absolute timestamp: AFSAbsTime64 and AFSAbsTime64Res. The only 310 difference between these two types is that AFSAbsTime64Res includes 311 resolution information, and AFSAbsTime64 does not. This section 312 serves to guide designers of future AFS-3 RPCs in what circumstances 313 each type should be used. 315 When deciding whether to use AFSAbsTime64 or AFSAbsTime64Res in a 316 structure field or RPC argument, the first determination that must be 317 made is whether the timestamp value will or could ever be used to 318 make ordering decisions by an AFS-3 service. If it will or could, 319 then the argument or field should be of the AFSAbsTime64Res type. 321 Otherwise, the determination should be made whether or not any 322 service (possibly unrelated to AFS-3) may realistically make ordering 323 decisions based on the field or argument. If it may, then the 324 AFSAbsTime64Res type should be considered; otherwise, the 325 AFSAbsTime64 type should be used. 327 For example, as mentioned in Section 4.2, the AFS-3 Volume Service 328 and clients make ordering decisions based on timestamps related to 329 when volume operations have occurred. So, timestamp fields related 330 to volume operations should probably use the AFSAbsTime64Res type. 332 However, when a timestamp is used to represent the modification time 333 of a file in AFS, that timestamp is not used by AFS-3 services to 334 make any ordering decisions. While it is possible that some software 335 unrelated to AFS-3 may try to make ordering decisions based off of 336 that timestamp, it is unlikely to be able to do so reliably. This is 337 because file modification timestamps can usually be set to any time 338 by humans, and any time resolution information stored is usually not 339 available to programs that are not AFS-3-aware. And in general, 340 AFS-3 file metadata is not intended to be a general-purpose 341 distributed synchronization mechanism. So, file modification 342 timestamps should probably use the AFSAbsTime64 type. 344 5. Resolution Limitations 346 The types specified in this document are limited to 100-nanosecond 347 resolution or coarser. There are other systems which may interact 348 with AFS-3 that have finer resolution; for example, the NFSv4 349 nfstime4 structure in Section 2.2 of [RFC3530] and the timespec 350 structure in [POSIX] both allow for timestamps with a resolution of 351 1-ns. Because of this, there are inherent problems with interacting 352 with such systems. 354 It is believed that for a large majority of use cases, timestamps 355 with resolution finer than 100-nanoseconds are not necessary, and so 356 the types defined in this document should be sufficient. However, 357 there may be use cases in which resolution finer than 100-ns is 358 required. In addition, there are also several use cases where the 359 legacy 32-bit timestamps are adequate, and the additional space 360 overhead of the types defined by this document may be considered 361 unnecessary overhead. 363 This document does not accommodate for those cases, but this document 364 does not restrict AFS-3 to only use the time types defined in this 365 document. It is recommended that future AFS-3 RPCs are designed such 366 that they make take advantage of several different time types of 367 varying resolutions, so that such use cases can be accommodated while 368 not sacrificing the space efficiency for the common case addressed by 369 the time types defined in this document. Any such method of 370 accommodating for different time types are left up to the individual 371 RPCs or wire structures, and are not discussed here. 373 6. Times Before UTC 375 The absolute time types defined in this document are specified as 376 relative to midnight January 1, 1970 UTC, excluding leap seconds, and 377 times far earlier than that are also representable. It is worthy to 378 note that UTC did not exist until January 1, 1972, and so times 379 before 1972 specified as UTC are technically meaningless. However, 380 it is convenient to assume that UTC has existed for all eternity. 381 For all times before 1972, we represent time as if UTC has always 382 existed, using the obvious backwards projection of the current UTC 383 time zone and Gregorian calendar rules. 385 7. Converting Time Types 387 In general, when converting an AFSAbsTime64 or AFSAbsTime64Res value 388 to some other type that has granularity coarser than 100 ns 389 granularity, the resulting value MUST always be rounded down to the 390 nearest lower increment of the resultant type. When converting to 391 the POSIX time_t type, for example, the AFSAbsTime or AFSAbsTime64Res 392 value MUST be rounded down to the nearest lower second. When 393 converting to the POSIX struct timeval type, the value MUST be 394 rounded down to the nearest lower microsecond. 396 When converting to or from the Microsoft FILETIME format, a constant 397 value must be added or subtracted, since FILETIME specifies time 398 relative to midnight 1 January 1601 UTC, but AFSAbsTime64 and 399 AFSAbsTime64Res specify time relative to midnight 1 January 1970 UTC. 400 When converting from an AFSAbsTime64 to a Microsoft FILETIME, the 401 value 116444736000000000 must be subtracted from the AFSAbsTime64 402 value. When converting to an AFSAbsTime64 from a Microsoft FILETIME, 403 the value 116444736000000000 must be added to the FILETIME value. 405 It is also important to keep in mind that when converting from 406 AFSAbsTime64Res to time_t or FILETIME types, strictly speaking the 407 AFSAbsTime64Res structure represents two times: the beginning and end 408 time. So it is impossible to accurately convert an AFSAbsTime64Res 409 structure to a single time value. This is often unavoidable when 410 converting to legacy AFS-3 interfaces, or interfaces unrelated to 411 AFS-3, however, and when only one time value is given to convert to, 412 implementations MUST specify the beginning time (that is, the time 413 represented by the timestamp field). 415 7.1. Special Cases 417 Extant AFS-3 RPCs often use a timestamp of 0 to represent a special 418 meaning. That is, a timestamp of 0 often does not indicate midnight 419 1 January 1970 UTC, but may represent a logical value of "negative 420 infinity", or indicates some special meaning that is specific to that 421 RPC. The value of 0 was often just used because it is the earliest 422 representable time for a 32-bit unsigned integer. 424 Any such special meanings must be specified by the RPC in question, 425 and this document assigns no special meaning to the value of 0 for 426 any of the types defined in this document. However, this document 427 recommends that any future RPCs keep the special meaning of the 0 428 timestamp, if the RPC is replacing an RPC that previously had a 429 special meaning for timestamp 0, even though that is no longer the 430 earliest representable time. If the new RPC uses an AFSAbsTime64Res 431 argument, the resolution field should be 0, as well. 433 For example, say there is an AFS-3 RPC called AFSFoo that accepts an 434 afs_uint32 absolute timestamp argument, and it specifies that a 435 timestamp of 0 represents some special case. Let another RPC, 436 AFSFoo64, define an RPC that is identical to AFSFoo except that it 437 accepts an AFSAbsTime64Res parameter. AFSFoo64 should specify that a 438 caller should specify an AFSAbsTime64Res with timestamp 0, resolution 439 0, to indicate the special case previously indicated by giving a 32- 440 bit timestamp of 0. 442 7.2. Sample Code 444 Sample C code is provided here to convert AFSAbsTime64, AFSRelTime64, 445 and AFSAbsTime64Res values to and from FILETIME and POSIX time_t 446 values where appropriate. Also provided is a function to compare two 447 AFSAbsTime64Res values, and functions to add an AFSRelTime64 to an 448 AFSAbsTime64Res and AFSAbsTime64. 450 The conversion functions follow the recommendations in Section 7.1. 451 So, a time_t with the value of 0 will be converted to an AFSAbsTime 452 with the value of 0, or an AFSAbsTime64Res value of timestamp 0, 453 resolution 0. AFSAbsTime64Res structures with a resolution of 0 (and 454 a non-zero timestamp) are treated as having an effective resolution 455 of 1 second, as suggested in Section 3.3.1. 457 These functions do not handle overflow, underflow, or other errors, 458 and are just guidelines for the general conversion algorithms. 460 #define AFSTIME64_WINNT_SHIFT 116444736000000000ULL 461 #define AFSTIME64_POSIX_SCALE 10000000U 462 #define AFSTIME64_DEFAULT_RES 10000000U 464 void 465 timet_to_AFSAbsTime64(time_t t, AFSAbsTime64 *atsp) 466 { 467 *atsp = (t * AFSTIME64_POSIX_SCALE); 468 } 469 void 470 AFSAbsTime64_to_timet(AFSAbsTime64 ats, time_t *tp) 471 { 472 *tp = (ats / AFSTIME64_POSIX_SCALE); 473 } 474 void 475 timet_to_AFSRelTime64(time_t t, AFSRelTime64 *artsp) 476 { 477 *artsp = (t * AFSTIME64_POSIX_SCALE); 478 } 479 void 480 AFSRelTime64_to_timet(AFSRelTime64 arts, time_t *tp) 481 { 482 *tp = (arts / AFSTIME64_POSIX_SCALE); 483 } 484 void 485 timet_to_AFSAbsTime64Res(time_t t, AFSAbsTime64Res *atp) 486 { 487 timet_to_AFSAbsTime64(t, &atp->timestamp); 488 if (t == 0) { 489 atp->resolution = 0; 490 } else { 491 atp->resolution = AFSTIME64_POSIX_SCALE; 492 } 493 } 494 void 495 AFSAbsTime64Res_to_timet(AFSAbsTime64Res *atp, time_t *t1, time_t *t2) 496 { 497 unsigned int res = atp->resolution; 498 if (res == 0) { 499 res = AFSTIME64_DEFAULT_RES; 500 } 501 AFSAbsTime64_to_timet(atp->timestamp, t1); 502 AFSAbsTime64_to_timet(atp->timestamp + res, t2); 503 } 504 void 505 FILETIME_to_AFSAbsTime64(FILETIME *ftp, AFSAbsTime64 *atsp) 506 { 507 ULARGE_INTEGER uli; 508 uli.LowPart = ftp->dwLowDateTime; 509 uli.HighPart = ftp->dwHighDateTime; 510 *atsp = uli.QuadPart - AFSTIME64_WINNT_SHIFT; 511 } 512 void 513 AFSAbsTime64_to_FILETIME(AFSAbsTime64 ats, FILETIME *ftp) 514 { 515 ULARGE_INTEGER uli; 516 uli.QuadPart = ats + AFSTIM64_WINNT_SHIFT; 517 ftp->dwLowDateTime = uli.LowPart; 518 ftp->dwHighDateTime = uli.HighPart; 519 } 520 void 521 AFSAbsTime64Res_to_FILETIME(AFSAbsTime64Res *atp, FILETIME *ft1, 522 FILETIME *ft2) 523 { 524 unsigned int res = atp->resolution; 525 if (res == 0) { 526 res = AFSTIME64_DEFAULT_RES; 527 } 528 AFSAbsTime64_to_FILEMTIME(atp->timestamp, ft1); 529 AFSAbsTime64_to_FILEMTIME(atp->timestamp + res, ft2); 530 } 531 void 532 AFSAbsTime64Res_add_AFSRelTime64(AFSAbsTime64Res *atp, 533 AFSRelTime64 arts) 534 { 535 atp->timestamp += arts; 536 } 537 void 538 AFSAbsTime64_add_AFSRelTime64(AFSAbsTime *atsp, 539 AFSRelTime arts) 540 { 541 *atsp += arts; 542 } 543 int 544 cmp_AFSAbsTime64Res(AFSAbsTime64Res *atp1, AFSAbsTime64Res *atp2) 545 { 546 unsigned int res1 = atp1->resolution; 547 unsigned int res2 = atp2->resolution; 548 if (res1 == 0) { 549 res1 = AFSTIME64_DEFAULT_RES; 550 } 551 if (res2 == 0) { 552 res2 = AFSTIME64_DEFAULT_RES; 554 } 555 if (atp1->timestamp + res1 <= atp2->timestamp) { 556 return -1; 557 } 558 if (atp2->timestamp + res2 <= atp1->timestamp) { 559 return 1; 560 } 561 return 0; 562 } 564 8. Security Considerations 566 This memo raises no security issues. 568 9. IANA Considerations 570 This document makes no request of the IANA. 572 10. Acknowledgements 574 The author thanks Simon Wilkinson and Jeffrey Altman for some 575 background text, Jeffrey Altman, David Boyes, Tom Keiser, and Simon 576 Wilkinson for discussion on the problem of time resolution, Steven 577 Jenkins for discussion on interoperability concerns, Russ Allbery for 578 input on UTC, leap seconds, and dates before 1970, and the general 579 membership of the afs3-standardization@openafs.org mailing list for 580 general discussion on the balance between time granularity and field 581 width overhead. 583 11. References 585 11.1. Normative References 587 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 588 Requirement Levels", BCP 14, RFC 2119, March 1997. 590 11.2. Informative References 592 [POSIX] Institute of Electrical and Electronics Engineers, "IEEE 593 Standard for Information Technology - Portable Operating 594 System Interface (POSIX) Base Specifications, Issue 7", 595 IEEE Std 1003.1-2008, 2008. 597 [RFC3530] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 598 Beame, C., Eisler, M., and D. Noveck, "Network File System 599 (NFS) version 4 Protocol", RFC 3530, April 2003. 601 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 602 STD 67, RFC 4506, May 2006. 604 Author's Address 606 Andrew Deason 607 Sine Nomine Associates 608 43596 Blacksmith Square 609 Ashburn, Virginia 20147-4606 610 USA 612 Phone: +1 703 723 6673 613 Email: adeason@sinenomine.net