2.5 Basic Data Types

The following XDR definitions are basic definitions that are used in other structures.

   uint64
         typedef unsigned hyper uint64;

   int64
         typedef hyper int64;

   uint32
         typedef unsigned long uint32;

   int32
         typedef long int32;

   filename3
         typedef string filename3<>;

   nfspath3
         typedef string nfspath3<>;

   fileid3
         typedef uint64 fileid3;

   cookie3
         typedef uint64 cookie3;

   cookieverf3
         typedef opaque cookieverf3[NFS3_COOKIEVERFSIZE];

   createverf3
         typedef opaque createverf3[NFS3_CREATEVERFSIZE];

   writeverf3
         typedef opaque writeverf3[NFS3_WRITEVERFSIZE];

   uid3
         typedef uint32 uid3;

   gid3
         typedef uint32 gid3;

   size3
         typedef uint64 size3;

   offset3
         typedef uint64 offset3;

   mode3
         typedef uint32 mode3;

   count3
         typedef uint32 count3;

   nfsstat3
      enum nfsstat3 {
         NFS3_OK             = 0,
         NFS3ERR_PERM        = 1,
         NFS3ERR_NOENT       = 2,
         NFS3ERR_IO          = 5,
         NFS3ERR_NXIO        = 6,
         NFS3ERR_ACCES       = 13,
         NFS3ERR_EXIST       = 17,
         NFS3ERR_XDEV        = 18,
         NFS3ERR_NODEV       = 19,
         NFS3ERR_NOTDIR      = 20,
         NFS3ERR_ISDIR       = 21,
         NFS3ERR_INVAL       = 22,
         NFS3ERR_FBIG        = 27,
         NFS3ERR_NOSPC       = 28,
         NFS3ERR_ROFS        = 30,
         NFS3ERR_MLINK       = 31,
         NFS3ERR_NAMETOOLONG = 63,
         NFS3ERR_NOTEMPTY    = 66,
         NFS3ERR_DQUOT       = 69,
         NFS3ERR_STALE       = 70,
         NFS3ERR_REMOTE      = 71,
         NFS3ERR_BADHANDLE   = 10001,
         NFS3ERR_NOT_SYNC    = 10002,
         NFS3ERR_BAD_COOKIE  = 10003,
         NFS3ERR_NOTSUPP     = 10004,
         NFS3ERR_TOOSMALL    = 10005,
         NFS3ERR_SERVERFAULT = 10006,
         NFS3ERR_BADTYPE     = 10007,
         NFS3ERR_JUKEBOX     = 10008
      };

The nfsstat3 type is returned with every procedure's results except for the NULL procedure. A value of NFS3_OK indicates that the call completed successfully. Any other value indicates that some error occurred on the call, as identified by the error code. Note that the precise numeric encoding must be followed. No other values may be returned by a server. Servers are expected to make a best effort mapping of error conditions to the set of error codes defined. In addition, no error precedences are specified by this specification. Error precedences determine the error value that should be returned when more than one error applies in a given situation. The error precedence will be determined by the individual server implementation. If the client requires specific error precedences, it should check for the specific errors for itself.

   ftype3

      enum ftype3 {
         NF3REG    = 1,
         NF3DIR    = 2,
         NF3BLK    = 3,
         NF3CHR    = 4,
         NF3LNK    = 5,
         NF3SOCK   = 6,
         NF3FIFO   = 7
      };

The enumeration, ftype3, gives the type of a file. The type, NF3REG, is a regular file, NF3DIR is a directory, NF3BLK is a block special device file, NF3CHR is a character special device file, NF3LNK is a symbolic link, NF3SOCK is a socket, and NF3FIFO is a named pipe. Note that the precise enum encoding must be followed.

   specdata3

      struct specdata3 {
           uint32     specdata1;
           uint32     specdata2;
      };

The interpretation of the two words depends on the type of file system object. For a block special (NF3BLK) or character special (NF3CHR) file, specdata1 and specdata2 are the major and minor device numbers, respectively. (This is obviously a UNIX-specific interpretation.) For all other file types, these two elements should either be set to 0 or the values should be agreed upon by the client and server. If the client and server do not agree upon the values, the client should treat these fields as if they are set to 0. This data field is returned as part of the fattr3 structure and so is available from all replies returning attributes. Since these fields are otherwise unused for objects which are not devices, out of band information can be passed from the server to the client. However, once again, both the server and the client must agree on the values passed.

   nfs_fh3

      struct nfs_fh3 {
         opaque       data<NFS3_FHSIZE>;
      };

