InfoMagic Internet Tools 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Internet Tools 1993 July / Internet Tools.iso / iso9660 / ip / nfs / spec < prev next >

Wrap

Text File | 1988-11-25 | 76.1 KB | 2,711 lines

Here is an ascii version of the NFS version 3 protocol specification. ========================================================================= CUT HERE ========================================================================= Sun Network Filesystem Protocol Specification Comments to: sun!nfs3 nfs3@SUN.COM Sun Microsystems, Inc. 2550 Garcia Ave. Mountain View, CA 94043 Introduction The Sun Network Filesystem (NFS) protocol provides transparent remote access to shared filesystems over local area networks. The NFS protocol is designed to be machine, operating system, network architecture, and transport protocol independent. This independence is achieved through the use of Remote Procedure Call (RPC) primitives built on top of an External Data Representation (XDR). The supporting MOUNT protocol [reference] allows the server to grant remote access privileges to a restricted set of clients. In this protocol specification the term "server" refers to a machine that provides resources to the network; a "client" is a machine that accesses resources over the network; a "user" is a person "logged in" at a client; an "application" is a program that executes on a client; and a "workstation" is a client machine that typically supports one user at a time. Remote Procedure Call Sun's Remote Procedure Call specification [RFC 1050] provides a clean, procedure oriented interface to remote services. Each server supplies a program which is a set of procedures. Servers can support multiple versions of a program by using different protocol version numbers. The combination of host address, program number, version number and procedure number specify one remote service procedure. External Data Representation The Sun External Data Representation (XDR) specification [RFC 1014] provides a standard way of representing a set of data types on a network. This takes care of the problem of different byte orders, structure alignment, and data type representation on different, communicating machines. In this document we use the XDR Data Definition Language [RFC 1014] to specify the parameters and results to each of the RPC service procedures that a NFS server provides. The XDR definition language is similar to declarations in the C programming language. A few new constructs have been added. The notation: string name[SIZE]; string data<DSIZE>; defines "name", which is a fixed size block of SIZE bytes, and "data", which is a variable size block of up to DSIZE bytes. This same notation is used to indicate fixed length arrays and arrays with a variable number of elements up to a fixed maximum. The discriminated union definition: union switch (enum status) { NFS_OK: struct { filename file1; filename file2; integer count; } NFS_ERROR: struct { errstat error; integer errno; } default: void v; } defines a structure where the first thing over the network is an enumeration type called status. If the value of status is NFS_OK, the next thing on the network will be the structure containing file1, file2, and count. If the value of status is neither NFS_OK nor NFS_ERROR then there is no more data to look at. The XDR type hyper is an 8 byte integer. It is used in the same way as the integer type. For example: hyper foo; unsigned hyper bar; "foo" is an 8 byte signed value, while "bar" is an 8 byte unsigned value. Authentication and Permission Checking The RPC protocol includes a slot for authentication parameters on every call. The contents of the authentication parameters are determined by the "flavor" of authentication used by the server and client. A server may support several different flavors of authentication at once. The flavor called AUTH_NONE provides null authentication, that is, no authentication information is passed. The AUTH_UNIX flavor passes uid, gid, and groups with each call. The AUTH_DES flavor provides DES encrypted authentication parameters based on a network-wide name. The NFS server does permission checking by assuming the identity of the caller before servicing a remote request. For example, using AUTH_UNIX flavor authentication the server gets the client's effective uid, effective gid and groups on each call, and uses them to check permission. Using uid and gids implies that the client and server either share the same uid list or do local uid mapping. Every server and client pair must have the same mapping from user to uid and from group to gid. The AUTH_DES style of authentication provides a network name that is encrypted using DES encryption and public keys. Again, the server and client must agree on the identity of a particular name on the network, but the name to identity mapping is more operating system independent then the uid and gid mapping in AUTH_UNIX. Also, because the authentication parameters are encrypted a malicious user must know another user's network password to masquerade as that user. Similarly, the server returns a verifier that is also encrypted so that masquerading as a server requires knowing a network password. The GETRESINFO and NULL procedures require no authentication. Clients can use the MOUNT protocol to find out which authentication flavors are required for other NFS procedures. Philosophy Because the NFS protocol is designed to be operating system independent it does not exactly match the semantics of any existing system. Server implementations are expected to make a "best effort" at supporting the protocol. If a server cannot support a particular protocol procedure it should return the NFSERR_OPNOTSUP error that indicates that the operation is not supported. For example, many operating systems do not support the notion of a "hard link". A server that cannot support hard links should return NFSERR_OPNOTSUP in response to a LINK or UNLINK request. In some cases a server can support most of the semantics described by the protocol but not all. For example, the ctime field in the fattr structure gives the time that a file's attributes were last modified. Many systems do not keep this information around. In this case, rather than not support the GETATTR operation, a server should fake it by returning the last modified time in place of ctime. NFS servers are dumb and NFS clients are smart. It is the clients that do the work required to convert the generalized file access that servers provide into a file access method which is useful to applications and users. In the LINK example given above, a UNIX(R) client that received an NFSERR_OPNOTSUP from a server would do the recovery necessary to either make it look to the application like the link request had succeeded or return an reasonable error. The NFS protocol assumes a stateless server implementation. Statelessness means that the server does not need to maintain state about any of its clients in order to function correctly. Stateless servers have a distinct advantage over stateful servers in the event of a crash. With stateless servers, a client need only retry a request until the server responds, the client does not even need to know that the server has crashed. This is not to say that servers are not allowed to maintain state about client operations, but that the state held by servers is not required for correct operation. In many cases servers will maintain state about previous operations to increase performance. For example, a client READ request might trigger a read-ahead of the next block of the file into the server's data cache in the hope that the client is doing a sequential read and the next client READ request will be satisfied from the cache instead of from the disk. The read-ahead block is not necessary for correct server behavior, but it increases the server's performance. All of the procedures in the NFS protocol except WRITECACHE are assumed to be synchronous. When a procedure returns to the client, the client can assume that the operation has completed and any modified data associated with the request is now on stable storage. For example, a client WRITE request may cause the server to update data blocks, filesystem information blocks, and file attribute information (size and modify times). When the WRITE operation completes, the client can assume that the write data is safe and discard it. This is a very important part of the statelessness of the server. If the server did not flush dirty data before returning to the client, the client would have no way of knowing when it was safe to discard modified data. The LOOKUP procedure is used by the client to traverse multi-segment file names (pathnames). Each call to LOOKUP is used to resolve one segment of a pathname. There are two reasons for restricting LOOKUP to a single segment: because it is hard to standardize a common format for hierarchical file names; and because the client and server may have different mappings of pathnames to filesystems. This implies that either the client must break the path name at filesystem attachment points, or the server must know about the client's filesystem attachment points. Clients can do as much or as little caching as they want. The protocol does not have any explicit support for client cache consistency. Changes for Version 3 Version 3 of the NFS protocol supports these new procedures: GETRESINFO returns information about server resources, ACCESS provides access permission checking, CREATEUNIQ creates a uniquely named file on the server, ZERO punches holes in files, LINKAGE maps file handles from one RPC service to another, STOREATTR stores extended attribute values. The ROOT, MKDIR and RMDIR procedures have been removed, and the WRITECACHE procedure is now fully supported. All procedures that affect the attributes of a file or directory now return the new attributes after the operation has completed. Below is a list of the important changes between version 2 and version 3 of the protocol. Port Number The port number is now registered with the Portmap service and can change if a server crashes. The client should consult the server's portmap service when in doubt about the validity of the port number (e.g. after a timeout or network addressing error.) Fhandle size The file handle is variable length up to 1024 bytes instead of a fixed array of 32 bytes. MAXDATA The maximum size of a data transfer used in the READ, WRITE, WRITECACHE and READDIR procedures is now set by values in the GETFSINFO return structure. Error return The error return on all calls now includes both an error number and a string. If the client does not understand the number it can print the string. File type The file type now includes NFSPEC for special files. The NFSPEC type also includes a subtype string that can be used to define new file types. File name The file name is now composed of a name string and an extension string. The extension string can be used to extend the name space. Predefined extensions are provided to support version numbering and Macintosh forked files. File attributes The rdev and blocksize fields have been removed and the mode field no longer contains file type information. Remove and system permission bits were added for owner, group and other. The user and group fields are strings instead of unsigned integers. The size and fileno fields are 8 byte unsigned instead of 4 bytes. The blocks field name has been changed to used, and it now returns the total number of bytes used by the file. It is also an 8 byte unsigned value. Set file attributes The set file attributes uses a boolean for each field to tell whether to set that field. The time fields can be set to either the server's current time or a time supplied by the client. Extended attributes The GETATTR and SETATTR operations now have an optional counted array of key/value strings that can be used to extend the standard set of attributes. The key string identifies the syntax and semantics of the value string. Lookup The lookup arguments now include a boolean "parent" used to request the parent directory fhandle instead of passing the well known filename "..". The lookup return structure includes a boolean that is TRUE if the fhandle returned is a mount point for another filesystem on the server. Read The reply structure includes a boolean that is TRUE if end-of-file was encountered on the read. This allows the server to return less data than the client requested. Write cache Allows the client to write file data into the server's data cache then flush all data to disk synchronously with the last WRITECACHE request. Write Removed the beginoffset and totalcount fields from the write arguments. The reply now includes a count so that the server can write less than the requested amount of data. Create, remove, rename, mkdir, rmdir, link, symlink Added an exclusive flag to allow creation of a name that already exists in the server's filesystem. If the exclusive flag is FALSE the arguments must also include the file handle of the existing target name. This allows the server to do real idempotent creation operations by comparing the file handle in the arguments against the file handle of the target file, and returning an error if they do not match. Create Create can now be used to make files directories and special files. Only the permission bits can be set in the initial attributes of the file. Remove Remove can now be used to remove all filesystem objects. Readdir The readdir arguments now include a boolean to request all names in the directory, including normally hidden names. fsinfo Added new fields to the reply structure for file counts, directory block size, initial timeout, read size, write size, illegal characters, an array that tells which procedures are supported and how long they take to service, a flags field with bits that tell whether the server supports special filesystem functions like version numbers and record files, and a variable length array of extended attributes. RPC Information Authentication The NFS service uses AUTH_NONE in the GETRESINFO and NULL procedures. Consult the PORTMAP service or use the GETRESINFO procedure to determine authentication requirements for other NFS procedures. Constants These are the RPC constants needed to call the NFS service. They are given in decimal. PROGRAM 100003 VERSION 3 Port Number Consult Portmap service for NFS port number. The RPC port number may change if the server crashes and restarts. Sizes These are the sizes, given in decimal bytes, of various XDR structures used in the protocol. MAXPATHLEN 1024 The maximum number of bytes in a pathname argument. MAXFILENAMELEN 256 The maximum number of bytes in a file name argument. MAXNAMEEXT 32 The maximum number of bytes in a file name extension string. MAXNAMELEN 128 The maximum number of bytes in a user name or group name. MAXERRLEN 128 The maximum length in bytes of the error string returned on a failed call. MAXFHSIZE 1024 The maximum size in bytes of the opaque file handle. COOKIESIZE 4 The size in bytes of the opaque "cookie" passed by READDIR. MAXEXATTR 64 Maximum number of extended attribute key-value pairs. MAXKEYLEN 32 The size in bytes of the key string in a key-value pair. MAXVALLEN 256 The size in bytes of the value string in a key-value pair. MAXTYPELEN 32 The maximum size in bytes of the subtype string in the "ftype" structure. MAXBADCHAR 256 Maximum number of illegal filename characters returned by GETFSINFO. Basic Data Types The following XDR definitions are basic definitions that are used in other structures later on. stat enum stat { NFS_OK = 0, NFS_ERROR=1 }; The stat type is returned with every procedure's results. A value of NFS_OK indicates that the call completed successfully and the results are valid. A value of NFS_ERROR indicates that some error occurred on the call. In this case a errinfo structure is returned. errinfo struct errinfo { unsigned error; string errstr<NFS_MAXERRLEN>; }; The errinfo structure contains the error information associated with a failed request. The error can either be one of the predefined errors below or an error that is specific to a particular server. In either case the error string should contain an error message that can be printed by the client. Predefined Error Numbers NFSERR_UNKNOWN = 1 Unknown error. The server could not map an error indication into a standard NFS error number, refer to the error string. NFSERR_NOENT = 2 No such file or directory. The file or directory name specified does not exist. NFSERR_IO = 3 I/O error. A hard error (e.g. disk error) occurred when the operation was in progress. NFSERR_BADTYPE = 4 File type not supported. The file type is not supported by the server. NFSERR_ACCESS = 5 Permission denied. The caller does not have the correct permission to perform the requested operation. NFSERR_EXIST = 6 File exists. The file specified already exists. NFSERR_BADOFFSET = 7 Illegal file offset. The offset given in a READ, WRITE, ZERO, or WRITECACHE call does not make sense. NFSERR_NOTDIR = 8 Not a directory. The caller specified a non-directory in a directory operation. NFSERR_ISDIR = 9 Is a directory. The caller specified a directory in a non-directory operation. NFSERR_FBIG = 10 File too large. The operation caused a file to grow beyond the server's limit. NFSERR_NOSPC = 11 No space left on device. The operation caused the server's filesystem to reach its limit. NFSERR_ROFS = 12 Read-only filesystem. Write attempted on a read-only filesystem. NFSERR_NAMETOOLONG = 13 File name too long. The file name in an operation was too long. NFSERR_NOTEMPTY = 14 Directory not empty. Attempt to remove a directory that was not empty. NFSERR_DQUOT = 15 Disk quota exceeded. The client's disk quota on the server has been exceeded. NFSERR_STALE = 16 Invalid file handle. The fhandle given in the arguments was invalid. The file referred to by that file handle no longer exists or access to it has been revoked. NFSERR_WFLUSH = 17 The client data from a set of WRITECACHE requests could not be flushed to disk. NFSERR_NOTSYMLINK = 18 The file is not a symbolic link. The fhandle passed in a READLINK request did not refer to a symbolic link file. NFSERR_NOTREG = 19 Not a regular file. An operation was attempted on an object whose filetype was not NFREG. NFSERR_OPNOTSUP = 20 Operation not supported. The server does not support this NFS operation. NFSSERR_DUPREQ = 21 Might be a duplicate request. The server has detected what might be a duplicate request. NFSERR_NOTFILE = 22 Not a file. A file operation was attempted on a non-file (e.g. WRITE on a directory.) NFSERR_PRIV = 23 Privileged operation. The caller does not have the correct identity to perform the requested privileged operation. NFSERR_NOTOWNER = 24 Not owner. The operation was not allowed because the caller does not own the target of the operation. NFSERR_BADCOOKIE = 25 Bad opaque cookie. A cookie passed in the READDIR request was invalid. NFSERR_BADCHAR = 26 Bad character. String contains an illegal character. NFSERR_BADNAME = 27 Illegal file name. The fname given is illegal on the server. NFSERR_BADATTR = 28 Illegal attribute. One of the attributes passed in a SETATTR call is not supported by the server. NFSERR_BADTYPE = 29 Illegal file type. The file type specified in a CREATE operation is not supported by the server. NFSERR_JUKEBOX = 30 Slow down, buddy. The server has detected a retransmission of a request that is already in progress. NFSERR_SOFTLIMIT = 31 Soft resource limit exceeded. Operation succeeded, but a soft resource limit was exceeded. NFSERR_HARDLIMIT = 32 Hard resource limit reached. Operation failed because a hard resource limit was reached. ftype enum filetype { NFREG = 1, NFDIR = 2, NFLNK = 3, NFSPEC =4, }; union ftype switch (filetype type) { NFSPEC: string spectype<MAXSPECTYPE>; default: void v; }; The union ftype gives the type of a file. The type NFREG is a regular file, NFDIR is a directory, NFLNK is a symbolic link. The NFSPEC type is used for special file types such as record files, devices and named pipes. It includes a sub-type identifier string that encodes the type of the object. The predefined special file subtypes are given below. UNX:BLCK:major#:minor# UNIX style block device. The major# and minor# fields are character strings that represent decimal numbers defining the major and minor device numbers (e.g. UNX:BLCK:25:8). UNX:CHAR:major#:minor# UNIX style character device. The major# and minor# fields are character strings that represent decimal numbers defining the major and minor device numbers. UNX:SOCK UNIX style named socket. UNX:FIFO UNIX style named pipe. MAC:DATA Macintosh data fork. MAC:FIND Macintosh finder info fork. MAC:RESR Macintosh resource fork. REC:FIXD:record-size Fixed length record file. The record-size field is a character string that represents the decimal number of bytes in a record. REC:VAR Variable length record file. fhandle typedef opaque fhandle<MAXFHSIZE>; The 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 contain all of the information the server needs to distinguish an individual file, while, to the client, the fhandle is opaque. The client can store fhandles for use in a later request, and can compare two fhandles from the same server for equality by doing a byte by byte comparison, but cannot otherwise interpret the contents of fhandles. If two fhandles 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 on e correspondence between fhandles and files, but they are not required to. Clients should use fhandle comparison only to improve performance, not for correct behavior. Servers can revoke the access provided by an fhandle at any time. If the fhandle passed in a call refers to an object that no longer exists on the server or access for that fhandle has been revoked the NFSERR_STALE error will be returned. nfsdata typedef opaque nfsdata The nfsdata type is used by the READ, WRITE, WRITECACHE and READDIR operations to define the data portion of a request or reply. The maximum size allowed by the protocol is limited by what XDR and underlying transports will allow, but the actual size allowed in a given operation is determined by values returned by the server in the GETFSINFO reply. Consult the procedure descriptions for details. fileid typedef unsigned hyper fileid; The fileid is returned by the server in response to a GETATTR or READDIR request. It is a number which uniquely identifies the file within a filesystem. Client applications can use this value to compare two files in the same filesystem for equality. filesize typedef unsigned hyper filesize; The filesize type is used for counts of bytes in files and directories. fileoffset typedef unsigned hyper fileoffset; The fileoffset type is used for byte offsets into files. position struct position { boolean append; fileoffset offset; } Position is used to specify the location of data in a file. The value of offset specifies a byte offset in a file. If append is TRUE the server will return the error NFSERR_BADOFFSET if offset does not match the current size of the file. timeval struct timeval { unsigned seconds; unsigned useconds; }; The timeval structure gives the number of seconds and microseconds 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 explicitly sets the file times to client time. permbits typedef unsigned permbits; Permbits encodes access permission as a set of bits. Some of the permission bits don't make sense on the server (e.g. execute permission) and are provided only for client use. A bit value of one means that the operation corresponding to that bit position is allowed. The descriptions given below specify the bit positions using hexadecimal numbers. 40000 Hidden. 20000 Read permission for system. 10000 Write permission for system. 08000 Execute permission for system on a file. 08000 Lookup permission for system on a directory. 04000 Remove permission for owner. 02000 Remove permission for group. 01000 Remove permission for others. 00800 Set user id on execution. 00400 Set group id on execution. 00200 Save swapped text. 00100 Read permission for owner. 00080 Write permission for owner. 00040 Execute permission for owner on a file. 00040 Lookup permission for owner on a directory. 00020 Read permission for group. 00010 Write permission for group. 00008 Execute permission for group on a file. 00008 Lookup permission for group on a directory. 00004 Read permission for others. 00002 Write permission for others. 00001 Execute permission for others on a file. 00001 Lookup permission for others on a directory. name typedef string name<MAXNAMELEN>; The name string is used for both user names and group names in the sattr and fattr structures. The interpretation of the name string is determined by a "type field" of the string, delimeted by a ":" character. The predefined type string "ID" specifies an ASCII encoding of a non-negative identifier number. For example: ID:1229 ID:2 ID:12345 As standards for mapping user and group identity in a network evolve, other name type strings and name interpretations will be defined. keystr, valstr and keyval typedef string keystr<MAXKEYLEN>; typedef string valstr<MAXVALLEN>; struct keyval { keystr key; valstr value; }; The keyval type is used to provide a hook for extending the attributes of files and filesystems. The key string is used to identify and determine how to interpret the value string. fattr struct fattr { ftype type; permbits perm; unsigned nlink; name user; name group; filesize size; filesize used; fileid fileno; timeval atime; timeval mtime; timeval ctime; timeval btime; }; The fattr structure contains the basic attributes of a file. All servers should support this set of attributes even if they have to fake some of the fields. Type is the type of the file. Nlink is the number of hard links to the file, that is, the number of different names for the same file. User is the user name of the owner of the file. Group is the group name of the group of the file. Size is the size in bytes of the file. Used is the number of byte of disk space that the file actually uses. File no is a number which uniquely identifies the file within its filesystem. Atime is the time when the file data was last accessed for either read or write. Mtime is the time when the file data was last modified (written). Ctime is the time when the attributes of the file was last changed. Btime is the time the file was created (born). Servers that do not support a creation time should return the value of ctime for the btime field. sattr enum settime { NONE=0, SERVER=1, CLIENT=2, }; struct sattr { union switch (boolean set_size) { TRUE: filesize size; }; union switch (boolean set_perm) { TRUE: permbits perm; }; union switch (boolean set_user) { TRUE: name user; }; union switch (boolean set_group) { TRUE: name group; }; union switch (settime set_atime) { CLIENT: timeval atime; }; union switch (settime set_mtime) { CLIENT: timeval mtime; }; union switch (settime set_ctime) { CLIENT: timeval ctime; }; }; The sattr structure contains the file attributes that can be set from the client. The fields are the same as the similarly named fields in the fattr structure above. The booleans set_perm, set_user, set_group and set_size tell whether the perm, user, group and size attributes should be set. The enumerations set_atime, set_m time and set_ctime tell whether the time attributes atime, mtime and ctime should be set to current server time (SERVER), to a time supplied by the client (CLIENT), or not set at all (NONE). filename struct filename { string name<MAXNAMLEN>; string extension<MAXNAMEEXT>; }; The filename is used for passing file names and pathname components. The name field contains the string which is the name of a single component of a path. The extension specifies an extension to the name, such as which version the name refers to. A NULL extension string means that no name extension should be used. There is no structure defined by the NFS protocol in the name portion of a filename. The predefined extension strings for version numbered files are given below. In these strings the "<num>" field represents the string encoding of a positive decimal number (e.g. "23"). VER:FST The first (oldest) version of a name. VER:CUR The current (youngest) version of a name. VER:NXT:<num> The next version after <num>. VER:PRE:<num> The previous version before <num>. VER:NUM:<num> The version <num>. The predefined extension strings for Macintosh forked files are given below. MAC:RES Macintosh resource fork. MAC:DAT Macintosh data fork. MAC:FND Macintosh finder info fork. Other name extension strings may be defined to support other special file features. Servers that don't support a file extension will return the error NFSERR_BADNAME. path typedef string path<MAXPATHLEN>; The type path is a string which is treated as opaque data by the server but can be used by the client to hold a pathname. attrstat union attrstat switch (stat status) { case NFS_OK: fattr attributes; case NFS_ERROR: errinfo errinfo; }; The attrstat structure is returned result as the result of a SETATTR operation. It contains a status and, if the call succeeded, the attributes of the file on which the operation was done; otherwise it contains error information. diropargs typedef struct { fhandle dir; filename name; } diropargs; 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 effected, for example: CREATE, REMOVE or LINK. diropres union diropres switch (stat status) { case NFS_OK: struct diropokres { fhandle targ; fattr targattr; fattr dirattr; } ok; case NFS_ERROR: errinfo errinfo; }; The results of a directory operation are returned in a diropres structure. If the call succeeded a new file handle and the attributes of both the parent directory and the target file are returned along with the status. rmtarget union rmtarget switch (boolean exclusive) { FALSE: fhandle targetfh; }; The rmtarget structure is used in calls that may destroy a file or directory such as CREATE and LINK. An exclusive flag value of TRUE means that if an object already exists with the same name as the target of the operation it should not be destroyed. If the exclusive flag is FALSE it means that the target of the operation should be destroyed if it exists. In this case the fhandle of the target is also included so the server can check that the correct target is being destroyed. For example, if a client wants to create a file in a single NFS operation but the file to be created already exists, the client would do a CREATE operation with exclusive set to FALSE and targetfh set to the fhandle of the existing file. When the server detects an incorrect value for targetfh the error value NFSERR_EXISTS error is returned. It is then up to the client to decide whether to retry the operation with a new value for the target fhandle or to give up. Server Procedures The following sections define the RPC procedures that are supplied by a NFS server. The RPC procedure number is given at the top of the page along with the name and version. The SYNOPSIS field has the format: <proc #>. <proc name>( <arguments> ) returns ( <results> ) <argument declarations> <results declarations> In the first line, <proc name> is the name of the procedure, <arguments> is a list of the names of the arguments, <results> is a list of the names of the results. The following lines give the XDR argument declarations and results declarations. The DESCRIPTION field tells what the procedure is expected to do and how its arguments and results are used. The ERRORS section lists the errors returned for specific types of failures. If there is no error return listed in this section for a particular error condition it is up to the server to return the error code that most closely describes the error. The IMPLEMENTATION field gives information about how the procedure is expected to work and how it should be used by clients. Procedure -1 GETRESINFO Version 3 Get Resource Information SYNOPSIS -1. NFSPROC_GETRESINFO( resources, keys ) returns ( resinfo ) const MAXRESNAME = 256; const MAXRESOURCES = 1024; const MAXINFO = 1024; string resource<MAXRESNAME>; resource resources<MAXRESOURCES>; keystr keys<MAXINFO>; union resinfo switch (unsigned integer error) { case 0: resinfo *next; resource resname; keyval info<MAXINFO>; default: string errstr<MAXERRLEN>; } DESCRIPTION GETRESINFO returns information about resources provided by the NFS server. If the array of resources names, resources, is zero length information about all known resources will be returned, otherwise only information about the given resource names will be returned. Likewise, if the array of key strings, keys, is zero length all key/value pairs will be returned, otherwise on the key/value pairs corresponding to the given keys strings will be returned. If error is zero, a list resource names and resource information follows, otherwise, errstr is a string which gives human readable information about the error that occured. GETRESINFO is provided as a way for servers to advertise the resources that they supply. Resource names are arbitrary strings with no interpretation. The key/value array associated with a resource name give information about that resource. Some key values are predefined, others will be added to the protocol as needed. (The predefined keys and their values are TBD.) IMPLEMENTATION If a key or resource name is given that the server does not understand no entry for that resource name or key string will be returned. It is up to the client to match the request strings against the reply strings. Procedure 0 NULL Version 3 Do Nothing SYNOPSIS 0. NFSPROC_NULL( ) returns ( ) DESCRIPTION This procedure does no work. It is made available in all RPC services to allow server response testing and timing. IMPLEMENTATION It is important that this procedure do no work at all so that it can be used to measure the overhead of processing a service request. Procedure 1 GETATTR Version 3 Get File Attributes SYNOPSIS 1. NFSPROC_GETATTR( file, exkeys ) returns ( reply ) fhandle file; keystr exkeys<MAXEXATTR>; union getattrreply switch (stat status) { case NFS_OK: fattr attributes; keyval exattr<MAXEXATTR>; case NFS_ERROR: errinfo errinfo; }reply; DESCRIPTION File is the file or directory whose attributes are to be returned. Exkeys is an optional array of extended attribute key strings to be returned in addition to the standard attributes (see the section on the exattr structure for more information on extended types.) If reply.status is NFS_OK then reply.attribu tes contains the attributes for file, and exattr is a counted array of key/value strings that correspond to the keys in exkeys. The key string identifies the syntax and semantics of the value string. Extended attributes requested in the exkeys array that are not supported by the server will not be returned. If reply.status is NFS_ERROR then reply.errinfo contains error information. IMPLEMENTATION The attributes of filesystem objects is the point of most disagreement between different operating systems. Servers should make a best attempt to support the attributes in the fattr structure so that clients can count on this as a common ground. The extended attributes are provided as a way to extend the standard attributes between cooperating clients and servers. The name space of extended attribute key strings is left open. It is expected that new attributes that arise that are of general use among a broad range of implementations will be given a general name, and will be included in future revisions of this specification. Attributes that are only used among a restricted set of implementations (e.g. used by a single vendor) should be given names that are not likely to conflict with other restricted names (e.g. <vendor name>.<attribute name>). Since GETATTR returns attributes that are both set and stored (see SETATTR and STOREATTR descriptions for more information) the client needs a way to distinguish between them. The GETFSINFO procedure returns an array, setkeys, of the extended attribute keys that can be set with a SETATTR call. Procedure 2 SETATTR Version 3 Set File Attributes SYNOPSIS 2. NFSPROC_SETATTR( file, ctime, newattr, exattr ) returns ( reply ) fhandle file; timeval ctime sattr newattr; keyval exattr<MAXEXATTR>; attrstat reply; DESCRIPTION The newattr argument contains booleans and enumerations that indicate which attributes of file to set (see the section on sattr for more details). The exattr argument is an array of key/value pairs that encode the extended attributes to be set. The ctime argument is the current ctime value from the attributes of file. If reply.status is NFS_OK, reply.attributes has the attributes of the file aft er the SETATTR operation has completed. If reply.status is NFS_ERROR then reply.errinfo contains error information. An error return NFSERR_DUPREQ means that the argument ctime did not match the ctime of file on the server. IMPLEMENTATION The ctime argument is included to allow servers to detect duplicated SETATTR requests and report them back to the client using the NFSERR_DUPREQ. This error can occur for two reasons: 1) the SETATTR request was duplicated before arriving at the server; 2) that attributes of file changed between when the client last got attributes for file from the server and when the SETATTR operation was attempted by the server. The client can recover from this error by getting fresh attributes from the server and sending a new SETATTR request using the new ctime. The client can optionally check the attributes to avoid the second SETATTR request if the new attributes show that case 1 occurred and the attributes have already been set. The newattr.size field changes the size of a file. A value of 0 causes the file to be truncated, a value less than the current size of file causes data from the end of the file to be discarded, and a size greater than the current size of file causes zeroed data bytes to be added to the end of file. To extend a file with "holes" (data that doesn't take up disk space) the client should use the ZERO procedure. The extended attributes are assumed to cause side effects on the use of file. For example, and extended attribute "access-list" might limit file access to users on the access list. Attributes that do not cause side effects, but are stored by the server and returned in a GETATTR request, are set using the STOREATTR procedure. If server and client times differ, programs that compare client time to file times can break. A time maintenance protocol should be used to limit client/server time skew. Procedure 3 STOREATTR Version 3 Store File Attributes SYNOPSIS 3. NFSPROC_STOREATTR( file, exattr ) returns ( reply ) fhandle file; keyval exattr<<MAXEXATTR>; attrstat reply; DESCRIPTION The exattr argument is an array of key/value pairs that encode the extended attributes to be stored. If reply.status is NFS_OK, reply.attributes has the attributes of the file aft er the STOREATTR operation has completed. If reply.status is NFS_ERROR then reply.errinfo contains error information. IMPLEMENTATION The extended attributes do not cause side effects on the use of file, they are just stored by the server and returned on a GETATTR request. To set extended attributes that do cause side effects the SETATTR procedure should be used. Procedure 4 ACCESS Version 3 Check Access Permission SYNOPSIS 4. NFSPROC_ACCESS( object ) returns ( reply ) fhandle object; #define SEARCH 01 #define WRITE 02 #define READ 04 #define CHANGE 08 #define REMOVE 10 union accessres switch (stat status) { case NFS_OK: unsigned allowed; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Check what type of access is allowed on object. If reply.status is NFS_OK then allowed encodes the type of access allowed using the bit encodings defined by the hexadecimal numbers SEARCH, WRITE, READ, CHANGE and REMOVE. A bit value of 1 means the corresponding access type is allowed. SEARCH access means that the directory file handle object can be used as the argument to a LOOKUP operation (this only makes sense if object is a directory,) WRITE access means the data in object can be changed, READ access means the data in object can be accessed, CHANGE means the attributes of object can be changed using the SETATTR or STOREATTR procedures, and REMOVE means that object can be removed. If reply.status is NFS_ERROR then reply.errinfo contains error information. IMPLEMENTATION The ACCESS operation is provided to allow clients to do access checking before doing a series of operations. This is useful in operating systems (such as UNIX) where permission checking is done only when a file or directory is opened. The information returned by the server in response to an ACCESS call is not permanent. The server can revoke access permission at any time. Procedure 5 INACTIVE Version3 Advise of Inactive File Handle SYNOPSIS 2. NFSPROC_INACTIVE( object ) returns ( reply ) fhandle object; union closeres switch (stat status) { case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Advise the server that object is no longer in use. This procedure is used by the client to inform the server that the fhandle obje ct is not longer in use. This allows the server to free any resources associated with object. If reply.status is NFS_ERROR then reply.errinfo contains error information. IMPLEMENTATION The INACTIVE operation is advisory only. The server can not rely on the client doing a INACTIVE for every fhandle since file handles may be lost due to client crashes. Clients should make a best effort to send a INACTIVE every time a file handle is thrown away. Procedure 6 LOOKUP Version 3 Lookup File Name SYNOPSIS 6. NFSPROC_LOOKUP( which ) returns ( reply ) struct lookupargs { fhandle dir; union switch ( boolean parent ) { case FALSE: filename name; }; } which; union lookupres switch (stat status) { case NFS_OK: struct lookupokres { fhandle file; filename realname; fattr attributes; boolean mountpt; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION If reply.status is NFS_OK, reply.ok.file and reply.ok. attributes are the file handle and attributes for the file which.name in the directory given by which.dir, and reply.ok.realname is the real name of the file. name and realname may be different if, for example, name includes a "next version number" extension string (see the filename structure definition for more information.) The boolean reply.ok.mountpt is TRUE if this is a mount point for a filesystem on the server. If which.parent is TRUE then file, attributes and mountpt refer to the parent directory of which.dir. If which.dir is the root directory of a filesystem it is its own parent. If reply. status is NFS_ERROR then reply.errinfo contains error information. IMPLEMENTATION The case where which.name refers to a mount point on the server two different replies are possible. The server can return either the file handle for the underlying directory that is mounted on, or the file handle of the root of the mounted directory. Returning the file handle of the underlying directory forces the client to use the MOUNT service to access the mounted directory, which insures that MOUNT access checking can be done on the server. On the other hand, for servers that don't care about MOUNT access checking returning the fhandle of the mounted directory provides the client access to all exported filesystems. The mountpt boolean is provided so that the client can tell when a mount point is reached that the sever will not cross. In this case the client can use the MOUNT protocol to duplicate the server's mounted filesystem at this mount point. ERRORS NFSERR_NOENT Which.name does not exist in which.dir. NFSERR_NOTDIR Which.dir is not a directory. NFSERR_NAMETOOLONG Which.name contains too many characters. Procedure 7 READ Version 3 Read From File SYNOPSIS 7. NFSPROC_READ( file, location, count , totalcount ) returns ( reply ) fhandle file; fileoffset location; unsigned count; unsigned totalcount; union readres switch (stat status) { case NFS_OK: struct readokres { nfsdata data; boolean eof; fattr attributes; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Returns up to count bytes of data from location in file. File must be either a regular (ftype NFREG) or special (ftype NFSPEC) file. When reading from a regular file location is the byte offset into file from which data should be read. A byte offset of zero mean read data starting at the beginning of the file. If reply.status is NFS_OK reply.ok.attributes is the attributes of the file following the read, reply.ok.data is the counted data read from the file, and reply.ok.eof indicates whether end-of-file was encountered on the read. If reply.status is NFS_ERROR then reply.errinfo contains error information. IMPLEMENTATION The server has the option of returning fewer than count bytes of data. Count must be less than or equal to the value of the rsize field in the GETFSINFO reply structure (see GETFSINFO procedure for more details) for the filesystem which contains file. The totalcount argument is provided as a hint to the server that more read operations will follow. Totalcount should be set to the number of bytes beyond location+count that the client intends to read. If the ftype of file is NFSPEC the READ operation might not be supported by the server. If it is supported the location argument encodes what to read in file. ERRORS NFSERR_NOTFILE File is not a file type that can be read. NFSERR_BADOFFSET The location given does not make sense. Procedure 8 WRITE Version 3 Write to File SYNOPSIS 8. NFSPROC_WRITE( file, location, data ) returns ( reply ) fhandle file; position location; nfsdata data; union writeres switch (stat status) { case NFS_OK: struct writeokres { unsigned count; fattr attributes; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Write data to location in file. File must be either a regular (ftype NFREG) or special (ftype NFSPEC) file. When writing to a regular file location.offset is the byte offset into file at which data should be written. A byte offset of zero mean write data starting at the beginning of the file. If location.append is TRUE data is written at the current end of file only if location.offset matches the current maximum offset into the file. If reply.status is NFS_OK reply.ok.attributes is the attributes of the file after the write operation has completed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. The server has the option of accepting only a portion of data. In this case reply.ok.count is the number of bytes of data that were written starting at offset in file. The size of data must be less than or equal to the value of the wsize field in the GETFSINFO reply structure (see GETFSINFO procedure for more details) for the filesystem which contains file. IMPLEMENTATION If the ftype of file is NFSPEC the WRITE operation might not be supported by the server. If it is supported the location argument encodes where to write in file. Append mode writes are only guaranteed in a single WRITE operation. If a client does multiple append mode WRITE requests, the data written may not be contiguous. ERRORS NFSERR_ISDIR File is a directory. Writing is not allowed on directories. NFSERR_FBIG The WRITE operation would cause file to become too large. NFSERR_ROFS The filesystem that contains file is read-only. NFSERR_NOSPC The filesystem that contains file is full. NFSERR_NOTFILE File is not a file type that can be written. NFSERR_BADOFFSET The location given does not make sense. Procedure 9 WRITECACHE Version 3 Write to Cache SYNOPSIS 9. NFSPROC_WRITECACHE(file, flush, beg inoffset, totalcount, offset, data) returns ( reply ) fhandle file; boolean flush; fileoffset beginoffset; unsigned totalcount; fileoffset offset; nfsdata data; union writecacheres switch (stat status) { case NFS_OK: unsigned count; union switch (boolean flushed) { case TRUE: fattr attributes; case FALSE: unsigned flushct; errinfo flusherr; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Writes data into the server's data cache for a regular (ftype NFREG) file. Beginoffset and totalcount describe the offset and size, in bytes, of the entire piece of data to be written. These values will be the same across a set of WRITECACHE operations. Each of the WRITECACHE operations in a set will have different values for offset and data. Offset is the byte offset into file where data should be written. The boolean flush, if TRUE, causes the server to flush a whole data set. That is, commit to disk the data from several WRITECACHE operations, whose offset values fall between beginoffset and beginoffset+totalcount. If the server's attempt to flush totalcount bytes of data starting at beginoffset bytes into the file is successful the server will return reply.flushed TRUE. If reply.status is NFS_OK and reply.flushed is TRUE reply.ok.attributes is the attributes of the file following the write of the cached data. If reply.flushed is FALSE reply.ok.flushct is the number of consecutive bytes that actually got written starting at beginoffset, which may be less than totalcount, and reply.ok.flusherr contains error information about the write operation that failed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. The server has the option of accepting only a portion of data. In this case reply.ok.count is the number of bytes of data that were cached starting at offset in file. The size of data must be less than or equal to the value of the wsize field in the GETFSINFO reply structure (see GETFSINFO procedure for more details) for the filesystem which contains file. In addition, totalcount must be less than or equal to the wcsize field in the GETFSINFO reply. IMPLEMENTATION The WRITECACHE operation is provided for performance only. Servers are not required to support it. Clients can use the WRITECACHE operation to group consecutive WRITE operations without incurring the overhead of flushing each chunk of data through to disk on the server. The client takes responsibility for recovering from server errors by holding on to data that has been written with WRITECAHE until a successful flush has occurred. This way, to recover from an error the client can either retry the set of WRITECACHE operations or use WRITE operations to insure that the data is safely on the servers disk. The server may pre-flush cached data to disk to free up cache space. If this happens the server can either return an error in response to the flush request and force the client to resend everything, or keep track of data that has already been flushed when the flush request comes along. This way, if the server can account for all data as either in the cache or already flushed the flush request can return success. ERRORS NFSERR_WFLUSH Cached data for file had to be discarded. NFSERR_ISDIR File is a directory. Writing is not allowed on directories. NFSERR_FBIG The WRITE operation would cause file to become too large. NFSERR_ROFS The filesystem that contains file is read-only. Procedure 10 ZERO Version 3 Zero Data in File SYNOPSIS 10. NFSPROC_ZERO( file, location, count ) returns ( reply ) fhandle file; position location; filesize size; union zerores switch (stat status) { case NFS_OK: struct zerookres { unsigned count; fattr attributes; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Zero up to count bytes of data starting at location in file. File must be either a regular (ftype NFREG) or record (ftype NFREC) file. When zeroing a regular file location.offset is the byte offset into file at which data should be zeroed. A byte offset of zero mean zero data starting at the beginning of the file. If location.append is TRUE and location.offset matches the offset of the current end of file, data is zeroed starting at the current end of file. If reply.status is NFS_OK reply.ok.attributes is the attributes of the file following the operation. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. The server has the option of zeroing less than count bytes. In this case reply.ok.count is the number of bytes that were zeroed starting at loaction.offset in file. IMPLEMENTATION The ZERO operation is provided as an optimization for those servers whose operating systems can support files with holes. The server should implement the ZERO operation by punching holes in files if possible. If the server cannot support holes in files it is up to the implementor whether to support the ZERO operation by writing zero bytes to the file or not to support the operation at all. A ZERO operation with location.append set to TRUE or location.offset+size greater that the size of file should cause the size of file to change. ERRORS NFSERR_ISDIR File is a directory. Writing is not allowed on directories. NFSERR_FBIG The WRITE operation would cause file to become too large. NFSERR_ROFS The filesystem that contains file is read-only. NFSERR_NOSPC The filesystem that contains file is full. NFSERR_NOTFILE File is not a file type that can be zeroed. NFSERR_BADOFFSET The location given does not make sense. Procedure 11 Create Version 3 Create a File or Directory SYNOPSIS 11. NFSPROC_CREATE( where, type, perm, rmtarg ) returns ( reply ) diropargs where; ftype type; permbits perm; rmtarget rmtarg; diropres reply; DESCRIPTION The CREATE operation is used to create files and directories. Where.dir is the directory in which the create will take place, where.name is the name of the object to be created, type is the type of the object and perm gives the initial permission bits of the object. If rmtarg.exclusive is FALSE this is a non-exclusive create request, that is, the target name already exists and it will be destroyed in the operation. In this case rmtarg.targetfh must match the fhandle of the target of the create operation or it will fail. If reply.status is NFS_OK reply.ok.targ is the fhandle of the new object, reply.ok.targattr is the attributes of the object and reply.ok.dirattr is the attributes of where.dir after the create operation has completed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION The rmtarg argument is provided to allow servers to detect duplicate requests. If the client is doing an exclusive operation and the target name already exists the server should return NFSERR_EXIST. If the client is doing a non-exclusive operation and rmtarg.targetfh does not match the fhandle for the target name the server should return NFSERR_DUPREQ. If the client is doing a non-exclusive create and the target name does not exist the server should do the operation as if it were exclusive. Clients should use the LOOKUP procedure to get the fhandle for the target name. If the LOOKUP fails because the name does not exist the client should set rmtarg.exclusive to TRUE. Clients can recover from NFSERR_DUPREQ by using the LOOKUP operation to get a new fhandle for the target name and resending the request. ERRORS NFSERR_NOTDIR Where.dir is not a directory. NFSERR_NAMETOOLONG Where.name contains too many characters. NFSERR_ROFS The filesystem that contains where.dir is read-only. NFSERR_NOSPC The filesystem that contains where.dir is full. NFSERR_EXIST Where.name already exists in where.dir. This error can occur only if rmtarg.exclusive is TRUE. NFSERR_DUPREQ Duplicate request. This error occurs only if rmtarg.exclusive is FALSE and rmtarg.targetfh does not match the fhandle for where.name. PROCEDURE 12 REMOVE Version 3 Remove a File or Directory SYNOPSIS 12. NFSPROC_REMOVE( target, targetfh ) returns ( reply ) diropargs target; fhandle targetfh; attrstat reply; DESCRIPTION Remove the object target.name from directory target.dir.Targetfh must match the file handle of the object on the server when the remove operation occurs or the operation will fail. If reply.status is NFS_OK reply.attributes is the attributes of the directory target.dir after the remove operation has completed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION The server should return no error if the target.name does not exist and targetfh does not exist. This should only occur if the target name has already been removed. Some servers will allow removal of non-empty directories. ERRORS NFSERR_NOENT Target.name does not exist in target.dir. NFSERR_NOTDIR Target.dir is not a directory. NFSERR_NAMETOOLONG Target.name contains too many characters. NFSERR_ROFS The filesystem that contains Target.dir is read-only. NFSERR_NOTEMPTY The server will only remove empty directories and target.name is a directory that is not empty. Procedure 13 RENAME Version 3 Rename File or Directory SYNOPSIS 13. NFSPROC_RENAME( from, to, rmtarg ) returns ( reply ) diropargs from; diropargs to; rmtarget rmtarg; union renameres switch (stat status) { case NFS_OK: struct renameresok { fattr fromattr; diropokres to; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Rename the object from.name in directory from.dir to to.name in directory to.dir. If rmtarg.exclusive is FALSE this is a non-exclusive rename request, that is, to.name already exists in to.dir and will be destroyed in the operation. In this case rmtarg.targetfh must match the fhandle of the target of the rename operation or it will fail. If reply.status is NFS_OK reply.ok.to.targ is the fhandle of the renamed object, reply.ok.to.targattr is the attributes of the object, reply.ok.to.dirattr is the attributes of to.dir after the rename operation has completed and reply.ok.fromattr is the attributes of from.dir after the rename operation has completed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION The rmtarg argument is provided to allow servers to detect duplicate requests. If the client is doing an exclusive operation and the target name already exists the server should return NFSERR_EXIST. If the client is doing a non-exclusive operation and rmtarg.targetfh does not match the fhandle for the target name the server should return NFSERR_DUPREQ. If the client is doing a non-exclusive create and the target name does not exist the server should do the operation as if it were exclusive. Clients should use the LOOKUP procedure to get the fhandle for the target name. If the LOOKUP fails because the name does not exist the client should set rmtarg.exclusive to TRUE. Clients can recover from NFSERR_DUPREQ by using the LOOKUP operation to get a new fhandle for the target name and resending the request. The rename operation should be atomic on the server. ERRORS NFSERR_NOTDIR From.dir or to.dir is not a directory. NFSERR_NAMETOOLONG From.name or to.name contains too many characters. NFSERR_ROFS The filesystem that contains From.dir or to.dir is read-only. NFSERR_NOSPC The filesystem that contains to.dir is full. NFSERR_EXIST To.name already exists in to.dir. This error can occur only if rmtarg.exclusive is TRUE. NFSERR_DUPREQ Duplicate request. This error occurs only if rmtarg.exclusive is FALSE and rmtarg.targetfh does not match the fhandle for to.name. Procedure 14 LINK Version 3 Create Link to an object SYNOPSIS 14. NFSPROC_LINK( from, to, rmtarg ) returns ( reply ) fhandle from; diropargs to; rmtarget rmtarg; diropres reply; DESCRIPTION Create a hard link from the object from to to.name in directory to.dir. If rmtarg.exclusive is FALSE this is a non-exclusive link request, that is, to.name already exists in to.dir and will be destroyed in the operation. In this case rmtarg.targetfh must match the fhandle of the target of the link operation or it will fail. If reply.status is NFS_OK reply.ok.targ is the fhandle of the new object, reply.ok.targattr is the attributes of the object and reply.ok.dirattr is the attributes of to.dir after the symlink operation has completed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION A hard link should have the property that changes to any of the 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 which is one greater than the value before the LINK. The rmtarg argument is provided to allow servers to detect duplicate requests. If the client is doing an exclusive operation and the target name already exists the server should return NFSERR_EXIST. If the client is doing a non-exclusive operation and rmtarg.targetfh does not match the fhandle for the target name the server should return NFSERR_DUPREQ. If the client is doing a non-exclusive create and the target name does not exist the server should do the operation as if it were exclusive. Clients should use the LOOKUP procedure to get the fhandle for the target name. If the LOOKUP fails because the name does not exist the client should set rmtarg.exclusive to TRUE. Clients can recover from NFSERR_DUPREQ by using the LOOKUP operation to get a new fhandle for the target name and resending the request. ERRORS NFSERR_NOTDIR From.dir or to.dir is not a directory. NFSERR_NAMETOOLONG From.name or to.name contains too many characters. NFSERR_ROFS The filesystem that contains From.dir or to.dir is read-only. NFSERR_NOSPC The filesystem that contains to.dir is full. NFSERR_EXIST To.name already exists in to.dir. This error can occur if rmtarg.exclusive is TRUE or if rmtarg.exclusive is FALSE and rmtarg.targetfh does not match the fhandle for to.name. Procedure 15 SYMLINK Version 3 Create Symbolic Link SYNOPSIS 15. NFSPROC_SYMLINK( where, data, perm, rmtarg ) returns ( reply ) diropargs where; path data; permbits perm; rmtarget rmtarg; diropres reply; DESCRIPTION Creates the symbolic link file where.name with ftype NFLNK in the directory where.dir. The new file contains the pathname data and has initial permission bits given by perm. If rmtarg.exclusive is FALSE this is a non-exclusive symlink request, that is, where.name already exists in where.dir and will be destroyed in the operation. In this case rmtarg.targetfh must match the fhandle of the target of the symlink operation or it will fail. If reply.status is NFS_OK reply.ok.targ is the fhandle of the new object, reply.ok.targattr is the attributes of the object and reply.ok.dirattr is the attributes of where.dir after the symlink operation has completed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION A symbolic link is a pointer to another file. The data is not interpreted by the server, just stored in the file created by the SYMLINK call. A READLINK operation returns the data to the client for interpretation. If different implementations want to share access to symbolic links they must agree on the interpretation of the data in the symbolic link. Symbolic links are a filesystem object that are not supported by many operating systems. The operations on symbolic links are therefore not combined with the operations on regular files, though they are very similar. This allows servers to return an NFSERR_OPNOTSUP if symbolic links are not supported, and it allows clients to recover easily. Servers that do not have support for symbolic links in their operating systems could implement them by using regular files to hold the symlink path. This special data file can be marked by setting some unique combination of file attributes that will never occur on a regular data file. When attributes for this file are returned to the client they should have the type filed set to NFLNK. Clients can use a similar trick to implement symbolic links if the server does not support them. In this case the client must check the attributes returned by the server and if the type is NFREG and some unique set of attributes is set change the type field to NFLNK. ERRORS NFSERR_NOTDIR Where.dir is not a directory. NFSERR_NAMETOOLONG Where.name contains too many characters. NFSERR_ROFS The filesystem that contains where.dir is read-only. NFSERR_NOSPC The filesystem that contains where.dir is full. NFSERR_EXIST Where.name already exists in where.dir. This error can occur if rmtarg.exclusive is TRUE or if rmtarg.exclusive is FALSE and rmtarg.targetfh does not match the fhandle for where.name. Procedure 16 READLINK Version 3 Read From Symbolic Link SYNOPSIS 16. NFSPROC_READLINK( file ) returns ( reply ) fhandle file; union readlinkres switch (stat status) { case NFS_OK: path data; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION If status has the value NFS_OK then reply.data is the data in the symbolic link given by file. The data is an ASCII string which is opaque to the server. If reply.status is NFS_ERROR then reply.errinfo contains error information. IMPLEMENTATION A symbolic link is a pointer to another file. The data is not interpreted by the server, just stored in the file created by the SYMLINK call. A READLINK operation returns the data to the client for interpretation. If different implementations want to share access to symbolic links they must agree on the interpretation of the data in the symbolic link. The READLINK operation is only allowed on objects of type NFLNK. For more information see SYMLINK. ERRORS NFSERR_NOTSYMLINK File is not a symbolic link (ftype NFLNK). Procedure 17 CREATEUNIQ Version 3 Create a Uniquely Named Object SYNOPSIS 17. NFSPROC_CREATEUNIQ( where, type, perm ) returns ( reply ) fhandle where; ftype type; permbits perm; union createuniqres switch (stat status) { case NFS_OK: struct { filename uniqname; diropokres to; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION The CREATEUNIQ operation is used to create uniquely named objects. Where is the directory in which the new object will be created, type is the type of the object and perm gives the initial permission bits of the object. If reply.status is NFS_OK reply.ok.uniqname is the unique name of the new object, reply.ok.to.targ is the fhandle of the new object, reply.ok.to.targattr is the attributes of the object and reply.ok.to.dirattr is the attributes of where after the create operation has completed. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION The CREATEUNIQ operation should be atomic on the server. It allows clients to create files and directories on the server without having to recover from naming errors (e.g. NFSERR_BADNAME) and name creation races with other clients. This is useful, for example, in creating temporary files where the name does not matter. ERRORS NFSERR_NOTDIR Where is not a directory. NFSERR_ROFS The filesystem that contains where is read-only. NFSERR_NOSPC The filesystem that contains where is full. Procedure 18 READDIR Version 3 Read From Directory SYNOPSIS 18. NFSPROC_READDIR( dir, cookie, count, allvers ) returns ( reply ) fhandle dir; opaque cookie<COOKIESIZE>; unsigne count; boolean all; struct entry { fileid fileno; filename name; nfscookie cookie; entry *nextentry; }; union readdirres switch (stat status) { case NFS_OK: struct dirlist { entry *entries; boolean eof; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION Returns a variable number of directory entries, with a total XDR encoded size of up to count bytes, from the directory dir. If all is TRUE entries for every name will be returned. Each entry contains a fileno which is a unique number to identify the file within a filesystem, the name of the file, and a cookie which is an opaque identifier of 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 fileno field should be the same number as the fileno field in the the attributes of the file. The eof flag has a value of TRUE if there are no more entries in the directory. If the returned value of reply.status is NFS_OK then it is followed by a variable number of entries. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION The server has the option of returning fewer than count bytes of XDR encoded entries. Count must be less than or equal to the value of the dirsize field in the GETFSINFO reply structure (see GETFSINFO procedure for more details) for the filesystem which contains dir. Directory entry cookies may become invalid if the directory is modified. The client should be careful to avoid holding directory entry cookies across operation that modify the directory contents, such as REMOVE and CREATE. If all is FALSE only the current version of version numbered files, the data fork of Macintosh files, and files with the permbit "Hidden" set to zero should be returned. Since UNIX clients impart a special meaning to the fileno value zero, UNIX clients should be careful to map zero filenos to some other value, and servers of UNIX clients should try to avoid sending zero filenos. ERRORS NFSERR_NOTDIR Dir is not a directory. NFSERR_BADCOOKIE Cookie is no longer valid. Procedure 19 LINKAGE Version 3 Map File Handle SYNOPSIS 19. NFSPROC_LINKAGE( fh, prognum, vers ) returns ( reply ) fhandle fh; unsigned prognum; unsigned vers; union linkageres switch (stat status) { case NFS_OK: fhandle newfh; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION LINKAGE provides a way of tying together different RPC services that use file handles. The prognum and vers arguments identify an RPC based service program number and version number. If reply.status is NFS_OK then reply.newfh is an fhandle that refers to the same object as fh and is in a form that the new service will understand. If reply.status is NFS_ERROR then the call failed and reply.errinfo contains error information. IMPLEMENTATION In order for a service to implement the LINKAGE operation it must know the contents of the file handles used by the target service. The intent is that all services that refer to files use file handles, and that they all support the linkage service. The reason that LINKAGE is necessary is that different services may encode different information in their file handles. In order for services that deal with files to cooperate there has to be a way to translate one file handle into another. An example of cooperating services is NFS and LOCK. Procedure 20 GETFSATTR Version 3 Get Filesystem Attributes SYNOPSIS 20. NFSPROC_GETFSATTR( file ) returns ( reply ) fhandle file; union fsattrres switch (stat status) { case NFS_OK: struct fsattrokres { hyper bytes; hyper bfree; hyper bavail; hyper files; hyper ffree; hyper favail; timeval stime; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION If reply.status is NFS_OK then reply.ok gives the attributes for the filesystem that contains file. The attribute fields contain the following values: bytes The total number of bytes in the filesystem. bfree The number of free bytes in the filesystem. bavail The number of bytes available to non-privileged users. files The total number of file slots on the filesystem. ffree The number of free file slots on the filesystem. favail The number of file slots available to non-privileged users. stime The server's current time of day. Procedure 21 GETFSINFO Version 3 Get Filesystem Information SYNOPSIS 21. NFSPROC_GETFSINFO( file ) returns ( reply ) fhandle file; union fsinfores switch (stat status) { case NFS_OK: struct fsinfookres { unsigned rsize; unsigned wsize; unsigned wcsize; unsigned nmsize; unsigned dirsize; unsigned timeo; unsigned flags; integer procinfo[NUMPROCS]; keystr setkeys<MAXEXATTR>; string badch<MAXBADCHARS>; keyval exattr<MAXEXATTR>; } ok; case NFS_ERROR: errinfo errinfo; } reply; DESCRIPTION If reply.status is NFS_OK then reply.ok gives information for the filesystem that contains file. The reply fields contain the following values: rsize The maximum number of bytes that the server will return on a READ or READDIR request. wsize The maximum number of bytes that the server will accept on a WRITE request. wcsize The maximum totalcount, in bytes, that the server will accept on a WRITECACHE request. nmsize The maximum number of bytes in a file or directory name in the filesystem. dirsize The recomended directory read size in bytes. timeo The initial timeout in .1 sec. expected before retransmission of a request. flags Boolean bits (defined below) that tell what services are supported on the filesystem. readonly 0001 Read only access allowed. version 0002 Version numbers supported. record 0004 Record files supported. unixspec 0008 UNIX style special files supported. unixpipe 0010 UNIX style named pipes supported. unixsock 0020 UNIX style named sockets supported. link 0040 Hard links supported. symlink 0080 Symbolic links supported. procinfo The estimated worst case time in milliseconds required to process each request. The array is indexed by procedure number. A time of -1 means the procedure is not supported. setkeys The extended attribute keys which can be set with a SETATTR operation. badch The characters that are not allowed in a file name. exattr Optional array of key/value string pairs whcih can be used for extended filesystem attributes. The predefined extended attributes are given below. Key Value Description FSTYPE The underlying filesystem type. BSD Berkeley UNIX fast filesystem. DOS MS-DOS filesystem. MAC Macintosh filesystem. SYV System V filesystem. IMPLEMENTATION The extended attributes are provided as a way to extend the standard attributes between cooperating clients and servers. The name space of extended attribute key strings is left open. It is expected that new attributes that arise that are of general use among a broad range of implementations will be given a general name, and will be included in future revisions of this specification. Attributes that are only used among a restricted set of implementations (e.g. used by a single vendor) should be given names that are not likely to conflict with other restricted names (e.g. <vendor name>.<attribute name>).