3.3.12 Procedure 12: REMOVE - Remove a File

   SYNOPSIS

      REMOVE3res NFSPROC3_REMOVE(REMOVE3args) = 12;

      struct REMOVE3args {
           diropargs3  object;
      };

      struct REMOVE3resok {
           wcc_data    dir_wcc;
      };

      struct REMOVE3resfail {
           wcc_data    dir_wcc;
      };

      union REMOVE3res switch (nfsstat3 status) {
      case NFS3_OK:
           REMOVE3resok   resok;
      default:
           REMOVE3resfail resfail;
      };

   DESCRIPTION

      Procedure REMOVE removes (deletes) an entry from a
      directory. If the entry in the directory was the last
      reference to the corresponding file system object, the
      object may be destroyed.  On entry, the arguments in
      REMOVE3args are:

      object
         A diropargs3 structure identifying the entry to be
         removed:

      dir
         The file handle for the directory from which the entry
         is to be removed.

      name
         The name of the entry to be removed. Refer to General
         comments on filenames on page 30.

      On successful return, REMOVE3res.status is NFS3_OK and
      REMOVE3res.resok contains:

      dir_wcc
         Weak cache consistency data for the directory,
         object.dir.  For a client that requires only the
         post-REMOVE directory attributes, these can be found in
         dir_wcc.after.

      Otherwise, REMOVE3res.status contains the error on failure
      and REMOVE3res.resfail contains the following:

      dir_wcc
         Weak cache consistency data for the directory,
         object.dir.  For a client that requires only the
         post-REMOVE directory attributes, these can be found in
         dir_wcc.after. Even though the REMOVE failed, full
         wcc_data is returned to allow the client to determine
         whether the failing REMOVE changed the directory.

   IMPLEMENTATION

      In general, REMOVE is intended to remove non-directory
      file objects and RMDIR is to be used to remove
      directories.  However, REMOVE can be used to remove
      directories, subject to restrictions imposed by either the
      client or server interfaces.  This had been a source of
      confusion in the NFS version 2 protocol.

      The concept of last reference is server specific. However,
      if the nlink field in the previous attributes of the
      object had the value 1, the client should not rely on
      referring to the object via a file handle. Likewise, the
      client should not rely on the resources (disk space,
      directory entry, and so on.) formerly associated with the
      object becoming immediately available. Thus, if a client
      needs to be 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 accessible. The usual
      mechanism used is to use RENAME to rename the file from
      its old name to a new hidden name.

      Refer to General comments on filenames on page 30.

   ERRORS

      NFS3ERR_NOENT
      NFS3ERR_IO
      NFS3ERR_ACCES
      NFS3ERR_NOTDIR
      NFS3ERR_NAMETOOLONG

      NFS3ERR_ROFS
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_SERVERFAULT

   SEE ALSO

      RMDIR and RENAME.

3.3.13 Procedure 13: RMDIR - Remove a Directory

   SYNOPSIS

      RMDIR3res NFSPROC3_RMDIR(RMDIR3args) = 13;

      struct RMDIR3args {
           diropargs3  object;
      };

      struct RMDIR3resok {
           wcc_data    dir_wcc;
      };

      struct RMDIR3resfail {
           wcc_data    dir_wcc;
      };

      union RMDIR3res switch (nfsstat3 status) {
      case NFS3_OK:
           RMDIR3resok   resok;
      default:
           RMDIR3resfail resfail;
      };

   DESCRIPTION

      Procedure RMDIR removes (deletes) a subdirectory from a
      directory. If the directory entry of the subdirectory is
      the last reference to the subdirectory, the subdirectory
      may be destroyed. On entry, the arguments in RMDIR3args
      are:

      object
         A diropargs3 structure identifying the directory entry
         to be removed:

         dir
            The file handle for the directory from which the
            subdirectory is to be removed.

         name
            The name of the subdirectory to be removed. Refer to
            General comments on filenames on page 30.

      On successful return, RMDIR3res.status is NFS3_OK and
      RMDIR3res.resok contains:

      dir_wcc
         Weak cache consistency data for the directory,
         object.dir.  For a client that requires only the
         post-RMDIR directory attributes, these can be found in
         dir_wcc.after.

      Otherwise, RMDIR3res.status contains the error on failure
      and RMDIR3res.resfail contains the following:

      dir_wcc
         Weak cache consistency data for the directory,
         object.dir.  For a client that requires only the
         post-RMDIR directory attributes, these can be found in
         dir_wcc.after. Note that even though the RMDIR failed,
         full wcc_data is returned to allow the client to
         determine whether the failing RMDIR changed the
         directory.

   IMPLEMENTATION

      Note that on some servers, removal of a non-empty
      directory is disallowed.

      On some servers, the filename, ".", is illegal. These
      servers will return the error, NFS3ERR_INVAL. On some
      servers, the filename, "..", is illegal. These servers
      will return the error, NFS3ERR_EXIST. This would seem
      inconsistent, but allows these servers to comply with
      their own specific interface definitions.  Clients should
      be prepared to handle both cases.

      The client should not rely on the resources (disk space,
      directory entry, and so on.) formerly associated with the
      directory becoming immediately available.

   ERRORS

      NFS3ERR_NOENT
      NFS3ERR_IO
      NFS3ERR_ACCES
      NFS3ERR_INVAL
      NFS3ERR_EXIST
      NFS3ERR_NOTDIR
      NFS3ERR_NAMETOOLONG
      NFS3ERR_ROFS
      NFS3ERR_NOTEMPTY
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_NOTSUPP
      NFS3ERR_SERVERFAULT

   SEE ALSO

      REMOVE.

