operations. Returning the file handle is an optimization so that
the client is not forced to immediately issue a LOOKUP request
to get the file handle.
sattr3
enum time_how {
DONT_CHANGE = 0,
SET_TO_SERVER_TIME = 1,
SET_TO_CLIENT_TIME = 2
};
union set_mode3 switch (bool set_it) {
case TRUE:
mode3 mode;
default:
void;
};
union set_uid3 switch (bool set_it) {
case TRUE:
uid3 uid;
default:
void;
};
union set_gid3 switch (bool set_it) {
case TRUE:
gid3 gid;
default:
void;
};
union set_size3 switch (bool set_it) {
case TRUE:
size3 size;
default:
void;
};
union set_atime switch (time_how set_it) {
case SET_TO_CLIENT_TIME:
nfstime3 atime;
default:
void;
};
union set_mtime switch (time_how set_it) {
case SET_TO_CLIENT_TIME:
nfstime3 mtime;
default:
void;
};
struct sattr3 {
set_mode3 mode;
set_uid3 uid;
set_gid3 gid;
set_size3 size;
set_atime atime;
set_mtime mtime;
};
The sattr3 structure contains the file attributes that can be
set from the client. The fields are the same as the similarly
named fields in the fattr3 structure. In the NFS version 3
protocol, the settable attributes are described by a structure
containing a set of discriminated unions. Each union indicates
whether the corresponding attribute is to be updated, and if so,
how.
There are two forms of discriminated unions used. In setting the
mode, uid, gid, or size, the discriminated union is switched on
a boolean, set_it; if it is TRUE, a value of the appropriate
type is then encoded.
In setting the atime or mtime, the union is switched on an
enumeration type, set_it. If set_it has the value DONT_CHANGE,
the corresponding attribute is unchanged. If it has the value,
SET_TO_SERVER_TIME, the corresponding attribute is set by the
server to its local time; no data is provided by the client.
Finally, if set_it has the value, SET_TO_CLIENT_TIME, the
attribute is set to the time passed by the client in an nfstime3
structure. (See FSINFO on page 86, which addresses the issue of
time granularity).
diropargs3
struct diropargs3 {
nfs_fh3 dir;
filename3 name;
};
The diropargs3 structure is used in directory operations. The
file handle, dir, identifies the directory in which to
manipulate or access the file, name. See additional comments in
File name component handling on page 101.
3. Server Procedures
The following sections define the RPC procedures that are
supplied by an NFS version 3 protocol server. The RPC
procedure number is given at the top of the page with the
name. The SYNOPSIS provides the name of the procedure, the
list of the names of the arguments, the list of the names of
the results, followed by the XDR argument declarations and
results declarations. The information in the SYNOPSIS is
specified in RPC Data Description Language as defined in
[RFC1014]. The DESCRIPTION section 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. These lists are not intended to be the
definitive statement of all of the errors which can be
returned by any specific procedure, but as a guide for the
more common errors which may be returned. Client
implementations should be prepared to deal with unexpected
errors coming from a server. The IMPLEMENTATION field gives
information about how the procedure is expected to work and
how it should be used by clients.
program NFS_PROGRAM {
version NFS_V3 {
void
NFSPROC3_NULL(void) = 0;
GETATTR3res
NFSPROC3_GETATTR(GETATTR3args) = 1;
SETATTR3res
NFSPROC3_SETATTR(SETATTR3args) = 2;
LOOKUP3res
NFSPROC3_LOOKUP(LOOKUP3args) = 3;
ACCESS3res
NFSPROC3_ACCESS(ACCESS3args) = 4;
READLINK3res
NFSPROC3_READLINK(READLINK3args) = 5;
READ3res
NFSPROC3_READ(READ3args) = 6;
WRITE3res
NFSPROC3_WRITE(WRITE3args) = 7;
CREATE3res
NFSPROC3_CREATE(CREATE3args) = 8;
MKDIR3res
NFSPROC3_MKDIR(MKDIR3args) = 9;
SYMLINK3res
NFSPROC3_SYMLINK(SYMLINK3args) = 10;
MKNOD3res
NFSPROC3_MKNOD(MKNOD3args) = 11;
REMOVE3res
NFSPROC3_REMOVE(REMOVE3args) = 12;
RMDIR3res
NFSPROC3_RMDIR(RMDIR3args) = 13;
RENAME3res
NFSPROC3_RENAME(RENAME3args) = 14;
LINK3res
NFSPROC3_LINK(LINK3args) = 15;
READDIR3res
NFSPROC3_READDIR(READDIR3args) = 16;
READDIRPLUS3res
NFSPROC3_READDIRPLUS(READDIRPLUS3args) = 17;
FSSTAT3res
NFSPROC3_FSSTAT(FSSTAT3args) = 18;
FSINFO3res
NFSPROC3_FSINFO(FSINFO3args) = 19;
PATHCONF3res
NFSPROC3_PATHCONF(PATHCONF3args) = 20;
COMMIT3res
NFSPROC3_COMMIT(COMMIT3args) = 21;
} = 3;
} = 100003;
Out of range (undefined) procedure numbers result in RPC
errors. Refer to [RFC1057] for more detail.
3.1 General comments on attributes and consistency data on failure
For those procedures that return either post_op_attr or wcc_data
structures on failure, the discriminated union may contain the
pre-operation attributes of the object or object parent
directory. This depends on the error encountered and may also
depend on the particular server implementation. Implementors are
strongly encouraged to return as much attribute data as possible
upon failure, but client implementors need to be aware that
their implementation must correctly handle the variant return
instance where no attributes or consistency data is returned.
3.2 General comments on filenames
The following comments apply to all NFS version 3 protocol
procedures in which the client provides one or more filenames in
the arguments: LOOKUP, CREATE, MKDIR, SYMLINK, MKNOD, REMOVE,
RMDIR, RENAME, and LINK.
1. The filename must not be null nor may it be the null
string. The server should return the error, NFS3ERR_ACCES, if
it receives such a filename. On some clients, the filename, ``''
or a null string, is assumed to be an alias for the current
directory. Clients which require this functionality should
implement it for themselves and not depend upon the server to
support such semantics.
2. A filename having the value of "." is assumed to be an
alias for the current directory. Clients which require this
functionality should implement it for themselves and not depend
upon the server to support such semantics. However, the server
should be able to handle such a filename correctly.
3. A filename having the value of ".." is assumed to be an
alias for the parent of the current directory, i.e. the
directory which contains the current directory. The server
should be prepared to handle this semantic, if it supports
directories, even if those directories do not contain UNIX-style
"." or ".." entries.
4. If the filename is longer than the maximum for the file
system (see PATHCONF on page 90, specifically name_max), the
result depends on the value of the PATHCONF flag, no_trunc. If
no_trunc is FALSE, the filename will be silently truncated to
name_max bytes. If no_trunc is TRUE and the filename exceeds the
server's file system maximum filename length, the operation will
fail with the error, NFS3ERR_NAMETOOLONG.
5. In general, there will be characters that a server will
not be able to handle as part of a filename. This set of
characters will vary from server to server and from
implementation to implementation. In most cases, it is the
server which will control the client's view of the file system.
If the server receives a filename containing characters that it
can not handle, the error, NFS3ERR_EACCES, should be returned.
Client implementations should be prepared to handle this side
affect of heterogeneity.
See also comments in File name component handling on page 101.
3.3.0 Procedure 0: NULL - Do nothing
SYNOPSIS
void NFSPROC3_NULL(void) = 0;
DESCRIPTION
Procedure NULL does not do any work. It is made available 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. By convention, the NULL procedure
should never require any authentication. A server may
choose to ignore this convention, in a more secure
implementation, where responding to the NULL procedure
call acknowledges the existence of a resource to an
unauthenticated client.
ERRORS
Since the NULL procedure takes no NFS version 3 protocol
arguments and returns no NFS version 3 protocol response,
it can not return an NFS version 3 protocol error.
However, it is possible that some server implementations
may return RPC errors based on security and authentication
requirements.
3.3.1 Procedure 1: GETATTR - Get file attributes
SYNOPSIS
GETATTR3res NFSPROC3_GETATTR(GETATTR3args) = 1;
struct GETATTR3args {
nfs_fh3 object;
};
struct GETATTR3resok {
fattr3 obj_attributes;
};
union GETATTR3res switch (nfsstat3 status) {
case NFS3_OK:
GETATTR3resok resok;
default:
void;
};
DESCRIPTION
Procedure GETATTR retrieves the attributes for a specified
file system object. The object is identified by the file
handle that the server returned as part of the response
from a LOOKUP, CREATE, MKDIR, SYMLINK, MKNOD, or
READDIRPLUS procedure (or from the MOUNT service,
described elsewhere). On entry, the arguments in
GETATTR3args are:
object
The file handle of an object whose attributes are to be
retrieved.
On successful return, GETATTR3res.status is NFS3_OK and
GETATTR3res.resok contains:
obj_attributes
The attributes for the object.
Otherwise, GETATTR3res.status contains the error on failure and
no other results are returned.
IMPLEMENTATION
The attributes of file system objects is a point of major
disagreement between different operating systems. Servers
should make a best attempt to support all of the
attributes in the fattr3 structure so that clients can
count on this as a common ground. Some mapping may be
required to map local attributes to those in the fattr3
structure.
Today, most client NFS version 3 protocol implementations
implement a time-bounded attribute caching scheme to
reduce over-the-wire attribute checks.
ERRORS
NFS3ERR_IO
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_SERVERFAULT
SEE ALSO
ACCESS.
3.3.2 Procedure 2: SETATTR - Set file attributes
SYNOPSIS
SETATTR3res NFSPROC3_SETATTR(SETATTR3args) = 2;
union sattrguard3 switch (bool check) {
case TRUE:
nfstime3 obj_ctime;
case FALSE:
void;
};
struct SETATTR3args {
nfs_fh3 object;
sattr3 new_attributes;
sattrguard3 guard;
};
struct SETATTR3resok {
wcc_data obj_wcc;
};
struct SETATTR3resfail {
wcc_data obj_wcc;
};
union SETATTR3res switch (nfsstat3 status) {
case NFS3_OK:
SETATTR3resok resok;
default:
SETATTR3resfail resfail;
};
DESCRIPTION
Procedure SETATTR changes one or more of the attributes of
a file system object on the server. The new attributes are
specified by a sattr3 structure. On entry, the arguments
in SETATTR3args are:
object
The file handle for the object.
new_attributes
A sattr3 structure containing booleans and
enumerations describing the attributes to be set and the new
values for those attributes.
guard
A sattrguard3 union:
check
TRUE if the server is to verify that guard.obj_ctime
matches the ctime for the object; FALSE otherwise.
A client may request that the server check that the object
is in an expected state before performing the SETATTR
operation. To do this, it sets the argument guard.check to
TRUE and the client passes a time value in guard.obj_ctime.
If guard.check is TRUE, the server must compare the value of
guard.obj_ctime to the current ctime of the object. If the
values are different, the server must preserve the object
attributes and must return a status of NFS3ERR_NOT_SYNC.
If guard.check is FALSE, the server will not perform this
check.
On successful return, SETATTR3res.status is NFS3_OK and
SETATTR3res.resok contains:
obj_wcc
A wcc_data structure containing the old and new
attributes for the object.
Otherwise, SETATTR3res.status contains the error on
failure and SETATTR3res.resfail contains the following:
obj_wcc
A wcc_data structure containing the old and new
attributes for the object.
IMPLEMENTATION
The guard.check mechanism allows the client to avoid
changing the attributes of an object on the basis of stale
attributes. It does not guarantee exactly-once semantics.
In particular, if a reply is lost and the server does not
detect the retransmission of the request, the procedure
can fail with the error, NFS3ERR_NOT_SYNC, even though the
attribute setting was previously performed successfully.
The client can attempt to 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 the
attributes have already been set as desired (though it may
not have been the issuing client that set the
attributes).
The new_attributes.size field is used to request changes
to the size of a file. A value of 0 causes the file to be
truncated, a value less than the current size of the file
causes data from new size to the end of the file to be
discarded, and a size greater than the current size of the
file causes logically zeroed data bytes to be added to the
end of the file. Servers are free to implement this using
holes or actual zero data bytes. Clients should not make
any assumptions regarding a server's implementation of
this feature, beyond that the bytes returned will be
zeroed. Servers must support extending the file size via
SETATTR.
SETATTR is not guaranteed atomic. A failed SETATTR may
partially change a file's attributes.
Changing the size of a file with SETATTR indirectly
changes the mtime. A client must account for this as size
changes can result in data deletion.
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.
In a heterogeneous environment, it is quite possible that
the server will not be able to support the full range of
SETATTR requests. The error, NFS3ERR_INVAL, may be
returned if the server can not store a uid or gid in its
own representation of uids or gids, respectively. If the
server can only support 32 bit offsets and sizes, a
SETATTR request to set the size of a file to larger than
can be represented in 32 bits will be rejected with this
same error.
ERRORS
NFS3ERR_PERM
NFS3ERR_IO
NFS3ERR_ACCES
NFS3ERR_INVAL
NFS3ERR_NOSPC
NFS3ERR_ROFS
NFS3ERR_DQUOT
NFS3ERR_NOT_SYNC
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_SERVERFAULT
SEE ALSO
CREATE, MKDIR, SYMLINK, and MKNOD.
3.3.3 Procedure 3: LOOKUP - Lookup filename
SYNOPSIS
LOOKUP3res NFSPROC3_LOOKUP(LOOKUP3args) = 3;
struct LOOKUP3args {
diropargs3 what;
};
struct LOOKUP3resok {
nfs_fh3 object;
post_op_attr obj_attributes;
post_op_attr dir_attributes;
};
struct LOOKUP3resfail {
post_op_attr dir_attributes;
};
union LOOKUP3res switch (nfsstat3 status) {
case NFS3_OK:
LOOKUP3resok resok;
default:
LOOKUP3resfail resfail;
};
DESCRIPTION
Procedure LOOKUP searches a directory for a specific name
and returns the file handle for the corresponding file
system object. On entry, the arguments in LOOKUP3args
are:
what
Object to look up:
dir
The file handle for the directory to search.
name
The filename to be searched for. Refer to General
comments on filenames on page 30.
On successful return, LOOKUP3res.status is NFS3_OK and
LOOKUP3res.resok contains:
object
The file handle of the object corresponding to
what.name.
obj_attributes
The attributes of the object corresponding to
what.name.
dir_attributes
The post-operation attributes of the directory,
what.dir.
Otherwise, LOOKUP3res.status contains the error on failure and
LOOKUP3res.resfail contains the following:
dir_attributes
The post-operation attributes for the directory,
what.dir.
IMPLEMENTATION
At first glance, in the case where what.name refers to a
mount point on the server, two different replies seem
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. This
ambiguity is simply resolved. A server will not allow a
LOOKUP operation to cross a mountpoint to the root of a
different filesystem, even if the filesystem is exported.
This does not prevent a client from accessing a hierarchy
of filesystems exported by a server, but the client must
mount each of the filesystems individually so that the
mountpoint crossing takes place on the client. A given
server implementation may refine these rules given
capabilities or limitations particular to that
implementation. Refer to [X/OpenNFS] for a discussion on
exporting file systems.
Two filenames are distinguished, as in the NFS version 2
protocol. The name, ".", is an alias for the current
directory and the name, "..", is an alias for the parent
directory; that is, the directory that includes the
specified directory as a member. There is no facility for
dealing with a multiparented directory and the NFS
protocol assumes a hierarchical organization, organized as
a single-rooted tree.
Note that this procedure does not follow symbolic links.
The client is responsible for all parsing of filenames
including filenames that are modified by symbolic links
encountered during the lookup process.
ERRORS
NFS3ERR_IO
NFS3ERR_NOENT
NFS3ERR_ACCES
NFS3ERR_NOTDIR
NFS3ERR_NAMETOOLONG
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_SERVERFAULT
SEE ALSO
CREATE, MKDIR, SYMLINK, MKNOD, READDIRPLUS, and PATHCONF.
3.3.4 Procedure 4: ACCESS - Check Access Permission
SYNOPSIS
ACCESS3res NFSPROC3_ACCESS(ACCESS3args) = 4;
const ACCESS3_READ = 0x0001;
const ACCESS3_LOOKUP = 0x0002;
const ACCESS3_MODIFY = 0x0004;
const ACCESS3_EXTEND = 0x0008;
const ACCESS3_DELETE = 0x0010;
const ACCESS3_EXECUTE = 0x0020;
struct ACCESS3args {
nfs_fh3 object;
uint32 access;
};
struct ACCESS3resok {
post_op_attr obj_attributes;
uint32 access;
};
struct ACCESS3resfail {
post_op_attr obj_attributes;
};
union ACCESS3res switch (nfsstat3 status) {
case NFS3_OK:
ACCESS3resok resok;
default:
ACCESS3resfail resfail;
};
DESCRIPTION
Procedure ACCESS determines the access rights that a user,
as identified by the credentials in the request, has with
respect to a file system object. The client encodes the
set of permissions that are to be checked in a bit mask.
The server checks the permissions encoded in the bit mask.
A status of NFS3_OK is returned along with a bit mask
encoded with the permissions that the client is allowed.
The results of this procedure are necessarily advisory in
nature. That is, a return status of NFS3_OK and the
appropriate bit set in the bit mask does not imply that
such access will be allowed to the file system object in
the future, as access rights can be revoked by the server
at any time.
On entry, the arguments in ACCESS3args are:
object
The file handle for the file system object to which
access is to be checked.
access
A bit mask of access permissions to check.
The following access permissions may be requested:
ACCESS3_READ
Read data from file or read a directory.
ACCESS3_LOOKUP
Look up a name in a directory (no meaning for
non-directory objects).
ACCESS3_MODIFY
Rewrite existing file data or modify existing
directory entries.
ACCESS3_EXTEND
Write new data or add directory entries.
ACCESS3_DELETE
Delete an existing directory entry.
ACCESS3_EXECUTE
Execute file (no meaning for a directory).
On successful return, ACCESS3res.status is NFS3_OK. The
server should return a status of NFS3_OK if no errors
occurred that prevented the server from making the
required access checks. The results in ACCESS3res.resok
are:
obj_attributes
The post-operation attributes of object.
access
A bit mask of access permissions indicating access
rights for the authentication credentials provided with
the request.
Otherwise, ACCESS3res.status contains the error on failure
and ACCESS3res.resfail contains the following:
obj_attributes
The attributes of object - if access to attributes is
permitted.
IMPLEMENTATION
In general, it is not sufficient for the client to attempt
to deduce access permissions by inspecting the uid, gid,
and mode fields in the file attributes, since the server
may perform uid or gid mapping or enforce additional
access control restrictions. It is also possible that the
NFS version 3 protocol server may not be in the same ID
space as the NFS version 3 protocol client. In these cases
(and perhaps others), the NFS version 3 protocol client
can not reliably perform an access check with only current
file attributes.
In the NFS version 2 protocol, the only reliable way to
determine whether an operation was allowed was to try it
and see if it succeeded or failed. Using the ACCESS
procedure in the NFS version 3 protocol, the client can
ask the server to indicate whether or not one or more
classes of operations are permitted. The ACCESS operation
is provided to allow clients to check 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. This procedure is also
invoked by NFS client access procedure (called possibly
through access(2)). The intent is to make the behavior of
opening a remote file more consistent with the behavior of
opening a local file.
The information returned by the server in response to an
ACCESS call is not permanent. It was correct at the exact
time that the server performed the checks, but not
necessarily afterwards. The server can revoke access
permission at any time.
The NFS version 3 protocol client should use the effective
credentials of the user to build the authentication
information in the ACCESS request used to determine access
rights. It is the effective user and group credentials
that are used in subsequent read and write operations. See
the comments in Permission issues on page 98 for more
information on this topic.
Many implementations do not directly support the
ACCESS3_DELETE permission. Operating systems like UNIX
will ignore the ACCESS3_DELETE bit if set on an access
request on a non-directory object. In these systems,
delete permission on a file is determined by the access
permissions on the directory in which the file resides,
instead of being determined by the permissions of the file
itself. Thus, the bit mask returned for such a request
will have the ACCESS3_DELETE bit set to 0, indicating that
the client does not have this permission.
ERRORS
NFS3ERR_IO
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_SERVERFAULT
SEE ALSO
GETATTR.
3.3.5 Procedure 5: READLINK - Read from symbolic link
SYNOPSIS
READLINK3res NFSPROC3_READLINK(READLINK3args) = 5;
struct READLINK3args {
nfs_fh3 symlink;
};
struct READLINK3resok {
post_op_attr symlink_attributes;
nfspath3 data;
};
struct READLINK3resfail {
post_op_attr symlink_attributes;
};
union READLINK3res switch (nfsstat3 status) {
case NFS3_OK:
READLINK3resok resok;
default:
READLINK3resfail resfail;
};
DESCRIPTION
Procedure READLINK reads the data associated with a
symbolic link. The data is an ASCII string that is opaque
to the server. That is, whether created by the NFS
version 3 protocol software from a client or created
locally on the server, the data in a symbolic link is not
interpreted when created, but is simply stored. On entry,
the arguments in READLINK3args are:
symlink
The file handle for a symbolic link (file system object
of type NF3LNK).
On successful return, READLINK3res.status is NFS3_OK and
READLINK3res.resok contains:
data
The data associated with the symbolic link.
symlink_attributes
The post-operation attributes for the symbolic link.
Otherwise, READLINK3res.status contains the error on
failure and READLINK3res.resfail contains the following:
symlink_attributes
The post-operation attributes for the symbolic link.
IMPLEMENTATION
A symbolic link is nominally a pointer to another file.
The data is not necessarily interpreted by the server,
just stored in the file. It is possible for a client
implementation to store a path name that is not meaningful
to the server operating system in a symbolic link. A
READLINK operation returns the data to the client for
interpretation. If different implementations want to share
access to symbolic links, then they must agree on the
interpretation of the data in the symbolic link.
The READLINK operation is only allowed on objects of type,
NF3LNK. The server should return the error,
NFS3ERR_INVAL, if the object is not of type, NF3LNK.
(Note: The X/Open XNFS Specification for the NFS version 2
protocol defined the error status in this case as
NFSERR_NXIO. This is inconsistent with existing server
practice.)
ERRORS
NFS3ERR_IO
NFS3ERR_INVAL
NFS3ERR_ACCES
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_NOTSUPP
NFS3ERR_SERVERFAULT
SEE ALSO
READLINK, SYMLINK.
3.3.6 Procedure 6: READ - Read From file
SYNOPSIS
READ3res NFSPROC3_READ(READ3args) = 6;
struct READ3args {
nfs_fh3 file;
offset3 offset;
count3 count;
};
struct READ3resok {
post_op_attr file_attributes;
count3 count;
bool eof;
opaque data<>;
};
struct READ3resfail {
post_op_attr file_attributes;
};
union READ3res switch (nfsstat3 status) {
case NFS3_OK:
READ3resok resok;
default:
READ3resfail resfail;
};
DESCRIPTION
Procedure READ reads data from a file. On entry, the
arguments in READ3args are:
file
The file handle of the file from which data is to be
read. This must identify a file system object of type,
NF3REG.
offset
The position within the file at which the read is to
begin. An offset of 0 means to read data starting at
the beginning of the file. If offset is greater than or
equal to the size of the file, the status, NFS3_OK, is
returned with count set to 0 and eof set to TRUE,
subject to access permissions checking.
count
The number of bytes of data that are to be read. If
count is 0, the READ will succeed and return 0 bytes of
data, subject to access permissions checking. count
must be less than or equal to the value of the rtmax
field in the FSINFO reply structure for the file system
that contains file. If greater, the server may return
only rtmax bytes, resulting in a short read.
On successful return, READ3res.status is NFS3_OK and
READ3res.resok contains:
file_attributes
The attributes of the file on completion of the read.
count
The number of bytes of data returned by the read.
eof
If the read ended at the end-of-file (formally, in a
correctly formed READ request, if READ3args.offset plus
READ3resok.count is equal to the size of the file), eof
is returned as TRUE; otherwise it is FALSE. A
successful READ of an empty file will always return eof
as TRUE.
data
The counted data read from the file.
Otherwise, READ3res.status contains the error on failure
and READ3res.resfail contains the following:
file_attributes
The post-operation attributes of the file.
IMPLEMENTATION
The nfsdata type used for the READ and WRITE operations in
the NFS version 2 protocol defining the data portion of a
request or reply has been changed to a variable-length
opaque byte array. The maximum size allowed by the
protocol is now limited by what XDR and underlying
transports will allow. There are no artificial limits
imposed by the NFS version 3 protocol. Consult the FSINFO
procedure description for details.
It is possible for the server to return fewer than count
bytes of data. If the server returns less than the count
requested and eof set to FALSE, the client should issue
another READ to get the remaining data. A server may
return less data than requested under several
circumstances. The file may have been truncated by another
client or perhaps on the server itself, changing the file
size from what the requesting client believes to be the
case. This would reduce the actual amount of data
available to the client. It is possible that the server
may back off the transfer size and reduce the read request
return. Server resource exhaustion may also occur
necessitating a smaller read return.
Some NFS version 2 protocol client implementations chose
to interpret a short read response as indicating EOF. The
addition of the eof flag in the NFS version 3 protocol
provides a correct way of handling EOF.
Some NFS version 2 protocol server implementations
incorrectly returned NFSERR_ISDIR if the file system
object type was not a regular file. The correct return
value for the NFS version 3 protocol is NFS3ERR_INVAL.
ERRORS
NFS3ERR_IO
NFS3ERR_NXIO
NFS3ERR_ACCES
NFS3ERR_INVAL
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_SERVERFAULT
SEE ALSO
READLINK.
3.3.7 Procedure 7: WRITE - Write to file
SYNOPSIS
WRITE3res NFSPROC3_WRITE(WRITE3args) = 7;
enum stable_how {
UNSTABLE = 0,
DATA_SYNC = 1,
FILE_SYNC = 2
};
struct WRITE3args {
nfs_fh3 file;
offset3 offset;
count3 count;
stable_how stable;
opaque data<>;
};
struct WRITE3resok {
wcc_data file_wcc;
count3 count;
stable_how committed;
writeverf3 verf;
};
struct WRITE3resfail {
wcc_data file_wcc;
};
union WRITE3res switch (nfsstat3 status) {
case NFS3_OK:
WRITE3resok resok;
default:
WRITE3resfail resfail;
};
DESCRIPTION
Procedure WRITE writes data to a file. On entry, the
arguments in WRITE3args are:
file
The file handle for the file to which data is to be
written. This must identify a file system object of
type, NF3REG.
offset
The position within the file at which the write is to
begin. An offset of 0 means to write data starting at
the beginning of the file.
count
The number of bytes of data to be written. If count is
0, the WRITE will succeed and return a count of 0,
barring errors due to permissions checking. The size of
data must be less than or equal to the value of the
wtmax field in the FSINFO reply structure for the file
system that contains file. If greater, the server may
write only wtmax bytes, resulting in a short write.
stable
If stable is FILE_SYNC, the server must commit the data
written plus all file system metadata to stable storage
before returning results. This corresponds to the NFS
version 2 protocol semantics. Any other behavior
constitutes a protocol violation. If stable is
DATA_SYNC, then the server must commit all of the data
to stable storage and enough of the metadata to
retrieve the data before returning. The server
implementor is free to implement DATA_SYNC in the same
fashion as FILE_SYNC, but with a possible performance
drop. If stable is UNSTABLE, the server is free to
commit any part of the data and the metadata to stable
storage, including all or none, before returning a
reply to the client. There is no guarantee whether or
when any uncommitted data will subsequently be
committed to stable storage. The only guarantees made
by the server are that it will not destroy any data
without changing the value of verf and that it will not
commit the data and metadata at a level less than that
requested by the client. See the discussion on COMMIT
on page 92 for more information on if and when
data is committed to stable storage.
data
The data to be written to the file.
On successful return, WRITE3res.status is NFS3_OK and
WRITE3res.resok contains:
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.
count
The number of bytes of data written to the file. The
server may write fewer bytes than requested. If so, the
actual number of bytes written starting at location,
offset, is returned.
committed
The server should return an indication of the level of
commitment of the data and metadata via committed. If
the server committed all data and metadata to stable
storage, committed should be set to FILE_SYNC. If the
level of commitment was at least as strong as
DATA_SYNC, then committed should be set to DATA_SYNC.
Otherwise, committed must be returned as UNSTABLE. If
stable was FILE_SYNC, then committed must also be
FILE_SYNC: anything else constitutes a protocol
violation. If stable was DATA_SYNC, then committed may
be FILE_SYNC or DATA_SYNC: anything else constitutes a
protocol violation. If stable was UNSTABLE, then
committed may be either FILE_SYNC, DATA_SYNC, or
UNSTABLE.
verf
This is a cookie that the client can use to determine
whether the server has changed state between a call to
WRITE and a subsequent call to either WRITE or COMMIT.
This cookie must be consistent during a single instance
of the NFS version 3 protocol service and must be
unique between instances of the NFS version 3 protocol
server, where uncommitted data may be lost.
Otherwise, WRITE3res.status contains the error on failure
and WRITE3res.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
write failed, full wcc_data is returned to allow the
client to determine whether the failed write resulted
in any change to the file.
If a client writes data to the server with the stable
argument set to UNSTABLE and the reply yields a committed
response of DATA_SYNC or UNSTABLE, the client will follow
up some time in the future with a COMMIT operation to
synchronize outstanding asynchronous data and metadata
with the server's stable storage, barring client error. It
is possible that due to client crash or other error that a
subsequent COMMIT will not be received by the server.
IMPLEMENTATION
The nfsdata type used for the READ and WRITE operations in
the NFS version 2 protocol defining the data portion of a
request or reply has been changed to a variable-length
opaque byte array. The maximum size allowed by the
protocol is now limited by what XDR and underlying
transports will allow. There are no artificial limits
imposed by the NFS version 3 protocol. Consult the FSINFO
procedure description for details.
It is possible for the server to write fewer than count
bytes of data. In this case, the server should not return
an error unless no data was written at all. If the server
writes less than count bytes, the client should issue
another WRITE to write the remaining data.
It is assumed that the act of writing data to a file will
cause the mtime of the file to be updated. However, the
mtime of the file should not be changed unless the
contents of the file are changed. Thus, a WRITE request
with count set to 0 should not cause the mtime of the file
to be updated.
The NFS version 3 protocol introduces safe asynchronous
writes. The combination of WRITE with stable set to
UNSTABLE followed by a COMMIT addresses the performance
bottleneck found in the NFS version 2 protocol, the need
to synchronously commit all writes to stable storage.
The definition of stable storage has been historically a
point of contention. The following expected properties of
stable storage may help in resolving design issues in the
implementation. Stable storage is persistent storage that
survives:
1. Repeated power failures.
2. Hardware failures (of any board, power supply, and so on.).
3. Repeated software crashes, including reboot cycle.
This definition does not address failure of the stable
storage module itself.
A cookie, verf, is defined to allow a client to detect
different instances of an NFS version 3 protocol server
over which cached, uncommitted data may be lost. In the
most likely case, the verf allows the client to detect
server reboots. This information is required so that the
client can safely determine whether the server could have
lost cached data. If the server fails unexpectedly and the
client has uncommitted data from previous WRITE requests
(done with the stable argument set to UNSTABLE and in
which the result committed was returned as UNSTABLE as
well) it may not have flushed cached data to stable
storage. The burden of recovery is on the client and the
client will need to retransmit the data to the server.
A suggested verf cookie would be to use the time that the
server was booted or the time the server was last started
(if restarting the server without a reboot results in lost
buffers).
The committed field in the results allows the client to do
more effective caching. If the server is committing all
WRITE requests to stable storage, then it should return
with committed set to FILE_SYNC, regardless of the value
of the stable field in the arguments. A server that uses
an NVRAM accelerator may choose to implement this policy.
The client can use this to increase the effectiveness of
the cache by discarding cached data that has already been
committed on the server.
Some implementations may return NFS3ERR_NOSPC instead of
NFS3ERR_DQUOT when a user's quota is exceeded.
Some NFS version 2 protocol server implementations
incorrectly returned NFSERR_ISDIR if the file system
object type was not a regular file. The correct return
value for the NFS version 3 protocol is NFS3ERR_INVAL.
ERRORS
NFS3ERR_IO
NFS3ERR_ACCES
NFS3ERR_FBIG
NFS3ERR_DQUOT
NFS3ERR_NOSPC
NFS3ERR_ROFS
NFS3ERR_INVAL
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_SERVERFAULT
SEE ALSO
COMMIT.
3.3.8 Procedure 8: CREATE - Create a file
SYNOPSIS
CREATE3res NFSPROC3_CREATE(CREATE3args) = 8;
enum createmode3 {
UNCHECKED = 0,
GUARDED = 1,
EXCLUSIVE = 2
};
union createhow3 switch (createmode3 mode) {
case UNCHECKED:
case GUARDED:
sattr3 obj_attributes;
case EXCLUSIVE:
createverf3 verf;
};
struct CREATE3args {
diropargs3 where;
createhow3 how;
};
struct CREATE3resok {
post_op_fh3 obj;
post_op_attr obj_attributes;
wcc_data dir_wcc;
};
struct CREATE3resfail {
wcc_data dir_wcc;
};
union CREATE3res switch (nfsstat3 status) {
case NFS3_OK:
CREATE3resok resok;
default:
CREATE3resfail resfail;
};
DESCRIPTION
Procedure CREATE creates a regular file. On entry, the
arguments in CREATE3args are:
where
The location of the file to be created:
dir
The file handle for the directory in which the file
is to be created.
name
The name that is to be associated with the created
file. Refer to General comments on filenames on
page 30.
When creating a regular file, there are three ways to
create the file as defined by:
how
A discriminated union describing how the server is to
handle the file creation along with the appropriate
attributes:
mode
One of UNCHECKED, GUARDED, and EXCLUSIVE. UNCHECKED
means that the file should be created without checking
for the existence of a duplicate file in the same
directory. In this case, how.obj_attributes is a sattr3
describing the initial attributes for the file. GUARDED
specifies that the server should check for the presence
of a duplicate file before performing the create and
should fail the request with NFS3ERR_EXIST if a
duplicate file exists. If the file does not exist, the
request is performed as described for UNCHECKED.
EXCLUSIVE specifies that the server is to follow
exclusive creation semantics, using the verifier to
ensure exclusive creation of the target. No attributes
may be provided in this case, since the server may use
the target file metadata to store the createverf3
verifier.
On successful return, CREATE3res.status is NFS3_OK and the
results in CREATE3res.resok are:
obj
The file handle of the newly created regular file.
obj_attributes
The attributes of the regular file just created.
dir_wcc
Weak cache consistency data for the directory,
where.dir. For a client that requires on the
post-CREATE directory attributes, these can be found in
dir_wcc.after.
Otherwise, CREATE3res.status contains the error on failure
and CREATE3res.resfail contains the following:
dir_wcc
Weak cache consistency data for the directory,
where.dir. For a client that requires only the
post-CREATE directory attributes, these can be found in
dir_wcc.after. Even though the CREATE failed, full
wcc_data is returned to allow the client to determine
whether the failing CREATE resulted in any change to
the directory.
IMPLEMENTATION
Unlike the NFS version 2 protocol, in which certain fields
in the initial attributes structure were overloaded to
indicate creation of devices and FIFOs in addition to
regular files, this procedure only supports the creation
of regular files. The MKNOD procedure was introduced in
the NFS version 3 protocol to handle creation of devices
and FIFOs. Implementations should have no reason in the
NFS version 3 protocol to overload CREATE semantics.
One aspect of the NFS version 3 protocol CREATE procedure
warrants particularly careful consideration: the mechanism
introduced to support the reliable exclusive creation of
regular files. The mechanism comes into play when how.mode
is EXCLUSIVE. In this case, how.verf contains a verifier
that can reasonably be expected to be unique. A
combination of a client identifier, perhaps the client
network address, and a unique number generated by the
client, perhaps the RPC transaction identifier, may be
appropriate.
If the file does not exist, the server creates the file
and stores the verifier in stable storage. For file
systems that do not provide a mechanism for the storage of
arbitrary file attributes, the server may use one or more
elements of the file metadata to store the verifier. The
verifier must be stored in stable storage to prevent
erroneous failure on retransmission of the request. It is
assumed that an exclusive create is being performed
because exclusive semantics are critical to the
application. Because of the expected usage, exclusive
CREATE does not rely solely on the normally volatile
duplicate request cache for storage of the verifier. The
duplicate request cache in volatile storage does not
survive a crash and may actually flush on a long network
partition, opening failure windows. In the UNIX local
file system environment, the expected storage location for
the verifier on creation is the metadata (time stamps) of
the file. For this reason, an exclusive file create may
not include initial attributes because the server would
have nowhere to store the verifier.
If the server can not support these exclusive create
semantics, possibly because of the requirement to commit
the verifier to stable storage, it should fail the CREATE
request with the error, NFS3ERR_NOTSUPP.
During an exclusive CREATE request, if the file already
exists, the server reconstructs the file's verifier and
compares it with the verifier in the request. If they
match, the server treats the request as a success. The
request is presumed to be a duplicate of an earlier,
successful request for which the reply was lost and that
the server duplicate request cache mechanism did not
detect. If the verifiers do not match, the request is
rejected with the status, NFS3ERR_EXIST.
Once the client has performed a successful exclusive
create, it must issue a SETATTR to set the correct file
attributes. Until it does so, it should not rely upon any
of the file attributes, since the server implementation
may need to overload file metadata to store the verifier.
Use of the GUARDED attribute does not provide exactly-once
semantics. In particular, if a reply is lost and the
server does not detect the retransmission of the request,
the procedure can fail with NFS3ERR_EXIST, even though the
create was performed successfully.
Refer to General comments on filenames on page 30.
ERRORS
NFS3ERR_IO
NFS3ERR_ACCES
NFS3ERR_EXIST
NFS3ERR_NOTDIR
NFS3ERR_NOSPC
NFS3ERR_ROFS
NFS3ERR_NAMETOOLONG
NFS3ERR_DQUOT
NFS3ERR_STALE
NFS3ERR_BADHANDLE
NFS3ERR_NOTSUPP
NFS3ERR_SERVERFAULT
SEE ALSO
MKDIR, SYMLINK, MKNOD, and PATHCONF.
3.3.9 Procedure 9: MKDIR - Create a directory
SYNOPSIS
MKDIR3res NFSPROC3_MKDIR(MKDIR3args) = 9;
struct MKDIR3args {
diropargs3 where;
sattr3 attributes;
};
struct MKDIR3resok {
post_op_fh3 obj;
post_op_attr obj_attributes;
wcc_data dir_wcc;
};
struct MKDIR3resfail {
wcc_data dir_wcc;
};
union MKDIR3res switch (nfsstat3 status) {
case NFS3_OK:
MKDIR3resok resok;
default:
MKDIR3resfail resfail;
};
DESCRIPTION
Procedure MKDIR creates a new subdirectory. On entry, the
arguments in MKDIR3args are:
where
The location of the subdirectory to be created:
dir
The file handle for the directory in which the
subdirectory is to be created.
name
The name that is to be associated with the created
subdirectory. Refer to General comments on filenames
on page 30.
attributes
The initial attributes for the subdirectory.
On successful return, MKDIR3res.status is NFS3_OK and the
results in MKDIR3res.resok are:
obj
The file handle for the newly created directory.
obj_attributes
The attributes for the newly created subdirectory.
dir_wcc
Weak cache consistency data for the directory,
where.dir. For a client that requires only the
post-MKDIR directory attributes, these can be found in
dir_wcc.after.
Otherwise, MKDIR3res.status contains the error on failure
and MKDIR3res.resfail contains the following:
dir_wcc
Weak cache consistency data for the directory,
where.dir. For a client that requires only the
post-MKDIR directory attributes, these can be found in
dir_wcc.after. Even though the MKDIR failed, full
wcc_data is returned to allow the client to determine
whether the failing MKDIR resulted in any change to the
directory.
IMPLEMENTATION
Many server implementations will not allow the filenames,
"." or "..", to be used as targets in a MKDIR operation.
In this case, the server should return NFS3ERR_EXIST.
Refer to General comments on filenames on page 30.
ERRORS
NFS3ERR_IO
NFS3ERR_ACCES
NFS3ERR_EXIST
NFS3ERR_NOTDIR
NFS3ERR_NOSPC
NFS3ERR_ROFS