The nfs_fh3 is the variable-length opaque object returned by the server on LOOKUP, CREATE, SYMLINK, MKNOD, LINK, or READDIRPLUS operations, which is used by the client on subsequent operations to reference the file. The file handle contains all the information the server needs to distinguish an individual file. To the client, the file handle is opaque. The client stores file handles for use in a later request and can compare two file handles from the same server for equality by doing a byte-by-byte comparison, but cannot otherwise interpret the contents of file handles. If two file handles from the same server are equal, they must refer to the same file, but if they are not equal, no conclusions can be drawn. Servers should try to maintain a one-to-one correspondence between file handles and files, but this is not required. Clients should use file handle comparisons only to improve performance, not for correct behavior.

Servers can revoke the access provided by a file handle at any time. If the file handle passed in a call refers to a file system object that no longer exists on the server or access for that file handle has been revoked, the error, NFS3ERR_STALE, should be returned.

   nfstime3

      struct nfstime3 {
         uint32   seconds;
         uint32   nseconds;
      };

The nfstime3 structure gives the number of seconds and nanoseconds since midnight January 1, 1970 Greenwich Mean Time. It is used to pass time and date information. The times associated with files are all server times except in the case of a SETATTR operation where the client can explicitly set the file time. A server converts to and from local time when processing time values, preserving as much accuracy as possible. If the precision of timestamps stored for a file is less than that defined by NFS version 3 protocol, loss of precision can occur. An adjunct time maintenance protocol is recommended to reduce client and server time skew.

   fattr3

      struct fattr3 {
         ftype3     type;
         mode3      mode;
         uint32     nlink;
         uid3       uid;
         gid3       gid;
         size3      size;
         size3      used;
         specdata3  rdev;
         uint64     fsid;
         fileid3    fileid;
         nfstime3   atime;
         nfstime3   mtime;
         nfstime3   ctime;
      };

This structure defines the attributes of a file system object. It is returned by most operations on an object; in the case of operations that affect two objects (for example, a MKDIR that modifies the target directory attributes and defines new attributes for the newly created directory), the attributes for both may be returned. In some cases, the attributes are returned in the structure, wcc_data, which is defined below; in other cases the attributes are returned alone. The main changes from the NFS version 2 protocol are that many of the fields have been widened and the major/minor device information is now presented in a distinct structure rather than being packed into a word.

The fattr3 structure contains the basic attributes of a file. All servers should support this set of attributes even if they have to simulate some of the fields. Type is the type of the file. Mode is the protection mode bits. Nlink is the number of hard links to the file - that is, the number of different names for the same file. Uid is the user ID of the owner of the file. Gid is the group ID of the group of the file. Size is the size of the file in bytes. Used is the number of bytes of disk space that the file actually uses (which can be smaller than the size because the file may have holes or it may be larger due to fragmentation). Rdev describes the device file if the file type is NF3CHR or NF3BLK - see specdata3 on page 20. Fsid is the file system identifier for the file system. Fileid is a number which uniquely identifies the file within its file system (on UNIX this would be the inumber). Atime is the time when the file data was last accessed. Mtime is the time when the file data was last modified. Ctime is the time when the attributes of the file were last changed. Writing to the file changes the ctime in addition to the mtime.

The mode bits are defined as follows:

      0x00800 Set user ID on execution.
      0x00400 Set group ID on execution.
      0x00200 Save swapped text (not defined in POSIX).
      0x00100 Read permission for owner.
      0x00080 Write permission for owner.
      0x00040 Execute permission for owner on a file. Or lookup
              (search) permission for owner in directory.
      0x00020 Read permission for group.
      0x00010 Write permission for group.
      0x00008 Execute permission for group on a file. Or lookup
              (search) permission for group in directory.
      0x00004 Read permission for others.
      0x00002 Write permission for others.
      0x00001 Execute permission for others on a file. Or lookup
              (search) permission for others in directory.

   post_op_attr

      union post_op_attr switch (bool attributes_follow) {
      case TRUE:
         fattr3   attributes;
      case FALSE:
         void;
      };

This structure is used for returning attributes in those operations that are not directly involved with manipulating attributes. One of the principles of this revision of the NFS protocol is to return the real value from the indicated operation and not an error from an incidental operation. The post_op_attr structure was designed to allow the server to recover from errors encountered while getting attributes.

This appears to make returning attributes optional. However, server implementors are strongly encouraged to make best effort to return attributes whenever possible, even when returning an error.

   wcc_attr

      struct wcc_attr {
         size3       size;
         nfstime3    mtime;
         nfstime3    ctime;
      };