3.3.14 Procedure 14: RENAME - Rename a File or Directory

   SYNOPSIS

      RENAME3res NFSPROC3_RENAME(RENAME3args) = 14;

      struct RENAME3args {
           diropargs3   from;
           diropargs3   to;
      };

      struct RENAME3resok {
           wcc_data     fromdir_wcc;
           wcc_data     todir_wcc;
      };

      struct RENAME3resfail {
           wcc_data     fromdir_wcc;
           wcc_data     todir_wcc;
      };

      union RENAME3res switch (nfsstat3 status) {
      case NFS3_OK:
           RENAME3resok   resok;
      default:
           RENAME3resfail resfail;
      };

   DESCRIPTION

      Procedure RENAME renames the file identified by from.name
      in the directory, from.dir, to to.name in the di- rectory,
      to.dir. The operation is required to be atomic to the
      client. To.dir and from.dir must reside on the same file
      system and server. On entry, the arguments in RENAME3args
      are:

      from
         A diropargs3 structure identifying the source (the file
         system object to be re-named):

         from.dir
            The file handle for the directory from which the
            entry is to be renamed.

         from.name
            The name of the entry that identifies the object to
            be renamed. Refer to General comments on filenames
            on page 30.

      to
         A diropargs3 structure identifying the target (the new
         name of the object):

         to.dir
            The file handle for the directory to which the
            object is to be renamed.

         to.name
            The new name for the object. Refer to General
            comments on filenames on page 30.

      If the directory, to.dir, already contains an entry with
      the name, to.name, the source object must be compatible
      with the target: either both are non-directories or both
      are directories and the target must be empty. If
      compatible, the existing target is removed before the
      rename occurs. If they are not compatible or if the target
      is a directory but not empty, the server should return the
      error, NFS3ERR_EXIST.

      On successful return, RENAME3res.status is NFS3_OK and
      RENAME3res.resok contains:

      fromdir_wcc
         Weak cache consistency data for the directory,
         from.dir.

      todir_wcc
         Weak cache consistency data for the directory, to.dir.

      Otherwise, RENAME3res.status contains the error on failure
      and RENAME3res.resfail contains the following:

      fromdir_wcc
         Weak cache consistency data for the directory,
         from.dir.

      todir_wcc
         Weak cache consistency data for the directory, to.dir.

   IMPLEMENTATION
      The RENAME operation must be atomic to the client. The
      message "to.dir and from.dir must reside on the same file
      system on the server, [or the operation will fail]" means
      that the fsid fields in the attributes for the directories
      are the same. If they reside on different file systems,
      the error, NFS3ERR_XDEV, is returned. Even though the
      operation is atomic, the status, NFS3ERR_MLINK, may be
      returned if the server used a "unlink/link/unlink"
      sequence internally.

      A file handle may or may not become stale on a rename.
      However, server implementors are strongly encouraged to
      attempt to keep file handles from becoming stale in this
      fashion.

      On some servers, the filenames, "." and "..", are illegal
      as either from.name or to.name. In addition, neither
      from.name nor to.name can be an alias for from.dir. These
      servers will return the error, NFS3ERR_INVAL, in these
      cases.

      If from and to both refer to the same file (they might
      be hard links of each other), then RENAME should perform
      no action and return NFS3_OK.

      Refer to General comments on filenames on page 30.

   ERRORS

      NFS3ERR_NOENT
      NFS3ERR_IO
      NFS3ERR_ACCES
      NFS3ERR_EXIST
      NFS3ERR_XDEV
      NFS3ERR_NOTDIR
      NFS3ERR_ISDIR
      NFS3ERR_INVAL
      NFS3ERR_NOSPC
      NFS3ERR_ROFS
      NFS3ERR_MLINK
      NFS3ERR_NAMETOOLONG
      NFS3ERR_NOTEMPTY
      NFS3ERR_DQUOT
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_NOTSUPP
      NFS3ERR_SERVERFAULT

   SEE ALSO

   REMOVE and LINK.

