nfs.rfc.ms

RTEMS (Real-Time Executive for Multiprocessor Systems) is a free open source real-time operating sys

The type
.I filename 
is used for  passing file names  or  pathname components.
.LP
.KS
.NH 3
\&path
.IX "NFS data types" path "" \fIpath\fP
.DS
typedef string path<MAXPATHLEN>;
.DE
.KE
The type
.I path 
is a pathname.  The server considers it as a string
with no internal structure,  but to the client  it is the name of a
node in a filesystem tree.
.LP
.KS
.NH 3
\&attrstat
.IX "NFS data types" attrstat "" \fIattrstat\fP
.DS
union attrstat switch (stat status) {
	case NFS_OK:
		fattr attributes;
	default:
		void;
};
.DE
.KE
The 
.I attrstat 
structure is a common procedure result.  It contains
a  "status" and,  if  the call   succeeded,   it also contains  the
attributes of the file on which the operation was done.
.LP
.KS
.NH 3
\&diropargs
.IX "NFS data types" diropargs "" \fIdiropargs\fP
.DS
struct diropargs {
	fhandle  dir;
	filename name;
};
.DE
.KE
The  
.I diropargs 
structure is used  in  directory  operations.  The
"fhandle" "dir" is the directory in  which to find the file "name".
A directory operation is one in which the directory is affected.
.LP
.KS
.NH 3
\&diropres
.IX "NFS data types" diropres "" \fIdiropres\fP
.DS
union diropres switch (stat status) {
	case NFS_OK:
		struct {
			fhandle file;
			fattr   attributes;
		} diropok;
	default:
		void;
};
.DE
.KE
The results of a directory operation  are returned  in a 
.I diropres 
structure.  If the call succeeded, a new file handle "file" and the
"attributes" associated with that file are  returned along with the
"status".
.NH 2
\&Server Procedures
.IX "NFS server procedures" "" "" "" PAGE MAJOR
.LP
The  protocol definition  is given as   a  set  of  procedures with
arguments  and results defined using the   RPC  language.   A brief
description of the function of each procedure should provide enough
information to allow implementation.
.LP
All of  the procedures  in   the NFS  protocol  are assumed  to  be
synchronous.   When a procedure  returns to the  client, the client
can assume that the operation has completed and any data associated
with the request is  now on stable storage.  For  example, a client
.I WRITE 
request   may  cause  the   server  to  update  data  blocks,
filesystem information blocks (such as indirect  blocks),  and file
attribute  information (size  and  modify  times).  When  the 
.I WRITE 
returns to the client, it can assume  that the write  is safe, even
in case of  a server  crash, and  it can discard the  data written.
This is a very important part  of the statelessness  of the server.
If the server waited to flush data from remote requests, the client
would have to  save those requests so that  it could resend them in
case of a server crash.
.ie t .DS
.el .DS L

.ft I
/*
* Remote file service routines
*/
.ft CW
program NFS_PROGRAM {
	version NFS_VERSION {
		void        NFSPROC_NULL(void)              = 0;
		attrstat    NFSPROC_GETATTR(fhandle)        = 1;
		attrstat    NFSPROC_SETATTR(sattrargs)      = 2;
		void        NFSPROC_ROOT(void)              = 3;
		diropres    NFSPROC_LOOKUP(diropargs)       = 4;
		readlinkres NFSPROC_READLINK(fhandle)       = 5;
		readres     NFSPROC_READ(readargs)          = 6;
		void        NFSPROC_WRITECACHE(void)        = 7;
		attrstat    NFSPROC_WRITE(writeargs)        = 8;
		diropres    NFSPROC_CREATE(createargs)      = 9;
		stat        NFSPROC_REMOVE(diropargs)       = 10;
		stat        NFSPROC_RENAME(renameargs)      = 11;
		stat        NFSPROC_LINK(linkargs)          = 12;
		stat        NFSPROC_SYMLINK(symlinkargs)    = 13;
		diropres    NFSPROC_MKDIR(createargs)       = 14;
		stat        NFSPROC_RMDIR(diropargs)        = 15;
		readdirres  NFSPROC_READDIR(readdirargs)    = 16;
		statfsres   NFSPROC_STATFS(fhandle)         = 17;
	} = 2;
} = 100003;
.DE
.KS
.NH 3
\&Do Nothing
.IX "NFS server procedures" NFSPROC_NULL() "" \fINFSPROC_NULL()\fP
.DS
void 
NFSPROC_NULL(void) = 0;
.DE
.KE
This procedure does no work.   It is made available  in  all RPC
services to allow server response testing and timing.
.KS
.NH 3
\&Get File Attributes
.IX "NFS server procedures" NFSPROC_GETATTR() "" \fINFSPROC_GETATTR()\fP
.DS
attrstat 
NFSPROC_GETATTR (fhandle) = 1;
.DE
.KE
If the reply  status is 
.I NFS_OK ,
then  the reply attributes contains
the attributes for the file given by the input fhandle.
.KS
.NH 3
\&Set File Attributes
.IX "NFS server procedures" NFSPROC_SETATTR() "" \fINFSPROC_SETATTR()\fP
.DS
struct sattrargs {
	fhandle file;
	sattr attributes;
	};

