Network File System: Version 2 Protocol Specification

Table of Contents

• 2. Introduction
  • 2.1. Remote Procedure Call
  • 2.2. External Data Representation
  • 2.3. Stateless Servers
• 3. NFS Protocol Definition
  • 3.1. File System Model
  • 3.2. RPC Information
  • 3.3. Sizes of XDR Structures
  • 3.4. Basic Data Types
    • 3.4.1. stat

      enum stat {
      	NFS_OK = 0,
      	NFSERR_PERM=1,
      	NFSERR_NOENT=2,
      	NFSERR_IO=5,
      	NFSERR_NXIO=6,
      	NFSERR_ACCES=13,
      	NFSERR_EXIST=17,
      	NFSERR_NODEV=19,
      	NFSERR_NOTDIR=20,
      	NFSERR_ISDIR=21,
      	NFSERR_FBIG=27,
      	NFSERR_NOSPC=28,
      	NFSERR_ROFS=30,
      	NFSERR_NAMETOOLONG=63,
      	NFSERR_NOTEMPTY=66,
      	NFSERR_DQUOT=69,
      	NFSERR_STALE=70,
      	NFSERR_WFLUSH=99
      };
      

    • 3.4.2. ftype

      enum ftype {
      	NFNON = 0,
      	NFREG = 1,
      	NFDIR = 2,
      	NFBLK = 3,
      	NFCHR = 4,
      	NFLNK = 5
      };
      

      The enumeration ftype gives the type of a file. The type NFNON indicates a non-file, NFREG is a regular file, NFDIR is a directory, NFBLK is a block-special device, NFCHR is a character-special device, and NFLNK is a symbolic link.
    • 3.4.3. fhandle

      typedef opaque fhandle[FHSIZE];
      

      The fhandle is the file handle passed between the server and the client. All file operations are done using file handles to refer to a file or directory. The file handle can contain whatever information the server needs to distinguish an individual file.
    • 3.4.4. timeval

      struct timeval {
      	unsigned int seconds;
      	unsigned int useconds;
      };
      

      The timeval structure is the number of seconds and microseconds since midnight January 1, 1970, Greenwich Mean Time. It is used to pass time and date information.
    • 3.4.5. fattr

      struct fattr {
      	ftype        type;
      	unsigned int mode;
      	unsigned int nlink;
      	unsigned int uid;
      	unsigned int gid;
      	unsigned int size;
      	unsigned int blocksize;
      	unsigned int rdev;
      	unsigned int blocks;
      	unsigned int fsid;
      	unsigned int fileid;
      	timeval      atime;
      	timeval      mtime;
      	timeval      ctime;
      };
      

      The fattr structure contains the attributes of a file; "type" is the type of the file; "nlink" is the number of hard links to the file (the number of different names for the same file); "uid" is the user identification number of the owner of the file; "gid" is the group identification number of the group of the file; "size" is the size in bytes of the file; "blocksize" is the size in bytes of a block of the file; "rdev" is the device number of the file if it is type NFCHR or NFBLK; "blocks" is the number of blocks the file takes up on disk; "fsid" is the file system identifier for the filesystem containing the file; "fileid" is a number that uniquely identifies the file within its filesystem; "atime" is the time when the file was last accessed for either read or write; "mtime" is the time when the file data was last modified (written); and "ctime" is the time when the status of the file was last changed. Writing to the file also changes "ctime" if the size of the file changes.
    • 3.4.6. sattr

      struct sattr {
      	unsigned int mode;
      	unsigned int uid;
      	unsigned int gid;
      	unsigned int size;
      	timeval      atime;
      	timeval      mtime;
      };
      

      The sattr structure contains the file attributes which can be set from the client. The fields are the same as for fattr above. A "size" of zero means the file should be truncated. A value of -1 indicates a field that should be ignored.
    • 3.4.7. filename

      typedef string filename<MAXNAMLEN>;
      

      The type filename is used for passing file names or pathname components.
    • 3.4.8. path

      typedef string path<MAXPATHLEN>;
      

      The type path is a pathname. The server considers it as a string with no internal structure, but to the client it is the name of a node in a filesystem tree.
    • 3.4.9. attrstat

      union attrstat switch (stat status) {
      	case NFS_OK:
      		fattr attributes;
      	default:
      		void;
      };
      

      The attrstat structure is a common procedure result. It contains a "status" and, if the call succeeded, it also contains the attributes of the file on which the operation was done.
    • 3.4.10. diropargs

      struct diropargs {
      	fhandle  dir;
      	filename name;
      };
      

      The diropargs structure is used in directory operations. The "fhandle" "dir" is the directory in which to find the file "name". A directory operation is one in which the directory is affected.
    • 3.4.11. diropres

      union diropres switch (stat status) {
      	case NFS_OK:
      		struct {
      			fhandle file;
      			fattr   attributes;
      		} diropok;
      	default:
      		void;
      };
      

      The results of a directory operation are returned in a diropres structure. If the call succeeded, a new file handle "file" and the "attributes" associated with that file are returned along with the "status".
  • 3.5. Server Procedures
    • 3.5.1. Do Nothing

      void 
      NFSPROC_NULL(void) = 0;
      

      This procedure does no work. It is made available in all RPC services to allow server response testing and timing.
    • 3.5.2. Get File Attributes

      attrstat 
      NFSPROC_GETATTR (fhandle) = 1;
      

      If the reply status is NFS_OK, then the reply attributes contains the attributes for the file given by the input fhandle.
    • 3.5.3. Set File Attributes

      struct sattrargs {
      	fhandle file;
      	sattr attributes;
      	};
      
      attrstat
      NFSPROC_SETATTR (sattrargs) = 2;
      

      The "attributes" argument contains fields which are either -1 or are the new value for the attributes of "file". If the reply status is NFS_OK, then the reply attributes have the attributes of the file after the "SETATTR" operation has completed.
    • 3.5.4. Get Filesystem Root

      void 
      NFSPROC_ROOT(void) = 3;
      

      Obsolete. This procedure is no longer used because finding the root file handle of a filesystem requires moving pathnames between client and server. To do this right we would have to define a network standard representation of pathnames. Instead, the function of looking up the root file handle is done by the MNTPROC_MNT() procedure. (See the Mount Protocol Definition later in this chapter for details).
    • 3.5.5. Look Up File Name

      diropres
      NFSPROC_LOOKUP(diropargs) = 4;
      

      If the reply "status" is NFS_OK, then the reply "file" and reply "attributes" are the file handle and attributes for the file "name" in the directory given by "dir" in the argument.
    • 3.5.6. Read From Symbolic Link

      union readlinkres switch (stat status) {
      	case NFS_OK:
      		path data;
      	default:
      		void;
      };
      
      readlinkres
      NFSPROC_READLINK(fhandle) = 5;
      

      If "status" has the value NFS_OK, then the reply "data" is the data in the symbolic link given by the file referred to by the fhandle argument.
    • 3.5.7. Read From File

      struct readargs {
      	fhandle file;
      	unsigned offset;
      	unsigned count;
      	unsigned totalcount;
      };
      
      union readres switch (stat status) {
      	case NFS_OK:
      		fattr attributes;
      		opaque data<NFS_MAXDATA>;
      	default:
      		void;
      };
      
      readres
      NFSPROC_READ(readargs) = 6;
      

      Returns up to "count" bytes of "data" from the file given by "file", starting at "offset" bytes from the beginning of the file. The first byte of the file is at offset zero. The file attributes after the read takes place are returned in "attributes".
    • 3.5.8. Write to Cache

      void
      NFSPROC_WRITECACHE(void) = 7;
      

      To be used in the next protocol revision.
    • 3.5.9. Write to File

      struct writeargs {
      	fhandle file;          
      	unsigned beginoffset;  
      	unsigned offset;       
      	unsigned totalcount;   
      	opaque data<NFS_MAXDATA>;
      };
      
      attrstat	
      NFSPROC_WRITE(writeargs) = 8;
      

      Writes "data" beginning "offset" bytes from the beginning of "file". The first byte of the file is at offset zero. If the reply "status" is NFS_OK, then the reply "attributes" contains the attributes of the file after the write has completed. The write operation is atomic. Data from this call to WRITE will not be mixed with data from another client's calls.
    • 3.5.10. Create File

      struct createargs {
      	diropargs where;
      	sattr attributes;
      };
      
      diropres
      NFSPROC_CREATE(createargs) = 9;
      

      The file "name" is created in the directory given by "dir". The initial attributes of the new file are given by "attributes". A reply "status" of NFS_OK indicates that the file was created, and reply "file" and reply "attributes" are its file handle and attributes. Any other reply "status" means that the operation failed and no file was created.
    • 3.5.11. Remove File

      stat
      NFSPROC_REMOVE(diropargs) = 10;
      

      The file "name" is removed from the directory given by "dir". A reply of NFS_OK means the directory entry was removed.
    • 3.5.12. Rename File

      struct renameargs {
      	diropargs from;	
      	diropargs to;
      };
      
      stat
      NFSPROC_RENAME(renameargs) = 11;
      

      The existing file "from.name" in the directory given by "from.dir" is renamed to "to.name" in the directory given by "to.dir". If the reply is NFS_OK, the file was renamed. The RENAME operation is atomic on the server; it cannot be interrupted in the middle.
    • 3.5.13. Create Link to File

      struct linkargs {
      	fhandle from;
      	diropargs to;
      };
      
      stat
      NFSPROC_LINK(linkargs) = 12;
      

      Creates the file "to.name" in the directory given by "to.dir", which is a hard link to the existing file given by "from". If the return value is NFS_OK, a link was created. Any other return value indicates an error, and the link was not created.
    • 3.5.14. Create Symbolic Link

      struct symlinkargs {
      	diropargs from;
      	path to;
      	sattr attributes;
      };
      
      stat
      NFSPROC_SYMLINK(symlinkargs) = 13;
      

      Creates the file "from.name" with ftype NFLNK in the directory given by "from.dir". The new file contains the pathname "to" and has initial attributes given by "attributes". If the return value is NFS_OK, a link was created. Any other return value indicates an error, and the link was not created.
    • 3.5.15. Create Directory

      diropres
      NFSPROC_MKDIR (createargs) = 14;
      

      The new directory "where.name" is created in the directory given by "where.dir". The initial attributes of the new directory are given by "attributes". A reply "status" of NFS_OK indicates that the new directory was created, and reply "file" and reply "attributes" are its file handle and attributes. Any other reply "status" means that the operation failed and no directory was created.
    • 3.5.16. Remove Directory

      stat
      NFSPROC_RMDIR(diropargs) = 15;
      

      The existing empty directory "name" in the directory given by "dir" is removed. If the reply is NFS_OK, the directory was removed.
    • 3.5.17. Read From Directory

      struct readdirargs {
      	fhandle dir;            
      	nfscookie cookie;
      	unsigned count;         
      };
      
      struct entry {
      	unsigned fileid;
      	filename name;
      	nfscookie cookie;
      	entry *nextentry;
      };
      
      union readdirres switch (stat status) {
      	case NFS_OK:
      		struct {
      			entry *entries;
      			bool eof;
      		} readdirok;
      	default:
      		void;
      };
      
      readdirres
      NFSPROC_READDIR (readdirargs) = 16;
      

      Returns a variable number of directory entries, with a total size of up to "count" bytes, from the directory given by "dir". If the returned value of "status" is NFS_OK, then it is followed by a variable number of "entry"s. Each "entry" contains a "fileid" which consists of a unique number to identify the file within a filesystem, the "name" of the file, and a "cookie" which is an opaque pointer to the next entry in the directory. The cookie is used in the next READDIR call to get more entries starting at a given point in the directory. The special cookie zero (all bits zero) can be used to get the entries starting at the beginning of the directory. The "fileid" field should be the same number as the "fileid" in the the attributes of the file. (See the Basic Data Types section.) The "eof" flag has a value of TRUE if there are no more entries in the directory.
    • 3.5.18. Get Filesystem Attributes

      union statfsres (stat status) {
      	case NFS_OK:
      		struct {
      			unsigned tsize; 
      			unsigned bsize; 
      			unsigned blocks;
      			unsigned bfree; 
      			unsigned bavail;
      		} info;
      	default:
      		void;
      };
      
      statfsres
      NFSPROC_STATFS(fhandle) = 17;
      

      If the reply "status" is NFS_OK, then the reply "info" gives the attributes for the filesystem that contains file referred to by the input fhandle. The attribute fields contain the following values:
• 4. NFS Implementation Issues
  • 4.1. Server/Client Relationship
  • 4.2. Pathname Interpretation
  • 4.3. Permission Issues
  • 4.4. Setting RPC Parameters
• 5. Mount Protocol Definition
  • 5.1. Introduction
  • 5.2. RPC Information
  • 5.3. Sizes of XDR Structures
  • 5.4. Basic Data Types
    • 5.4.1. fhandle

      typedef opaque fhandle[FHSIZE];
      

      The type fhandle is the file handle that the server passes to the client. All file operations are done using file handles to refer to a file or directory. The file handle can contain whatever information the server needs to distinguish an individual file.
    • 5.4.2. fhstatus

      union fhstatus switch (unsigned status) {
      	case 0:
      		fhandle directory;
      	default:
      		void;
      };
      

      The type fhstatus is a union. If a "status" of zero is returned, the call completed successfully, and a file handle for the "directory" follows. A non-zero status indicates some sort of error. In this case the status is a UNIX error number.
    • 5.4.3. dirpath

      typedef string dirpath<MNTPATHLEN>;
      

      The type dirpath is a server pathname of a directory.
    • 5.4.4. name

      typedef string name<MNTNAMLEN>;
      

      The type name is an arbitrary string used for various names.
  • 5.5. Server Procedures
    • 5.5.1. Do Nothing

      void 
      MNTPROC_NULL(void) = 0;
      

      This procedure does no work. It is made available in all RPC services to allow server response testing and timing.
    • 5.5.2. Add Mount Entry

      fhstatus
      MNTPROC_MNT(dirpath) = 1;
      

      If the reply "status" is 0, then the reply "directory" contains the file handle for the directory "dirname". This file handle may be used in the NFS protocol. This procedure also adds a new entry to the mount list for this client mounting "dirname".
    • 5.5.3. Return Mount Entries

      struct *mountlist {
      	name      hostname;
      	dirpath   directory;
      	mountlist nextentry;
      };
      
      mountlist
      MNTPROC_DUMP(void) = 2;
      

      Returns the list of remote mounted filesystems. The "mountlist" contains one entry for each "hostname" and "directory" pair.
    • 5.5.4. Remove Mount Entry

      void
      MNTPROC_UMNT(dirpath) = 3;
      

      Removes the mount list entry for the input "dirpath".
    • 5.5.5. Remove All Mount Entries

      void
      MNTPROC_UMNTALL(void) = 4;
      

      Removes all of the mount list entries for this client.
    • 5.5.6. Return Export List

      struct *groups {
      	name grname;
      	groups grnext;
      };
      
      struct *exportlist {
      	dirpath filesys;
      	groups groups;
      	exportlist next;
      };
      
      exportlist
      MNTPROC_EXPORT(void) = 5;
      

      Returns a variable number of export list entries. Each entry contains a filesystem name and a list of groups that are allowed to import it. The filesystem name is in "filesys", and the group name is in the list "groups".