3.3.15 Procedure 15: LINK - Create Link to an object

   SYNOPSIS

      LINK3res NFSPROC3_LINK(LINK3args) = 15;

      struct LINK3args {
           nfs_fh3     file;
           diropargs3  link;
      };

      struct LINK3resok {
           post_op_attr   file_attributes;
           wcc_data       linkdir_wcc;
      };

      struct LINK3resfail {
           post_op_attr   file_attributes;
           wcc_data       linkdir_wcc;
      };

      union LINK3res switch (nfsstat3 status) {
      case NFS3_OK:

           LINK3resok    resok;
      default:
           LINK3resfail  resfail;
      };

   DESCRIPTION

      Procedure LINK creates a hard link from file to link.name,
      in the directory, link.dir. file and link.dir must reside
      on the same file system and server. On entry, the
      arguments in LINK3args are:

      file
         The file handle for the existing file system object.

      link
         The location of the link to be created:

         link.dir
            The file handle for the directory in which the link
            is to be created.

         link.name
            The name that is to be associated with the created
            link. Refer to General comments on filenames on page
            17.

      On successful return, LINK3res.status is NFS3_OK and
      LINK3res.resok contains:

      file_attributes
         The post-operation attributes of the file system object
         identified by file.

      linkdir_wcc
         Weak cache consistency data for the directory,
         link.dir.

      Otherwise, LINK3res.status contains the error on failure
      and LINK3res.resfail contains the following:

      file_attributes
         The post-operation attributes of the file system object
         identified by file.

      linkdir_wcc
         Weak cache consistency data for the directory,
         link.dir.

   IMPLEMENTATION

      Changes to any property of the hard-linked files are
      reflected in all of the linked files. When a hard link is
      made to a file, the attributes for the file should have a
      value for nlink that is one greater than the value before
      the LINK.

      The comments under RENAME regarding object and target
      residing on the same file system apply here as well. The
      comments regarding the target name applies as well. Refer
      to General comments on filenames on page 30.

   ERRORS

      NFS3ERR_IO
      NFS3ERR_ACCES
      NFS3ERR_EXIST
      NFS3ERR_XDEV
      NFS3ERR_NOTDIR
      NFS3ERR_INVAL
      NFS3ERR_NOSPC
      NFS3ERR_ROFS
      NFS3ERR_MLINK
      NFS3ERR_NAMETOOLONG
      NFS3ERR_DQUOT
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_NOTSUPP
      NFS3ERR_SERVERFAULT

   SEE ALSO

      SYMLINK, RENAME and FSINFO.