attrstat
NFSPROC_SETATTR (sattrargs) = 2;
.DE
.KE
The  "attributes" argument  contains fields which are either  -1 or
are  the  new value for  the  attributes of  "file".   If the reply
status is 
.I NFS_OK ,
then the  reply attributes have the attributes of
the file after the "SETATTR" operation has completed.
.LP
Note: The use of -1 to indicate an unused field in "attributes" is
changed in the next version of the protocol.
.KS
.NH 3
\&Get Filesystem Root
.IX "NFS server procedures" NFSPROC_ROOT "" \fINFSPROC_ROOT\fP
.DS
void 
NFSPROC_ROOT(void) = 3;
.DE
.KE
Obsolete.  This procedure  is no longer used   because  finding the
root file handle of a filesystem requires moving  pathnames between
client  and server.  To  do  this right we would  have  to define a
network standard representation of pathnames.  Instead, the
function  of  looking up  the   root  file handle  is  done  by the
.I MNTPROC_MNT() 
procedure.    (See the
.I "Mount Protocol Definition"
later in this chapter for details).
.KS
.NH 3
\&Look Up File Name
.IX "NFS server procedures" NFSPROC_LOOKUP() "" \fINFSPROC_LOOKUP()\fP
.DS
diropres
NFSPROC_LOOKUP(diropargs) = 4;
.DE
.KE
If  the reply "status"  is 
.I NFS_OK ,
then the reply  "file" and reply
"attributes" are the file handle and attributes for the file "name"
in the directory given by "dir" in the argument.
.KS
.NH 3
\&Read From Symbolic Link
.IX "NFS server procedures" NFSPROC_READLINK() "" \fINFSPROC_READLINK()\fP
.DS
union readlinkres switch (stat status) {
	case NFS_OK:
		path data;
	default:
		void;
};

readlinkres
NFSPROC_READLINK(fhandle) = 5;
.DE
.KE
If "status" has the value 
.I NFS_OK ,
then the reply "data" is the data in 
the symbolic link given by the file referred to by the fhandle argument.
.LP
Note:  since   NFS always  parses pathnames    on the  client, the
pathname in  a symbolic  link may  mean something  different (or be
meaningless) on a different client or on the server if  a different
pathname syntax is used.
.KS
.NH 3
\&Read From File
.IX "NFS server procedures" NFSPROC_READ "" \fINFSPROC_READ\fP
.DS
struct readargs {
	fhandle file;
	unsigned offset;
	unsigned count;
	unsigned totalcount;
};

union readres switch (stat status) {
	case NFS_OK:
		fattr attributes;
		opaque data<NFS_MAXDATA>;
	default:
		void;
};

readres
NFSPROC_READ(readargs) = 6;
.DE
.KE
Returns  up  to  "count" bytes of   "data" from  the file  given by
"file", starting at "offset" bytes from  the beginning of the file.
The first byte of the file is  at offset zero.  The file attributes
after the read takes place are returned in "attributes".
.LP
Note: The  argument "totalcount" is  unused, and is removed in the
next protocol revision.
.KS
.NH 3
\&Write to Cache
.IX "NFS server procedures" NFSPROC_WRITECACHE() "" \fINFSPROC_WRITECACHE()\fP
.DS
void
NFSPROC_WRITECACHE(void) = 7;
.DE
.KE
To be used in the next protocol revision.
.KS
.NH 3
\&Write to File
.IX "NFS server procedures" NFSPROC_WRITE() "" \fINFSPROC_WRITE()\fP
.DS
struct writeargs {
	fhandle file;          
	unsigned beginoffset;  
	unsigned offset;       
	unsigned totalcount;   
	opaque data<NFS_MAXDATA>;
};

attrstat	
NFSPROC_WRITE(writeargs) = 8;
.DE
.KE
Writes   "data" beginning  "offset"  bytes  from the  beginning  of
"file".  The first byte  of  the file is at  offset  zero.  If  the
reply "status" is NFS_OK, then  the reply "attributes" contains the
attributes  of the file after the  write has  completed.  The write
operation is atomic.  Data from this  call to 
.I WRITE 
will not be mixed with data from another client's calls.
.LP
Note: The arguments "beginoffset" and "totalcount" are ignored and
are removed in the next protocol revision.
.KS
.NH 3
\&Create File
.IX "NFS server procedures" NFSPROC_CREATE() "" \fINFSPROC_CREATE()\fP
.DS
struct createargs {
	diropargs where;
	sattr attributes;
};

