STYXSERVER(10.2) STYXSERVER(10.2)
NAME
Styxserver - C Styx server library
SYNOPSIS
#define Qroot 0
#define MSGMAX ((((8192+128)*2)+3) & ~3)
extern char Enomem[]; /* out of memory */
extern char Eperm[]; /* permission denied */
extern char Enodev[]; /* no free devices */
extern char Ehungup[]; /* i/o on hungup channel */
extern char Eexist[]; /* file exists */
extern char Enonexist[]; /* file does not exist */
extern char Ebadcmd[]; /* bad command */
extern char Ebadarg[]; /* bad arguments */
typedef uvlong Path;
typedef struct Styxserver Styxserver;
typedef struct Styxops Styxops;
typedef struct Styxfile Styxfile;
typedef struct Client Client;
struct Styxserver
{
Styxops *ops;
Path qidgen;
int connfd;
Client *clients;
Client *curc;
Styxfile *root;
Styxfile **ftab;
void *priv; /* private */
};
struct Client
{
Styxserver *server;
Client *next;
int fd;
char msg[MSGMAX];
uint nread; /* valid bytes in msg (including nc)*/
int nc; /* bytes consumed from front of msg by convM2S */
char data[MSGMAX]; /* Tread/Rread data */
int state;
Fid *fids;
char *uname; /* uid */
char *aname; /* attach name */
void *u;
};
Page 1 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
struct Styxops
{
char *(*newclient)(Client *c);
char *(*freeclient)(Client *c);
char *(*attach)(char *uname, char *aname);
char *(*walk)(Qid *qid, char *name);
char *(*open)(Qid *qid, int mode);
char *(*create)(Qid *qid, char *name, int perm, int mode);
char *(*read)(Qid qid, char *buf, ulong *n, vlong offset);
char *(*write)(Qid qid, char *buf, ulong *n, vlong offset);
char *(*close)(Qid qid, int mode);
char *(*remove)(Qid qid);
char *(*stat)(Qid qid, Dir *d);
char *(*wstat)(Qid qid, Dir *d);
};
struct Styxfile
{
Dir d;
Styxfile *parent;
Styxfile *child;
Styxfile *sibling;
Styxfile *next;
int ref;
int open;
void *u;
};
char *styxinit(Styxserver *server, Styxops *ops, char *port, int perm, int needfile);
char *styxwait(Styxserver *server);
char *styxprocess(Styxserver *server);
char *styxend(Styxserver *server);
Client *styxclient(Styxserver *server);
Styxfile *styxaddfile(Styxserver *server, Path pqid, Path qid, char *name,
int mode, char *owner);
Styxfile *styxadddir(Styxserver *server, Path pqid, Path qid, char *name,
int mode, char *owner);
int styxrmfile(Styxserver *server, Path qid);
Styxfile *styxfindfile(Styxserver *server, Path qid);
int styxperm(Styxfile *file, char *uid, int mode);
long styxreadstr(ulong off, char *buf, ulong n, char *str);
Qid styxqid(int path, int isdir);
void *styxmalloc(int bytes);
void styxfree(void *p);
void styxdebug(void);
DESCRIPTION
The C Styx server library provides a small suite of
Page 2 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
functions to enable the production of a file server based on
the Inferno Styx protocol. The following elements define the
primary routines in the interface:
styxinit(server, ops, port, perm, needfile)
Initializes the interface given a pointer to a Styx-
server structure server , a callback table of opera-
tions ops , a port number port to announce the file
service on and the permissions perm on the root direc-
tory. The default permission is 0555 (read and execute
for user, group and others) if the latter is specified
as -1. If the last argument needfile is set to true,
the styx library will check that each path number it
deals with has a corresponding file associated with it
and, if it hasn't, it will issue a "file does not
exist" message automatically. In case of an error, the
error message is returned, otherwise nil is returned to
indicate success.
styxwait(server)
Waits for communication from a client. Return value as
above.
styxprocess(server)
Processes the client message after a successful call to
styxwait . This may result in calls to the functions in
the table provided to styxinit . Return value as above.
styxend(server)
End all file service. Return value as above.
styxclient(server)
Returns the client whose request is currently being
processed.
The next set of functions allow the creation of a file sys-
tem structure based upon the Styxfile structure. This con-
tains a Dir structure d describing the properties of the
file (defined in lib9.h) and pointers to other files in the
file tree: parent , child , sibling and next . The ref field
counts current references to the file. The open field counts
the current number of opens on the file. Finally the u field
allows further fields to be tagged onto each file. It is not
used by the Styx server library.
Each file must have a unique path number in the server. The
root of the tree Qroot always has path number zero. It's
corresponding file is created during library initialization
and placed in the root field of the server structure. All
other files must be supplied with a path number to identify
them. Files are created/deleted as follows:
Page 3 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
styxaddfile(server, ppath, path, name, mode, owner)
Add a new file (ie non-directory) with the given path
path , name name , mode mode and owner owner to the
directory identified by the path ppath . If path is -1
the library will generate a unique path number instead.
Returns nil if the parent file with path ppath does not
exist, if the parent is not a directory, if the path
number path already is assigned to a file or if the
parent already contains a file of name name .
styxadddir(server, ppath, path, name, mode, owner)
Add a new directory with the given path path , name
name , mode mode and owner owner to the directory iden-
tified by the path ppath . Returns nil in the same cir-
cumstances as styxaddfile .
styxrmfile(server, path)
Remove the file or directory with path path from the
file server tree. If the file is a directory, it's con-
tents will be recursively removed. If the file does not
exist, -1 is returned, otherwise 0 is returned for suc-
cess.
styxfindfile(server, path)
Return the file structure corresponding to the file or
directory with path path . Nil is returned if the file
does not exist.
If the file system is created in this way the Styx library
will check read/write/execute permissions, check for invalid
uses of files and check that path numbers exist in the file
system (see styxinit for the latter). If it's not feasible
to do this (for instance if there is a more suitable way of
describing the file system in question), then all file
checking must be done as part of the callback functions
below.
The library provides a callback mechanism so that the imple-
menter of the file server can take corresponding action when
a particular request is made of the server. All of these
functions may return an error message which will be communi-
cated back to the client. Otherwise they should return nil
to indicate the success of the operation. Any of these func-
tions may be nil in which case the library performs a
default operation which will be described below. These rou-
tines use the Qid structure defined in lib9.h to describe
files. This structure contains the path number( path ), a
version number( vers ) typically zero and a type( type )
which indicates whether the file is a directory, append-only
etc.
newclient(c)
Page 4 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
Called whenever a new client connects to the server.
The Client structure c contains mainly private data but
the uname field contains a user name and the aname
field an attach name if required. The u field may be
used to tag further data onto each client. It is not
used by the Styx server library.
freeclient(c)
Called whenever a client disconnects from the server.
attach(uname, aname)
Called when a client user first mounts the file server.
The uname is the user id and aname is typically the
file tree to access if the server provides a choice.
The default action is to allow the attach to the root
of the file system.
walk(qid, name)
In a directory represented by qid , find a file member
whose name is that given and place it's Qid in qid .
The default action is to perform the walk using any
directory structure provided.
open(qid, mode)
Open the file represented by qid with mode mode . The
latter may be one of OREAD, OWRITE, ORDWR etc (see
lib9.h). If the Qid of the newly opened file is differ-
ent from that given (a file server may understand the
opening of a file called "new" say to signify the cre-
ation of a directory whose Qid is returned instead)
place it's Qid in qid . The default action is to nomi-
nally allow the open.
create(qid, name, perm, mode)
Create a file in the directory given by qid with name
name , permissions perm and mode mode . Place the Qid
of the newly created file in qid . The default action
is to issue a permission denied message.
read(qid, buf, n, offset)
Read n bytes of the file represented by qid at offset
offset and place the result in buf.
Place in n the actual number of bytes read. The
default action is to read directories but to issue per-
mission denied on ordinary files.
write(qid, buf, n, offset)
Write n bytes to the file represented by qid at offset
offset from the buffer buf.
Place in n the actual number of bytes written. The
default action is to issue permission denied.
Page 5 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
close(qid, mode)
Close the file represented by qid . The mode it was
originally opened with is given by mode . The default
action is to allow the close.
remove(qid)
Remove the file represented by qid . The default action
is to issue a permission denied message.
stat(qid, d)
Place the information for the file represented by qid
in the Dir structure(see lib9.h) d . The default action
is to allow the stat using any information in the file
tree.
wstat(qid, d)
Update the information for the file represented by qid
according to the Dir structure d . The default action
is to disallow this with a permission denied message.
A small number of utility functions are provided:
styxperm(file, uid, mode)
Does the file/directory file allow the user uid the
permission given by mode . For example use OREAD for
read permission, OWRITE for write permission and ORDWR
for both.
styxreadstr(off, buf, n, str)
Read n bytes of data from the string str at offset off
and place the result in buf . Returns the actual number
of bytes read.
styxqid(path, isdir)
Returns a typical Qid structure with the given path
number path and whether the Qid is for a directory
isdir .
styxmalloc(n)
Allocate n bytes of memory and return it.
styxfree(p)
Free the memory pointed to by p .
styxdebug()
Print out some of the actions of the server.
EXAMPLE
A very small file server example is illustrated. First the
include files and globals.
#include <lib9.h>
Page 6 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
#include "styxserver.h"
int nq;
Styxserver *server;
The main processing loop:
main(int argc, char **argv)
{
Styxserver s;
server = &s;
styxinit(&s, &ops, "6701", 100, 0555, 0);
myinit(&s);
for(;;) {
styxwait(&s);
styxprocess(&s);
}
return 0;
}
Here the port number is 6701 and the root file permissions
are 0555 - no write permission for anyone which implies that
files and directories cannot be created in the root direc-
tory.
The creation of the directory tree:
myinit(Styxserver *s)
{
styxaddfile(s, Qroot, 1, "fred", 0664, "inferno");
styxaddfile(s, Qroot, 2, "joe", 0664, "inferno");
styxadddir(s, Qroot, 3, "adir", 0775, "inferno");
styxaddfile(s, 3, 4, "bill", 0664, "inferno");
styxadddir(s, Qroot, 5, "new", 0775, "inferno");
styxadddir(s, 5, 6, "cdir", 0775, "inferno");
styxaddfile(s, 6, 7, "cfile", 0664, "inferno");
nq = 8;
}
This creates two files fred and joe and two directories adir
and new at the top level. adir contains a file called bill
and new contains a directory called cdir which contains a
file called cfile . Note that each new path number is
unique.
The callback functions:
Styxops ops = {
nil, /* newclient */
nil, /* freeclient */
Page 7 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
nil, /* attach */
nil, /* walk */
nil, /* open */
mycreate, /* create */
myread, /* read */
nil, /* write */
nil, /* close */
myremove, /* remove */
nil, /* stat */
nil, /* wstat */
};
Here we choose the defaults most of the time.
The supplied callback routines:
char *
mycreate(Qid *qid, char *name, int perm, int mode)
{
int isdir;
Styxfile *f;
isdir = perm&DMDIR;
if(isdir)
f = styxadddir(server, qid->path, nq++, name , perm, "inferno");
else
f = styxaddfile(server, qid->path, nq++, name, perm, "inferno");
if(f == nil)
return Eexist;
*qid = f->d.qid;
return nil;
}
char *
myremove(Qid qid)
{
Styxfile *f;
f = styxfindfile(server, qid.path);
if(f != nil && (f->d.qid.type&QTDIR) && f->child != nil)
return "directory not empty";
if(styxrmfile(server, qid.path) < 0)
return Enonexist;
return nil;
}
char *
myread(Qid qid, char *d, ulong *n, vlong offset)
{
if(qid.path != 1){
*n = 0;
Page 8 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
return nil;
}
*n = styxreadstr(offset, d, *n, "abcdeghijklmn");
return nil;
}
Permission checking for walk (need execute permission on
directory), open (the given mode must be compatible with the
file permissions), create and remove (both of which need
write permission on directory) is done automatically when-
ever possible. The functions mycreate and myremove below
therefore can omit these checks.
The function mycreate simply creates a directory or file and
if the file cannot be added to the directory tree it returns
a 'file exists' error string. It sets the Qid for the newly
created file before returning.
The function myremove first checks to see if the file repre-
sents a non-empty directory, in which case it disallows it's
removal. Otherwise it removes the file if it can find it and
returns a 'file does not exist' error string if it can't.
The function myread considers all files to be empty except
for fred which notionally contains abcdefghijklmn . Note
that the number of bytes read is returned in the argument n
.
Once this file server is running, the root can be accessed
by doing for example
mount -A tcp!<address>!6701 /n/remote
under Inferno. Here <address> is the address of the machine
running the file server (or the loopback address 127.0.0.1
if it's all on one machine). The -A option is used to pre-
vent authentication which is not supported at the moment.
Then we can do
cd /n/remote
ls
adir
fred
joe
new
...
For a more complicated file server see
/tools/styxtest/styxtest.c.
The file /tools/styxtest/mkfile shows how to compile and
link the file server sources.
Page 9 Plan 9 (printed 12/22/24)
STYXSERVER(10.2) STYXSERVER(10.2)
SOURCE
/Nt/386/include/lib9.h
/tools/libstyx/styxserver.h
/tools/libstyx/styxserver.c
/tools/styxtest/styxtest.c
/tools/styxtest/styxtest0.c
BUGS
Currently the library is available under Windows, Linux and
Solaris only.
Authentication is not supported.
Page 10 Plan 9 (printed 12/22/24)