3.3.16 Procedure 16: READDIR - Read From Directory

   SYNOPSIS

      READDIR3res NFSPROC3_READDIR(READDIR3args) = 16;

      struct READDIR3args {
           nfs_fh3      dir;
           cookie3      cookie;
           cookieverf3  cookieverf;
           count3       count;
      };

      struct entry3 {
           fileid3      fileid;
           filename3    name;
           cookie3      cookie;
           entry3       *nextentry;
      };

      struct dirlist3 {
           entry3       *entries;
           bool         eof;
      };

      struct READDIR3resok {
           post_op_attr dir_attributes;
           cookieverf3  cookieverf;
           dirlist3     reply;
      };

      struct READDIR3resfail {
           post_op_attr dir_attributes;
      };

      union READDIR3res switch (nfsstat3 status) {
      case NFS3_OK:
           READDIR3resok   resok;
      default:
           READDIR3resfail resfail;
      };

   DESCRIPTION

      Procedure READDIR retrieves a variable number of entries,
      in sequence, from a directory and returns the name and
      file identifier for each, with information to allow the
      client to request additional directory entries in a
      subsequent READDIR request. On entry, the arguments in
      READDIR3args are:

      dir
         The file handle for the directory to be read.

      cookie
         This should be set to 0 in the first request to read
         the directory. On subsequent requests, it should be a
         cookie as returned by the server.

      cookieverf
         This should be set to 0 in the first request to read
         the directory. On subsequent requests, it should be a
         cookieverf as returned by the server. The cookieverf
         must match that returned by the READDIR in which the
         cookie was acquired.

      count
         The maximum size of the READDIR3resok structure, in
         bytes.  The size must include all XDR overhead. The
         server is free to return less than count bytes of
         data.

      On successful return, READDIR3res.status is NFS3_OK and
      READDIR3res.resok contains:

      dir_attributes
         The attributes of the directory, dir.

      cookieverf
         The cookie verifier.

      reply
         The directory list:

         entries
            Zero or more directory (entry3) entries.

         eof
            TRUE if the last member of reply.entries is the last
            entry in the directory or the list reply.entries is
            empty and the cookie corresponded to the end of the
            directory. If FALSE, there may be more entries to
            read.

      Otherwise, READDIR3res.status contains the error on
      failure and READDIR3res.resfail contains the following:

      dir_attributes
         The attributes of the directory, dir.

   IMPLEMENTATION

      In the NFS version 2 protocol, each directory entry
      returned included a cookie identifying a point in the
      directory. By including this cookie in a subsequent
      READDIR, the client could resume the directory read at any
      point in the directory.  One problem with this scheme was

      that there was no easy way for a server to verify that a
      cookie was valid. If two READDIRs were separated by one or
      more operations that changed the directory in some way
      (for example, reordering or compressing it), it was
      possible that the second READDIR could miss entries, or
      process entries more than once. If the cookie was no
      longer usable, for example, pointing into the middle of a
      directory entry, the server would have to either round the
      cookie down to the cookie of the previous entry or round
      it up to the cookie of the next entry in the directory.
      Either way would possibly lead to incorrect results and
      the client would be unaware that any problem existed.

      In the NFS version 3 protocol, each READDIR request
      includes both a cookie and a cookie verifier. For the
      first call, both are set to 0.  The response includes a
      new cookie verifier, with a cookie per entry.  For
      subsequent READDIRs, the client must present both the
      cookie and the corresponding cookie verifier.  If the
      server detects that the cookie is no longer valid, the
      server will reject the READDIR request with the status,
      NFS3ERR_BAD_COOKIE. The client should be careful to
      avoid holding directory entry cookies across operations
      that modify the directory contents, such as REMOVE and
      CREATE.

      One implementation of the cookie-verifier mechanism might
      be for the server to use the modification time of the
      directory. This might be overly restrictive, however. A
      better approach would be to record the time of the last
      directory modification that changed the directory
      organization in a way that would make it impossible to
      reliably interpret a cookie. Servers in which directory
      cookies are always valid are free to use zero as the
      verifier always.

      The server may return fewer than count bytes of
      XDR-encoded entries.  The count specified by the client in
      the request should be greater than or equal to FSINFO
      dtpref.

      Since UNIX clients give a special meaning to the fileid
      value zero, UNIX clients should be careful to map zero
      fileid values to some other value and servers should try
      to avoid sending a zero fileid.

   ERRORS

      NFS3ERR_IO
      NFS3ERR_ACCES
      NFS3ERR_NOTDIR
      NFS3ERR_BAD_COOKIE
      NFS3ERR_TOOSMALL
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_SERVERFAULT

   SEE ALSO

      READDIRPLUS and FSINFO.