diropres
NFSPROC_CREATE(createargs) = 9;
.DE
.KE
The file "name" is created  in the directory given  by "dir".   The
initial  attributes of the  new file  are given by "attributes".  A
reply "status"  of NFS_OK indicates that the  file was created, and
reply "file"   and   reply "attributes"  are    its file handle and
attributes.   Any  other reply  "status"  means that  the operation
failed and no file was created.
.LP
Note: This  routine should pass  an exclusive create flag, meaning
"create the file only if it is not already there".
.KS
.NH 3
\&Remove File
.IX "NFS server procedures" NFSPROC_REMOVE() "" \fINFSPROC_REMOVE()\fP
.DS
stat
NFSPROC_REMOVE(diropargs) = 10;
.DE
.KE
The file "name" is  removed from the directory  given by "dir".   A
reply of NFS_OK means the directory entry was removed.
.LP
Note: possibly non-idempotent operation.
.KS
.NH 3
\&Rename File
.IX "NFS server procedures" NFSPROC_RENAME() "" \fINFSPROC_RENAME()\fP
.DS
struct renameargs {
	diropargs from;	
	diropargs to;
};

stat
NFSPROC_RENAME(renameargs) = 11;
.DE
.KE
The existing file "from.name" in  the directory given by "from.dir"
is renamed to "to.name" in the directory given by "to.dir".  If the
reply  is 
.I NFS_OK ,
the file was  renamed.  The  
RENAME  
operation is
atomic on the server; it cannot be interrupted in the middle.
.LP
Note: possibly non-idempotent operation.
.KS
.NH 3
\&Create Link to File
.IX "NFS server procedures" NFSPROC_LINK() "" \fINFSPROC_LINK()\fP
.DS
struct linkargs {
	fhandle from;
	diropargs to;
};

stat
NFSPROC_LINK(linkargs) = 12;
.DE
.KE
Creates the  file "to.name"  in the directory  given   by "to.dir",
which is a hard link to the existing file given  by "from".  If the
return value is 
.I NFS_OK ,
a link was created.  Any other return value
indicates an error, and the link was not created.
.LP
A hard link should have the property that changes  to either of the
linked files are reflected in both files.  When a hard link is made
to a  file, the attributes  for  the file should  have  a value for
"nlink" that is one greater than the value before the link.
.LP
Note: possibly non-idempotent operation.
.KS
.NH 3
\&Create Symbolic Link
.IX "NFS server procedures" NFSPROC_SYMLINK() "" \fINFSPROC_SYMLINK()\fP
.DS
struct symlinkargs {
	diropargs from;
	path to;
	sattr attributes;
};

stat
NFSPROC_SYMLINK(symlinkargs) = 13;
.DE
.KE
Creates the  file "from.name" with  ftype  
.I NFLNK 
in  the  directory
given by "from.dir".   The new file contains  the pathname "to" and
has initial attributes given by "attributes".  If  the return value
is 
.I NFS_OK ,
a link was created.  Any other return value indicates an
error, and the link was not created.
.LP
A symbolic  link is  a pointer to another file.   The name given in
"to" is  not interpreted by  the server, only stored in  the  newly
created file.  When the client references a file that is a symbolic
link, the contents of the symbolic  link are normally transparently
reinterpreted  as a pathname  to substitute.   A 
.I READLINK 
operation returns the data to the client for interpretation.
.LP
Note:  On UNIX servers the attributes are never used, since
symbolic links always have mode 0777.
.KS
.NH 3
\&Create Directory
.IX "NFS server procedures" NFSPROC_MKDIR() "" \fINFSPROC_MKDIR()\fP
.DS
diropres
NFSPROC_MKDIR (createargs) = 14;
.DE
.KE
The new directory "where.name" is created in the directory given by
"where.dir".  The initial attributes of the new directory are given
by "attributes".  A reply "status" of NFS_OK indicates that the new
directory was created, and reply "file" and  reply "attributes" are
its file  handle and attributes.  Any  other  reply "status"  means
that the operation failed and no directory was created.
.LP
Note: possibly non-idempotent operation.
.KS
.NH 3
\&Remove Directory
.IX "NFS server procedures" NFSPROC_RMDIR() "" \fINFSPROC_RMDIR()\fP
.DS
stat
NFSPROC_RMDIR(diropargs) = 15;
.DE
.KE
The existing empty directory "name" in the directory given by "dir"
is removed.  If the reply is 
.I NFS_OK ,
the directory was removed.
.LP
Note: possibly non-idempotent operation.
.KS
.NH 3