Found wdiff, but it reported no recognisable version. Falling back to builtin diff colouring... Diff: draft-pre-ch-18-openattr.txt - draft-ietf-nfsv4-minorversion1-22.txt
 draft-pre-ch-18-openattr.txt   draft-ietf-nfsv4-minorversion1-22.txt 
NFSv4 S. Shepler NFSv4 S. Shepler
Internet-Draft M. Eisler Internet-Draft M. Eisler
Intended status: Standards Track D. Noveck Intended status: Standards Track D. Noveck
Expires: October 12, 2008 Editors Expires: October 13, 2008 Editors
April 10, 2008 April 11, 2008
NFS Version 4 Minor Version 1 NFS Version 4 Minor Version 1
draft-ietf-nfsv4-minorversion1-22.txt draft-ietf-nfsv4-minorversion1-22.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
skipping to change at page 1, line 35 skipping to change at page 1, line 35
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on October 12, 2008. This Internet-Draft will expire on October 13, 2008.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2008). Copyright (C) The IETF Trust (2008).
Abstract Abstract
This Internet-Draft describes NFS version 4 minor version one, This Internet-Draft describes NFS version 4 minor version one,
including features retained from the base protocol and protocol including features retained from the base protocol and protocol
extensions made subsequently. Major extensions introduced in NFS extensions made subsequently. Major extensions introduced in NFS
skipping to change at page 3, line 32 skipping to change at page 3, line 32
4.2.1. General Properties of a Filehandle . . . . . . . . . 91 4.2.1. General Properties of a Filehandle . . . . . . . . . 91
4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 92 4.2.2. Persistent Filehandle . . . . . . . . . . . . . . . 92
4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 92 4.2.3. Volatile Filehandle . . . . . . . . . . . . . . . . 92
4.3. One Method of Constructing a Volatile Filehandle . . . . 93 4.3. One Method of Constructing a Volatile Filehandle . . . . 93
4.4. Client Recovery from Filehandle Expiration . . . . . . . 94 4.4. Client Recovery from Filehandle Expiration . . . . . . . 94
5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 95 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 95
5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 96 5.1. REQUIRED Attributes . . . . . . . . . . . . . . . . . . 96
5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 96 5.2. RECOMMENDED Attributes . . . . . . . . . . . . . . . . . 96
5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 97 5.3. Named Attributes . . . . . . . . . . . . . . . . . . . . 97
5.4. Classification of Attributes . . . . . . . . . . . . . . 98 5.4. Classification of Attributes . . . . . . . . . . . . . . 98
5.5. REQUIRED Attributes - List and Definition References . . 100 5.5. Set-Only and Get-Only Attributes . . . . . . . . . . . . 99
5.6. RECOMMENDED Attributes - List and Definition 5.6. REQUIRED Attributes - List and Definition References . . 99
5.7. RECOMMENDED Attributes - List and Definition
References . . . . . . . . . . . . . . . . . . . . . . . 100 References . . . . . . . . . . . . . . . . . . . . . . . 100
5.7. Attribute Definitions . . . . . . . . . . . . . . . . . 102 5.8. Attribute Definitions . . . . . . . . . . . . . . . . . 102
5.7.1. Definitions of REQUIRED Attributes . . . . . . . . . 102 5.8.1. Definitions of REQUIRED Attributes . . . . . . . . . 102
5.7.2. Definitions of Uncategorized RECOMMENDED 5.8.2. Definitions of Uncategorized RECOMMENDED
Attributes . . . . . . . . . . . . . . . . . . . . . 104 Attributes . . . . . . . . . . . . . . . . . . . . . 104
5.8. Interpreting owner and owner_group . . . . . . . . . . . 110 5.9. Interpreting owner and owner_group . . . . . . . . . . . 111
5.9. Character Case Attributes . . . . . . . . . . . . . . . 112 5.10. Character Case Attributes . . . . . . . . . . . . . . . 113
5.10. Directory Notification Attributes . . . . . . . . . . . 112 5.11. Directory Notification Attributes . . . . . . . . . . . 113
5.11. pNFS Attribute Definitions . . . . . . . . . . . . . . . 113 5.12. pNFS Attribute Definitions . . . . . . . . . . . . . . . 113
5.12. Retention Attributes . . . . . . . . . . . . . . . . . . 115 5.13. Retention Attributes . . . . . . . . . . . . . . . . . . 115
6. Access Control Attributes . . . . . . . . . . . . . . . . . . 117 6. Access Control Attributes . . . . . . . . . . . . . . . . . . 118
6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 118 6.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . 118
6.2. File Attributes Discussion . . . . . . . . . . . . . . . 119 6.2. File Attributes Discussion . . . . . . . . . . . . . . . 119
6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 119 6.2.1. Attribute 12: acl . . . . . . . . . . . . . . . . . 119
6.2.2. Attribute 58: dacl . . . . . . . . . . . . . . . . . 134 6.2.2. Attribute 58: dacl . . . . . . . . . . . . . . . . . 134
6.2.3. Attribute 59: sacl . . . . . . . . . . . . . . . . . 134 6.2.3. Attribute 59: sacl . . . . . . . . . . . . . . . . . 134
6.2.4. Attribute 33: mode . . . . . . . . . . . . . . . . . 134 6.2.4. Attribute 33: mode . . . . . . . . . . . . . . . . . 134
6.2.5. Attribute 74: mode_set_masked . . . . . . . . . . . 134 6.2.5. Attribute 74: mode_set_masked . . . . . . . . . . . 135
6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 135 6.3. Common Methods . . . . . . . . . . . . . . . . . . . . . 136
6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 135 6.3.1. Interpreting an ACL . . . . . . . . . . . . . . . . 136
6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 136 6.3.2. Computing a Mode Attribute from an ACL . . . . . . . 137
6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 137 6.4. Requirements . . . . . . . . . . . . . . . . . . . . . . 138
6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 138 6.4.1. Setting the mode and/or ACL Attributes . . . . . . . 138
6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 139 6.4.2. Retrieving the mode and/or ACL Attributes . . . . . 140
6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 140 6.4.3. Creating New Objects . . . . . . . . . . . . . . . . 140
7. Single-server Namespace . . . . . . . . . . . . . . . . . . . 143 7. Single-server Namespace . . . . . . . . . . . . . . . . . . . 144
7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 144 7.1. Server Exports . . . . . . . . . . . . . . . . . . . . . 144
7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 144 7.2. Browsing Exports . . . . . . . . . . . . . . . . . . . . 145
7.3. Server Pseudo File System . . . . . . . . . . . . . . . 145 7.3. Server Pseudo File System . . . . . . . . . . . . . . . 145
7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 145 7.4. Multiple Roots . . . . . . . . . . . . . . . . . . . . . 146
7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 145 7.5. Filehandle Volatility . . . . . . . . . . . . . . . . . 146
7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 146 7.6. Exported Root . . . . . . . . . . . . . . . . . . . . . 146
7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 146 7.7. Mount Point Crossing . . . . . . . . . . . . . . . . . . 147
7.8. Security Policy and Namespace Presentation . . . . . . . 147 7.8. Security Policy and Namespace Presentation . . . . . . . 147
8. State Management . . . . . . . . . . . . . . . . . . . . . . 148 8. State Management . . . . . . . . . . . . . . . . . . . . . . 148
8.1. Client and Session ID . . . . . . . . . . . . . . . . . 148 8.1. Client and Session ID . . . . . . . . . . . . . . . . . 149
8.2. Stateid Definition . . . . . . . . . . . . . . . . . . . 149 8.2. Stateid Definition . . . . . . . . . . . . . . . . . . . 149
8.2.1. Stateid Types . . . . . . . . . . . . . . . . . . . 149 8.2.1. Stateid Types . . . . . . . . . . . . . . . . . . . 150
8.2.2. Stateid Structure . . . . . . . . . . . . . . . . . 150 8.2.2. Stateid Structure . . . . . . . . . . . . . . . . . 151
8.2.3. Special Stateids . . . . . . . . . . . . . . . . . . 152 8.2.3. Special Stateids . . . . . . . . . . . . . . . . . . 152
8.2.4. Stateid Lifetime and Validation . . . . . . . . . . 153 8.2.4. Stateid Lifetime and Validation . . . . . . . . . . 154
8.2.5. Stateid Use for I/O Operations . . . . . . . . . . . 156 8.2.5. Stateid Use for I/O Operations . . . . . . . . . . . 157
8.2.6. Stateid Use for SETATTR Operations . . . . . . . . . 157 8.2.6. Stateid Use for SETATTR Operations . . . . . . . . . 158
8.3. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 157 8.3. Lease Renewal . . . . . . . . . . . . . . . . . . . . . 158
8.4. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 160 8.4. Crash Recovery . . . . . . . . . . . . . . . . . . . . . 160
8.4.1. Client Failure and Recovery . . . . . . . . . . . . 160 8.4.1. Client Failure and Recovery . . . . . . . . . . . . 161
8.4.2. Server Failure and Recovery . . . . . . . . . . . . 161 8.4.2. Server Failure and Recovery . . . . . . . . . . . . 161
8.4.3. Network Partitions and Recovery . . . . . . . . . . 165 8.4.3. Network Partitions and Recovery . . . . . . . . . . 165
8.5. Server Revocation of Locks . . . . . . . . . . . . . . . 169 8.5. Server Revocation of Locks . . . . . . . . . . . . . . . 170
8.6. Short and Long Leases . . . . . . . . . . . . . . . . . 170 8.6. Short and Long Leases . . . . . . . . . . . . . . . . . 171
8.7. Clocks, Propagation Delay, and Calculating Lease 8.7. Clocks, Propagation Delay, and Calculating Lease
Expiration . . . . . . . . . . . . . . . . . . . . . . . 171 Expiration . . . . . . . . . . . . . . . . . . . . . . . 171
8.8. Obsolete Locking Infrastructure From NFSv4.0 . . . . . . 171 8.8. Obsolete Locking Infrastructure From NFSv4.0 . . . . . . 172
9. File Locking and Share Reservations . . . . . . . . . . . . . 172 9. File Locking and Share Reservations . . . . . . . . . . . . . 173
9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 172 9.1. Opens and Byte-Range Locks . . . . . . . . . . . . . . . 173
9.1.1. State-owner Definition . . . . . . . . . . . . . . . 173 9.1.1. State-owner Definition . . . . . . . . . . . . . . . 173
9.1.2. Use of the Stateid and Locking . . . . . . . . . . . 173 9.1.2. Use of the Stateid and Locking . . . . . . . . . . . 174
9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 176 9.2. Lock Ranges . . . . . . . . . . . . . . . . . . . . . . 177
9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 177 9.3. Upgrading and Downgrading Locks . . . . . . . . . . . . 177
9.4. Stateid Seqid Values and Byte-Range Locks . . . . . . . 177 9.4. Stateid Seqid Values and Byte-Range Locks . . . . . . . 178
9.5. Issues with Multiple Open-Owners . . . . . . . . . . . . 177 9.5. Issues with Multiple Open-Owners . . . . . . . . . . . . 178
9.6. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 178 9.6. Blocking Locks . . . . . . . . . . . . . . . . . . . . . 179
9.7. Share Reservations . . . . . . . . . . . . . . . . . . . 179 9.7. Share Reservations . . . . . . . . . . . . . . . . . . . 180
9.8. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 180 9.8. OPEN/CLOSE Operations . . . . . . . . . . . . . . . . . 180
9.9. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 180 9.9. Open Upgrade and Downgrade . . . . . . . . . . . . . . . 181
9.10. Parallel OPENs . . . . . . . . . . . . . . . . . . . . . 181 9.10. Parallel OPENs . . . . . . . . . . . . . . . . . . . . . 182
9.11. Reclaim of Open and Byte-Range Locks . . . . . . . . . . 182 9.11. Reclaim of Open and Byte-Range Locks . . . . . . . . . . 183
10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 182 10. Client-Side Caching . . . . . . . . . . . . . . . . . . . . . 183
10.1. Performance Challenges for Client-Side Caching . . . . . 183 10.1. Performance Challenges for Client-Side Caching . . . . . 184
10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 184 10.2. Delegation and Callbacks . . . . . . . . . . . . . . . . 185
10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 186 10.2.1. Delegation Recovery . . . . . . . . . . . . . . . . 187
10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 188 10.3. Data Caching . . . . . . . . . . . . . . . . . . . . . . 189
10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 189 10.3.1. Data Caching and OPENs . . . . . . . . . . . . . . . 189
10.3.2. Data Caching and File Locking . . . . . . . . . . . 190 10.3.2. Data Caching and File Locking . . . . . . . . . . . 190
10.3.3. Data Caching and Mandatory File Locking . . . . . . 191 10.3.3. Data Caching and Mandatory File Locking . . . . . . 192
10.3.4. Data Caching and File Identity . . . . . . . . . . . 192 10.3.4. Data Caching and File Identity . . . . . . . . . . . 192
10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 193 10.4. Open Delegation . . . . . . . . . . . . . . . . . . . . 194
10.4.1. Open Delegation and Data Caching . . . . . . . . . . 195 10.4.1. Open Delegation and Data Caching . . . . . . . . . . 196
10.4.2. Open Delegation and File Locks . . . . . . . . . . . 196 10.4.2. Open Delegation and File Locks . . . . . . . . . . . 197
10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 197 10.4.3. Handling of CB_GETATTR . . . . . . . . . . . . . . . 198
10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 200 10.4.4. Recall of Open Delegation . . . . . . . . . . . . . 201
10.4.5. Clients that Fail to Honor Delegation Recalls . . . 202 10.4.5. Clients that Fail to Honor Delegation Recalls . . . 203
10.4.6. Delegation Revocation . . . . . . . . . . . . . . . 202 10.4.6. Delegation Revocation . . . . . . . . . . . . . . . 203
10.4.7. Delegations via WANT_DELEGATION . . . . . . . . . . 203 10.4.7. Delegations via WANT_DELEGATION . . . . . . . . . . 204
10.5. Data Caching and Revocation . . . . . . . . . . . . . . 204 10.5. Data Caching and Revocation . . . . . . . . . . . . . . 205
10.5.1. Revocation Recovery for Write Open Delegation . . . 204 10.5.1. Revocation Recovery for Write Open Delegation . . . 205
10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 205 10.6. Attribute Caching . . . . . . . . . . . . . . . . . . . 206
10.7. Data and Metadata Caching and Memory Mapped Files . . . 207 10.7. Data and Metadata Caching and Memory Mapped Files . . . 208
10.8. Name and Directory Caching without Directory 10.8. Name and Directory Caching without Directory
Delegations . . . . . . . . . . . . . . . . . . . . . . 209 Delegations . . . . . . . . . . . . . . . . . . . . . . 210
10.8.1. Name Caching . . . . . . . . . . . . . . . . . . . . 209 10.8.1. Name Caching . . . . . . . . . . . . . . . . . . . . 210
10.8.2. Directory Caching . . . . . . . . . . . . . . . . . 211 10.8.2. Directory Caching . . . . . . . . . . . . . . . . . 212
10.9. Directory Delegations . . . . . . . . . . . . . . . . . 212 10.9. Directory Delegations . . . . . . . . . . . . . . . . . 213
10.9.1. Introduction to Directory Delegations . . . . . . . 212 10.9.1. Introduction to Directory Delegations . . . . . . . 213
10.9.2. Directory Delegation Design . . . . . . . . . . . . 213 10.9.2. Directory Delegation Design . . . . . . . . . . . . 214
10.9.3. Attributes in Support of Directory Notifications . . 214 10.9.3. Attributes in Support of Directory Notifications . . 215
10.9.4. Directory Delegation Recall . . . . . . . . . . . . 214 10.9.4. Directory Delegation Recall . . . . . . . . . . . . 215
10.9.5. Directory Delegation Recovery . . . . . . . . . . . 215 10.9.5. Directory Delegation Recovery . . . . . . . . . . . 216
11. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 215 11. Multi-Server Namespace . . . . . . . . . . . . . . . . . . . 216
11.1. Location Attributes . . . . . . . . . . . . . . . . . . 215 11.1. Location Attributes . . . . . . . . . . . . . . . . . . 216
11.2. File System Presence or Absence . . . . . . . . . . . . 216 11.2. File System Presence or Absence . . . . . . . . . . . . 217
11.3. Getting Attributes for an Absent File System . . . . . . 217 11.3. Getting Attributes for an Absent File System . . . . . . 218
11.3.1. GETATTR Within an Absent File System . . . . . . . . 217 11.3.1. GETATTR Within an Absent File System . . . . . . . . 218
11.3.2. READDIR and Absent File Systems . . . . . . . . . . 218 11.3.2. READDIR and Absent File Systems . . . . . . . . . . 219
11.4. Uses of Location Information . . . . . . . . . . . . . . 219 11.4. Uses of Location Information . . . . . . . . . . . . . . 220
11.4.1. File System Replication . . . . . . . . . . . . . . 220 11.4.1. File System Replication . . . . . . . . . . . . . . 221
11.4.2. File System Migration . . . . . . . . . . . . . . . 220 11.4.2. File System Migration . . . . . . . . . . . . . . . 221
11.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 222 11.4.3. Referrals . . . . . . . . . . . . . . . . . . . . . 223
11.5. Location Entries and Server Identity . . . . . . . . . . 223 11.5. Location Entries and Server Identity . . . . . . . . . . 224
11.6. Additional Client-side Considerations . . . . . . . . . 224 11.6. Additional Client-side Considerations . . . . . . . . . 225
11.7. Effecting File System Transitions . . . . . . . . . . . 224 11.7. Effecting File System Transitions . . . . . . . . . . . 225
11.7.1. File System Transitions and Simultaneous Access . . 226 11.7.1. File System Transitions and Simultaneous Access . . 227
11.7.2. Simultaneous Use and Transparent Transitions . . . . 226 11.7.2. Simultaneous Use and Transparent Transitions . . . . 227
11.7.3. Filehandles and File System Transitions . . . . . . 229 11.7.3. Filehandles and File System Transitions . . . . . . 230
11.7.4. Fileids and File System Transitions . . . . . . . . 229 11.7.4. Fileids and File System Transitions . . . . . . . . 230
11.7.5. Fsids and File System Transitions . . . . . . . . . 231 11.7.5. Fsids and File System Transitions . . . . . . . . . 232
11.7.6. The Change Attribute and File System Transitions . . 231 11.7.6. The Change Attribute and File System Transitions . . 232
11.7.7. Lock State and File System Transitions . . . . . . . 232 11.7.7. Lock State and File System Transitions . . . . . . . 233
11.7.8. Write Verifiers and File System Transitions . . . . 236 11.7.8. Write Verifiers and File System Transitions . . . . 237
11.7.9. Readdir Cookies and Verifiers and File System 11.7.9. Readdir Cookies and Verifiers and File System
Transitions . . . . . . . . . . . . . . . . . . . . 236 Transitions . . . . . . . . . . . . . . . . . . . . 237
11.7.10. File System Data and File System Transitions . . . . 236 11.7.10. File System Data and File System Transitions . . . . 237
11.8. Effecting File System Referrals . . . . . . . . . . . . 238 11.8. Effecting File System Referrals . . . . . . . . . . . . 239
11.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 238 11.8.1. Referral Example (LOOKUP) . . . . . . . . . . . . . 239
11.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 242 11.8.2. Referral Example (READDIR) . . . . . . . . . . . . . 243
11.9. The Attribute fs_locations . . . . . . . . . . . . . . . 244 11.9. The Attribute fs_locations . . . . . . . . . . . . . . . 245
11.10. The Attribute fs_locations_info . . . . . . . . . . . . 247 11.10. The Attribute fs_locations_info . . . . . . . . . . . . 248
11.10.1. The fs_locations_server4 Structure . . . . . . . . . 251 11.10.1. The fs_locations_server4 Structure . . . . . . . . . 252
11.10.2. The fs_locations_info4 Structure . . . . . . . . . . 256 11.10.2. The fs_locations_info4 Structure . . . . . . . . . . 257
11.10.3. The fs_locations_item4 Structure . . . . . . . . . . 257 11.10.3. The fs_locations_item4 Structure . . . . . . . . . . 258
11.11. The Attribute fs_status . . . . . . . . . . . . . . . . 259 11.11. The Attribute fs_status . . . . . . . . . . . . . . . . 260
12. Parallel NFS (pNFS) . . . . . . . . . . . . . . . . . . . . . 263 12. Parallel NFS (pNFS) . . . . . . . . . . . . . . . . . . . . . 264
12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 263 12.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 264
12.2. pNFS Definitions . . . . . . . . . . . . . . . . . . . . 264 12.2. pNFS Definitions . . . . . . . . . . . . . . . . . . . . 265
12.2.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 265 12.2.1. Metadata . . . . . . . . . . . . . . . . . . . . . . 266
12.2.2. Metadata Server . . . . . . . . . . . . . . . . . . 265 12.2.2. Metadata Server . . . . . . . . . . . . . . . . . . 266
12.2.3. pNFS Client . . . . . . . . . . . . . . . . . . . . 265 12.2.3. pNFS Client . . . . . . . . . . . . . . . . . . . . 266
12.2.4. Storage Device . . . . . . . . . . . . . . . . . . . 265 12.2.4. Storage Device . . . . . . . . . . . . . . . . . . . 266
12.2.5. Storage Protocol . . . . . . . . . . . . . . . . . . 265 12.2.5. Storage Protocol . . . . . . . . . . . . . . . . . . 266
12.2.6. Control Protocol . . . . . . . . . . . . . . . . . . 266 12.2.6. Control Protocol . . . . . . . . . . . . . . . . . . 267
12.2.7. Layout Types . . . . . . . . . . . . . . . . . . . . 266 12.2.7. Layout Types . . . . . . . . . . . . . . . . . . . . 267
12.2.8. Layout . . . . . . . . . . . . . . . . . . . . . . . 267 12.2.8. Layout . . . . . . . . . . . . . . . . . . . . . . . 268
12.2.9. Layout Iomode . . . . . . . . . . . . . . . . . . . 267 12.2.9. Layout Iomode . . . . . . . . . . . . . . . . . . . 268
12.2.10. Device IDs . . . . . . . . . . . . . . . . . . . . . 268 12.2.10. Device IDs . . . . . . . . . . . . . . . . . . . . . 269
12.3. pNFS Operations . . . . . . . . . . . . . . . . . . . . 269 12.3. pNFS Operations . . . . . . . . . . . . . . . . . . . . 270
12.4. pNFS Attributes . . . . . . . . . . . . . . . . . . . . 270 12.4. pNFS Attributes . . . . . . . . . . . . . . . . . . . . 271
12.5. Layout Semantics . . . . . . . . . . . . . . . . . . . . 270 12.5. Layout Semantics . . . . . . . . . . . . . . . . . . . . 271
12.5.1. Guarantees Provided by Layouts . . . . . . . . . . . 270 12.5.1. Guarantees Provided by Layouts . . . . . . . . . . . 271
12.5.2. Getting a Layout . . . . . . . . . . . . . . . . . . 271 12.5.2. Getting a Layout . . . . . . . . . . . . . . . . . . 272
12.5.3. Layout Stateid . . . . . . . . . . . . . . . . . . . 272 12.5.3. Layout Stateid . . . . . . . . . . . . . . . . . . . 273
12.5.4. Committing a Layout . . . . . . . . . . . . . . . . 273 12.5.4. Committing a Layout . . . . . . . . . . . . . . . . 274
12.5.5. Recalling a Layout . . . . . . . . . . . . . . . . . 277 12.5.5. Recalling a Layout . . . . . . . . . . . . . . . . . 278
12.5.6. Revoking Layouts . . . . . . . . . . . . . . . . . . 284 12.5.6. Revoking Layouts . . . . . . . . . . . . . . . . . . 285
12.5.7. Metadata Server Write Propagation . . . . . . . . . 284 12.5.7. Metadata Server Write Propagation . . . . . . . . . 285
12.6. pNFS Mechanics . . . . . . . . . . . . . . . . . . . . . 285 12.6. pNFS Mechanics . . . . . . . . . . . . . . . . . . . . . 286
12.7. Recovery . . . . . . . . . . . . . . . . . . . . . . . . 286 12.7. Recovery . . . . . . . . . . . . . . . . . . . . . . . . 287
12.7.1. Recovery from Client Restart . . . . . . . . . . . . 286 12.7.1. Recovery from Client Restart . . . . . . . . . . . . 287
12.7.2. Dealing with Lease Expiration on the Client . . . . 287 12.7.2. Dealing with Lease Expiration on the Client . . . . 288
12.7.3. Dealing with Loss of Layout State on the Metadata 12.7.3. Dealing with Loss of Layout State on the Metadata
Server . . . . . . . . . . . . . . . . . . . . . . . 288 Server . . . . . . . . . . . . . . . . . . . . . . . 289
12.7.4. Recovery from Metadata Server Restart . . . . . . . 288 12.7.4. Recovery from Metadata Server Restart . . . . . . . 289
12.7.5. Operations During Metadata Server Grace Period . . . 290 12.7.5. Operations During Metadata Server Grace Period . . . 291
12.7.6. Storage Device Recovery . . . . . . . . . . . . . . 291 12.7.6. Storage Device Recovery . . . . . . . . . . . . . . 292
12.8. Metadata and Storage Device Roles . . . . . . . . . . . 291 12.8. Metadata and Storage Device Roles . . . . . . . . . . . 292
12.9. Security Considerations for pNFS . . . . . . . . . . . . 292 12.9. Security Considerations for pNFS . . . . . . . . . . . . 293
13. PNFS: NFSv4.1 File Layout Type . . . . . . . . . . . . . . . 293 13. PNFS: NFSv4.1 File Layout Type . . . . . . . . . . . . . . . 294
13.1. Client ID and Session Considerations . . . . . . . . . . 293 13.1. Client ID and Session Considerations . . . . . . . . . . 294
13.1.1. Sessions Considerations for Data Servers . . . . . . 295 13.1.1. Sessions Considerations for Data Servers . . . . . . 296
13.2. File Layout Definitions . . . . . . . . . . . . . . . . 296 13.2. File Layout Definitions . . . . . . . . . . . . . . . . 297
13.3. File Layout Data Types . . . . . . . . . . . . . . . . . 296 13.3. File Layout Data Types . . . . . . . . . . . . . . . . . 297
13.4. Interpreting the File Layout . . . . . . . . . . . . . . 300 13.4. Interpreting the File Layout . . . . . . . . . . . . . . 301
13.4.1. Determining the Stripe Unit Number . . . . . . . . . 300 13.4.1. Determining the Stripe Unit Number . . . . . . . . . 301
13.4.2. Interpreting the File Layout Using Sparse Packing . 300 13.4.2. Interpreting the File Layout Using Sparse Packing . 301
13.4.3. Interpreting the File Layout Using Dense Packing . . 303 13.4.3. Interpreting the File Layout Using Dense Packing . . 304
13.4.4. Sparse and Dense Stripe Unit Packing . . . . . . . . 305 13.4.4. Sparse and Dense Stripe Unit Packing . . . . . . . . 306
13.5. Data Server Multipathing . . . . . . . . . . . . . . . . 307 13.5. Data Server Multipathing . . . . . . . . . . . . . . . . 308
13.6. Operations Sent to NFSv4.1 Data Servers . . . . . . . . 308 13.6. Operations Sent to NFSv4.1 Data Servers . . . . . . . . 309
13.7. COMMIT Through Metadata Server . . . . . . . . . . . . . 310 13.7. COMMIT Through Metadata Server . . . . . . . . . . . . . 311
13.8. The Layout Iomode . . . . . . . . . . . . . . . . . . . 312 13.8. The Layout Iomode . . . . . . . . . . . . . . . . . . . 313
13.9. Metadata and Data Server State Coordination . . . . . . 312 13.9. Metadata and Data Server State Coordination . . . . . . 313
13.9.1. Global Stateid Requirements . . . . . . . . . . . . 312 13.9.1. Global Stateid Requirements . . . . . . . . . . . . 313
13.9.2. Data Server State Propagation . . . . . . . . . . . 313 13.9.2. Data Server State Propagation . . . . . . . . . . . 314
13.10. Data Server Component File Size . . . . . . . . . . . . 315 13.10. Data Server Component File Size . . . . . . . . . . . . 316
13.11. Layout Revocation and Fencing . . . . . . . . . . . . . 316 13.11. Layout Revocation and Fencing . . . . . . . . . . . . . 317
13.12. Security Considerations for the File Layout Type . . . . 316 13.12. Security Considerations for the File Layout Type . . . . 317
14. Internationalization . . . . . . . . . . . . . . . . . . . . 317 14. Internationalization . . . . . . . . . . . . . . . . . . . . 318
14.1. Stringprep profile for the utf8str_cs type . . . . . . . 318 14.1. Stringprep profile for the utf8str_cs type . . . . . . . 319
14.2. Stringprep profile for the utf8str_cis type . . . . . . 320 14.2. Stringprep profile for the utf8str_cis type . . . . . . 321
14.3. Stringprep profile for the utf8str_mixed type . . . . . 321 14.3. Stringprep profile for the utf8str_mixed type . . . . . 322
14.4. UTF-8 Capabilities . . . . . . . . . . . . . . . . . . . 323 14.4. UTF-8 Capabilities . . . . . . . . . . . . . . . . . . . 324
14.5. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 323 14.5. UTF-8 Related Errors . . . . . . . . . . . . . . . . . . 324
15. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 324 15. Error Values . . . . . . . . . . . . . . . . . . . . . . . . 325
15.1. Error Definitions . . . . . . . . . . . . . . . . . . . 324 15.1. Error Definitions . . . . . . . . . . . . . . . . . . . 325
15.1.1. General Errors . . . . . . . . . . . . . . . . . . . 326 15.1.1. General Errors . . . . . . . . . . . . . . . . . . . 327
15.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 328 15.1.2. Filehandle Errors . . . . . . . . . . . . . . . . . 329
15.1.3. Compound Structure Errors . . . . . . . . . . . . . 329 15.1.3. Compound Structure Errors . . . . . . . . . . . . . 330
15.1.4. File System Errors . . . . . . . . . . . . . . . . . 331 15.1.4. File System Errors . . . . . . . . . . . . . . . . . 332
15.1.5. State Management Errors . . . . . . . . . . . . . . 333 15.1.5. State Management Errors . . . . . . . . . . . . . . 334
15.1.6. Security Errors . . . . . . . . . . . . . . . . . . 334 15.1.6. Security Errors . . . . . . . . . . . . . . . . . . 335
15.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 334 15.1.7. Name Errors . . . . . . . . . . . . . . . . . . . . 335
15.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 335 15.1.8. Locking Errors . . . . . . . . . . . . . . . . . . . 336
15.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 336 15.1.9. Reclaim Errors . . . . . . . . . . . . . . . . . . . 337
15.1.10. pNFS Errors . . . . . . . . . . . . . . . . . . . . 337 15.1.10. pNFS Errors . . . . . . . . . . . . . . . . . . . . 338
15.1.11. Session Use Errors . . . . . . . . . . . . . . . . . 338 15.1.11. Session Use Errors . . . . . . . . . . . . . . . . . 339
15.1.12. Session Management Errors . . . . . . . . . . . . . 340 15.1.12. Session Management Errors . . . . . . . . . . . . . 341
15.1.13. Client Management Errors . . . . . . . . . . . . . . 340 15.1.13. Client Management Errors . . . . . . . . . . . . . . 341
15.1.14. Delegation Errors . . . . . . . . . . . . . . . . . 341 15.1.14. Delegation Errors . . . . . . . . . . . . . . . . . 342
15.1.15. Attribute Handling Errors . . . . . . . . . . . . . 341 15.1.15. Attribute Handling Errors . . . . . . . . . . . . . 342
15.1.16. Obsoleted Errors . . . . . . . . . . . . . . . . . . 342 15.1.16. Obsoleted Errors . . . . . . . . . . . . . . . . . . 343
15.2. Operations and their valid errors . . . . . . . . . . . 343 15.2. Operations and their valid errors . . . . . . . . . . . 344
15.3. Callback operations and their valid errors . . . . . . . 359 15.3. Callback operations and their valid errors . . . . . . . 360
15.4. Errors and the operations that use them . . . . . . . . 361 15.4. Errors and the operations that use them . . . . . . . . 362
16. NFSv4.1 Procedures . . . . . . . . . . . . . . . . . . . . . 375 16. NFSv4.1 Procedures . . . . . . . . . . . . . . . . . . . . . 376
16.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 375 16.1. Procedure 0: NULL - No Operation . . . . . . . . . . . . 376
16.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 376 16.2. Procedure 1: COMPOUND - Compound Operations . . . . . . 377
17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . 387 17. Operations: REQUIRED, RECOMMENDED, or OPTIONAL . . . . . . . 388
18. NFSv4.1 Operations . . . . . . . . . . . . . . . . . . . . . 390 18. NFSv4.1 Operations . . . . . . . . . . . . . . . . . . . . . 391
18.1. Operation 3: ACCESS - Check Access Rights . . . . . . . 390 18.1. Operation 3: ACCESS - Check Access Rights . . . . . . . 391
18.2. Operation 4: CLOSE - Close File . . . . . . . . . . . . 396 18.2. Operation 4: CLOSE - Close File . . . . . . . . . . . . 397
18.3. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 397 18.3. Operation 5: COMMIT - Commit Cached Data . . . . . . . . 398
18.4. Operation 6: CREATE - Create a Non-Regular File Object . 400 18.4. Operation 6: CREATE - Create a Non-Regular File Object . 401
18.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting 18.5. Operation 7: DELEGPURGE - Purge Delegations Awaiting
Recovery . . . . . . . . . . . . . . . . . . . . . . . . 403 Recovery . . . . . . . . . . . . . . . . . . . . . . . . 404
18.6. Operation 8: DELEGRETURN - Return Delegation . . . . . . 404 18.6. Operation 8: DELEGRETURN - Return Delegation . . . . . . 405
18.7. Operation 9: GETATTR - Get Attributes . . . . . . . . . 404 18.7. Operation 9: GETATTR - Get Attributes . . . . . . . . . 405
18.8. Operation 10: GETFH - Get Current Filehandle . . . . . . 406 18.8. Operation 10: GETFH - Get Current Filehandle . . . . . . 407
18.9. Operation 11: LINK - Create Link to a File . . . . . . . 407 18.9. Operation 11: LINK - Create Link to a File . . . . . . . 408
18.10. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 410 18.10. Operation 12: LOCK - Create Lock . . . . . . . . . . . . 411
18.11. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 414 18.11. Operation 13: LOCKT - Test For Lock . . . . . . . . . . 415
18.12. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 415 18.12. Operation 14: LOCKU - Unlock File . . . . . . . . . . . 416
18.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 417 18.13. Operation 15: LOOKUP - Lookup Filename . . . . . . . . . 418
18.14. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 418 18.14. Operation 16: LOOKUPP - Lookup Parent Directory . . . . 419
18.15. Operation 17: NVERIFY - Verify Difference in 18.15. Operation 17: NVERIFY - Verify Difference in
Attributes . . . . . . . . . . . . . . . . . . . . . . . 420 Attributes . . . . . . . . . . . . . . . . . . . . . . . 421
18.16. Operation 18: OPEN - Open a Regular File . . . . . . . . 421 18.16. Operation 18: OPEN - Open a Regular File . . . . . . . . 422
18.17. Operation 19: OPENATTR - Open Named Attribute 18.17. Operation 19: OPENATTR - Open Named Attribute
Directory . . . . . . . . . . . . . . . . . . . . . . . 440 Directory . . . . . . . . . . . . . . . . . . . . . . . 441
18.18. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 441 18.18. Operation 21: OPEN_DOWNGRADE - Reduce Open File Access . 442
18.19. Operation 22: PUTFH - Set Current Filehandle . . . . . . 442 18.19. Operation 22: PUTFH - Set Current Filehandle . . . . . . 444
18.20. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 443 18.20. Operation 23: PUTPUBFH - Set Public Filehandle . . . . . 444
18.21. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 445 18.21. Operation 24: PUTROOTFH - Set Root Filehandle . . . . . 446
18.22. Operation 25: READ - Read from File . . . . . . . . . . 445 18.22. Operation 25: READ - Read from File . . . . . . . . . . 447
18.23. Operation 26: READDIR - Read Directory . . . . . . . . . 448 18.23. Operation 26: READDIR - Read Directory . . . . . . . . . 449
18.24. Operation 27: READLINK - Read Symbolic Link . . . . . . 452 18.24. Operation 27: READLINK - Read Symbolic Link . . . . . . 453
18.25. Operation 28: REMOVE - Remove File System Object . . . . 453 18.25. Operation 28: REMOVE - Remove File System Object . . . . 454
18.26. Operation 29: RENAME - Rename Directory Entry . . . . . 455 18.26. Operation 29: RENAME - Rename Directory Entry . . . . . 456
18.27. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 459 18.27. Operation 31: RESTOREFH - Restore Saved Filehandle . . . 460
18.28. Operation 32: SAVEFH - Save Current Filehandle . . . . . 460 18.28. Operation 32: SAVEFH - Save Current Filehandle . . . . . 461
18.29. Operation 33: SECINFO - Obtain Available Security . . . 461 18.29. Operation 33: SECINFO - Obtain Available Security . . . 462
18.30. Operation 34: SETATTR - Set Attributes . . . . . . . . . 464 18.30. Operation 34: SETATTR - Set Attributes . . . . . . . . . 465
18.31. Operation 37: VERIFY - Verify Same Attributes . . . . . 466 18.31. Operation 37: VERIFY - Verify Same Attributes . . . . . 468
18.32. Operation 38: WRITE - Write to File . . . . . . . . . . 467 18.32. Operation 38: WRITE - Write to File . . . . . . . . . . 469
18.33. Operation 40: BACKCHANNEL_CTL - Backchannel control . . 472 18.33. Operation 40: BACKCHANNEL_CTL - Backchannel control . . 474
18.34. Operation 41: BIND_CONN_TO_SESSION . . . . . . . . . . . 473 18.34. Operation 41: BIND_CONN_TO_SESSION . . . . . . . . . . . 475
18.35. Operation 42: EXCHANGE_ID - Instantiate Client ID . . . 476 18.35. Operation 42: EXCHANGE_ID - Instantiate Client ID . . . 478
18.36. Operation 43: CREATE_SESSION - Create New Session and 18.36. Operation 43: CREATE_SESSION - Create New Session and
Confirm Client ID . . . . . . . . . . . . . . . . . . . 492 Confirm Client ID . . . . . . . . . . . . . . . . . . . 494
18.37. Operation 44: DESTROY_SESSION - Destroy existing 18.37. Operation 44: DESTROY_SESSION - Destroy existing
session . . . . . . . . . . . . . . . . . . . . . . . . 502 session . . . . . . . . . . . . . . . . . . . . . . . . 504
18.38. Operation 45: FREE_STATEID - Free stateid with no 18.38. Operation 45: FREE_STATEID - Free stateid with no
locks . . . . . . . . . . . . . . . . . . . . . . . . . 504 locks . . . . . . . . . . . . . . . . . . . . . . . . . 506
18.39. Operation 46: GET_DIR_DELEGATION - Get a directory 18.39. Operation 46: GET_DIR_DELEGATION - Get a directory
delegation . . . . . . . . . . . . . . . . . . . . . . . 505 delegation . . . . . . . . . . . . . . . . . . . . . . . 507
18.40. Operation 47: GETDEVICEINFO - Get Device Information . . 509 18.40. Operation 47: GETDEVICEINFO - Get Device Information . . 511
18.41. Operation 48: GETDEVICELIST - Get All Device Mappings 18.41. Operation 48: GETDEVICELIST - Get All Device Mappings
for a File System . . . . . . . . . . . . . . . . . . . 511 for a File System . . . . . . . . . . . . . . . . . . . 513
18.42. Operation 49: LAYOUTCOMMIT - Commit writes made using 18.42. Operation 49: LAYOUTCOMMIT - Commit writes made using
a layout . . . . . . . . . . . . . . . . . . . . . . . . 513 a layout . . . . . . . . . . . . . . . . . . . . . . . . 515
18.43. Operation 50: LAYOUTGET - Get Layout Information . . . . 516 18.43. Operation 50: LAYOUTGET - Get Layout Information . . . . 518
18.44. Operation 51: LAYOUTRETURN - Release Layout 18.44. Operation 51: LAYOUTRETURN - Release Layout
Information . . . . . . . . . . . . . . . . . . . . . . 520 Information . . . . . . . . . . . . . . . . . . . . . . 522
18.45. Operation 52: SECINFO_NO_NAME - Get Security on 18.45. Operation 52: SECINFO_NO_NAME - Get Security on
Unnamed Object . . . . . . . . . . . . . . . . . . . . . 525 Unnamed Object . . . . . . . . . . . . . . . . . . . . . 527
18.46. Operation 53: SEQUENCE - Supply per-procedure 18.46. Operation 53: SEQUENCE - Supply per-procedure
sequencing and control . . . . . . . . . . . . . . . . . 526 sequencing and control . . . . . . . . . . . . . . . . . 528
18.47. Operation 54: SET_SSV - Update SSV for a Client ID . . . 532 18.47. Operation 54: SET_SSV - Update SSV for a Client ID . . . 534
18.48. Operation 55: TEST_STATEID - Test stateids for 18.48. Operation 55: TEST_STATEID - Test stateids for
validity . . . . . . . . . . . . . . . . . . . . . . . . 534 validity . . . . . . . . . . . . . . . . . . . . . . . . 536
18.49. Operation 56: WANT_DELEGATION - Request Delegation . . . 536 18.49. Operation 56: WANT_DELEGATION - Request Delegation . . . 538
18.50. Operation 57: DESTROY_CLIENTID - Destroy existing 18.50. Operation 57: DESTROY_CLIENTID - Destroy existing
client ID . . . . . . . . . . . . . . . . . . . . . . . 540 client ID . . . . . . . . . . . . . . . . . . . . . . . 542
18.51. Operation 58: RECLAIM_COMPLETE - Indicates Reclaims 18.51. Operation 58: RECLAIM_COMPLETE - Indicates Reclaims
Finished . . . . . . . . . . . . . . . . . . . . . . . . 540 Finished . . . . . . . . . . . . . . . . . . . . . . . . 542
18.52. Operation 10044: ILLEGAL - Illegal operation . . . . . . 543 18.52. Operation 10044: ILLEGAL - Illegal operation . . . . . . 545
19. NFSv4.1 Callback Procedures . . . . . . . . . . . . . . . . . 543 19. NFSv4.1 Callback Procedures . . . . . . . . . . . . . . . . . 545
19.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 544 19.1. Procedure 0: CB_NULL - No Operation . . . . . . . . . . 546
19.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 544 19.2. Procedure 1: CB_COMPOUND - Compound Operations . . . . . 546
20. NFSv4.1 Callback Operations . . . . . . . . . . . . . . . . . 548 20. NFSv4.1 Callback Operations . . . . . . . . . . . . . . . . . 550
20.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . . . 548 20.1. Operation 3: CB_GETATTR - Get Attributes . . . . . . . . 550
20.2. Operation 4: CB_RECALL - Recall an Open Delegation . . . 549 20.2. Operation 4: CB_RECALL - Recall an Open Delegation . . . 551
20.3. Operation 5: CB_LAYOUTRECALL - Recall Layout from 20.3. Operation 5: CB_LAYOUTRECALL - Recall Layout from
Client . . . . . . . . . . . . . . . . . . . . . . . . . 550 Client . . . . . . . . . . . . . . . . . . . . . . . . . 552
20.4. Operation 6: CB_NOTIFY - Notify directory changes . . . 554 20.4. Operation 6: CB_NOTIFY - Notify directory changes . . . 556
20.5. Operation 7: CB_PUSH_DELEG - Offer Delegation to 20.5. Operation 7: CB_PUSH_DELEG - Offer Delegation to
Client . . . . . . . . . . . . . . . . . . . . . . . . . 558 Client . . . . . . . . . . . . . . . . . . . . . . . . . 560
20.6. Operation 8: CB_RECALL_ANY - Keep any N delegations . . 559 20.6. Operation 8: CB_RECALL_ANY - Keep any N delegations . . 561
20.7. Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal 20.7. Operation 9: CB_RECALLABLE_OBJ_AVAIL - Signal
Resources for Recallable Objects . . . . . . . . . . . . 561 Resources for Recallable Objects . . . . . . . . . . . . 563
20.8. Operation 10: CB_RECALL_SLOT - change flow control 20.8. Operation 10: CB_RECALL_SLOT - change flow control
limits . . . . . . . . . . . . . . . . . . . . . . . . . 562 limits . . . . . . . . . . . . . . . . . . . . . . . . . 564
20.9. Operation 11: CB_SEQUENCE - Supply backchannel 20.9. Operation 11: CB_SEQUENCE - Supply backchannel
sequencing and control . . . . . . . . . . . . . . . . . 563 sequencing and control . . . . . . . . . . . . . . . . . 565
20.10. Operation 12: CB_WANTS_CANCELLED - Cancel Pending 20.10. Operation 12: CB_WANTS_CANCELLED - Cancel Pending
Delegation Wants . . . . . . . . . . . . . . . . . . . . 565 Delegation Wants . . . . . . . . . . . . . . . . . . . . 567
20.11. Operation 13: CB_NOTIFY_LOCK - Notify of possible 20.11. Operation 13: CB_NOTIFY_LOCK - Notify of possible
lock availability . . . . . . . . . . . . . . . . . . . 566 lock availability . . . . . . . . . . . . . . . . . . . 568
20.12. Operation 14: CB_NOTIFY_DEVICEID - Notify device ID 20.12. Operation 14: CB_NOTIFY_DEVICEID - Notify device ID
changes . . . . . . . . . . . . . . . . . . . . . . . . 568 changes . . . . . . . . . . . . . . . . . . . . . . . . 570
20.13. Operation 10044: CB_ILLEGAL - Illegal Callback 20.13. Operation 10044: CB_ILLEGAL - Illegal Callback
Operation . . . . . . . . . . . . . . . . . . . . . . . 570 Operation . . . . . . . . . . . . . . . . . . . . . . . 572
21. Security Considerations . . . . . . . . . . . . . . . . . . . 570 21. Security Considerations . . . . . . . . . . . . . . . . . . . 572
22. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 572 22. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 574
22.1. Named Attribute Definitions . . . . . . . . . . . . . . 572 22.1. Named Attribute Definitions . . . . . . . . . . . . . . 574
22.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 572 22.2. ONC RPC Network Identifiers (netids) . . . . . . . . . . 574
22.3. Defining New Notifications . . . . . . . . . . . . . . . 573 22.3. Defining New Notifications . . . . . . . . . . . . . . . 575
22.4. Defining New Layout Types . . . . . . . . . . . . . . . 573 22.4. Defining New Layout Types . . . . . . . . . . . . . . . 575
22.5. Path Variable Definitions . . . . . . . . . . . . . . . 575 22.5. Path Variable Definitions . . . . . . . . . . . . . . . 577
22.5.1. Path Variable Values . . . . . . . . . . . . . . . . 575 22.5.1. Path Variable Values . . . . . . . . . . . . . . . . 577
22.5.2. Path Variable Names . . . . . . . . . . . . . . . . 575 22.5.2. Path Variable Names . . . . . . . . . . . . . . . . 577
23. References . . . . . . . . . . . . . . . . . . . . . . . . . 575 23. References . . . . . . . . . . . . . . . . . . . . . . . . . 577
23.1. Normative References . . . . . . . . . . . . . . . . . . 575 23.1. Normative References . . . . . . . . . . . . . . . . . . 577
23.2. Informative References . . . . . . . . . . . . . . . . . 577 23.2. Informative References . . . . . . . . . . . . . . . . . 579
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 579 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . 581
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 581 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 583
Intellectual Property and Copyright Statements . . . . . . . . . 582 Intellectual Property and Copyright Statements . . . . . . . . . 584
1. Introduction 1. Introduction
1.1. The NFS Version 4 Minor Version 1 Protocol 1.1. The NFS Version 4 Minor Version 1 Protocol
The NFS version 4 minor version 1 (NFSv4.1) protocol is the second The NFS version 4 minor version 1 (NFSv4.1) protocol is the second
minor version of the NFS version 4 (NFSv4) protocol. The first minor minor version of the NFS version 4 (NFSv4) protocol. The first minor
version, NFSv4.0 is described in [21]. It generally follows the version, NFSv4.0 is described in [21]. It generally follows the
guidelines for minor versioning model listed in Section 10 of RFC guidelines for minor versioning model listed in Section 10 of RFC
3530. However, it diverges from guidelines 11 ("a client and server 3530. However, it diverges from guidelines 11 ("a client and server
skipping to change at page 13, line 39 skipping to change at page 13, line 39
Client Owner The client owner is a unique string, opaque to the Client Owner The client owner is a unique string, opaque to the
server, which identifies a client. Multiple network connections server, which identifies a client. Multiple network connections
and source network addresses originating from those connections and source network addresses originating from those connections
may share a client owner. The server is expected to treat may share a client owner. The server is expected to treat
requests from connnections with the same client owner as coming requests from connnections with the same client owner as coming
from the same client. from the same client.
File System The collection of objects on a server (as identified by File System The collection of objects on a server (as identified by
the major identifier of a Server Owner, which is defined later in the major identifier of a Server Owner, which is defined later in
this section), that share the same fsid attribute (see this section), that share the same fsid attribute (see
Section 5.7.1.9). Section 5.8.1.9).
Lease An interval of time defined by the server for which the client Lease An interval of time defined by the server for which the client
is irrevocably granted a lock. At the end of a lease period the is irrevocably granted a lock. At the end of a lease period the
lock may be revoked if the lease has not been extended. The lock lock may be revoked if the lease has not been extended. The lock
must be revoked if a conflicting lock has been granted after the must be revoked if a conflicting lock has been granted after the
lease interval. lease interval.
All leases granted by a server have the same fixed interval. Note All leases granted by a server have the same fixed interval. Note
that the fixed interval was chosen to alleviate the expense a that the fixed interval was chosen to alleviate the expense a
server would have in maintaining state about variable length server would have in maintaining state about variable length
skipping to change at page 73, line 35 skipping to change at page 73, line 35
At this point the session has reached steady state. At this point the session has reached steady state.
2.10.10. Session Inactivity Timer 2.10.10. Session Inactivity Timer
The server MAY maintain a session inactivity timer for each session. The server MAY maintain a session inactivity timer for each session.
If the session inactivity timer expires, then the server MAY destroy If the session inactivity timer expires, then the server MAY destroy
the session. To avoid losing a session due to inactivity, the client the session. To avoid losing a session due to inactivity, the client
MUST renew the session inactivity timer. The length of session MUST renew the session inactivity timer. The length of session
inactivity timer MUST NOT be less than the lease_time attribute inactivity timer MUST NOT be less than the lease_time attribute
(Section 5.7.1.11). As with lease renewal (Section 8.3), when the (Section 5.8.1.11). As with lease renewal (Section 8.3), when the
server receives a SEQUENCE operation, it resets the session server receives a SEQUENCE operation, it resets the session
inactivity timer, and MUST NOT allow the timer to expire while the inactivity timer, and MUST NOT allow the timer to expire while the
rest of the operations in the COMPOUND procedure's request are still rest of the operations in the COMPOUND procedure's request are still
executing. Once the last operation has finished, the server MUST set executing. Once the last operation has finished, the server MUST set
the session inactivity timer to expire no sooner that the sum of the the session inactivity timer to expire no sooner that the sum of the
current time and the value of the lease_time attribute. current time and the value of the lease_time attribute.
2.10.11. Session Mechanics - Recovery 2.10.11. Session Mechanics - Recovery
2.10.11.1. Events Requiring Client Action 2.10.11.1. Events Requiring Client Action
skipping to change at page 85, line 19 skipping to change at page 85, line 19
3.3.13. layouttype4 3.3.13. layouttype4
enum layouttype4 { enum layouttype4 {
LAYOUT4_NFSV4_1_FILES = 0x1, LAYOUT4_NFSV4_1_FILES = 0x1,
LAYOUT4_OSD2_OBJECTS = 0x2, LAYOUT4_OSD2_OBJECTS = 0x2,
LAYOUT4_BLOCK_VOLUME = 0x3 LAYOUT4_BLOCK_VOLUME = 0x3
}; };
This data type indicates what type of layout is being used. The file This data type indicates what type of layout is being used. The file
server advertises the layout types it supports through the server advertises the layout types it supports through the
fs_layout_type file system attribute (Section 5.11.1). A client asks fs_layout_type file system attribute (Section 5.12.1). A client asks
for layouts of a particular type in LAYOUTGET, and processes those for layouts of a particular type in LAYOUTGET, and processes those
layouts in its layout-type-specific logic. layouts in its layout-type-specific logic.
The layouttype4 data type is 32 bits in length. The range The layouttype4 data type is 32 bits in length. The range
represented by the layout type is split into three parts. Type 0x0 represented by the layout type is split into three parts. Type 0x0
is reserved. Types within the range 0x00000001-0x7FFFFFFF are is reserved. Types within the range 0x00000001-0x7FFFFFFF are
globally unique and are assigned according to the description in globally unique and are assigned according to the description in
Section 22.4; they are maintained by IANA. Types within the range Section 22.4; they are maintained by IANA. Types within the range
0x80000000-0xFFFFFFFF are site specific and for private use only. 0x80000000-0xFFFFFFFF are site specific and for private use only.
skipping to change at page 87, line 33 skipping to change at page 87, line 33
3.3.19. layouthint4 3.3.19. layouthint4
struct layouthint4 { struct layouthint4 {
layouttype4 loh_type; layouttype4 loh_type;
opaque loh_body<>; opaque loh_body<>;
}; };
The layouthint4 data type is used by the client to pass in a hint The layouthint4 data type is used by the client to pass in a hint
about the type of layout it would like created for a particular file. about the type of layout it would like created for a particular file.
It is the data type specified by the layout_hint attribute described It is the data type specified by the layout_hint attribute described
in Section 5.11.4. The metadata server may ignore the hint, or may in Section 5.12.4. The metadata server may ignore the hint, or may
selectively ignore fields within the hint. This hint should be selectively ignore fields within the hint. This hint should be
provided at create time as part of the initial attributes within provided at create time as part of the initial attributes within
OPEN. The loh_body field is specific to the type of layout OPEN. The loh_body field is specific to the type of layout
(loh_type). The NFSv4.1 file-based layout uses the (loh_type). The NFSv4.1 file-based layout uses the
nfsv4_1_file_layouthint4 data type as defined in Section 13.3. nfsv4_1_file_layouthint4 data type as defined in Section 13.3.
3.3.20. layoutiomode4 3.3.20. layoutiomode4
enum layoutiomode4 { enum layoutiomode4 {
LAYOUTIOMODE4_READ = 1, LAYOUTIOMODE4_READ = 1,
skipping to change at page 100, line 5 skipping to change at page 99, line 35
time_access, time_backup, time_create, time_metadata, time_access, time_backup, time_create, time_metadata,
time_modify, mounted_on_fileid, dir_notif_delay, time_modify, mounted_on_fileid, dir_notif_delay,
dirent_notif_delay, dacl, sacl, layout_type, layout_hint, dirent_notif_delay, dacl, sacl, layout_type, layout_hint,
layout_blksize, layout_alignment, mdsthreshold, retention_get, layout_blksize, layout_alignment, mdsthreshold, retention_get,
retention_set, retentevt_get, retentevt_set, retention_hold, retention_set, retentevt_get, retentevt_set, retention_hold,
mode_set_masked mode_set_masked
For quota_avail_hard, quota_avail_soft, and quota_used see their For quota_avail_hard, quota_avail_soft, and quota_used see their
definitions below for the appropriate classification. definitions below for the appropriate classification.
5.5. REQUIRED Attributes - List and Definition References 5.5. Set-Only and Get-Only Attributes
Some REQUIRED and RECOMMENDED attributes are set-only, i.e. they can
be set via SETATTR but not retrieved via GETATTR. Similarly, some
REQUIRED and RECOMMENDED attributes are get-only, i.e. they can be
retrieved GETATTR but not set via SETATTR. If a client attempts to
set a get-only attribute or get a set-only attributes, the server
MUST return NFS4ERR_INVAL.
5.6. REQUIRED Attributes - List and Definition References
The list of REQUIRED attributes appears in Table 4. The meaning of
hte columns of the table are:
o Name: the name of attribute
o Id: the number assigned to the attribute. In the event of
conflicts between the assigned number and [12], the latter is
authoritative.
o Data Type: The XDR data type of the attribute.
o Acc: Access allowed. RD means read-only (GETATTR may retrieve,
SETATTR may not set). WR means write-only (SETATTR may set,
GETATTR may not retrieve). R/W means SETATTR may set, and GETATTR
may retrieve the attribute.
o Defined in: the section of this specification that describes the
attribute.
+--------------------+----+------------+-----+------------------+ +--------------------+----+------------+-----+------------------+
| name | Id | Data Type | Acc | Defined in: | | Name | Id | Data Type | Acc | Defined in: |
+--------------------+----+------------+-----+------------------+ +--------------------+----+------------+-----+------------------+
| supported_attrs | 0 | bitmap4 | RD | Section 5.7.1.1 | | supported_attrs | 0 | bitmap4 | RD | Section 5.8.1.1 |
| type | 1 | nfs_ftype4 | RD | Section 5.7.1.2 | | type | 1 | nfs_ftype4 | RD | Section 5.8.1.2 |
| fh_expire_type | 2 | uint32_t | RD | Section 5.7.1.3 | | fh_expire_type | 2 | uint32_t | RD | Section 5.8.1.3 |
| change | 3 | uint64_t | RD | Section 5.7.1.4 | | change | 3 | uint64_t | RD | Section 5.8.1.4 |
| size | 4 | uint64_t | R/W | Section 5.7.1.5 | | size | 4 | uint64_t | R/W | Section 5.8.1.5 |
| link_support | 5 | bool | RD | Section 5.7.1.6 | | link_support | 5 | bool | RD | Section 5.8.1.6 |
| symlink_support | 6 | bool | RD | Section 5.7.1.7 | | symlink_support | 6 | bool | RD | Section 5.8.1.7 |
| named_attr | 7 | bool | RD | Section 5.7.1.8 | | named_attr | 7 | bool | RD | Section 5.8.1.8 |
| fsid | 8 | fsid4 | RD | Section 5.7.1.9 | | fsid | 8 | fsid4 | RD | Section 5.8.1.9 |
| unique_handles | 9 | bool | RD | Section 5.7.1.10 | | unique_handles | 9 | bool | RD | Section 5.8.1.10 |
| lease_time | 10 | nfs_lease4 | RD | Section 5.7.1.11 | | lease_time | 10 | nfs_lease4 | RD | Section 5.8.1.11 |
| rdattr_error | 11 | enum | RD | Section 5.7.1.12 | | rdattr_error | 11 | enum | RD | Section 5.8.1.12 |
| filehandle | 19 | nfs_fh4 | RD | Section 5.7.1.13 | | filehandle | 19 | nfs_fh4 | RD | Section 5.8.1.13 |
| suppattr_exclcreat | 75 | bitmap4 | RD | Section 5.7.1.14 | | suppattr_exclcreat | 75 | bitmap4 | RD | Section 5.8.1.14 |
+--------------------+----+------------+-----+------------------+ +--------------------+----+------------+-----+------------------+
5.6. RECOMMENDED Attributes - List and Definition References Table 4
5.7. RECOMMENDED Attributes - List and Definition References
The RECOMMENDED attributes are defined in Table 5. The meanings of
the column headers are the same as Table 4; see Section 5.6 for the
meanings.
+--------------------+----+----------------+-----+------------------+ +--------------------+----+----------------+-----+------------------+
| name | Id | Data Type | Acc | Defined in: | | Name | Id | Data Type | Acc | Defined in: |
+--------------------+----+----------------+-----+------------------+ +--------------------+----+----------------+-----+------------------+
| acl | 12 | nfsace4<> | R/W | Section 6.2.1 | | acl | 12 | nfsace4<> | R/W | Section 6.2.1 |
| aclsupport | 13 | uint32_t | RD | Section 6.2.1.2 | | aclsupport | 13 | uint32_t | RD | Section 6.2.1.2 |
| archive | 14 | bool | R/W | Section 5.7.2.1 | | archive | 14 | bool | R/W | Section 5.8.2.1 |
| cansettime | 15 | bool | RD | Section 5.7.2.2 | | cansettime | 15 | bool | RD | Section 5.8.2.2 |
| case_insensitive | 16 | bool | RD | Section 5.7.2.3 | | case_insensitive | 16 | bool | RD | Section 5.8.2.3 |
| case_preserving | 17 | bool | RD | Section 5.7.2.4 | | case_preserving | 17 | bool | RD | Section 5.8.2.4 |
| change_policy | 60 | chg_policy4 | RD | Section 5.7.2.5 | | change_policy | 60 | chg_policy4 | RD | Section 5.8.2.5 |
| chown_restricted | 18 | bool | RD | Section 5.7.2.6 | | chown_restricted | 18 | bool | RD | Section 5.8.2.6 |
| dacl | 58 | nfsacl41 | R/W | Section 6.2.2 | | dacl | 58 | nfsacl41 | R/W | Section 6.2.2 |
| dir_notif_delay | 56 | nfstime4 | RD | Section 5.10.1 | | dir_notif_delay | 56 | nfstime4 | RD | Section 5.11.1 |
| dirent_notif_delay | 57 | nfstime4 | RD | Section 5.10.2 | | dirent_notif_delay | 57 | nfstime4 | RD | Section 5.11.2 |
| fileid | 20 | uint64_t | RD | Section 5.7.2.7 | | fileid | 20 | uint64_t | RD | Section 5.8.2.7 |
| files_avail | 21 | uint64_t | RD | Section 5.7.2.8 | | files_avail | 21 | uint64_t | RD | Section 5.8.2.8 |
| files_free | 22 | uint64_t | RD | Section 5.7.2.9 | | files_free | 22 | uint64_t | RD | Section 5.8.2.9 |
| files_total | 23 | uint64_t | RD | Section 5.7.2.10 | | files_total | 23 | uint64_t | RD | Section 5.8.2.10 |
| fs_charset_cap | 76 | uint32_t | RD | Section 5.7.2.11 | | fs_charset_cap | 76 | uint32_t | RD | Section 5.8.2.11 |
| fs_layout_type | 62 | layouttype4<> | RD | Section 5.11.1 | | fs_layout_type | 62 | layouttype4<> | RD | Section 5.12.1 |
| fs_locations | 24 | fs_locations | RD | Section 5.7.2.12 | | fs_locations | 24 | fs_locations | RD | Section 5.8.2.12 |
| fs_locations_info | 67 | * | RD | Section 5.7.2.13 | | fs_locations_info | 67 | * | RD | Section 5.8.2.13 |
| fs_status | 61 | fs4_status | RD | Section 5.7.2.14 | | fs_status | 61 | fs4_status | RD | Section 5.8.2.14 |
| hidden | 25 | bool | R/W | Section 5.7.2.15 | | hidden | 25 | bool | R/W | Section 5.8.2.15 |
| homogeneous | 26 | bool | RD | Section 5.7.2.16 | | homogeneous | 26 | bool | RD | Section 5.8.2.16 |
| layout_alignment | 66 | uint32_t | RD | Section 5.11.2 | | layout_alignment | 66 | uint32_t | RD | Section 5.12.2 |
| layout_blksize | 65 | uint32_t | RD | Section 5.11.3 | | layout_blksize | 65 | uint32_t | RD | Section 5.12.3 |
| layout_hint | 63 | layouthint4 | WRT | Section 5.11.4 | | layout_hint | 63 | layouthint4 | WRT | Section 5.12.4 |
| layout_type | 64 | layouttype4<> | RD | Section 5.11.5 | | layout_type | 64 | layouttype4<> | RD | Section 5.12.5 |
| maxfilesize | 27 | uint64_t | RD | Section 5.7.2.17 | | maxfilesize | 27 | uint64_t | RD | Section 5.8.2.17 |
| maxlink | 28 | uint32_t | RD | Section 5.7.2.18 | | maxlink | 28 | uint32_t | RD | Section 5.8.2.18 |
| maxname | 29 | uint32_t | RD | Section 5.7.2.19 | | maxname | 29 | uint32_t | RD | Section 5.8.2.19 |
| maxread | 30 | uint64_t | RD | Section 5.7.2.20 | | maxread | 30 | uint64_t | RD | Section 5.8.2.20 |
| maxwrite | 31 | uint64_t | RD | Section 5.7.2.21 | | maxwrite | 31 | uint64_t | RD | Section 5.8.2.21 |
| mdsthreshold | 68 | mdsthreshold4 | RD | Section 5.11.6 | | mdsthreshold | 68 | mdsthreshold4 | RD | Section 5.12.6 |
| mimetype | 32 | utf8<> | R/W | Section 5.7.2.22 | | mimetype | 32 | utf8<> | R/W | Section 5.8.2.22 |
| mode | 33 | mode4 | R/W | Section 6.2.4 | | mode | 33 | mode4 | R/W | Section 6.2.4 |
| mode_set_masked | 74 | mode_masked4 | WRT | Section 6.2.5 | | mode_set_masked | 74 | mode_masked4 | WRT | Section 6.2.5 |
| mounted_on_fileid | 55 | uint64_t | RD | Section 5.7.2.23 | | mounted_on_fileid | 55 | uint64_t | RD | Section 5.8.2.23 |
| no_trunc | 34 | bool | RD | Section 5.7.2.24 | | no_trunc | 34 | bool | RD | Section 5.8.2.24 |
| numlinks | 35 | uint32_t | RD | Section 5.7.2.25 | | numlinks | 35 | uint32_t | RD | Section 5.8.2.25 |
| owner | 36 | utf8<> | R/W | Section 5.7.2.26 | | owner | 36 | utf8<> | R/W | Section 5.8.2.26 |
| owner_group | 37 | utf8<> | R/W | Section 5.7.2.27 | | owner_group | 37 | utf8<> | R/W | Section 5.8.2.27 |
| quota_avail_hard | 38 | uint64_t | RD | Section 5.7.2.28 | | quota_avail_hard | 38 | uint64_t | RD | Section 5.8.2.28 |
| quota_avail_soft | 39 | uint64_t | RD | Section 5.7.2.29 | | quota_avail_soft | 39 | uint64_t | RD | Section 5.8.2.29 |
| quota_used | 40 | uint64_t | RD | Section 5.7.2.30 | | quota_used | 40 | uint64_t | RD | Section 5.8.2.30 |
| rawdev | 41 | specdata4 | RD | Section 5.7.2.31 | | rawdev | 41 | specdata4 | RD | Section 5.8.2.31 |
| retentevt_get | 71 | retention_get4 | RD | Section 5.12.3 | | retentevt_get | 71 | retention_get4 | RD | Section 5.13.3 |
| retentevt_set | 72 | retention_set4 | WRT | Section 5.12.4 | | retentevt_set | 72 | retention_set4 | WRT | Section 5.13.4 |
| retention_get | 69 | retention_get4 | RD | Section 5.12.1 | | retention_get | 69 | retention_get4 | RD | Section 5.13.1 |
| retention_hold | 73 | uint64_t | R/W | Section 5.12.5 | | retention_hold | 73 | uint64_t | R/W | Section 5.13.5 |
| retention_set | 70 | retention_set4 | WRT | Section 5.12.2 | | retention_set | 70 | retention_set4 | WRT | Section 5.13.2 |
| sacl | 59 | nfsacl41 | R/W | Section 6.2.3 | | sacl | 59 | nfsacl41 | R/W | Section 6.2.3 |
| space_avail | 42 | uint64_t | RD | Section 5.7.2.32 | | space_avail | 42 | uint64_t | RD | Section 5.8.2.32 |
| space_free | 43 | uint64_t | RD | Section 5.7.2.33 | | space_free | 43 | uint64_t | RD | Section 5.8.2.33 |
| space_total | 44 | uint64_t | RD | Section 5.7.2.34 | | space_total | 44 | uint64_t | RD | Section 5.8.2.34 |
| space_used | 45 | uint64_t | RD | Section 5.7.2.35 | | space_used | 45 | uint64_t | RD | Section 5.8.2.35 |
| system | 46 | bool | R/W | Section 5.7.2.36 | | system | 46 | bool | R/W | Section 5.8.2.36 |
| time_access | 47 | nfstime4 | RD | Section 5.7.2.37 | | time_access | 47 | nfstime4 | RD | Section 5.8.2.37 |
| time_access_set | 48 | settime4 | WRT | Section 5.7.2.38 | | time_access_set | 48 | settime4 | WRT | Section 5.8.2.38 |
| time_backup | 49 | nfstime4 | R/W | Section 5.7.2.39 | | time_backup | 49 | nfstime4 | R/W | Section 5.8.2.39 |
| time_create | 50 | nfstime4 | R/W | Section 5.7.2.40 | | time_create | 50 | nfstime4 | R/W | Section 5.8.2.40 |
| time_delta | 51 | nfstime4 | RD | Section 5.7.2.41 | | time_delta | 51 | nfstime4 | RD | Section 5.8.2.41 |
| time_metadata | 52 | nfstime4 | RD | Section 5.7.2.42 | | time_metadata | 52 | nfstime4 | RD | Section 5.8.2.42 |
| time_modify | 53 | nfstime4 | RD | Section 5.7.2.43 | | time_modify | 53 | nfstime4 | RD | Section 5.8.2.43 |
| time_modify_set | 54 | settime4 | WRT | Section 5.7.2.44 | | time_modify_set | 54 | settime4 | WRT | Section 5.8.2.44 |
+--------------------+----+----------------+-----+------------------+ +--------------------+----+----------------+-----+------------------+
Table 5
* fs_locations_info4 * fs_locations_info4
5.7. Attribute Definitions 5.8. Attribute Definitions
5.7.1. Definitions of REQUIRED Attributes 5.8.1. Definitions of REQUIRED Attributes
5.7.1.1. Attribute 0: supported_attrs 5.8.1.1. Attribute 0: supported_attrs
The bit vector which would retrieve all REQUIRED and RECOMMENDED The bit vector which would retrieve all REQUIRED and RECOMMENDED
attributes that are supported for this object. The scope of this attributes that are supported for this object. The scope of this
attribute applies to all objects with a matching fsid. attribute applies to all objects with a matching fsid.
5.7.1.2. Attribute 1: type 5.8.1.2. Attribute 1: type
Designates the type of an object in terms of one of a number of Designates the type of an object in terms of one of a number of
special constants: special constants:
o NF4REG designates a regular file. o NF4REG designates a regular file.
o NF4DIR designates a directory. o NF4DIR designates a directory.
o NF4BLK designates a block device special file. o NF4BLK designates a block device special file.
skipping to change at page 103, line 5 skipping to change at page 103, line 17
o The phrase "is a directory" means that the object is of type o The phrase "is a directory" means that the object is of type
NF4DIR or of type NF4ATTRDIR. NF4DIR or of type NF4ATTRDIR.
o The phrase "is a special file" means that the object is of one of o The phrase "is a special file" means that the object is of one of
the types NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO. the types NF4BLK, NF4CHR, NF4SOCK, or NF4FIFO.
o The phrase "is an ordinary file" means that the object is of type o The phrase "is an ordinary file" means that the object is of type
NF4REG or of type NF4NAMEDATTR. NF4REG or of type NF4NAMEDATTR.
5.7.1.3. Attribute 2: fh_expire_type 5.8.1.3. Attribute 2: fh_expire_type
Server uses this to specify filehandle expiration behavior to the Server uses this to specify filehandle expiration behavior to the
client. See Section 4 for additional description. client. See Section 4 for additional description.
5.7.1.4. Attribute 3: change 5.8.1.4. Attribute 3: change
A value created by the server that the client can use to determine if A value created by the server that the client can use to determine if
file data, directory contents or attributes of the object have been file data, directory contents or attributes of the object have been
modified. The server may return the object's time_metadata attribute modified. The server may return the object's time_metadata attribute
for this attribute's value but only if the file system object can not for this attribute's value but only if the file system object can not
be updated more frequently than the resolution of time_metadata. be updated more frequently than the resolution of time_metadata.
5.7.1.5. Attribute 4: size 5.8.1.5. Attribute 4: size
The size of the object in bytes. The size of the object in bytes.
5.7.1.6. Attribute 5: link_support 5.8.1.6. Attribute 5: link_support
True, if the object's file system supports hard links. True, if the object's file system supports hard links.
5.7.1.7. Attribute 6: symlink_support 5.8.1.7. Attribute 6: symlink_support
True, if the object's file system supports symbolic links. True, if the object's file system supports symbolic links.
5.7.1.8. Attribute 7: named_attr 5.8.1.8. Attribute 7: named_attr
True, if this object has named attributes. In other words, object True, if this object has named attributes. In other words, object
has a non-empty named attribute directory. has a non-empty named attribute directory.
5.7.1.9. Attribute 8: fsid 5.8.1.9. Attribute 8: fsid
Unique file system identifier for the file system holding this Unique file system identifier for the file system holding this
object. fsid contains major and minor components each of which are of object. fsid contains major and minor components each of which are of
data type uint64_t. data type uint64_t.
5.7.1.10. Attribute 9: unique_handles 5.8.1.10. Attribute 9: unique_handles
True, if two distinct filehandles guaranteed to refer to two True, if two distinct filehandles guaranteed to refer to two
different file system objects. different file system objects.
5.7.1.11. Attribute 10: lease_time 5.8.1.11. Attribute 10: lease_time
Duration of leases at server in seconds. Duration of leases at server in seconds.
5.7.1.12. Attribute 11: rdattr_error 5.8.1.12. Attribute 11: rdattr_error
Error returned from getattr during readdir. Error returned from getattr during readdir.
5.7.1.13. Attribute 19: filehandle 5.8.1.13. Attribute 19: filehandle
The filehandle of this object (primarily for readdir requests). The filehandle of this object (primarily for readdir requests).
5.7.1.14. Attribute 75: suppattr_exclcreat 5.8.1.14. Attribute 75: suppattr_exclcreat
The bit vector which would set all REQUIRED and RECOMMENDED The bit vector which would set all REQUIRED and RECOMMENDED
attributes that are supported by the EXCLUSIVE4_1 method of file attributes that are supported by the EXCLUSIVE4_1 method of file
creation via the OPEN operation. The scope of this attribute applies creation via the OPEN operation. The scope of this attribute applies
to all objects with a matching fsid. to all objects with a matching fsid.
5.7.2. Definitions of Uncategorized RECOMMENDED Attributes 5.8.2. Definitions of Uncategorized RECOMMENDED Attributes
The definitions of most of the RECOMMENDED attributes follow. The definitions of most of the RECOMMENDED attributes follow.
Collections that share a common category are defined in other Collections that share a common category are defined in other
sections. sections.
5.7.2.1. Attribute 14: archive 5.8.2.1. Attribute 14: archive
True, if this file has been archived since the time of last True, if this file has been archived since the time of last
modification (deprecated in favor of time_backup). modification (deprecated in favor of time_backup).
5.7.2.2. Attribute 15: cansettime 5.8.2.2. Attribute 15: cansettime
True, if the server able to change the times for a file system object True, if the server able to change the times for a file system object
as specified in a SETATTR operation. as specified in a SETATTR operation.
5.7.2.3. Attribute 16: case_insensitive 5.8.2.3. Attribute 16: case_insensitive
True, if file name comparisons on this file system are case True, if file name comparisons on this file system are case
insensitive. insensitive.
5.7.2.4. Attribute 17: case_preserving 5.8.2.4. Attribute 17: case_preserving
True, if file name case on this file system is preserved. True, if file name case on this file system is preserved.
5.7.2.5. Attribute 60: change_policy 5.8.2.5. Attribute 60: change_policy
A value created by the server that the client can use to determine if A value created by the server that the client can use to determine if
some server policy related to the current file system has been some server policy related to the current file system has been
subject to change. If the value remains the same then the client can subject to change. If the value remains the same then the client can
be sure that the values of the attributes related to fs location and be sure that the values of the attributes related to fs location and
the fss_type field of the fs_status attribute have not changed. On the fss_type field of the fs_status attribute have not changed. On
the other hand, a change in this value does necessarily imply a the other hand, a change in this value does necessarily imply a
change in policy. It is up to the client to interrogate the server change in policy. It is up to the client to interrogate the server
to determine if some policy relevant to it has changed. See to determine if some policy relevant to it has changed. See
Section 3.3.6 for details. Section 3.3.6 for details.
This attribute MUST change when the value returned by the This attribute MUST change when the value returned by the
fs_locations or fs_locations_info attribute changes, when a file fs_locations or fs_locations_info attribute changes, when a file
system goes from read-only to writable or vice versa, or when the system goes from read-only to writable or vice versa, or when the
allowable set of security flavors for the file system or any part allowable set of security flavors for the file system or any part
thereof is changed. thereof is changed.
5.7.2.6. Attribute 18: chown_restricted 5.8.2.6. Attribute 18: chown_restricted
If TRUE, the server will reject any request to change either the If TRUE, the server will reject any request to change either the
owner or the group associated with a file if the caller is not a owner or the group associated with a file if the caller is not a
privileged user (for example, "root" in UNIX operating environments privileged user (for example, "root" in UNIX operating environments
or in Windows 2000 the "Take Ownership" privilege). or in Windows 2000 the "Take Ownership" privilege).
5.7.2.7. Attribute 20: fileid 5.8.2.7. Attribute 20: fileid
A number uniquely identifying the file within the file system. A number uniquely identifying the file within the file system.
5.7.2.8. Attribute 21: files_avail 5.8.2.8. Attribute 21: files_avail
File slots available to this user on the file system containing this File slots available to this user on the file system containing this
object - this should be the smallest relevant limit. object - this should be the smallest relevant limit.
5.7.2.9. Attribute 22: files_free 5.8.2.9. Attribute 22: files_free
Free file slots on the file system containing this object - this Free file slots on the file system containing this object - this
should be the smallest relevant limit. should be the smallest relevant limit.
5.7.2.10. Attribute 23: files_total 5.8.2.10. Attribute 23: files_total
Total file slots on the file system containing this object. Total file slots on the file system containing this object.
5.7.2.11. Attribute 76: fs_charset_cap 5.8.2.11. Attribute 76: fs_charset_cap
Character set capabilities for this file system. See Section 14.4. Character set capabilities for this file system. See Section 14.4.
5.7.2.12. Attribute 24: fs_locations 5.8.2.12. Attribute 24: fs_locations
Locations where this file system may be found. If the server returns Locations where this file system may be found. If the server returns
NFS4ERR_MOVED as an error, this attribute MUST be supported. NFS4ERR_MOVED as an error, this attribute MUST be supported.
5.7.2.13. Attribute 67: fs_locations_info 5.8.2.13. Attribute 67: fs_locations_info
Full function file system location. Full function file system location.
5.7.2.14. Attribute 61: fs_status 5.8.2.14. Attribute 61: fs_status
Generic file system type information. Generic file system type information.
5.7.2.15. Attribute 25: hidden 5.8.2.15. Attribute 25: hidden
True, if the file is considered hidden with respect to the Windows True, if the file is considered hidden with respect to the Windows
API. API.
5.7.2.16. Attribute 26: homogeneous 5.8.2.16. Attribute 26: homogeneous
True, if this object's file system is homogeneous, i.e. are per file True, if this object's file system is homogeneous, i.e. are per file
system attributes the same for all file system's objects. system attributes the same for all file system's objects.
5.7.2.17. Attribute 27: maxfilesize 5.8.2.17. Attribute 27: maxfilesize
Maximum supported file size for the file system of this object. Maximum supported file size for the file system of this object.
5.7.2.18. Attribute 28: maxlink 5.8.2.18. Attribute 28: maxlink
Maximum number of links for this object. Maximum number of links for this object.
5.7.2.19. Attribute 29: maxname 5.8.2.19. Attribute 29: maxname
Maximum file name size supported for this object. Maximum file name size supported for this object.
5.7.2.20. Attribute 30: maxread 5.8.2.20. Attribute 30: maxread
Maximum read size supported for this object. Maximum read size supported for this object.
5.7.2.21. Attribute 31: maxwrite 5.8.2.21. Attribute 31: maxwrite
Maximum write size supported for this object. This attribute SHOULD Maximum write size supported for this object. This attribute SHOULD
be supported if the file is writable. Lack of this attribute can be supported if the file is writable. Lack of this attribute can
lead to the client either wasting bandwidth or not receiving the best lead to the client either wasting bandwidth or not receiving the best
performance. performance.
5.7.2.22. Attribute 32: mimetype 5.8.2.22. Attribute 32: mimetype
MIME body type/subtype of this object. MIME body type/subtype of this object.
5.7.2.23. Attribute 55: mounted_on_fileid 5.8.2.23. Attribute 55: mounted_on_fileid
Like fileid, but if the target filehandle is the root of a file Like fileid, but if the target filehandle is the root of a file
system, this attribute represents the fileid of the underlying system, this attribute represents the fileid of the underlying
directory. directory.
UNIX-based operating environments connect a file system into the UNIX-based operating environments connect a file system into the
namespace by connecting (mounting) the file system onto the existing namespace by connecting (mounting) the file system onto the existing
file object (the mount point, usually a directory) of an existing file object (the mount point, usually a directory) of an existing
file system. When the mount point's parent directory is read via an file system. When the mount point's parent directory is read via an
API like readdir(), the return results are directory entries, each API like readdir(), the return results are directory entries, each
skipping to change at page 108, line 5 skipping to change at page 108, line 18
fileid of a directory entry returned by readdir(). If fileid of a directory entry returned by readdir(). If
mounted_on_fileid is requested in a GETATTR operation, the server mounted_on_fileid is requested in a GETATTR operation, the server
should obey an invariant that has it returning a value that is equal should obey an invariant that has it returning a value that is equal
to the file object's entry in the object's parent directory, i.e. to the file object's entry in the object's parent directory, i.e.
what readdir() would have returned. Some operating environments what readdir() would have returned. Some operating environments
allow a series of two or more file systems to be mounted onto a allow a series of two or more file systems to be mounted onto a
single mount point. In this case, for the server to obey the single mount point. In this case, for the server to obey the
aforementioned invariant, it will need to find the base mount point, aforementioned invariant, it will need to find the base mount point,
and not the intermediate mount points. and not the intermediate mount points.
5.7.2.24. Attribute 34: no_trunc 5.8.2.24. Attribute 34: no_trunc
If this attribute is TRUE, then if the client uses a file name longer If this attribute is TRUE, then if the client uses a file name longer
than name_max, an error will be returned instead of the name being than name_max, an error will be returned instead of the name being
truncated. truncated.
5.7.2.25. Attribute 35: numlinks 5.8.2.25. Attribute 35: numlinks
Number of hard links to this object. Number of hard links to this object.
5.7.2.26. Attribute 36: owner 5.8.2.26. Attribute 36: owner
The string name of the owner of this object. The string name of the owner of this object.
5.7.2.27. Attribute 37: owner_group 5.8.2.27. Attribute 37: owner_group
The string name of the group ownership of this object. The string name of the group ownership of this object.
5.7.2.28. Attribute 38: quota_avail_hard 5.8.2.28. Attribute 38: quota_avail_hard
The value in bytes which represents the amount of additional disk The value in bytes which represents the amount of additional disk
space beyond the current allocation that can be allocated to this space beyond the current allocation that can be allocated to this
file or directory before further allocations will be refused. It is file or directory before further allocations will be refused. It is
understood that this space may be consumed by allocations to other understood that this space may be consumed by allocations to other
files or directories. files or directories.
5.7.2.29. Attribute 39: quota_avail_soft 5.8.2.29. Attribute 39: quota_avail_soft
The value in bytes which represents the amount of additional disk The value in bytes which represents the amount of additional disk
space that can be allocated to this file or directory before the user space that can be allocated to this file or directory before the user
may reasonably be warned. It is understood that this space may be may reasonably be warned. It is understood that this space may be
consumed by allocations to other files or directories though there is consumed by allocations to other files or directories though there is
a rule as to which other files or directories. a rule as to which other files or directories.
5.7.2.30. Attribute 40: quota_used 5.8.2.30. Attribute 40: quota_used
The value in bytes which represent the amount of disc space used by The value in bytes which represent the amount of disc space used by
this file or directory and possibly a number of other similar files this file or directory and possibly a number of other similar files
or directories, where the set of "similar" meets at least the or directories, where the set of "similar" meets at least the
criterion that allocating space to any file or directory in the set criterion that allocating space to any file or directory in the set
will reduce the "quota_avail_hard" of every other file or directory will reduce the "quota_avail_hard" of every other file or directory
in the set. in the set.
Note that there may be a number of distinct but overlapping sets of Note that there may be a number of distinct but overlapping sets of
files or directories for which a quota_used value is maintained. files or directories for which a quota_used value is maintained.
E.g. "all files with a given owner", "all files with a given group E.g. "all files with a given owner", "all files with a given group
owner". etc. owner". etc.
The server is at liberty to choose any of those sets but should do so The server is at liberty to choose any of those sets but should do so
in a repeatable way. The rule may be configured per file system or in a repeatable way. The rule may be configured per file system or
may be "choose the set with the smallest quota". may be "choose the set with the smallest quota".
5.7.2.31. Attribute 41: rawdev 5.8.2.31. Attribute 41: rawdev
Raw device identifier; the UNIX device major/minor node information. Raw device identifier; the UNIX device major/minor node information.
If the value of type is not NF4BLK or NF4CHR, the value returned If the value of type is not NF4BLK or NF4CHR, the value returned
SHOULD NOT be considered useful. SHOULD NOT be considered useful.
5.7.2.32. Attribute 42: space_avail 5.8.2.32. Attribute 42: space_avail
Disk space in bytes available to this user on the file system Disk space in bytes available to this user on the file system
containing this object - this should be the smallest relevant limit. containing this object - this should be the smallest relevant limit.
5.7.2.33. Attribute 43: space_free 5.8.2.33. Attribute 43: space_free
Free disk space in bytes on the file system containing this object - Free disk space in bytes on the file system containing this object -
this should be the smallest relevant limit. this should be the smallest relevant limit.
5.7.2.34. Attribute 44: space_total 5.8.2.34. Attribute 44: space_total
Total disk space in bytes on the file system containing this object. Total disk space in bytes on the file system containing this object.
5.7.2.35. Attribute 45: space_used 5.8.2.35. Attribute 45: space_used
Number of file system bytes allocated to this object. Number of file system bytes allocated to this object.
5.7.2.36. Attribute 46: system 5.8.2.36. Attribute 46: system
This attribute is TRUE if this file is a "system" file with respect This attribute is TRUE if this file is a "system" file with respect
to the Windows operating environment. to the Windows operating environment.
5.7.2.37. Attribute 47: time_access 5.8.2.37. Attribute 47: time_access
The time_access attribute represents the time of last access to the The time_access attribute represents the time of last access to the
object by a read that was satisfied by the server. The notion of object by a read that was satisfied by the server. The notion of
what is an "access" depends on server's operating environment and/or what is an "access" depends on server's operating environment and/or
the server's file system semantics. For example, for servers obeying the server's file system semantics. For example, for servers obeying
POSIX semantics, time_access would be updated only by the READLINK, POSIX semantics, time_access would be updated only by the READLINK,
READ, and READDIR operations and not any of the operations that READ, and READDIR operations and not any of the operations that
modify the content of the object. Of course, setting the modify the content of the object. Of course, setting the
corresponding time_access_set attribute is another way to modify the corresponding time_access_set attribute is another way to modify the
time_access attribute. time_access attribute.
Whenever the file object resides on a writable file system, the Whenever the file object resides on a writable file system, the
server should make best efforts to record time_access into stable server should make best efforts to record time_access into stable
storage. However, to mitigate the performance effects of doing so, storage. However, to mitigate the performance effects of doing so,
and most especially whenever the server is satisfying the read of the and most especially whenever the server is satisfying the read of the
object's content from its cache, the server MAY cache access time object's content from its cache, the server MAY cache access time
updates and lazily write them to stable storage. It is also updates and lazily write them to stable storage. It is also
acceptable to give administrators of the server the option to disable acceptable to give administrators of the server the option to disable
time_access updates. time_access updates.
5.7.2.38. Attribute 48: time_access_set 5.8.2.38. Attribute 48: time_access_set
Set the time of last access to the object. SETATTR use only. Set the time of last access to the object. SETATTR use only.
5.7.2.39. Attribute 49: time_backup 5.8.2.39. Attribute 49: time_backup
The time of last backup of the object. The time of last backup of the object.
5.7.2.40. Attribute 50: time_create 5.8.2.40. Attribute 50: time_create
The time of creation of the object. This attribute does not have any The time of creation of the object. This attribute does not have any
relation to the traditional UNIX file attribute "ctime" or "change relation to the traditional UNIX file attribute "ctime" or "change
time". time".
5.7.2.41. Attribute 51: time_delta 5.8.2.41. Attribute 51: time_delta
Smallest useful server time granularity. Smallest useful server time granularity.
5.7.2.42. Attribute 52: time_metadata 5.8.2.42. Attribute 52: time_metadata
The time of last metadata modification of the object. The time of last metadata modification of the object.
5.7.2.43. Attribute 53: time_modify 5.8.2.43. Attribute 53: time_modify
The time of last modification to the object. The time of last modification to the object.
5.7.2.44. Attribute 54: time_modify_set 5.8.2.44. Attribute 54: time_modify_set
Set the time of last modification to the object. SETATTR use only. Set the time of last modification to the object. SETATTR use only.
5.8. Interpreting owner and owner_group 5.9. Interpreting owner and owner_group
The RECOMMENDED attributes "owner" and "owner_group" (and also users The RECOMMENDED attributes "owner" and "owner_group" (and also users
and groups within the "acl" attribute) are represented in terms of a and groups within the "acl" attribute) are represented in terms of a
UTF-8 string. To avoid a representation that is tied to a particular UTF-8 string. To avoid a representation that is tied to a particular
underlying implementation at the client or server, the use of the underlying implementation at the client or server, the use of the
UTF-8 string has been chosen. Note that section 6.1 of RFC2624 [34] UTF-8 string has been chosen. Note that section 6.1 of RFC2624 [34]
provides additional rationale. It is expected that the client and provides additional rationale. It is expected that the client and
server will have their own local representation of owner and server will have their own local representation of owner and
owner_group that is used for local storage or presentation to the end owner_group that is used for local storage or presentation to the end
user. Therefore, it is expected that when these attributes are user. Therefore, it is expected that when these attributes are
skipping to change at page 112, line 37 skipping to change at page 113, line 5
groups in numeric form, a server SHOULD return an NFS4ERR_BADOWNER groups in numeric form, a server SHOULD return an NFS4ERR_BADOWNER
error when there is a valid translation for the user or owner error when there is a valid translation for the user or owner
designated in this way. In that case, the client must use the designated in this way. In that case, the client must use the
appropriate name@domain string and not the special form for appropriate name@domain string and not the special form for
compatibility. compatibility.
The owner string "nobody" may be used to designate an anonymous user, The owner string "nobody" may be used to designate an anonymous user,
which will be associated with a file created by a security principal which will be associated with a file created by a security principal
that cannot be mapped through normal means to the owner attribute. that cannot be mapped through normal means to the owner attribute.
5.9. Character Case Attributes 5.10. Character Case Attributes
With respect to the case_insensitive and case_preserving attributes, With respect to the case_insensitive and case_preserving attributes,
each UCS-4 character (which UTF-8 encodes) has a "long descriptive each UCS-4 character (which UTF-8 encodes) has a "long descriptive
name" RFC1345 [35] which may or may not include the word "CAPITAL" or name" RFC1345 [35] which may or may not include the word "CAPITAL" or
"SMALL". The presence of SMALL or CAPITAL allows an NFS server to "SMALL". The presence of SMALL or CAPITAL allows an NFS server to
implement unambiguous and efficient table driven mappings for case implement unambiguous and efficient table driven mappings for case
insensitive comparisons, and non-case-preserving storage. For insensitive comparisons, and non-case-preserving storage. For
general character handling and internationalization issues, see general character handling and internationalization issues, see
Section 14. Section 14.
5.10. Directory Notification Attributes 5.11. Directory Notification Attributes
As described in Section 18.39, the client can request a minimum delay As described in Section 18.39, the client can request a minimum delay
for notifications of changes to attributes, but the server is free to for notifications of changes to attributes, but the server is free to
ignore what the client requests. The client can determine in advance ignore what the client requests. The client can determine in advance
what notification delays the server will accept by issuing a GETATTR what notification delays the server will accept by issuing a GETATTR
for either or both of two directory notification attributes. When for either or both of two directory notification attributes. When
the client calls the GET_DIR_DELEGATION operation and asks for the client calls the GET_DIR_DELEGATION operation and asks for
attribute change notifications, it should request notification delays attribute change notifications, it should request notification delays
that are no less than the values in the server-provided attributes. that are no less than the values in the server-provided attributes.
5.10.1. Attribute 56: dir_notif_delay 5.11.1. Attribute 56: dir_notif_delay
The dir_notif_delay attribute is the minimum number of seconds the The dir_notif_delay attribute is the minimum number of seconds the
server will delay before notifying the client of a change to the server will delay before notifying the client of a change to the
directory's attributes. directory's attributes.
5.10.2. Attribute 57: dirent_notif_delay 5.11.2. Attribute 57: dirent_notif_delay
The dirent_notif_delay attribute is the minimum number of seconds the The dirent_notif_delay attribute is the minimum number of seconds the
server will delay before notifying the client of a change to a file server will delay before notifying the client of a change to a file
object that has an entry in the directory. object that has an entry in the directory.
5.11. pNFS Attribute Definitions 5.12. pNFS Attribute Definitions
5.11.1. Attribute 62: fs_layout_type 5.12.1. Attribute 62: fs_layout_type
The fs_layout_type attribute (see Section 3.3.13) applies to a file The fs_layout_type attribute (see Section 3.3.13) applies to a file
system and indicates what layout types are supported by the file system and indicates what layout types are supported by the file
system. When the client encounters a new fsid, the client SHOULD system. When the client encounters a new fsid, the client SHOULD
obtain the value for the fs_layout_type attribute associated with the obtain the value for the fs_layout_type attribute associated with the
new file system. This attribute is used by the client to determine new file system. This attribute is used by the client to determine
if the layout types supported by the server match any of the client's if the layout types supported by the server match any of the client's
supported layout types. supported layout types.
5.11.2. Attribute 66: layout_alignment 5.12.2. Attribute 66: layout_alignment
When a client holds layouts on files of a file system, the When a client holds layouts on files of a file system, the
layout_alignment attribute indicates the preferred alignment for I/O layout_alignment attribute indicates the preferred alignment for I/O
to files on that file system. Where possible, the client should send to files on that file system. Where possible, the client should send
READ and WRITE operations with offsets that are whole multiples of READ and WRITE operations with offsets that are whole multiples of
the layout_alignment attribute. the layout_alignment attribute.
5.11.3. Attribute 65: layout_blksize 5.12.3. Attribute 65: layout_blksize
When a client holds layouts on files of a file system, the When a client holds layouts on files of a file system, the
layout_blksize attribute indicates the preferred block size for I/O layout_blksize attribute indicates the preferred block size for I/O
to files on that file system. Where possible, the client should send to files on that file system. Where possible, the client should send
READ operations with a count argument that is a whole multiple of READ operations with a count argument that is a whole multiple of
layout_blksize, and WRITE operations with a data argument of size layout_blksize, and WRITE operations with a data argument of size
that is a whole multiple of layout_blksize. that is a whole multiple of layout_blksize.
5.11.4. Attribute 63: layout_hint 5.12.4. Attribute 63: layout_hint
The layout_hint attribute (see Section 3.3.19) may be set on newly The layout_hint attribute (see Section 3.3.19) may be set on newly
created files to influence the metadata server's choice for the created files to influence the metadata server's choice for the
file's layout. If possible, this attribute is one of those set in file's layout. If possible, this attribute is one of those set in
the initial attributes within the OPEN operation. The metadata the initial attributes within the OPEN operation. The metadata
server may choose to ignore this attribute. The layout_hint server may choose to ignore this attribute. The layout_hint
attribute is a sub-set of the layout structure returned by LAYOUTGET. attribute is a sub-set of the layout structure returned by LAYOUTGET.
For example, instead of specifying particular devices, this would be For example, instead of specifying particular devices, this would be
used to suggest the stripe width of a file. The server used to suggest the stripe width of a file. The server
implementation determines which fields within the layout will be implementation determines which fields within the layout will be
used. used.
5.11.5. Attribute 64: layout_type 5.12.5. Attribute 64: layout_type
This attribute lists the layout type(s) available for a file. The This attribute lists the layout type(s) available for a file. The
value returned by the server is for informational purposes only. The value returned by the server is for informational purposes only. The
client will use the LAYOUTGET operation to obtain the information client will use the LAYOUTGET operation to obtain the information
needed in order to perform I/O. For example, the specific device needed in order to perform I/O. For example, the specific device
information for the file and its layout. information for the file and its layout.
5.11.6. Attribute 68: mdsthreshold 5.12.6. Attribute 68: mdsthreshold
This attribute is a server provided hint used to communicate to the This attribute is a server provided hint used to communicate to the
client when it is more efficient to send READ and WRITE operations to client when it is more efficient to send READ and WRITE operations to
the metadata server or the data server. The two types of thresholds the metadata server or the data server. The two types of thresholds
described are file size thresholds and I/O size thresholds. If a described are file size thresholds and I/O size thresholds. If a
file's size is smaller than the file size threshold, data accesses file's size is smaller than the file size threshold, data accesses
SHOULD be sent to the metadata server. If an I/O request has a SHOULD be sent to the metadata server. If an I/O request has a
length that is below the I/O size threshold, the I/O SHOULD be sent length that is below the I/O size threshold, the I/O SHOULD be sent
to the metadata server. Each threshold type is specified separately to the metadata server. Each threshold type is specified separately
for READ and WRITE. for READ and WRITE.
skipping to change at page 115, line 9 skipping to change at page 115, line 26
The attribute is available on a per filehandle basis. If the current The attribute is available on a per filehandle basis. If the current
filehandle refers to a non-pNFS file or directory, the metadata filehandle refers to a non-pNFS file or directory, the metadata
server should return an attribute that is representative of the server should return an attribute that is representative of the
filehandle's file system. It is suggested that this attribute is filehandle's file system. It is suggested that this attribute is
queried as part of the OPEN operation. Due to dynamic system queried as part of the OPEN operation. Due to dynamic system
changes, the client should not assume that the attribute will remain changes, the client should not assume that the attribute will remain
constant for any specific time period, thus it should be periodically constant for any specific time period, thus it should be periodically
refreshed. refreshed.
5.12. Retention Attributes 5.13. Retention Attributes
Retention is a concept whereby a file object can be placed in an Retention is a concept whereby a file object can be placed in an
immutable, undeletable, unrenamable state for a fixed or infinite immutable, undeletable, unrenamable state for a fixed or infinite
duration of time. Once in this "retained" state, the file cannot be duration of time. Once in this "retained" state, the file cannot be
moved out of the state until the duration of retention has been moved out of the state until the duration of retention has been
reached. reached.
When retention is enabled, retention MUST extend to the data of the When retention is enabled, retention MUST extend to the data of the
file, and the name of file. The server MAY extend retention to any file, and the name of file. The server MAY extend retention to any
other property of the file, including any subset of REQUIRED, other property of the file, including any subset of REQUIRED,
RECOMMENDED, and named attributes, with the exceptions noted in this RECOMMENDED, and named attributes, with the exceptions noted in this
section. section.
Servers MAY support or not support retention on any file object type. Servers MAY support or not support retention on any file object type.
The five retention attributes are explained in the next subsections. The five retention attributes are explained in the next subsections.
5.12.1. Attribute 69: retention_get 5.13.1. Attribute 69: retention_get
If retention is enabled for the associated file, this attribute's If retention is enabled for the associated file, this attribute's
value represents the retention begin time of the file object. This value represents the retention begin time of the file object. This
attribute's value is only readable with the GETATTR operation and may attribute's value is only readable with the GETATTR operation and
not be modified by the SETATTR operation. The value of the attribute MUST NOT be modified by the SETATTR operation (Section 5.5). The
consists of: value of the attribute consists of:
const RET4_DURATION_INFINITE = 0xffffffffffffffff; const RET4_DURATION_INFINITE = 0xffffffffffffffff;
struct retention_get4 { struct retention_get4 {
uint64_t rg_duration; uint64_t rg_duration;
nfstime4 rg_begin_time<1>; nfstime4 rg_begin_time<1>;
}; };
The field rg_duration is the duration in seconds indicating how long The field rg_duration is the duration in seconds indicating how long
the file will be retained once retention is enabled. The field the file will be retained once retention is enabled. The field
rg_begin_time is an array of up to one absolute time value. If the rg_begin_time is an array of up to one absolute time value. If the
array is zero length, no beginning retention time has been array is zero length, no beginning retention time has been
established, and retention is not enabled. If rg_duration is equal established, and retention is not enabled. If rg_duration is equal
to RET4_DURATION_INFINITE, the file, once retention is enabled, will to RET4_DURATION_INFINITE, the file, once retention is enabled, will
be retained for an infinite duration. be retained for an infinite duration.
If (as soon as) rg_duration is zero, then rg_begin_time will be of If (as soon as) rg_duration is zero, then rg_begin_time will be of
zero length, and again, retention is not (no longer) enabled. zero length, and again, retention is not (no longer) enabled.
5.12.2. Attribute 70: retention_set 5.13.2. Attribute 70: retention_set
This attribute is used to set the retention duration and optionally This attribute is used to set the retention duration and optionally
enable retention for the associated file object. This attribute is enable retention for the associated file object. This attribute is
only modifiable via the SETATTR operation and may not be read with only modifiable via the SETATTR operation and MUST NOT be retrieved
the GETATTR operation. This attribute corresponds to retention_get. by the GETATTR operation (Section 5.5). This attribute corresponds
The value of the attribute consists of: to retention_get. The value of the attribute consists of:
struct retention_set4 { struct retention_set4 {
bool rs_enable; bool rs_enable;
uint64_t rs_duration<1>; uint64_t rs_duration<1>;
}; };
If the client sets rs_enable to TRUE, then it is enabling retention If the client sets rs_enable to TRUE, then it is enabling retention
on the file object with the begin time of retention starting from the on the file object with the begin time of retention starting from the
server's current time and date. The duration of the retention can server's current time and date. The duration of the retention can
also be provided if the rs_duration array is of length one. The also be provided if the rs_duration array is of length one. The
skipping to change at page 116, line 40 skipping to change at page 117, line 8
The following rules apply to both the retention_set and retentevt_set The following rules apply to both the retention_set and retentevt_set
attributes. attributes.
o As long as retention is not enabled, the client is permitted to o As long as retention is not enabled, the client is permitted to
decrease the duration. decrease the duration.
o The duration can always be set to an equal or higher value, even o The duration can always be set to an equal or higher value, even
if retention is enabled. Note that once retention is enabled, the if retention is enabled. Note that once retention is enabled, the
actual duration (as returned by the retention_get or retentevt_get actual duration (as returned by the retention_get or retentevt_get
attributes, see Section 5.12.1 or Section 5.12.3), is constantly attributes, see Section 5.13.1 or Section 5.13.3), is constantly
counting down to zero (one unit per second), unless the duration counting down to zero (one unit per second), unless the duration
was set to RET4_DURATION_INFINITE. Thus it will not be possible was set to RET4_DURATION_INFINITE. Thus it will not be possible
for the client to precisely extend the duration on a file that has for the client to precisely extend the duration on a file that has
retention enabled. retention enabled.
o While retention is enabled, attempts to disable retention or o While retention is enabled, attempts to disable retention or
decrease the retention's duration MUST fail with the error decrease the retention's duration MUST fail with the error
NFS4ERR_INVAL. NFS4ERR_INVAL.
o If the principal attempting to change retention_set or o If the principal attempting to change retention_set or
retentevt_set does not have ACE4_WRITE_RETENTION permissions, the retentevt_set does not have ACE4_WRITE_RETENTION permissions, the
attempt MUST fail with NFS4ERR_ACCESS. attempt MUST fail with NFS4ERR_ACCESS.
5.12.3. Attribute 71: retentevt_get 5.13.3. Attribute 71: retentevt_get
Get the event-based retention duration, and if enabled, the event- Get the event-based retention duration, and if enabled, the event-
based retention begin time of the file object. This attribute is based retention begin time of the file object. This attribute is
like retention_get but refers to event-based retention. The event like retention_get but refers to event-based retention. The event
that triggers event-based retention is not defined by the NFSv4.1 that triggers event-based retention is not defined by the NFSv4.1
specification. specification.
5.12.4. Attribute 72: retentevt_set 5.13.4. Attribute 72: retentevt_set
Set the event-based retention duration, and optionally enable event- Set the event-based retention duration, and optionally enable event-
based retention on the file object. This attribute corresponds to based retention on the file object. This attribute corresponds to
retentevt_get, is like retention_set, but refers to event-based retentevt_get, is like retention_set, but refers to event-based
retention. When event based retention is set, the file MUST be retention. When event based retention is set, the file MUST be
retained even if non-event-based retention has been set, and the retained even if non-event-based retention has been set, and the
duration of non-event-based retention has been reached. Conversely, duration of non-event-based retention has been reached. Conversely,
when non-event-based retention has been set, the file MUST be when non-event-based retention has been set, the file MUST be
retained even if event-based retention has been set, and the duration retained even if event-based retention has been set, and the duration
of event-based retention has been reached. The server MAY restrict of event-based retention has been reached. The server MAY restrict
the enabling of event-based retention or the duration of event-based the enabling of event-based retention or the duration of event-based
retention on the basis of the ACE4_WRITE_RETENTION ACL permission. retention on the basis of the ACE4_WRITE_RETENTION ACL permission.
The enabling of event-based retention MUST NOT prevent the enabling The enabling of event-based retention MUST NOT prevent the enabling
of non-event-based retention nor the modification of the of non-event-based retention nor the modification of the
retention_hold attribute. retention_hold attribute.
5.12.5. Attribute 73: retention_hold 5.13.5. Attribute 73: retention_hold
Get or set administrative retention holds, one hold per bit position. Get or set administrative retention holds, one hold per bit position.
This attribute allows one to 64 administrative holds, one hold per This attribute allows one to 64 administrative holds, one hold per
bit on the attribute. If retention_hold is not zero, then the file bit on the attribute. If retention_hold is not zero, then the file
MUST NOT be deleted, renamed, or modified, even if the duration on MUST NOT be deleted, renamed, or modified, even if the duration on
enabled event or non-event-based retention has been reached. The enabled event or non-event-based retention has been reached. The
server MAY restrict the modification of retention_hold on the basis server MAY restrict the modification of retention_hold on the basis
of the ACE4_WRITE_RETENTION_HOLD ACL permission. The enabling of of the ACE4_WRITE_RETENTION_HOLD ACL permission. The enabling of
administration retention holds does not prevent the enabling of administration retention holds does not prevent the enabling of
skipping to change at page 214, line 17 skipping to change at page 215, line 17
Delegations can be recalled by the server at any time. Normally, the Delegations can be recalled by the server at any time. Normally, the
server will recall the delegation when the directory changes in a way server will recall the delegation when the directory changes in a way
that is not covered by the notification, or when the directory that is not covered by the notification, or when the directory
changes and notifications have not been requested. If another client changes and notifications have not been requested. If another client
removes the directory for which a delegation has been granted, the removes the directory for which a delegation has been granted, the
server will recall the delegation. server will recall the delegation.
10.9.3. Attributes in Support of Directory Notifications 10.9.3. Attributes in Support of Directory Notifications
See Section 5.10 for a description of the attributes associated with See Section 5.11 for a description of the attributes associated with
directory notifications. directory notifications.
10.9.4. Directory Delegation Recall 10.9.4. Directory Delegation Recall
The server will recall the directory delegation by sending a callback The server will recall the directory delegation by sending a callback
to the client. It will use the same callback procedure as used for to the client. It will use the same callback procedure as used for
recalling file delegations. The server will recall the delegation recalling file delegations. The server will recall the delegation
when the directory changes in a way that is not covered by the when the directory changes in a way that is not covered by the
notification. However the server need not recall the delegation if notification. However the server need not recall the delegation if
attributes of an entry within the directory change. attributes of an entry within the directory change.
skipping to change at page 270, line 23 skipping to change at page 271, line 23
CB_RECALLABLE_OBJ_AVAIL (Section 20.7) tells a client that a CB_RECALLABLE_OBJ_AVAIL (Section 20.7) tells a client that a
recallable object that it was denied (in case of pNFS, a layout, recallable object that it was denied (in case of pNFS, a layout,
denied by LAYOUTGET) due to resource exhaustion, is now available. denied by LAYOUTGET) due to resource exhaustion, is now available.
CB_NOTIFY_DEVICEID (Section 20.12) Notifies the client of changes to CB_NOTIFY_DEVICEID (Section 20.12) Notifies the client of changes to
device IDs. device IDs.
12.4. pNFS Attributes 12.4. pNFS Attributes
A number of attributes specific to pNFS are listed and described in A number of attributes specific to pNFS are listed and described in
Section 5.11 Section 5.12
12.5. Layout Semantics 12.5. Layout Semantics
12.5.1. Guarantees Provided by Layouts 12.5.1. Guarantees Provided by Layouts
Layouts grant to the client the ability to access data located at a Layouts grant to the client the ability to access data located at a
storage device with the appropriate storage protocol. The client is storage device with the appropriate storage protocol. The client is
guaranteed the layout will be recalled when one of two things occur; guaranteed the layout will be recalled when one of two things occur;
either a conflicting layout is requested or the state encapsulated by either a conflicting layout is requested or the state encapsulated by
the layout becomes invalid and this can happen when an event directly the layout becomes invalid and this can happen when an event directly
skipping to change at page 272, line 22 skipping to change at page 273, line 22
The storage protocol used by the client to access the data on the The storage protocol used by the client to access the data on the
storage device is determined by the layout's type. The client is storage device is determined by the layout's type. The client is
responsible for matching the layout type with an available method to responsible for matching the layout type with an available method to
interpret and use the layout. The method for this layout type interpret and use the layout. The method for this layout type
selection is outside the scope of the pNFS functionality. selection is outside the scope of the pNFS functionality.
Although the metadata server is in control of the layout for a file, Although the metadata server is in control of the layout for a file,
the pNFS client can provide hints to the server when a file is opened the pNFS client can provide hints to the server when a file is opened
or created about the preferred layout type and aggregation schemes. or created about the preferred layout type and aggregation schemes.
pNFS introduces a layout_hint (Section 5.11.4) attribute that the pNFS introduces a layout_hint (Section 5.12.4) attribute that the
client can set at file creation time to provide a hint to the server client can set at file creation time to provide a hint to the server
for new files. Setting this attribute separately, after the file has for new files. Setting this attribute separately, after the file has
been created might make it difficult, or impossible, for the server been created might make it difficult, or impossible, for the server
implementation to comply. implementation to comply.
Because the EXCLUSIVE4 createmode4 does not allow the setting of Because the EXCLUSIVE4 createmode4 does not allow the setting of
attributes at file creation time, NFSv4.1 introduces the EXCLUSIVE4_1 attributes at file creation time, NFSv4.1 introduces the EXCLUSIVE4_1
createmode4, which does allow attributes to be set at file creation createmode4, which does allow attributes to be set at file creation
time. In addition, if the session is created with persistent reply time. In addition, if the session is created with persistent reply
caches, EXCLUSIVE4_1 is neither necessary nor allowed. Instead, caches, EXCLUSIVE4_1 is neither necessary nor allowed. Instead,
skipping to change at page 285, line 14 skipping to change at page 286, line 14
prevent reads being done that cannot be handled correctly. Note that prevent reads being done that cannot be handled correctly. Note that
the layouts MUST be recalled prior to the server responding to the the layouts MUST be recalled prior to the server responding to the
associated WRITE operations. associated WRITE operations.
12.6. pNFS Mechanics 12.6. pNFS Mechanics
This section describes the operations flow taken by a pNFS client to This section describes the operations flow taken by a pNFS client to
a metadata server and storage device. a metadata server and storage device.
When a pNFS client encounters a new FSID, it sends a GETATTR to the When a pNFS client encounters a new FSID, it sends a GETATTR to the
NFSv4.1 server for the fs_layout_type (Section 5.11.1) attribute. If NFSv4.1 server for the fs_layout_type (Section 5.12.1) attribute. If
the attribute returns at least one layout type, and the layout types the attribute returns at least one layout type, and the layout types
returned are among the set supported by the client, the client knows returned are among the set supported by the client, the client knows
that pNFS is a possibility for the file system. If, from the server that pNFS is a possibility for the file system. If, from the server
that returned the new FSID, the client does not have a client ID that that returned the new FSID, the client does not have a client ID that
came from an EXCHANGE_ID result that returned came from an EXCHANGE_ID result that returned
EXCHGID4_FLAG_USE_PNFS_MDS, it MUST send an EXCHANGE_ID to the server EXCHGID4_FLAG_USE_PNFS_MDS, it MUST send an EXCHANGE_ID to the server
with the EXCHGID4_FLAG_USE_PNFS_MDS bit set. If the server's with the EXCHGID4_FLAG_USE_PNFS_MDS bit set. If the server's
response does not have EXCHGID4_FLAG_USE_PNFS_MDS, then contrary to response does not have EXCHGID4_FLAG_USE_PNFS_MDS, then contrary to
what the fs_layout_type attribute said, the server does not support what the fs_layout_type attribute said, the server does not support
pNFS, and the client will not be able use pNFS to that server; in pNFS, and the client will not be able use pNFS to that server; in
skipping to change at page 296, line 40 skipping to change at page 297, line 40
server that has multiple stripe units per stripe MAY store each unit server that has multiple stripe units per stripe MAY store each unit
in a different data file (and depending on the implementation, will in a different data file (and depending on the implementation, will
possibly assign a unique data filehandle to each data file). possibly assign a unique data filehandle to each data file).
13.3. File Layout Data Types 13.3. File Layout Data Types
The high level NFSv4.1 layout types are nfsv4_1_file_layouthint4, The high level NFSv4.1 layout types are nfsv4_1_file_layouthint4,
nfsv4_1_file_layout_ds_addr4, and nfsv4_1_file_layout4. nfsv4_1_file_layout_ds_addr4, and nfsv4_1_file_layout4.
The SETATTR operation supports a layout hint attribute The SETATTR operation supports a layout hint attribute
(Section 5.11.4). When the client sets a layout hint (data type (Section 5.12.4). When the client sets a layout hint (data type
layouthint4) with a layout type of LAYOUT4_NFSV4_1_FILES (the layouthint4) with a layout type of LAYOUT4_NFSV4_1_FILES (the
loh_type field), the loh_body field contains a value of data type loh_type field), the loh_body field contains a value of data type
nfsv4_1_file_layouthint4. nfsv4_1_file_layouthint4.
const NFL4_UFLG_MASK = 0x0000003F; const NFL4_UFLG_MASK = 0x0000003F;
const NFL4_UFLG_DENSE = 0x00000001; const NFL4_UFLG_DENSE = 0x00000001;
const NFL4_UFLG_COMMIT_THRU_MDS = 0x00000002; const NFL4_UFLG_COMMIT_THRU_MDS = 0x00000002;
const NFL4_UFLG_STRIPE_UNIT_SIZE_MASK const NFL4_UFLG_STRIPE_UNIT_SIZE_MASK
= 0xFFFFFFC0; = 0xFFFFFFC0;
skipping to change at page 297, line 25 skipping to change at page 298, line 25
/* Encoded in the loh_body field of type layouthint4: */ /* Encoded in the loh_body field of type layouthint4: */
struct nfsv4_1_file_layouthint4 { struct nfsv4_1_file_layouthint4 {
uint32_t nflh_care; uint32_t nflh_care;
nfl_util4 nflh_util; nfl_util4 nflh_util;
count4 nflh_stripe_count; count4 nflh_stripe_count;
}; };
The generic layout hint structure is described in Section 3.3.19. The generic layout hint structure is described in Section 3.3.19.
The client uses the layout hint in the layout_hint (Section 5.11.4) The client uses the layout hint in the layout_hint (Section 5.12.4)
attribute to indicate the preferred type of layout to be used for a attribute to indicate the preferred type of layout to be used for a
newly created file. The LAYOUT4_NFSV4_1_FILES layout type-specific newly created file. The LAYOUT4_NFSV4_1_FILES layout type-specific
content for the layout hint is composed of three fields. The first content for the layout hint is composed of three fields. The first
field, nflh_care, is a set of flags indicating which values of the field, nflh_care, is a set of flags indicating which values of the
hint the client cares about. If the NFLH4_CARE_DENSE flag is set, hint the client cares about. If the NFLH4_CARE_DENSE flag is set,
then the client indicates in the second field, nflh_util, a then the client indicates in the second field, nflh_util, a
preference for how the data file is packed (Section 13.4.4), which is preference for how the data file is packed (Section 13.4.4), which is
controlled by the value of nflh_util & NFL4_UFLG_DENSE. If the controlled by the value of nflh_util & NFL4_UFLG_DENSE. If the
NFLH4_CARE_COMMIT_THRU_MDS flag is set, then the client indicates a NFLH4_CARE_COMMIT_THRU_MDS flag is set, then the client indicates a
preference for whether the client should send COMMIT operations to preference for whether the client should send COMMIT operations to
skipping to change at page 323, line 14 skipping to change at page 324, line 14
14.4. UTF-8 Capabilities 14.4. UTF-8 Capabilities
const FSCHARSET_CAP4_CONTAINS_NON_UTF8 = 0x1; const FSCHARSET_CAP4_CONTAINS_NON_UTF8 = 0x1;
const FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 = 0x2; const FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 = 0x2;
typedef uint32_t fs_charset_cap4; typedef uint32_t fs_charset_cap4;
Because some operating environments and file systems do not enforce Because some operating environments and file systems do not enforce
character set encodings, NFSv4.1 supports the fs_charset_cap character set encodings, NFSv4.1 supports the fs_charset_cap
attribute (Section 5.7.2.11) that indicates to the client a file attribute (Section 5.8.2.11) that indicates to the client a file
system's UTF-8 capabilities. The attribute is an integer containing system's UTF-8 capabilities. The attribute is an integer containing
a pair of flags. The first flag is FSCHARSET_CAP4_CONTAINS_NON_UTF8, a pair of flags. The first flag is FSCHARSET_CAP4_CONTAINS_NON_UTF8,
which, if set to one tells the client the file system contains non- which, if set to one tells the client the file system contains non-
UTF-8 characters, and the server will not convert non-UTF characters UTF-8 characters, and the server will not convert non-UTF characters
to UTF-8 if the client reads a symlink or directory, nor will to UTF-8 if the client reads a symlink or directory, nor will
operations with component names or pathnames in the arguments convert operations with component names or pathnames in the arguments convert
the strings to UTF-8. The second flag is the strings to UTF-8. The second flag is
FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 which if set to one, indicates that FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 which if set to one, indicates that
the server will accept (and generate) only UTF-8 characters on the the server will accept (and generate) only UTF-8 characters on the
file system. If FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set to one, file system. If FSCHARSET_CAP4_ALLOWS_ONLY_UTF8 is set to one,
skipping to change at page 411, line 48 skipping to change at page 412, line 48
NFS4ERR_INVAL under the following combinations of length and offset: NFS4ERR_INVAL under the following combinations of length and offset:
o Length is equal to zero. o Length is equal to zero.
o Length is not equal to NFS4_UINT64_MAX, and the sum of length and o Length is not equal to NFS4_UINT64_MAX, and the sum of length and
offset exceeds NFS4_UINT64_MAX. offset exceeds NFS4_UINT64_MAX.
32-bit servers are servers that support locking for byte offsets that 32-bit servers are servers that support locking for byte offsets that
fit within 32 bits (i.e. less than or equal to NFS4_UINT32_MAX). If fit within 32 bits (i.e. less than or equal to NFS4_UINT32_MAX). If
the client specifies a range that overlaps one or more bytes beyond the client specifies a range that overlaps one or more bytes beyond
offset NFS4_UINT32_MAX, but does not end at offset NFS4_UINT64_MAX offset NFS4_UINT32_MAX, but does not end at offset NFS4_UINT64_MAX,
such a 32-bit server MUST return the error NFS4ERR_BAD_RANGE. then such a 32-bit server MUST return the error NFS4ERR_BAD_RANGE.
If the server returns NFS4ERR_DENIED, owner, offset, and length of a If the server returns NFS4ERR_DENIED, owner, offset, and length of a
conflicting lock are returned. conflicting lock are returned.
The locker argument specifies the lock-owner that is associated with The locker argument specifies the lock-owner that is associated with
the LOCK request. The locker4 structure is a switched union that the LOCK request. The locker4 structure is a switched union that
indicates whether the client has already created byte-range locking indicates whether the client has already created byte-range locking
state associated with the current open file and lock-owner. In the state associated with the current open file and lock-owner. In the
case in which it has, the argument is just a stateid representing the case in which it has, the argument is just a stateid representing the
set of locks associated with that open file and lock-owner, together set of locks associated with that open file and lock-owner, together
skipping to change at page 415, line 22 skipping to change at page 416, line 22
If the server is unable to determine the exact offset and length of If the server is unable to determine the exact offset and length of
the conflicting lock, the same offset and length that were provided the conflicting lock, the same offset and length that were provided
in the arguments should be returned in the denied results. in the arguments should be returned in the denied results.
LOCKT uses a lock_owner4 rather a stateid4, as is used in LOCK to LOCKT uses a lock_owner4 rather a stateid4, as is used in LOCK to
identify the owner. This is because the client does not have to open identify the owner. This is because the client does not have to open
the file to test for the existence of a lock, so a stateid might not the file to test for the existence of a lock, so a stateid might not
be available. be available.
The test for conflicting locks should exclude locks for the current As noted in Section 18.10.4, some servers may return
lock-owner, but the NFSv4.1 specification is flexible in this regard. NFS4ERR_LOCK_RANGE to certain (otherwise non-conflicting) lock
Note that if such locks are not examined, the possible existence of requests that overlap ranges already granted to the current lock-
overlapping ranges might not affect the results of LOCKT, but might owner.
affect the results of LOCK. If the server does examine locks that
match the lock-owner for the purpose of range checking, The LOCKT operation's test for conflicting locks SHOULD exclude locks
NFS4ERR_LOCK_RANGE may be returned in the rely to LOCKT. In the for the current lock-owner, and thus should return NFS4_OK in such
event the server returns NFS4_OK in the reply to LOCKT, it is cases. Note that this means that a server might return NFS4_OK to a
possible when the client sends LOCK request, the server will reject LOCKT request even though a LOCK request for the same range and lock
it with NFS4ERR_LOCK_RANGE due to the flexibility the NFSv4.1 owner would fail with NFS4ERR_LOCK_RANGE.
specification allows the server.
When a client holds a write delegation, it may choose (see When a client holds a write delegation, it may choose (see
Section 18.10.4) to handle LOCK requests locally. In such a case, Section 18.10.4) to handle LOCK requests locally. In such a case,
LOCKT requests will similarly be handled locally. LOCKT requests will similarly be handled locally.
18.12. Operation 14: LOCKU - Unlock File 18.12. Operation 14: LOCKU - Unlock File
18.12.1. ARGUMENTS 18.12.1. ARGUMENTS
struct LOCKU4args { struct LOCKU4args {
skipping to change at page 429, line 14 skipping to change at page 430, line 14
EXCLUSIVE4_1, EXCLUSIVE4 does not support the setting of attributes EXCLUSIVE4_1, EXCLUSIVE4 does not support the setting of attributes
at file creation, and after a successful OPEN via EXCLUSIVE4, the at file creation, and after a successful OPEN via EXCLUSIVE4, the
client MUST send a SETATTR to set attributes to a known state. client MUST send a SETATTR to set attributes to a known state.
In NFSv4.1, EXCLUSIVE4 has been deprecated in favor of EXCLUSIVE4_1. In NFSv4.1, EXCLUSIVE4 has been deprecated in favor of EXCLUSIVE4_1.
Unlike EXCLUSIVE4, attributes may be provided in the EXCLUSIVE4_1 Unlike EXCLUSIVE4, attributes may be provided in the EXCLUSIVE4_1
case, but because the server may use attributes of the target object case, but because the server may use attributes of the target object
to store the verifier, the set of allowable attributes may be fewer to store the verifier, the set of allowable attributes may be fewer
than the set of attributes SETATTR allows. The allowable attributes than the set of attributes SETATTR allows. The allowable attributes
for EXCLUSIVE4_1 are indicated in the suppattr_exclcreat for EXCLUSIVE4_1 are indicated in the suppattr_exclcreat
(Section 5.7.1.14) attribute. If the client attempts to set in (Section 5.8.1.14) attribute. If the client attempts to set in
cva_attrs an attribute that is not in suppattr_exclcreat, the server cva_attrs an attribute that is not in suppattr_exclcreat, the server
MUST return NFS4ERR_INVAL. The response field, attrset indicates MUST return NFS4ERR_INVAL. The response field, attrset indicates
both which attributes the server set from cva_attrs, and which both which attributes the server set from cva_attrs, and which
attributes the server used to store the verifier. As described in attributes the server used to store the verifier. As described in
Section 18.16.4, the client can compare cva_attrs.attrmask with Section 18.16.4, the client can compare cva_attrs.attrmask with
attrset to determine which attributes were used to store the attrset to determine which attributes were used to store the
verifier. verifier.
With the addition of persistent sessions and pNFS, under some With the addition of persistent sessions and pNFS, under some
conditions EXCLUSIVE4 MUST NOT be used by the client or supported by conditions EXCLUSIVE4 MUST NOT be used by the client or supported by
skipping to change at page 442, line 7 skipping to change at page 443, line 7
union OPEN_DOWNGRADE4res switch(nfsstat4 status) { union OPEN_DOWNGRADE4res switch(nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
OPEN_DOWNGRADE4resok resok4; OPEN_DOWNGRADE4resok resok4;
default: default:
void; void;
}; };
18.18.3. DESCRIPTION 18.18.3. DESCRIPTION
This operation is used to adjust the share_access and share_deny bits This operation is used to adjust the access and deny states for a
for a given open. This is necessary when a given open-owner opens given open. This is necessary when a given open-owner opens the same
the same file multiple times with different share_access and file multiple times with different access and deny values. In this
share_deny flags. In this situation, a close of one of the opens may situation, a close of one of the opens may change the appropriate
change the appropriate share_access and share_deny flags to remove share_access and share_deny flags to remove bits associated with
bits associated with opens no longer in effect. opens no longer in effect.
The share_access and share_deny bits specified in this operation Valid values for the share_access field are: OPEN4_SHARE_ACCESS_READ,
replace the current ones for the specified open file. The OPEN4_SHARE_ACCESS_WRITE, or OPEN4_SHARE_ACCESS_BOTH. If the client
share_access and share_deny bits specified must be exactly equal to specifies other values, the server MUST reply with NFS4ERR_INVAL.
the union of the share_access and share_deny bits specified for some
subset of the OPENs in effect for current open-owner on the current Valid values for the share_deny field are: OPEN4_SHARE_DENY_NONE,
file. If that constraint is not respected, the server may return the OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or
error NFS4ERR_INVAL. Since share_access and share_deny bits are OPEN4_SHARE_DENY_BOTH. If the client specifies other values, the
subsets of those already granted, it is not possible for this request server MUST reply with NFS4ERR_INVAL.
to be denied because of conflicting share reservations.
After checking for valid values of share_access and share_deny, the
server replaces the current access and deny modes on the file with
share_access and share_deny subject to the following constraints:
o The bits in share_access MUST equal the union of the share_access
bits (not including OPEN4_SHARE_WANT_* bits) specified for some
subset of the OPENs in effect for the current open-owner on the
current file.
o The bits in share_deny MUST equal the union of the share_deny bits
specified for some subset of the OPENs in effect for the current
open-owner on the current file.
If the above constraints are not respected, the server MUST return
the error NFS4ERR_INVAL. Since share_access and share_deny bits
should be subsets of those already granted, short of a defect in the
client or server implementation, it is not possible for the
OPEN_DOWNGRADE request to be denied because of conflicting share
reservations.
The seqid argument is not used in NFSv4.1, MAY be any value, and MUST The seqid argument is not used in NFSv4.1, MAY be any value, and MUST
be ignored by the server. be ignored by the server.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
18.18.4. IMPLEMENTATION 18.18.4. IMPLEMENTATION
An OPEN_DOWNGRADE operation may make read delegations grantable where An OPEN_DOWNGRADE operation may make read delegations grantable where
they were not previously. Servers may choose to respond immediately they were not previously. Servers may choose to respond immediately
skipping to change at page 443, line 30 skipping to change at page 444, line 39
If the security mechanism used by the requester does not meet the If the security mechanism used by the requester does not meet the
requirements of the filehandle provided to this operation, the server requirements of the filehandle provided to this operation, the server
MUST return NFS4ERR_WRONGSEC. MUST return NFS4ERR_WRONGSEC.
See Section 16.2.3.1.1 for more details on the current filehandle. See Section 16.2.3.1.1 for more details on the current filehandle.
See Section 16.2.3.1.2 for more details on the current stateid. See Section 16.2.3.1.2 for more details on the current stateid.
18.19.4. IMPLEMENTATION 18.19.4. IMPLEMENTATION
Commonly used as the first operator in an NFS request to set the Commonly used as the second operator (after SEQUENCE) in a COMPOUND
context for following operations. request to set the context for following operations.
18.20. Operation 23: PUTPUBFH - Set Public Filehandle 18.20. Operation 23: PUTPUBFH - Set Public Filehandle
18.20.1. ARGUMENT 18.20.1. ARGUMENT
void; void;
18.20.2. RESULT 18.20.2. RESULT
struct PUTPUBFH4res { struct PUTPUBFH4res {
skipping to change at page 449, line 45 skipping to change at page 450, line 45
each entry along with information to allow the client to request each entry along with information to allow the client to request
additional directory entries in a subsequent READDIR. additional directory entries in a subsequent READDIR.
The arguments contain a cookie value that represents where the The arguments contain a cookie value that represents where the
READDIR should start within the directory. A value of 0 (zero) for READDIR should start within the directory. A value of 0 (zero) for
the cookie is used to start reading at the beginning of the the cookie is used to start reading at the beginning of the
directory. For subsequent READDIR requests, the client specifies a directory. For subsequent READDIR requests, the client specifies a
cookie value that is provided by the server on a previous READDIR cookie value that is provided by the server on a previous READDIR
request. request.
The cookieverf value should be set to 0 (zero) when the cookie value The request's cookieverf field should be set to 0 (zero) when the
is 0 (zero) (first directory read). On subsequent requests, it request's cookie field is 0 (zero) (first directory read). On
should be a cookieverf as returned by the server. The cookieverf subsequent requests, the cookieverf field must match the cookieverf
must match that returned by the READDIR in which the cookie was returned by the READDIR in which the cookie was acquired. If the
acquired. If the server determines that the cookieverf is no longer server determines that the cookieverf is no longer valid for the
valid for the directory, the error NFS4ERR_NOT_SAME must be returned. directory, the error NFS4ERR_NOT_SAME must be returned.
The dircount portion of the argument is a hint of the maximum number The dircount field of the request is a hint of the maximum number of
of bytes of directory information that should be returned. This bytes of directory information that should be returned. This value
value represents the length of the names of the directory entries and represents the total length of the names of the directory entries and
the cookie value for these entries. This length represents the XDR the cookie value for these entries. This length represents the XDR
encoding of the data (names and cookies) and not the length in the encoding of the data (names and cookies) and not the length in the
native format of the server. native format of the server.
The maxcount value of the argument is the maximum number of bytes for The maxcount field of the request represents the maximum total size
the result. This maximum size represents all of the data being of all of the data being returned within the READDIR4resok structure
returned within the READDIR4resok structure and includes the XDR and includes the XDR overhead. The server MAY return less data. If
overhead. The server may return less data. If the server is unable the server is unable to return a single directory entry within the
to return a single directory entry within the maxcount limit, the maxcount limit, the error NFS4ERR_TOOSMALL MUST be returned to the
error NFS4ERR_TOOSMALL will be returned to the client. client.
Finally, attr_request represents the list of attributes to be Finally, the request's attr_request field represents the list of
returned for each directory entry supplied by the server. attributes to be returned for each directory entry supplied by the
server.
On successful return, the server's response will provide a list of A successful reply consists of a list of directory entries. Each of
directory entries. Each of these entries contains the name of the these entries contains the name of the directory entry, a cookie
directory entry, a cookie value for that entry, and the associated value for that entry, and the associated attributes as requested.
attributes as requested. The "eof" flag has a value of TRUE if there The "eof" flag has a value of TRUE if there are no more entries in
are no more entries in the directory. the directory.
The cookie value is only meaningful to the server and is used as a The cookie value is only meaningful to the server and is used as a
"bookmark" for the directory entry. As mentioned, this cookie is cursor for the directory entry. As mentioned, this cookie is used by
used by the client for subsequent READDIR operations so that it may the client for subsequent READDIR operations so that it may continue
continue reading a directory. The cookie is similar in concept to a reading a directory. The cookie is similar in concept to a READ
READ offset but should not be interpreted as such by the client. offset but MUST NOT be interpreted as such by the client. Ideally,
Ideally, the cookie value should not change if the directory is the cookie value SHOULD NOT change if the directory is modified since
modified since the client may be caching these values. the client may be caching these values.
In some cases, the server may encounter an error while obtaining the In some cases, the server may encounter an error while obtaining the
attributes for a directory entry. Instead of returning an error for attributes for a directory entry. Instead of returning an error for
the entire READDIR operation, the server can instead return the the entire READDIR operation, the server can instead return the
attribute 'fattr4_rdattr_error'. With this, the server is able to attribute rdattr_error (Section 5.8.1.12). With this, the server is
communicate the failure to the client and not fail the entire able to communicate the failure to the client and not fail the entire
operation in the instance of what might be a transient failure. operation in the instance of what might be a transient failure.
Obviously, the client must request the fattr4_rdattr_error attribute Obviously, the client must request the fattr4_rdattr_error attribute
for this method to work properly. If the client does not request the for this method to work properly. If the client does not request the
attribute, the server has no choice but to return failure for the attribute, the server has no choice but to return failure for the
entire READDIR operation. entire READDIR operation.
For some file system environments, the directory entries "." and ".." For some file system environments, the directory entries "." and ".."
have special meaning and in other environments, they may not. If the have special meaning and in other environments, they do not. If the
server supports these special entries within a directory, they should server supports these special entries within a directory, they SHOULD
not be returned to the client as part of the READDIR response. To NOT be returned to the client as part of the READDIR response. To
enable some client environments, the cookie values of 0, 1, and 2 are enable some client environments, the cookie values of 0, 1, and 2 are
to be considered reserved. Note that the UNIX client will use these to be considered reserved. Note that the UNIX client will use these
values when combining the server's response and local representations values when combining the server's response and local representations
to enable a fully formed UNIX directory presentation to the to enable a fully formed UNIX directory presentation to the
application. application.
For READDIR arguments, cookie values of 1 and 2 should not be used For READDIR arguments, cookie values of 1 and 2 SHOULD NOT be used
and for READDIR results cookie values of 0, 1, and 2 should not be and for READDIR results cookie values of 0, 1, and 2 SHOULD NOT be
returned. returned.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
18.23.4. IMPLEMENTATION 18.23.4. IMPLEMENTATION
The server's file system directory representations can differ The server's file system directory representations can differ
greatly. A client's programming interfaces may also be bound to the greatly. A client's programming interfaces may also be bound to the
local operating environment in a way that does not translate well local operating environment in a way that does not translate well
into the NFS protocol. Therefore the use of the dircount and into the NFS protocol. Therefore the use of the dircount and
maxcount fields are provided to allow the client the ability to maxcount fields are provided to enable the client to provide hints to
provide guidelines to the server. If the client is aggressive about the server. If the client is aggressive about attribute collection
attribute collection during a READDIR, the server has an idea of how during a READDIR, the server has an idea of how to limit the encoded
to limit the encoded response. The dircount field provides a hint on response.
the number of entries based solely on the names of the directory
entries. Since it is a hint, it may be possible that a dircount If dircount is zero, the server bounds the reply's size based on
value is zero. In this case, the server is free to ignore the request's maxcount field.
dircount value and return directory information based on the
specified maxcount value.
The cookieverf may be used by the server to help manage cookie values The cookieverf may be used by the server to help manage cookie values
that may become stale. It should be a rare occurrence that a server that may become stale. It should be a rare occurrence that a server
is unable to continue properly reading a directory with the provided is unable to continue properly reading a directory with the provided
cookie/cookieverf pair. The server should make every effort to avoid cookie/cookieverf pair. The server SHOULD make every effort to avoid
this condition since the application at the client may not be able to this condition since the application at the client might be unable to
properly handle this type of failure. properly handle this type of failure.
The use of the cookieverf will also protect the client from using The use of the cookieverf will also protect the client from using
READDIR cookie values that may be stale. For example, if the file READDIR cookie values that might be stale. For example, if the file
system has been migrated, the server may or may not be able to use system has been migrated, the server might or might not be able to
the same cookie values to service READDIR as the previous server use the same cookie values to service READDIR as the previous server
used. With the client providing the cookieverf, the server is able used. With the client providing the cookieverf, the server is able
to provide the appropriate response to the client. This prevents the to provide the appropriate response to the client. This prevents the
case where the server may accept a cookie value but the underlying case where the server accepts a cookie value but the underlying
directory has changed and the response is invalid from the client's directory has changed and the response is invalid from the client's
context of its previous READDIR. context of its previous READDIR.
Since some servers will not be returning "." and ".." entries as has Since some servers will not be returning "." and ".." entries as has
been done with previous versions of the NFS protocol, the client that been done with previous versions of the NFS protocol, the client that
requires these entries be present in READDIR responses must fabricate requires these entries be present in READDIR responses must fabricate
them. them.
18.24. Operation 27: READLINK - Read Symbolic Link 18.24. Operation 27: READLINK - Read Symbolic Link
skipping to change at page 452, line 28 skipping to change at page 453, line 27
union READLINK4res switch (nfsstat4 status) { union READLINK4res switch (nfsstat4 status) {
case NFS4_OK: case NFS4_OK:
READLINK4resok resok4; READLINK4resok resok4;
default: default:
void; void;
}; };
18.24.3. DESCRIPTION 18.24.3. DESCRIPTION
READLINK reads the data associated with a symbolic link. The data is READLINK reads the data associated with a symbolic link. Depending
a UTF-8 string that is opaque to the server. That is, whether on the value of the UTF-8 capability attribute (Section 14.4), the
created by an NFS client or created locally on the server, the data data is encoded in UTF-8. Whether created by an NFS client or
in a symbolic link is not interpreted when created, but is simply created locally on the server, the data in a symbolic link is not
stored. interpreted (except possibly to check for proper UTF-8 encoding) when
created, but is simply stored.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
18.24.4. IMPLEMENTATION 18.24.4. IMPLEMENTATION
A symbolic link is nominally a pointer to another file. The data is A symbolic link is nominally a pointer to another file. The data is
not necessarily interpreted by the server, just stored in the file. not necessarily interpreted by the server, just stored in the file.
It is possible for a client implementation to store a path name that It is possible for a client implementation to store a path name that
is not meaningful to the server operating system in a symbolic link. is not meaningful to the server operating system in a symbolic link.
A READLINK operation returns the data to the client for A READLINK operation returns the data to the client for
interpretation. If different implementations want to share access to interpretation. If different implementations want to share access to
symbolic links, then they must agree on the interpretation of the symbolic links, then they must agree on the interpretation of the
data in the symbolic link. data in the symbolic link.
The READLINK operation is only allowed on objects of type NF4LNK. The READLINK operation is only allowed on objects of type NF4LNK.
The server should return the error NFS4ERR_WRONG_TYPE, if the object The server should return the error NFS4ERR_WRONG_TYPE if the object
is not of type NF4LNK. is not of type NF4LNK.
18.25. Operation 28: REMOVE - Remove File System Object 18.25. Operation 28: REMOVE - Remove File System Object
18.25.1. ARGUMENTS 18.25.1. ARGUMENTS
struct REMOVE4args { struct REMOVE4args {
/* CURRENT_FH: directory */ /* CURRENT_FH: directory */
component4 target; component4 target;
}; };
skipping to change at page 453, line 42 skipping to change at page 454, line 42
corresponding file system object, the object may be destroyed. The corresponding file system object, the object may be destroyed. The
directory may be either of type NF4DIR or NF4ATTRDIR. directory may be either of type NF4DIR or NF4ATTRDIR.
For the directory where the filename was removed, the server returns For the directory where the filename was removed, the server returns
change_info4 information in cinfo. With the atomic field of the change_info4 information in cinfo. With the atomic field of the
change_info4 data type, the server will indicate if the before and change_info4 data type, the server will indicate if the before and
after change attributes were obtained atomically with respect to the after change attributes were obtained atomically with respect to the
removal. removal.
If the target has a length of 0 (zero), or if target does not obey If the target has a length of 0 (zero), or if target does not obey
the UTF-8 definition, the error NFS4ERR_INVAL will be returned. the UTF-8 definition (and the server is enforcing UTF-8 encoding, see
Section 14.4), the error NFS4ERR_INVAL will be returned.
On success, the current filehandle retains its value. On success, the current filehandle retains its value.
18.25.4. IMPLEMENTATION 18.25.4. IMPLEMENTATION
NFSv3 required a different operator RMDIR for directory removal and NFSv3 required a different operator RMDIR for directory removal and
REMOVE for non-directory removal. This allowed clients to skip REMOVE for non-directory removal. This allowed clients to skip
checking the file type when being passed a non-directory delete checking the file type when being passed a non-directory delete
system call (e.g. unlink() in POSIX) to remove a directory, as well system call (e.g. unlink() in POSIX) to remove a directory, as well
as the converse (e.g. a rmdir() on a non-directory) because they knew as the converse (e.g. a rmdir() on a non-directory) because they knew
skipping to change at page 454, line 23 skipping to change at page 455, line 24
REMOVE operation in the same COMPOUND call. REMOVE operation in the same COMPOUND call.
The concept of last reference is server specific. However, if the The concept of last reference is server specific. However, if the
numlinks field in the previous attributes of the object had the value numlinks field in the previous attributes of the object had the value
1, the client should not rely on referring to the object via a 1, the client should not rely on referring to the object via a
filehandle. Likewise, the client should not rely on the resources filehandle. Likewise, the client should not rely on the resources
(disk space, directory entry, and so on) formerly associated with the (disk space, directory entry, and so on) formerly associated with the
object becoming immediately available. Thus, if a client needs to be object becoming immediately available. Thus, if a client needs to be
able to continue to access a file after using REMOVE to remove it, able to continue to access a file after using REMOVE to remove it,
the client should take steps to make sure that the file will still be the client should take steps to make sure that the file will still be
accessible. The usual mechanism used is to RENAME the file from its accessible. While the traditional mechanism used is to RENAME the
old name to a new hidden name. file from its old name to a new hidden name, the NFSv4.1 OPEN
operation MAY return a result flag, OPEN4_RESULT_PRESERVE_UNLINKED,
which indicates to the client that the file will be preserved if the
file has an outstanding open (see Section 18.16).
If the server finds that the file is still open when the REMOVE If the server finds that the file is still open when the REMOVE
arrives: arrives:
o The server SHOULD NOT delete the file's directory entry if the o The server SHOULD NOT delete the file's directory entry if the
file was opened with OPEN4_SHARE_DENY_WRITE or file was opened with OPEN4_SHARE_DENY_WRITE or
OPEN4_SHARE_DENY_BOTH. OPEN4_SHARE_DENY_BOTH.
o If the file was not opened with OPEN4_SHARE_DENY_WRITE or o If the file was not opened with OPEN4_SHARE_DENY_WRITE or
OPEN4_SHARE_DENY_BOTH, the server SHOULD delete the file's OPEN4_SHARE_DENY_BOTH, the server SHOULD delete the file's
directory entry. However, until last CLOSE of the file, the directory entry. However, until last CLOSE of the file, the
server MAY continue to allow access to the file via its server MAY continue to allow access to the file via its
filehandle. filehandle.
The server MAY choose to implement its own restrictions on removal of o The server MUST NOT delete the directory entry if the reply from
files while they are open such that REMOVE or a removal that occurs OPEN had the flag OPEN4_RESULT_PRESERVE_UNLINKED set.
as part of RENAME may not be done when the file being removed is if
the open is done by particular protocols, or with particular options The server MAY implement its own restrictions on removal of a file
or access modes. In all cases in which a decision is made to not while it is open. The server might disallow such a REMOVE (or a
allow the file's directory entry be removed because of an open, the removal that occurs as part of RENAME). The conditions that
error NFS4ERR_FILE_OPEN is returned. influence the restrictions on removal of a file while it is still
open include:
o Whether certain access protocols (i.e. not just NFS) are holding
the file open.
o Whether particular options, access modes, or policies on the
server are enabled.
In all cases in which a decision is made to not allow the file's
directory entry be removed because of an open, the error
NFS4ERR_FILE_OPEN is returned.
Where the determination above cannot be made definitively because Where the determination above cannot be made definitively because
delegations are being held, they must be recalled to allow processing delegations are being held, they MUST be recalled to allow processing
of the REMOVE to continue. When a delegation is held, the server's of the REMOVE to continue. When a delegation is held, the server's
knowledge of the status of opens for that client is not to be relied knowledge of the status of opens for that client is not to be relied
on, so that unless there are files opened with the particular deny on, so that unless there are files opened with the particular deny
modes by clients without delegations, the determination cannot be modes by clients without delegations, the determination cannot be
made until delegations are recalled, and the operation cannot proceed made until delegations are recalled, and the operation cannot proceed
until each sufficient delegations have been returned or revoked to until each sufficient delegations have been returned or revoked to
allow the server to make a correct determination. allow the server to make a correct determination.
When a REMOVE is successfully processed, in that it will remove a In all cases in which delegations are recalled, the server is likely
directory entry, whether that is the last reference to the object or to return one or more NFS4ERR_DELAY errors while delegations remain
not, and another client holds a delegation for that object, the outstanding.
delegation(s) must be recalled, the operation cannot proceed until
each such delegation is returned or revoked. In all cases in which
delegations are recalled, the server is likely to return one or more
NFS4ERR_DELAY error while the delegation(s) remains outstanding,
although it may, if the returns happen quickly, not do that.
If the current filehandle designates a directory for which another If the current filehandle designates a directory for which another
client holds a directory delegation, then, unless the delegation is client holds a directory delegation, then, unless the situation can
such that the situation can be resolved by sending a notification, be resolved by sending a notification, the directory delegation MUST
the delegation must be recalled, and the operation cannot proceed be recalled, and the operation MUST NOT proceed until the delegation
until the delegation is returned or revoked. Except where this is returned or revoked. Except where this happens very quickly, one
happens very quickly, one or more NFS4ERR_DELAY errors will be or more NFS4ERR_DELAY errors will be returned to requests made while
returned to requests made while delegation remains outstanding. delegation remains outstanding.
When the current filehandle designates a directory for which one or When the current filehandle designates a directory for which one or
more directory delegations exist, then, when those delegations more directory delegations exist, then, when those delegations
request such notifications, NOTIFY4_REMOVE_ENTRY will be generated as request such notifications, NOTIFY4_REMOVE_ENTRY will be generated as
a result of this operation. Note that when a remove occurs as a a result of this operation.
result of a RENAME, this notification will only be generated if the
removal happens as a separate operation. In the case in which the Note that when a remove occurs as a result of a RENAME,
removal is integrated with RENAME and is atomic with it, notification NOTIFY4_REMOVE_ENTRY will only be generated if the removal happens as
of the removal is integrated with notification for the RENAME. a separate operation. In the case in which the removal is integrated
and atomic with RENAME, the notification of the removal is integrated
with notification for the RENAME. See the discussion of the
NOTIFY4_RENAME_ENTRY notification in Section 20.4.
18.26. Operation 29: RENAME - Rename Directory Entry 18.26. Operation 29: RENAME - Rename Directory Entry
18.26.1. ARGUMENTS 18.26.1. ARGUMENTS
struct RENAME4args { struct RENAME4args {
/* SAVED_FH: source directory */ /* SAVED_FH: source directory */
component4 oldname; component4 oldname;
/* CURRENT_FH: target directory */ /* CURRENT_FH: target directory */
component4 newname; component4 newname;
skipping to change at page 495, line 42 skipping to change at page 497, line 42
server to provide a persistent reply cache. For sessions in server to provide a persistent reply cache. For sessions in
which only idempotent operations will be used (e.g. a read-only which only idempotent operations will be used (e.g. a read-only
session), clients SHOULD NOT set CREATE_SESSION4_FLAG_PERSIST. session), clients SHOULD NOT set CREATE_SESSION4_FLAG_PERSIST.
If the server does not or cannot provide a persistent reply If the server does not or cannot provide a persistent reply
cache, the server MUST NOT set CREATE_SESSION4_FLAG_PERSIST in cache, the server MUST NOT set CREATE_SESSION4_FLAG_PERSIST in
the field csr_flags. the field csr_flags.
If the server is a pNFS metadata server, for reasons described If the server is a pNFS metadata server, for reasons described
in Section 12.5.2 it SHOULD support in Section 12.5.2 it SHOULD support
CREATE_SESSION4_FLAG_PERSIST if it supports the layout_hint CREATE_SESSION4_FLAG_PERSIST if it supports the layout_hint
(Section 5.11.4) attribute. (Section 5.12.4) attribute.
CREATE_SESSION4_FLAG_CONN_BACK_CHAN: CREATE_SESSION4_FLAG_CONN_BACK_CHAN:
If CREATE_SESSION4_FLAG_CONN_BACK_CHAN is set in csa_flags, the If CREATE_SESSION4_FLAG_CONN_BACK_CHAN is set in csa_flags, the
client is requesting that the server use the connection client is requesting that the server use the connection
CREATE_SESSION is called over for the backchannel as well as CREATE_SESSION is called over for the backchannel as well as
the fore channel. The server sets the fore channel. The server sets
CREATE_SESSION4_FLAG_CONN_BACK_CHAN in the result field CREATE_SESSION4_FLAG_CONN_BACK_CHAN in the result field
csr_flags if it agrees. If CREATE_SESSION4_FLAG_CONN_BACK_CHAN csr_flags if it agrees. If CREATE_SESSION4_FLAG_CONN_BACK_CHAN
is not set in csa_flags, then is not set in csa_flags, then
 End of changes. 181 change blocks. 
565 lines changed or deleted 633 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/