3.3.17 Procedure 17: READDIRPLUS - Extended read from directory

   SYNOPSIS

      READDIRPLUS3res NFSPROC3_READDIRPLUS(READDIRPLUS3args) = 17;

      struct READDIRPLUS3args {
           nfs_fh3      dir;
           cookie3      cookie;
           cookieverf3  cookieverf;
           count3       dircount;
           count3       maxcount;
      };

      struct entryplus3 {
           fileid3      fileid;
           filename3    name;
           cookie3      cookie;
           post_op_attr name_attributes;
           post_op_fh3  name_handle;
           entryplus3   *nextentry;
      };

      struct dirlistplus3 {
           entryplus3   *entries;
           bool         eof;
      };

      struct READDIRPLUS3resok {
           post_op_attr dir_attributes;
           cookieverf3  cookieverf;
           dirlistplus3 reply;
      };

      struct READDIRPLUS3resfail {
           post_op_attr dir_attributes;
      };

      union READDIRPLUS3res switch (nfsstat3 status) {
      case NFS3_OK:
           READDIRPLUS3resok   resok;
      default:
           READDIRPLUS3resfail resfail;
      };

   DESCRIPTION

      Procedure READDIRPLUS retrieves a variable number of
      entries from a file system directory and returns complete
      information about each along with information to allow the
      client to request additional directory entries in a
      subsequent READDIRPLUS.  READDIRPLUS differs from READDIR
      only in the amount of information returned for each
      entry.  In READDIR, each entry returns the filename and
      the fileid.  In READDIRPLUS, each entry returns the name,
      the fileid, attributes (including the fileid), and file
      handle. On entry, the arguments in READDIRPLUS3args are:

      dir
         The file handle for the directory to be read.

      cookie
         This should be set to 0 on the first request to read a
         directory. On subsequent requests, it should be a
         cookie as returned by the server.

      cookieverf
         This should be set to 0 on the first request to read a
         directory. On subsequent requests, it should be a
         cookieverf as returned by the server. The cookieverf
         must match that returned by the READDIRPLUS call in
         which the cookie was acquired.

      dircount
         The maximum number of bytes of directory information
         returned. This number should not include the size of
         the attributes and file handle portions of the result.

      maxcount
         The maximum size of the READDIRPLUS3resok structure, in
         bytes. The size must include all XDR overhead. The

         server is free to return fewer than maxcount bytes of
         data.

      On successful return, READDIRPLUS3res.status is NFS3_OK
      and READDIRPLUS3res.resok contains:

      dir_attributes
         The attributes of the directory, dir.

      cookieverf
         The cookie verifier.

      reply
         The directory list:

         entries
            Zero or more directory (entryplus3) entries.

         eof
            TRUE if the last member of reply.entries is the last
            entry in the directory or the list reply.entries is
            empty and the cookie corresponded to the end of the
            directory. If FALSE, there may be more entries to
            read.

      Otherwise, READDIRPLUS3res.status contains the error on
      failure and READDIRPLUS3res.resfail contains the following:

      dir_attributes
         The attributes of the directory, dir.

   IMPLEMENTATION

      Issues that need to be understood for this procedure
      include increased cache flushing activity on the client
      (as new file handles are returned with names which are
      entered into caches) and over-the-wire overhead versus
      expected subsequent LOOKUP elimination. It is thought that
      this procedure may improve performance for directory
      browsing where attributes are always required as on the
      Apple Macintosh operating system and for MS-DOS.

      The dircount and maxcount fields are included as an
      optimization.  Consider a READDIRPLUS call on a UNIX
      operating system implementation for 1048 bytes; the reply
      does not contain many entries because of the overhead due
      to attributes and file handles. An alternative is to issue
      a READDIRPLUS call for 8192 bytes and then only use the

      first 1048 bytes of directory information. However, the
      server doesn't know that all that is needed is 1048 bytes
      of directory information (as would be returned by
      READDIR). It sees the 8192 byte request and issues a
      VOP_READDIR for 8192 bytes. It then steps through all of
      those directory entries, obtaining attributes and file
      handles for each entry.  When it encodes the result, the
      server only encodes until it gets 8192 bytes of results
      which include the attributes and file handles. Thus, it
      has done a larger VOP_READDIR and many more attribute
      fetches than it needed to. The ratio of the directory
      entry size to the size of the attributes plus the size of
      the file handle is usually at least 8 to 1. The server has
      done much more work than it needed to.

      The solution to this problem is for the client to provide
      two counts to the server. The first is the number of bytes
      of directory information that the client really wants,
      dircount.  The second is the maximum number of bytes in
      the result, including the attributes and file handles,
      maxcount. Thus, the server will issue a VOP_READDIR for
      only the number of bytes that the client really wants to
      get, not an inflated number.  This should help to reduce
      the size of VOP_READDIR requests on the server, thus
      reducing the amount of work done there, and to reduce the
      number of VOP_LOOKUP, VOP_GETATTR, and other calls done by
      the server to construct attributes and file handles.

   ERRORS

      NFS3ERR_IO
      NFS3ERR_ACCES
      NFS3ERR_NOTDIR
      NFS3ERR_BAD_COOKIE
      NFS3ERR_TOOSMALL
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_NOTSUPP
      NFS3ERR_SERVERFAULT

   SEE ALSO

      READDIR.

3.3.18 Procedure 18: FSSTAT - Get dynamic file system information

   SYNOPSIS

      FSSTAT3res NFSPROC3_FSSTAT(FSSTAT3args) = 18;

      struct FSSTAT3args {
           nfs_fh3   fsroot;
      };

      struct FSSTAT3resok {
           post_op_attr obj_attributes;
           size3        tbytes;
           size3        fbytes;
           size3        abytes;
           size3        tfiles;
           size3        ffiles;
           size3        afiles;
           uint32       invarsec;
      };

      struct FSSTAT3resfail {
           post_op_attr obj_attributes;
      };

      union FSSTAT3res switch (nfsstat3 status) {
      case NFS3_OK:
           FSSTAT3resok   resok;
      default:
           FSSTAT3resfail resfail;
      };

   DESCRIPTION

      Procedure FSSTAT retrieves volatile file system state
      information. On entry, the arguments in FSSTAT3args are:

      fsroot
         A file handle identifying a object in the file system.
         This is normally a file handle for a mount point for a
         file system, as originally obtained from the MOUNT
         service on the server.

      On successful return, FSSTAT3res.status is NFS3_OK and
      FSSTAT3res.resok contains:

      obj_attributes
         The attributes of the file system object specified in
         fsroot.

      tbytes
         The total size, in bytes, of the file system.

      fbytes
         The amount of free space, in bytes, in the file
         system.

      abytes
         The amount of free space, in bytes, available to the
         user identified by the authentication information in
         the RPC.  (This reflects space that is reserved by the
         file system; it does not reflect any quota system
         implemented by the server.)

      tfiles
         The total number of file slots in the file system. (On
         a UNIX server, this often corresponds to the number of
         inodes configured.)

      ffiles
         The number of free file slots in the file system.

      afiles
         The number of free file slots that are available to the
         user corresponding to the authentication information in
         the RPC.  (This reflects slots that are reserved by the
         file system; it does not reflect any quota system
         implemented by the server.)

      invarsec
         A measure of file system volatility: this is the number
         of seconds for which the file system is not expected to
         change. For a volatile, frequently updated file system,
         this will be 0. For an immutable file system, such as a
         CD-ROM, this would be the largest unsigned integer. For
         file systems that are infrequently modified, for
         example, one containing local executable programs and
         on-line documentation, a value corresponding to a few
         hours or days might be used. The client may use this as
         a hint in tuning its cache management. Note however,
         this measure is assumed to be dynamic and may change at
         any time.

      Otherwise, FSSTAT3res.status contains the error on failure
      and FSSTAT3res.resfail contains the following:

      obj_attributes
         The attributes of the file system object specified in
         fsroot.

   IMPLEMENTATION

      Not all implementations can support the entire list of
      attributes. It is expected that servers will make a best
      effort at supporting all the attributes.

   ERRORS

      NFS3ERR_IO
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_SERVERFAULT

   SEE ALSO

      FSINFO.

