<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> The Venus kernel interface: The interface at the call level </TITLE>
<LINK HREF="kernel-venus-protocol-5.html" REL=next>
<LINK HREF="kernel-venus-protocol-3.html" REL=previous>
<LINK HREF="kernel-venus-protocol.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="kernel-venus-protocol-5.html">Next</A>
<A HREF="kernel-venus-protocol-3.html">Previous</A>
<A HREF="kernel-venus-protocol.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4. The interface at the call level </A></H2>
<P>
<P>This section describes the upcalls a Coda FS driver can make to Venus.
Each of these upcalls make use of three structures: <CODE>inputArgs</CODE> for communication from kernel to Venus, and
<CODE>outputArgs</CODE> back from Venus to the kernel and finally downcalls
which are calls from Venus to the kernel initiated by Venus.
<P>
<PRE>
union inputArgs {
struct cfs_in_hdr ih; /* NB: every struct below begins with an ih */
struct cfs_open_in cfs_open;
struct cfs_close_in cfs_close;
struct cfs_ioctl_in cfs_ioctl;
struct cfs_getattr_in cfs_getattr;
struct cfs_setattr_in cfs_setattr;
struct cfs_access_in cfs_access;
struct cfs_lookup_in cfs_lookup;
struct cfs_create_in cfs_create;
struct cfs_remove_in cfs_remove;
struct cfs_link_in cfs_link;
struct cfs_rename_in cfs_rename;
struct cfs_mkdir_in cfs_mkdir;
struct cfs_rmdir_in cfs_rmdir;
struct cfs_readdir_in cfs_readdir;
struct cfs_symlink_in cfs_symlink;
struct cfs_readlink_in cfs_readlink;
struct cfs_fsync_in cfs_fsync;
struct cfs_inactive_in cfs_inactive;
struct cfs_vget_in cfs_vget;
struct cfs_rdwr_in cfs_rdwr;
struct cfs_open_by_path_in cfs_open_by_path;
};
</PRE>
<P>
<PRE>
union outputArgs {
struct cfs_out_hdr oh; /* NB: every struct below begins with an oh */
struct cfs_root_out cfs_root;
struct cfs_open_out cfs_open;
struct cfs_ioctl_out cfs_ioctl;
struct cfs_getattr_out cfs_getattr;
struct cfs_lookup_out cfs_lookup;
struct cfs_create_out cfs_create;
struct cfs_mkdir_out cfs_mkdir;
struct cfs_readdir_out cfs_readdir;
struct cfs_readlink_out cfs_readlink;
struct cfs_vget_out cfs_vget;
struct cfs_purgeuser_out cfs_purgeuser;
struct cfs_zapfile_out cfs_zapfile;
struct cfs_zapdir_out cfs_zapdir;
struct cfs_zapvnode_out cfs_zapvnode;
struct cfs_purgefid_out cfs_purgefid;
struct cfs_rdwr_out cfs_rdwr;
struct cfs_replace_out cfs_replace;
struct cfs_open_by_path_out cfs_open_by_path;
};
</PRE>
<P>
<PRE>
union cfs_downcalls {
/* CFS_FLUSH is also a down call */
struct cfs_purgeuser_out purgeuser;
struct cfs_zapfile_out zapfile;
struct cfs_zapdir_out zapdir;
struct cfs_zapvnode_out zapvnode;
struct cfs_purgefid_out purgefid;
struct cfs_replace_out replace;
};
</PRE>
<P>The headers are common to all calls and contain process, authentication and opcode information:
<P>
<PRE>
struct cfs_in_hdr {
unsigned long opcode;
unsigned long unique; /* Keep multiple outstanding msgs distinct */
u_short pid; /* Common to all */
u_short pgid; /* Common to all */
u_short sid; /* to become the PAG */
struct coda_cred cred; /* to become a PAG */
};
/* Really important that opcode and unique are 1st two fields! */
struct cfs_out_hdr {
unsigned long opcode;
unsigned long unique;
unsigned long result;
};
</PRE>
<P>Before going on let us elucidate the role of the various fields. The
inputArgs start with the <CODE>opcode</CODE> which defines the type of service
requested from Venus. There are approximately 30 upcalls at present
which we will discuss. The <CODE>unique</CODE> field labels the inputArg
with unique number which will identify the message uniquely. A
process and process group id are passed. Finally the credentials of
the caller are included.
<P>Before delving into the specific calls we need to discuss a variety of
data structures shared by the kernel and Venus.
<P>
<H2><A NAME="ss4.1">4.1 Data structures shared by the kernel and Venus </A>
</H2>
<P>
<P>The <CODE>CodaCred</CODE> structure defines a variety of user and group id's as
they are set for the calling process. The <CODE>vuid_t</CODE> and <CODE>guid_t</CODE>
are 32 bit unsigned integers. It also defines group member
ship in an array. On Unix the CodaCred has proven sufficient to
implement good security semantics for Coda but the structure may have
to undergo modification for the Windows environment when these mature.
<PRE>
struct CodaCred {
vuid_t cr_uid, cr_euid, cr_suid, cr_fsuid; /* Real, efftve, set, fs uid*/
vgid_t cr_gid, cr_egid, cr_sgid, cr_fsgid; /* same for groups */
vgid_t cr_groups[NGROUPS]; /* Group membership for caller */
};
</PRE>
<P><B>NOTE</B> It is questionable if we need CodaCreds in Venus. Finally
Venus doesn't know about groups, although it does create files with
the default uid/gid. Perhaps the list of group membership is
superfluous.
<P>
<P>The next item is the fundamental identifier used to identify Coda
files, the <CODE>ViceFid</CODE>. A fid of a file uniquely defines a file or
directory in the Coda filesystem within a <EM>cell</EM>.
<BLOCKQUOTE>A
<EM>cell</EM> is a group of Coda servers acting under the aegis of a
single system control machine or SCM. See the Coda Administration
manual for a detailed description of the role of the SCM.</BLOCKQUOTE>
<P>
<PRE>
typedef struct ViceFid {
VolumeId Volume;
VnodeId Vnode;
Unique_t Unique;
} ViceFid;
</PRE>
<P>Each of the constituent fields: <CODE>VolumeId, VnodeId</CODE> and
<CODE>Unique_t</CODE> are unsigned 32 bit integers. We envisage that a
further field will need to be prefixed to identify the Coda cell; this
will probably take the form of a Ipv6 size IP address naming the Coda
cell through DNS.
<P>The next important structure shared between Venus and the kernel are
the attributes of the file. The following structure is used to
exchange information. It has room for future extensions such as
support for device files (currently not present in Coda).
<P>
<PRE>
struct coda_vattr {
enum coda_vtype va_type; /* vnode type (for create) */
u_short va_mode; /* files access mode and type */
short va_nlink; /* number of references to file */
vuid_t va_uid; /* owner user id */
vgid_t va_gid; /* owner group id */
long va_fsid; /* file system id (dev for now) */
long va_fileid; /* file id */
u_quad_t va_size; /* file size in bytes */
long va_blocksize; /* blocksize preferred for i/o */
struct timespec va_atime; /* time of last access */
struct timespec va_mtime; /* time of last modification */
struct timespec va_ctime; /* time file changed */
u_long va_gen; /* generation number of file */
u_long va_flags; /* flags defined for file */
dev_t va_rdev; /* device special file represents */
u_quad_t va_bytes; /* bytes of disk space held by file */
u_quad_t va_filerev; /* file modification number */
u_int va_vaflags; /* operations flags, see below */
long va_spare; /* remain quad aligned */
};
</PRE>
<P>
<H2><A NAME="ss4.2">4.2 The pioctl interface </A>
</H2>
<P>
<P>Coda specific requests can be made by application through the pioctl
interface. The pioctl is implemented as an ordinary ioctl on a
ficticious file <CODE>/coda/.CONTROL</CODE>. The piocl call opens this
file, gets a file handle and makes the ioctl call. Finally it closes
the file.
<P>The kernel involvement in this is limited to providing the facility to
open and close and pass the ioctl message <EM>and</EM> to verify that a
path in the pioctl data buffers is a file in a Coda filesystem.
<P>The kernel is handed a data packet of the form:
<PRE>
struct {
const char *path;
struct ViceIoctl vidata;
int follow;
} data;
</PRE>
<P>where
<P>
<PRE>
struct ViceIoctl {
caddr_t in, out; /* Data to be transferred in, or out */
short in_size; /* Size of input buffer <= 2K */
short out_size; /* Maximum size of output buffer, <= 2K */
};
</PRE>
<P>The <CODE>path</CODE> must be a Coda file, otherwise the <CODE>ioctl</CODE> upcall
will not be made.
<P><B>NOTE</B> The data structures and code are a mess. We need to clean
this up.
<P>We now proceed to document the individual calls:
<P>\newpage
<H2><A NAME="ss4.3">4.3 root</A>
</H2>
<P>
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>empty
<DT><B>out</B><DD><P>
<PRE>
struct cfs_root_out {
ViceFid VFid;
} cfs_root;
</PRE>
</DL>
<P><B>Description</B> This call is made to Venus during the initialization
of the Coda filesystem. If the <CODE>result</CODE> is zero, the <CODE>cfs_root</CODE>
structure contains the ViceFid of the root of the Coda filesystem. If
a non-zero result is generated, its value is a platform dependent
error code indicating the difficulty Venus encountered in locating the
root of the Coda filesystem.
<P>\newpage
<H2><A NAME="ss4.4">4.4 lookup</A>
</H2>
<P>
<P><B>Summary</B> Find the ViceFid and type of an object in a directory if
it exists.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_lookup_in {
ViceFid VFid;
char *name; /* Place holder for data. */
} cfs_lookup;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_lookup_out {
ViceFid VFid;
int vtype;
} cfs_lookup;
</PRE>
</DL>
<P><B>Description</B> This call is made to determine the ViceFid and
filetype of a directory entry. The directory entry requested carries
name <CODE>name</CODE> and Venus will search the directory identified by
<CODE>cfs_lookup_in.VFid</CODE>. The <CODE>result</CODE> may indicate that the name
does not exist, or that difficulty was encountered in finding it
(e.g. due to disconnection). If the <CODE>result</CODE> is zero, the field
<CODE>cfs_lookup_out.VFid</CODE> contains the targets ViceFid and
<CODE>cfs_lookup_out.vtype</CODE> the <CODE>coda_vtype</CODE> giving the type of
object the name designates.
<P>The name of the object is an 8 bit character string of maximum length
CFS_MAXNAMLEN, currently set to 256 (including a 0 terminator.)
<P>It is extremely important to realize that Venus bitwise or's the field
<CODE>cfs_lookup.vtype</CODE> with <CODE>CFS_NOCACHE</CODE> to indicate that the
object should not be put in the kernel name cache. Files in conflict or
uncovered mountpoints should never be cached by the kernel and each lookup
should make it to Venus.
<P><B>NOTE</B> The type of the vtype is currently wrong. It should be
<CODE>coda_vtype</CODE>. Linux does not take note of <CODE>CFS_NOCACHE</CODE>. It
should.
<P>\newpage
<H2><A NAME="ss4.5">4.5 getattr</A>
</H2>
<P>
<P><B>Summary</B> Get the attributes of a file.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_getattr_in {
ViceFid VFid;
struct coda_vattr attr; /* XXXXX */
} cfs_getattr;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_getattr_out {
struct coda_vattr attr;
} cfs_getattr;
</PRE>
</DL>
<P><B>Description</B>
This call returns the attributes of the file identified by fid.
<P><B>Errors</B> Errors can occur if the object with fid does not exist,
are unaccessible or if the caller does not have permission to fetch
attributes.
<P><B>Note</B> Many kernel FS drivers (Linux, NT and Windows 95 need to
acquire the attributes as well as the Fid for the instantiation of an
internal "inode" or "FileHandle". A significant improvement in
performance on such systems could be made by combining the <EM>lookup</EM>
and <EM>getattr</EM> calls both at the Venus/kernel interaction level and
at the RPC level.
<P>The <CODE>vattr</CODE> structure included in the input arguments is
superfluous and should be removed.
<P>\newpage
<H2><A NAME="ss4.6">4.6 setattr</A>
</H2>
<P>
<P><B>Summary</B> Set the attributes of a file.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_setattr_in {
ViceFid VFid;
struct coda_vattr attr;
} cfs_setattr;
</PRE>
<DT><B>out</B><DD><P>empty
</DL>
<P><B>Description</B> The structure <CODE>attr</CODE> is filled with attributes to
be changed in BSD style. Attributes not to be changed are set to -1,
apart from <CODE>vtype</CODE> which is set to <CODE>VNON</CODE>. Other are set to the
value to be assigned. The only attributes which the FS driver may
request to change are the mode, ownner, groupid, atime, mtime and
ctime. The return value indicates success or failure.
<P><B>Errors</B> A variety of errors can occur. The object may not exist,
may be inaccessible, or permission may not be granted by Venus.
<P>\newpage
<H2><A NAME="ss4.7">4.7 access</A>
</H2>
<P>
<P><B>Summary</B>
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_access_in {
ViceFid VFid;
int flags;
} cfs_access;
</PRE>
<DT><B>out</B><DD><P>empty
</DL>
<P><B>Description</B> Verify if access to the object identified by <CODE>VFid</CODE> for
operations described by <CODE>flags</CODE> is permitted. The result indicates
if access will be granted. It is important to remember that Coda uses
ACL's to enforce protection and that ultimately the servers, not the
clients enforce the security of the system. The result of this call
will depend on wether a <EM>token</EM> is held by the user.
<P><B>Errors</B> The object may not exist, or the ACL describing the
protection may not be accessible.
<P>\newpage
<H2><A NAME="ss4.8">4.8 create</A>
</H2>
<P>
<P><B>Summary</B> Invoked to create a file
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_create_in {
ViceFid VFid;
struct coda_vattr attr;
int excl;
int mode;
char *name; /* Place holder for data. */
} cfs_create;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_create_out {
ViceFid VFid;
struct coda_vattr attr;
} cfs_create;
</PRE>
</DL>
<P><B>Description</B> This upcall is invoked to request creation of a
file. The file will be created in the directory identified by
<CODE>VFid</CODE>, its name will be <CODE>name</CODE>, and the mode will be
<CODE>mode</CODE>. If <CODE>excl</CODE> is set an error will be returned if the file
already exists. If the size field in attr is set to zero the file
will be truncated. The uid and gid of the file are set by converting
the CodaCred to a uid using a macro <CODE>CRTOUID</CODE> (this macro is
platform dependent). Upon success the VFid and attributes of the file
are returned. The Coda FS Driver will normally instantiate a vnode,
inode or filehandle at kernel level for the new object.
<P>
<P><B>Errors</B> A variety of errors can occur. Permissions may be
insufficient. If the object exists and is not a file the error
<CODE>EISDIR</CODE> is returned under Unix.
<P><B>NOTE</B> The packing of parameters is very inefficient and appears to
indicate confusion between the system call creat and the VFS operation
create. The VFS operation create is only called to create new
objects. This create call differs from the Unix one in that it is not
invoked to return a file descriptor. The trunctate and exclusive
options, together with the mode, could simply be part of the mode as
it is under Unix. There should be no flags argument; this is used in
<CODE>open</CODE> (2) to return a filedescriptor for READ or WRITE mode.
<P>The attributes of the directory should be returned too, since the size
and mtime changed.
<P>\newpage
<H2><A NAME="ss4.9">4.9 mkdir</A>
</H2>
<P>
<P><B>Summary</B> Create a new directory.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_mkdir_in {
ViceFid VFid;
struct coda_vattr attr;
char *name; /* Place holder for data. */
} cfs_mkdir;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_mkdir_out {
ViceFid VFid;
struct coda_vattr attr;
} cfs_mkdir;
</PRE>
</DL>
<P><B>Description</B> This call is similar to <CODE>create</CODE> but creates a
directory. Only the <CODE>mode</CODE> field in the input parameters is used
for creation. Upon successful creation, the <CODE>attr</CODE> returned
contains the attributes of the new directory.
<P><B>Errors</B> As for create.
<P><B>NOTE</B> The input parameter should be changed to <CODE>mode</CODE> instead
of attributes.
<P>The attributes of the parent should be returned since the size and
mtime changes.
<P>\newpage
<H2><A NAME="ss4.10">4.10 link</A>
</H2>
<P>
<P><B>Summary</B> Create a link to an existing file.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_link_in {
ViceFid sourceFid; /* cnode to link *to* */
ViceFid destFid; /* Directory in which to place link */
char *tname; /* Place holder for data. */
} cfs_link;
</PRE>
<DT><B>out</B><DD><P>empty
</DL>
<P><B>Description</B> This call creates a link to the <CODE>sourceFid</CODE> in the
directory identified by <CODE>destFid</CODE> with name <CODE>tname</CODE>. The source
must reside in the targets parent, i.e. the source must be have parent
<CODE>destFid</CODE>, i.e. Coda does not support cross directory hard links.
Only the return value is relevant. It indicates success or the type
of failure.
<P><B>Errors</B> The usual errors can occur.\newpage
<H2><A NAME="ss4.11">4.11 symlink</A>
</H2>
<P>
<P><B>Summary</B> create a symbolic link
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_symlink_in {
ViceFid VFid; /* Directory to put symlink in */
char *srcname;
struct coda_vattr attr;
char *tname;
} cfs_symlink;
</PRE>
<DT><B>out</B><DD><P>none
</DL>
<P><B>Description</B> Create a symbolic link. The link is to be placed in
the directory identified by <CODE>VFid</CODE> and named <CODE>tname</CODE>. It should
point to the pathname <CODE>srcname</CODE>. The attributes of the newly
created object are to be set to <CODE>attr</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> The attributes of the target directory should be returned
since its size changed.
<P>\newpage
<H2><A NAME="ss4.12">4.12 remove</A>
</H2>
<P>
<P><B>Summary</B> Remove a file
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_remove_in {
ViceFid VFid;
char *name; /* Place holder for data. */
} cfs_remove;
</PRE>
<DT><B>out</B><DD><P>none
</DL>
<P><B>Description</B> Remove file named <CODE>cfs_remove_in.name</CODE> in
directory identified by <CODE>VFid</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> The attributes of the directory should be returned since its
mtime and size may change.
<P>\newpage
<H2><A NAME="ss4.13">4.13 rmdir</A>
</H2>
<P>
<P><B>Summary</B> Remove a directory
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_rmdir_in {
ViceFid VFid;
char *name; /* Place holder for data. */
} cfs_rmdir;
</PRE>
<DT><B>out</B><DD><P>none
</DL>
<P><B>Description</B> Remove the directory with name <CODE>name</CODE> from the
directory identified by <CODE>VFid</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> The attributes of the parent directory should be returned
since its mtime and size may change.
<P>\newpage
<H2><A NAME="ss4.14">4.14 readlink</A>
</H2>
<P>
<P><B>Summary</B> Read the value of a symbolic link.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_readlink_in {
ViceFid VFid;
} cfs_readlink;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_readlink_out {
int count;
caddr_t data; /* Place holder for data. */
} cfs_readlink;
</PRE>
</DL>
<P><B>Description</B> This routine reads the contents of symbolic link
identified by <CODE>VFid</CODE> into the buffer <CODE>data</CODE>. The buffer
<CODE>data</CODE> must be able to hold any name up to <CODE>CFS_MAXNAMLEN</CODE> (PATH or
NAM??).
<P><B>Errors</B> No unusual errors.
<P>\newpage
<H2><A NAME="ss4.15">4.15 open</A>
</H2>
<P>
<P><B>Summary</B> Open a file.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_open_in {
ViceFid VFid;
int flags;
} cfs_open;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_open_out {
dev_t dev;
ino_t inode;
} cfs_open;
</PRE>
</DL>
<P><B>Description</B> This request asks Venus to place the file identified
by <CODE>VFid</CODE> in its cache and to note that the calling process wishes
to open it with <CODE>flags</CODE> as in <CODE>open(2)</CODE>. The return value to
the kernel differs for Unix and Windows systems. For Unix systems the
Coda FS Driver is informed of the device and inode number of the
container file in the fields <CODE>dev</CODE> and <CODE>inode</CODE>. For Windows the
path of the container file is returned to the kernel.
<P><B>Errors</B>
<P><B>NOTE</B> Currently the <CODE>cfs_open_out</CODE> structure is not properly
adapted to deal with the windows case. It might be best to implement
two upcalls, one to open aiming at a container file name, the other at
a container file inode.
<P>\newpage
<H2><A NAME="ss4.16">4.16 close</A>
</H2>
<P>
<P><B>Summary</B> Close a file, update it on the servers.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_close_in {
ViceFid VFid;
int flags;
} cfs_close;
</PRE>
<DT><B>out</B><DD><P>none
</DL>
<P><B>Description</B> Close the file identified by <CODE>VFid</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> The <CODE>flags</CODE> argument is bogus and not used. However,
Venus' code has room to deal with an <CODE>execp</CODE> input field, probably
this field should be used to inform Venus that the file was closed but
is still memory mapped for execution. There are comments about
fetching versus not fetching the data in Venus <CODE>vproc_vfscalls</CODE>.
This seems silly. If a file is being closed, the data in the
container file is to be the new data. Here again the <CODE>execp</CODE> flag
might be in play to create confusion: presently Venus might think a
file can be flushed from the cache when it is still memory mapped.
This needs to be understood.
<P>\newpage
<H2><A NAME="ss4.17">4.17 ioctl</A>
</H2>
<P>
<P><B>Summary</B> Do an ioctl on a file. This includes the piocl interface.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_ioctl_in {
ViceFid VFid;
int cmd;
int len;
int rwflag;
char *data; /* Place holder for data. */
} cfs_ioctl;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_ioctl_out {
int len;
caddr_t data; /* Place holder for data. */
} cfs_ioctl;
</PRE>
</DL>
<P><B>Description</B> Do an ioctl operation on a file. The <CODE>command,
len</CODE> and <CODE>data</CODE> arguments are filled as usual. <CODE>flags</CODE> is not
used by Venus.
<P><B>Errors</B>
<P><B>NOTE</B> Another bogus parameter. <CODE>flags</CODE> is not used. What is
the business about PREFETCHING in the Venus' code?
<P>
<P>\newpage
<H2><A NAME="ss4.18">4.18 rename</A>
</H2>
<P>
<P><B>Summary</B> Rename a fid.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_rename_in {
ViceFid sourceFid;
char *srcname;
ViceFid destFid;
char *destname;
} cfs_rename;
</PRE>
<DT><B>out</B><DD><P>none
</DL>
<P><B>Description</B> Rename the object with name <CODE>srcname</CODE> in
directory <CODE>sourceFid</CODE> to <CODE>destname</CODE> in <CODE>destFid</CODE>. It is
important that the names <CODE>srcname</CODE> and <CODE>destname</CODE> are 0
terminated strings. Strings in Unix kernels are not always null
terminated.
<P><B>Errors</B>
<P>\newpage
<H2><A NAME="ss4.19">4.19 readdir</A>
</H2>
<P>
<P><B>Summary</B> Read directory entries.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_readdir_in {
ViceFid VFid;
int count;
int offset;
} cfs_readdir;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_readdir_out {
int size;
caddr_t data; /* Place holder for data. */
} cfs_readdir;
</PRE>
</DL>
<P><B>Description</B> Read directory entries from <CODE>VFid</CODE> starting at
<CODE>offset</CODE> and read at most <CODE>count</CODE> bytes. Returns the data
into <CODE>data</CODE> and indicates the size returned <CODE>size</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> This call is not used. Readdir operations exploit container
files. We will re-evaluate this during the directory revamp which is
about to take place.
<P>\newpage
<H2><A NAME="ss4.20">4.20 vget</A>
</H2>
<P>
<P><B>Summary</B> instructs Venus to do an <CODE>FSDB->Get</CODE>.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_vget_in {
ViceFid VFid;
} cfs_vget;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_vget_out {
ViceFid VFid;
int vtype;
} cfs_vget;
</PRE>
</DL>
<P><B>Description</B> This upcall asks Venus to do a <CODE>get</CODE> operation on
an <CODE>fsobj</CODE> labelled by <CODE>VFid</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> This operation is not used. However, it is extremely useful
since it can be used to deal with read/write memory mapped files.
These can be "pinned" in the Venus cache using <CODE>vget</CODE> and release
with <CODE>inactive</CODE>.
<P>\newpage
<H2><A NAME="ss4.21">4.21 fsync</A>
</H2>
<P>
<P><B>Summary</B> Tell Venus to update the RVM attributes of a file.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_fsync_in {
ViceFid VFid;
} cfs_fsync;
</PRE>
<DT><B>out</B><DD><P>none
</DL>
<P><B>Description</B> Ask Venus to update RVM attributes of object
<CODE>VFid</CODE>. This should be called as part of kernel level <CODE>fsync</CODE>
type calls. The <CODE>result</CODE> indicates if the synching was
successful.
<P><B>Errors</B>
<P><B>NOTE</B> Linux does not implement this call. It should.
<P>\newpage
<H2><A NAME="ss4.22">4.22 inactive</A>
</H2>
<P>
<P><B>Summary</B> Tell Venus a vnode is no longer in use.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_inactive_in {
ViceFid VFid;
} cfs_inactive;
</PRE>
<DT><B>out</B><DD><P>none
</DL>
<P><B>Description</B> This operation returns <CODE>EOPNOTSUPP</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> This should perhaps be removed.
<P>\newpage
<H2><A NAME="ss4.23">4.23 rdwr</A>
</H2>
<P>
<P><B>Summary</B> Read or write from a file
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct cfs_rdwr_in {
ViceFid VFid;
int rwflag;
int count;
int offset;
int ioflag;
caddr_t data; /* Place holder for data. */
} cfs_rdwr;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct cfs_rdwr_out {
int rwflag;
int count;
caddr_t data; /* Place holder for data. */
} cfs_rdwr;
</PRE>
</DL>
<P><B>Description</B> This upcall asks Venus to read or write from a file.
<P><B>Errors</B>
<P><B>NOTE</B> It should be removed since it is against the Coda philosophy that
read/write operations never reach Venus. I have been told the
operation does not work. It is not currently used.
<P>
<P>\newpage
<H2><A NAME="ss4.24">4.24 odymount</A>
</H2>
<P>
<P><B>Summary</B> Allows mounting multiple Coda "filesystems" on one Unix mount
point.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>
<PRE>
struct ody_mount_in {
char *name; /* Place holder for data. */
} ody_mount;
</PRE>
<DT><B>out</B><DD><P>
<PRE>
struct ody_mount_out {
ViceFid VFid;
} ody_mount;
</PRE>
</DL>
<P><B>Description</B> Asks Venus to return the rootfid of a Coda system
named <CODE>name</CODE>. The fid is returned in <CODE>VFid</CODE>.
<P><B>Errors</B>
<P><B>NOTE</B> This call was used by David for dynamic sets. It should be
removed since it causes a jungle of pointers in the VFS mounting area.
It is not used by Coda proper. Call is not implemented by Venus.
<P>\newpage
<H2><A NAME="ss4.25">4.25 ody_lookup</A>
</H2>
<P>
<P><B>Summary</B> Looks up something.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>irrelevant
<DT><B>out</B><DD><P>irrelevant
</DL>
<P><B>Description</B>
<P><B>Errors</B>
<P><B>NOTE</B> Gut it. Call is not implemented by Venus.
<P>\newpage
<H2><A NAME="ss4.26">4.26 ody_expand</A>
</H2>
<P>
<P><B>Summary</B> expands something in a dynamic set.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>irrelevant
<DT><B>out</B><DD><P>irrelevant
</DL>
<P><B>Description</B>
<P><B>Errors</B>
<P><B>NOTE</B> Gut it. Call is not implemented by Venus.
<P>\newpage
<H2><A NAME="ss4.27">4.27 prefetch</A>
</H2>
<P>
<P><B>Summary</B> Prefetch a dynamic set.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>Not documented.
<DT><B>out</B><DD><P>Not documented.
</DL>
<P><B>Description</B> Venus worker.cc has support for this call, although
it is noted that it doesn't work. Not surprising, since the kernel
does not have support for it. (ODY_PREFETCH is not a defined
operation).
<P><B>Errors</B>
<P><B>NOTE</B> Gut it. It isn't working and isn't used by Coda.
<P>
<P>\newpage
<H2><A NAME="ss4.28">4.28 signal</A>
</H2>
<P>
<P><B>Summary</B> Send Venus a signal about an upcall.
<P><B>Arguments</B>
<DL>
<DT><B>in</B><DD><P>none
<DT><B>out</B><DD><P>not applicable.
</DL>
<P><B>Description</B> This is an out-of-band upcall to Venus to inform
Venus that the calling process received a signal after Venus read the
message from the input queue. Venus is supposed to clean up the
operation.
<P><B>Errors</B> No reply is given.
<P><B>NOTE</B> We need to better understand what Venus needs to clean up
and if it is doing this correctly. Also we need to handle multiple
upcall per system call situations correctly. It would be important to
know what state changes in Venus take place after an upcall for which
the kernel is responsible for notifying Venus to clean up (e.g. open
definitely is such a state change, but many others are maybe not).
<P>\newpage
<HR>
<A HREF="kernel-venus-protocol-5.html">Next</A>
<A HREF="kernel-venus-protocol-3.html">Previous</A>
<A HREF="kernel-venus-protocol.html#toc4">Contents</A>
</BODY>
</HTML>
distrib
>
Mandriva
>
8.2
>
i586
>
media
>
contrib
>
by-pkgid
>
211238da6d926d1ca4390483bb29f586
>
files
>
21