This is the subset of pre-operation attributes needed to better support the weak cache consistency semantics. Size is the file size in bytes of the object before the operation. Mtime is the time of last modification of the object before the operation. Ctime is the time of last change to the attributes of the object before the operation. See discussion in wcc_attr on page 24.

The use of mtime by clients to detect changes to file system objects residing on a server is dependent on the granularity of the time base on the server.

   pre_op_attr

      union pre_op_attr switch (bool attributes_follow) {
      case TRUE:
           wcc_attr  attributes;
      case FALSE:
           void;
      };

   wcc_data

      struct wcc_data {
         pre_op_attr    before;
         post_op_attr   after;
      };

When a client performs an operation that modifies the state of a file or directory on the server, it cannot immediately determine from the post-operation attributes whether the operation just performed was the only operation on the object since the last time the client received the attributes for the object. This is important, since if an intervening operation has changed the object, the client will need to invalidate any cached data for the object (except for the data that it just wrote).

To deal with this, the notion of weak cache consistency data or wcc_data is introduced. A wcc_data structure consists of certain key fields from the object attributes before the operation, together with the object attributes after the operation. This information allows the client to manage its cache more accurately than in NFS version 2 protocol implementations. The term, weak cache consistency, emphasizes the fact that this mechanism does not provide the strict server-client consistency that a cache consistency protocol would provide.

In order to support the weak cache consistency model, the server will need to be able to get the pre-operation attributes of the object, perform the intended modify operation, and then get the post-operation attributes atomically. If there is a window for the object to get modified between the operation and either of the get attributes operations, then the client will not be able to determine whether it was the only entity to modify the object. Some information will have been lost, thus weakening the weak cache consistency guarantees.

   post_op_fh3

      union post_op_fh3 switch (bool handle_follows) {
      case TRUE:
           nfs_fh3  handle;
      case FALSE:
           void;
      };

One of the principles of this revision of the NFS protocol is to return the real value from the indicated operation and not an error from an incidental operation. The post_op_fh3 structure was designed to allow the server to recover from errors encountered while constructing a file handle.

This is the structure used to return a file handle from the CREATE, MKDIR, SYMLINK, MKNOD, and READDIRPLUS requests. In each case, the client can get the file handle by issuing a LOOKUP request after a successful return from one of the listed operations. Returning the file handle is an optimization so that the client is not forced to immediately issue a LOOKUP request to get the file handle.

   sattr3

      enum time_how {
         DONT_CHANGE        = 0,
         SET_TO_SERVER_TIME = 1,
         SET_TO_CLIENT_TIME = 2
      };

      union set_mode3 switch (bool set_it) {
      case TRUE:
         mode3    mode;
      default:
         void;
      };

      union set_uid3 switch (bool set_it) {
      case TRUE:
         uid3     uid;
      default:
         void;
      };

      union set_gid3 switch (bool set_it) {
      case TRUE:
         gid3     gid;
      default:
         void;
      };

      union set_size3 switch (bool set_it) {
      case TRUE:
         size3    size;
      default:
         void;
      };

      union set_atime switch (time_how set_it) {
      case SET_TO_CLIENT_TIME:
         nfstime3  atime;
      default:
         void;
      };

      union set_mtime switch (time_how set_it) {
      case SET_TO_CLIENT_TIME:
         nfstime3  mtime;
      default:
         void;
      };

      struct sattr3 {
         set_mode3   mode;
         set_uid3    uid;
         set_gid3    gid;
         set_size3   size;
         set_atime   atime;
         set_mtime   mtime;
      };

The sattr3 structure contains the file attributes that can be set from the client. The fields are the same as the similarly named fields in the fattr3 structure. In the NFS version 3 protocol, the settable attributes are described by a structure containing a set of discriminated unions. Each union indicates whether the corresponding attribute is to be updated, and if so, how.

There are two forms of discriminated unions used. In setting the mode, uid, gid, or size, the discriminated union is switched on a boolean, set_it; if it is TRUE, a value of the appropriate type is then encoded.

In setting the atime or mtime, the union is switched on an enumeration type, set_it. If set_it has the value DONT_CHANGE, the corresponding attribute is unchanged. If it has the value, SET_TO_SERVER_TIME, the corresponding attribute is set by the server to its local time; no data is provided by the client. Finally, if set_it has the value, SET_TO_CLIENT_TIME, the attribute is set to the time passed by the client in an nfstime3 structure. (See FSINFO on page 86, which addresses the issue of time granularity).

   diropargs3

      struct diropargs3 {
         nfs_fh3     dir;
         filename3   name;
      };

The diropargs3 structure is used in directory operations. The file handle, dir, identifies the directory in which to manipulate or access the file, name. See additional comments in File name component handling on page 101.