3.3.19 Procedure 19: FSINFO - Get static file system Information

   SYNOPSIS

      FSINFO3res NFSPROC3_FSINFO(FSINFO3args) = 19;

      const FSF3_LINK        = 0x0001;
      const FSF3_SYMLINK     = 0x0002;
      const FSF3_HOMOGENEOUS = 0x0008;
      const FSF3_CANSETTIME  = 0x0010;

      struct FSINFOargs {
           nfs_fh3   fsroot;
      };

      struct FSINFO3resok {
           post_op_attr obj_attributes;
           uint32       rtmax;
           uint32       rtpref;
           uint32       rtmult;
           uint32       wtmax;
           uint32       wtpref;
           uint32       wtmult;
           uint32       dtpref;

           size3        maxfilesize;
           nfstime3     time_delta;
           uint32       properties;
      };

      struct FSINFO3resfail {
           post_op_attr obj_attributes;
      };

      union FSINFO3res switch (nfsstat3 status) {
      case NFS3_OK:
           FSINFO3resok   resok;
      default:
           FSINFO3resfail resfail;
      };

   DESCRIPTION

      Procedure FSINFO retrieves nonvolatile file system state
      information and general information about the NFS version
      3 protocol server implementation. On entry, the arguments
      in FSINFO3args are:

      fsroot
         A file handle identifying a file object. Normal usage
         is to provide a file handle for a mount point for a
         file system, as originally obtained from the MOUNT
         service on the server.

      On successful return, FSINFO3res.status is NFS3_OK and
      FSINFO3res.resok contains:

      obj_attributes
         The attributes of the file system object specified in
         fsroot.

      rtmax
         The maximum size in bytes of a READ request supported
         by the server. Any READ with a number greater than
         rtmax will result in a short read of rtmax bytes or
         less.

      rtpref
         The preferred size of a READ request. This should be
         the same as rtmax unless there is a clear benefit in
         performance or efficiency.

      rtmult
         The suggested multiple for the size of a READ request.

      wtmax
         The maximum size of a WRITE request supported by the
         server.  In general, the client is limited by wtmax
         since there is no guarantee that a server can handle a
         larger write. Any WRITE with a count greater than wtmax
         will result in a short write of at most wtmax bytes.

      wtpref
         The preferred size of a WRITE request. This should be
         the same as wtmax unless there is a clear benefit in
         performance or efficiency.

      wtmult
         The suggested multiple for the size of a WRITE
         request.

      dtpref
         The preferred size of a READDIR request.

      maxfilesize
         The maximum size of a file on the file system.

      time_delta
         The server time granularity. When setting a file time
         using SETATTR, the server guarantees only to preserve
         times to this accuracy. If this is {0, 1}, the server
         can support nanosecond times, {0, 1000000} denotes
         millisecond precision, and {1, 0} indicates that times
         are accurate only to the nearest second.

      properties
         A bit mask of file system properties. The following
         values are defined:

         FSF_LINK
            If this bit is 1 (TRUE), the file system supports
            hard links.

         FSF_SYMLINK
            If this bit is 1 (TRUE), the file system supports
            symbolic links.

         FSF_HOMOGENEOUS
            If this bit is 1 (TRUE), the information returned by
            PATHCONF is identical for every file and directory

            in the file system. If it is 0 (FALSE), the client
            should retrieve PATHCONF information for each file
            and directory as required.

         FSF_CANSETTIME
            If this bit is 1 (TRUE), the server will set the
            times for a file via SETATTR if requested (to the
            accuracy indicated by time_delta). If it is 0
            (FALSE), the server cannot set times as requested.

      Otherwise, FSINFO3res.status contains the error on failure
      and FSINFO3res.resfail contains the following:

      attributes
         The attributes of the file system object specified in
         fsroot.

   IMPLEMENTATION

      Not all implementations can support the entire list of
      attributes. It is expected that a server will make a best
      effort at supporting all the attributes.

      The file handle provided is expected to be the file handle
      of the file system root, as returned to the MOUNT
      operation.  Since mounts may occur anywhere within an
      exported tree, the server should expect FSINFO requests
      specifying file handles within the exported file system.
      A server may export different types of file systems with
      different attributes returned to the FSINFO call. The
      client should retrieve FSINFO information for each mount
      completed. Though a server may return different FSINFO
      information for different files within a file system,
      there is no requirement that a client obtain FSINFO
      information for other than the file handle returned at
      mount.

      The maxfilesize field determines whether a server's
      particular file system uses 32 bit sizes and offsets or 64
      bit file sizes and offsets. This may affect a client's
      processing.

      The preferred sizes for requests are nominally tied to an
      exported file system mounted by a client. A surmountable
      issue arises in that the transfer size for an NFS version
      3 protocol request is not only dependent on
      characteristics of the file system but also on
      characteristics of the network interface, particularly the

      maximum transfer unit (MTU). A server implementation can
      advertise different transfer sizes (for the fields, rtmax,
      rtpref, wtmax, wtpref, and dtpref) depending on the
      interface on which the FSINFO request is received. This is
      an implementation issue.

   ERRORS

      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_SERVERFAULT

   SEE ALSO

      READLINK, WRITE, READDIR, FSSTAT and PATHCONF.

3.3.20 Procedure 20: PATHCONF - Retrieve POSIX information

   SYNOPSIS

      PATHCONF3res NFSPROC3_PATHCONF(PATHCONF3args) = 20;

      struct PATHCONF3args {
           nfs_fh3   object;
      };

      struct PATHCONF3resok {
           post_op_attr obj_attributes;
           uint32       linkmax;
           uint32       name_max;
           bool         no_trunc;
           bool         chown_restricted;
           bool         case_insensitive;
           bool         case_preserving;
      };

      struct PATHCONF3resfail {
           post_op_attr obj_attributes;
      };

      union PATHCONF3res switch (nfsstat3 status) {
      case NFS3_OK:
           PATHCONF3resok   resok;
      default:
           PATHCONF3resfail resfail;
      };

   DESCRIPTION

      Procedure PATHCONF retrieves the pathconf information for
      a file or directory. If the FSF_HOMOGENEOUS bit is set in
      FSFINFO3resok.properties, the pathconf information will be
      the same for all files and directories in the exported
      file system in which this file or directory resides. On
      entry, the arguments in PATHCONF3args are:

      object
         The file handle for the file system object.

      On successful return, PATHCONF3res.status is NFS3_OK and
      PATHCONF3res.resok contains:

      obj_attributes
         The attributes of the object specified by object.

      linkmax
         The maximum number of hard links to an object.

      name_max
         The maximum length of a component of a filename.

      no_trunc
         If TRUE, the server will reject any request that
         includes a name longer than name_max with the error,
         NFS3ERR_NAMETOOLONG. If FALSE, any length name over
         name_max bytes will be silently truncated to name_max
         bytes.

      chown_restricted
         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 the privileged user. (Uid 0.)

      case_insensitive
         If TRUE, the server file system does not distinguish
         case when interpreting filenames.

      case_preserving
         If TRUE, the server file system will preserve the case
         of a name during a CREATE, MKDIR, MKNOD, SYMLINK,
         RENAME, or LINK operation.

      Otherwise, PATHCONF3res.status contains the error on
      failure and PATHCONF3res.resfail contains the following:

      obj_attributes
         The attributes of the object specified by object.

   IMPLEMENTATION

      In some implementations of the NFS version 2 protocol,
      pathconf information was obtained at mount time through
      the MOUNT protocol.  The proper place to obtain it, is as
      here, in the NFS version 3 protocol itself.

   ERRORS

      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_SERVERFAULT

   SEE ALSO

      LOOKUP, CREATE, MKDIR, SYMLINK, MKNOD, RENAME, LINK and FSINFO.

3.3.21 Procedure 21: COMMIT - Commit cached data on a server to stable
       storage

   SYNOPSIS

      COMMIT3res NFSPROC3_COMMIT(COMMIT3args) = 21;

      struct COMMIT3args {
           nfs_fh3    file;
           offset3    offset;
           count3     count;
      };

      struct COMMIT3resok {
           wcc_data   file_wcc;
           writeverf3 verf;
      };

      struct COMMIT3resfail {
           wcc_data   file_wcc;
      };

      union COMMIT3res switch (nfsstat3 status) {
      case NFS3_OK:
           COMMIT3resok   resok;
      default:
           COMMIT3resfail resfail;
      };

   DESCRIPTION

      Procedure COMMIT forces or flushes data to stable storage
      that was previously written with a WRITE procedure call
      with the stable field set to UNSTABLE. On entry, the
      arguments in COMMIT3args are:

      file
         The file handle for the file to which data is to be
         flushed (committed). This must identify a file system
         object of type, NF3REG.

      offset
         The position within the file at which the flush is to
         begin.  An offset of 0 means to flush data starting at
         the beginning of the file.

      count
         The number of bytes of data to flush. If count is 0, a
         flush from offset to the end of file is done.

      On successful return, COMMIT3res.status is NFS3_OK and
      COMMIT3res.resok contains:

      file_wcc
         Weak cache consistency data for the file. For a client
         that requires only the post-operation file attributes,
         these can be found in file_wcc.after.

      verf
         This is a cookie that the client can use to determine
         whether the server has rebooted between a call to WRITE
         and a subsequent call to COMMIT. This cookie must be
         consistent during a single boot session and must be
         unique between instances of the NFS version 3 protocol
         server where uncommitted data may be lost.

      Otherwise, COMMIT3res.status contains the error on failure
      and COMMIT3res.resfail contains the following:

      file_wcc
         Weak cache consistency data for the file. For a client
         that requires only the post-write file attributes,
         these can be found in file_wcc.after. Even though the
         COMMIT failed, full wcc_data is returned to allow the
         client to determine whether the file changed on the
         server between calls to WRITE and COMMIT.

   IMPLEMENTATION

      Procedure COMMIT is similar in operation and semantics to
      the POSIX fsync(2) system call that synchronizes a file's
      state with the disk, that is it flushes the file's data
      and metadata to disk. COMMIT performs the same operation
      for a client, flushing any unsynchronized data and
      metadata on the server to the server's disk for the
      specified file. Like fsync(2), it may be that there is
      some modified data or no modified data to synchronize. The
      data may have been synchronized by the server's normal
      periodic buffer synchronization activity. COMMIT will
      always return NFS3_OK, unless there has been an unexpected
      error.

      COMMIT differs from fsync(2) in that it is possible for
      the client to flush a range of the file (most likely
      triggered by a buffer-reclamation scheme on the client
      before file has been completely written).

      The server implementation of COMMIT is reasonably simple.
      If the server receives a full file COMMIT request, that is
      starting at offset 0 and count 0, it should do the
      equivalent of fsync()'ing the file. Otherwise, it should
      arrange to have the cached data in the range specified by
      offset and count to be flushed to stable storage.  In both
      cases, any metadata associated with the file must be
      flushed to stable storage before returning. It is not an
      error for there to be nothing to flush on the server.
      This means that the data and metadata that needed to be
      flushed have already been flushed or lost during the last
      server failure.

      The client implementation of COMMIT is a little more
      complex.  There are two reasons for wanting to commit a
      client buffer to stable storage. The first is that the
      client wants to reuse a buffer. In this case, the offset
      and count of the buffer are sent to the server in the
      COMMIT request. The server then flushes any cached data
      based on the offset and count, and flushes any metadata
      associated with the file. It then returns the status of
      the flush and the verf verifier.  The other reason for the
      client to generate a COMMIT is for a full file flush, such
      as may be done at close. In this case, the client would
      gather all of the buffers for this file that contain
      uncommitted data, do the COMMIT operation with an offset
      of 0 and count of 0, and then free all of those buffers.
      Any other dirty buffers would be sent to the server in the

      normal fashion.

      This implementation will require some modifications to the
      buffer cache on the client. After a buffer is written with
      stable UNSTABLE, it must be considered as dirty by the
      client system until it is either flushed via a COMMIT
      operation or written via a WRITE operation with stable set
      to FILE_SYNC or DATA_SYNC. This is done to prevent the
      buffer from being freed and reused before the data can be
      flushed to stable storage on the server.

      When a response comes back from either a WRITE or a COMMIT
      operation that contains an unexpected verf, the client
      will need to retransmit all of the buffers containing
      uncommitted cached data to the server.  How this is to be
      done is up to the implementor. If there is only one buffer
      of interest, then it should probably be sent back over in
      a WRITE request with the appropriate stable flag. If there
      more than one, it might be worthwhile retransmitting all
      of the buffers in WRITE requests with stable set to
      UNSTABLE and then retransmitting the COMMIT operation to
      flush all of the data on the server to stable storage. The
      timing of these retransmissions is left to the
      implementor.

      The above description applies to page-cache-based systems
      as well as buffer-cache-based systems. In those systems,
      the virtual memory system will need to be modified instead
      of the buffer cache.

      See additional comments on WRITE on page 49.

   ERRORS

      NFS3ERR_IO
      NFS3ERR_STALE
      NFS3ERR_BADHANDLE
      NFS3ERR_SERVERFAULT

   SEE ALSO

      WRITE.