NINEPSERVER

NAME
SYNOPSIS
DESCRIPTION
EXAMPLE
BUGS

NAME

Ninepserver − C 9P server library

SYNOPSIS

#include <lib9.h>
#include <ninep.h>
#include <ninepserver.h>
#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 Ninepserver Ninepserver;
typedef struct Ninepops Ninepops;
typedef struct Ninepfile Ninepfile;
typedef struct Client Client;
typedef struct Pending Pending;
typedef struct Fid Fid;

struct Ninepserver
{
     Ninepops *ops;
     Path qidgen;
     int connfd;
     int needfile;
     Client *clients;
     Client *curc;
     Fcall fcall;
     Ninepfile *root;
     Ninepfile **ftab;
     void *priv;    /* private */
};

struct Client
{
     Ninepserver *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;
     Pending **pending;
     char      *uname;   /* uid */
     char      *aname;   /* attach name */
     void      *u;
};

struct Pending
{
     Client *c;
     Fcall fcall;
     int flushed;
     Pending *next;
};

struct Ninepops
{
     char *(*newclient)(Client *c);
     char *(*freeclient)(Client *c);

     char *(*attach)(Qid *qid, 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 Ninepfile
{
     Dir  d;
     Ninepfile *parent;
     Ninepfile *child;
     Ninepfile *sibling;
     Ninepfile *next;
     Ninepfile *bind;
     Ninepfile *nf;
     int ref;
     int open;
     void *u;
};

char* ninepsetowner(char* user);
char *ninepnamespace(void);
char *ninepinit(Ninepserver *server, Ninepops *ops, char *address, int perm, int needfile);
char *ninepend(Ninepserver *server);

char *ninepwait(Ninepserver *server);

void nineplisten(Ninepserver *server, int fd);
int ninepready(Ninepserver *server, int fd);

void ninepdefault(Ninepserver *server);
void nineperror(Ninepserver *server, char *err);
void ninepreply(Ninepserver *server);

Pending *ninepreplylater(Ninepserver *server);
void ninepcompleted(Pending *pend);

Ninepfile *ninepaddfile(Ninepserver *server, Path pqid, Path qid, char *name, int mode, char *owner);
Ninepfile *ninepadddir(Ninepserver *server, Path pqid, Path qid, char *name, int mode, char *owner);
Ninepfile *ninepbind(Ninepserver *server, Path pqid, Path qid);
int nineprmfile(Ninepserver *server, Path qid);
Ninepfile *ninepfindfile(Ninepserver *server, Path qid);


int  ninepperm(Ninepfile *file, char *uid, int mode);
long ninepreadstr(ulong off, char *buf, ulong n, char *str);
Qid ninepqid(int path, int isdir);
void *ninepmalloc(int n);
void ninepfree(void *p);
void ninepdebug(void);

DESCRIPTION

The C Ninep server library provides a small suite of functions to enable the production of a file server based on the 9P protocol. The following elements define the primary routines in the interface:
ninepinit(server
opsaddresspermneedfile)

Initializes the interface given a pointer to a Ninepserver structure server , a callback table of operations ops , an address to announce the file service on and the permissions perm on the root directory. 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 Ninep 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. By default, files are owned by current user: ninepsetowner can be called before ninepinit to make user the default owner of files. The function ninepnamespace gives a default namespace path to build an address.

ninepend(server)

End all file service. Return value as above.

ninepwait(server)

Waits for communication from a client. If a 9P request is received server->curc is set to the client doing the request and server->fcall to the corresponding Fcall. Return value as above.

nineplisten(serverfd)

Waits for communication from an additional file descriptor fd.

ninepready(serverfd)

Returns 1 if the file descriptor fd is ready for reading, 0 otherwise.

ninepdefault(server)

Processes the client message after a successful call to ninepwait. The fields of server->fcall are set for a reply message. This may result in calls to the functions in the table provided to ninepinit .

nineperror(servererr)

Sets server->fcall.type to Rerror and server->fcall.ename to err.

ninepreply(server)

Reply to client server->curc with the contents of server->fcall.

ninepreplylater(server)

Returns a Pending structure corresponding to the current request, which will not be replied until ninepcompleted is called. The Pending structure contains fields to the corresponding Client and Fcall.

ninepcompleted(pend)

Reply to a pend pending request postponed with a call to ninepreplylater.

The next set of functions allow the creation of a file system structure based upon the Ninepfile structure. This contains a Dir structure d describing the properties of the file (defined in lib9.h) and pointers to other files in the file tree: parent , bind , 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 inherited from the parent by default, but not used by the Ninep 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:
ninepaddfile(server
ppathpathnamemodeowner)

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 .

ninepadddir(serverppathpathnamemodeowner)

Add a new directory with the given path path , name name , mode mode and owner owner to the directory identified by the path ppath . Returns nil in the same circumstances as ninepaddfile .

ninepbind(serverppathpath)

Bind the contents of directory with path path in the directory with path ppath. If one of the files is not a directory -1 is returned, otherwise 0 is returned for success.

nineprmfile(serverpath)

Remove the file or directory with path path from the file server tree. If the file is a directory, it’s contents will be recursively removed. If the file does not exist, -1 is returned, otherwise 0 is returned for success.

ninepfindfile(serverpath)

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 Ninep library will check read/write/execute permissions, check for invalid uses of files and check that path numbers exist in the file system (see ninepinit 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 implementer of the file server can take corresponding action when ninepdefault is called. All of these functions may return an error message which will be communicated back to the client. Otherwise they should return nil to indicate the success of the operation. Any of these functions may be nil in which case the library performs a default operation which will be described below. These routines 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
)

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 Ninep server library.

freeclient(c)

Called whenever a client disconnects from the server.

attach(qidunameaname)

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, with qid qid , if the server provides a choice. The default action is to allow the attach to the root of the file system.

walk(qidname)

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(qidmode)

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 different from that given (a file server may understand the opening of a file called "new" say to signify the creation of a directory whose Qid is returned instead) place it’s Qid in qid . The default action is to nominally allow the open.

create(qidnamepermmode)

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(qidbufnoffset)

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 permission denied on ordinary files.

write(qidbufnoffset)

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.

close(qidmode)

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(qidd)

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(qidd)

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.

Alternatively to calling ninepdefault and use Ninepops functions, a program using Ninepserver may opt for processing server->fcall by its own means.

A small number of utility functions are provided:
ninepperm(file
uidmode)

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.

ninepeadstr(offbufnstr)

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.

ninepqid(pathisdir)

Returns a typical Qid structure with the given path number path and whether the Qid is for a directory isdir .

ninepmalloc(n)

Allocate n bytes of memory and return it.

ninepfree(p)

Free the memory pointed to by p .

ninepdebug()

Print out some of the actions of the server.

EXAMPLE

wsys(4)

BUGS

Currently only the Linux version of the library is supported, Window or other Unix versions could (and surely will) need adjustments.
Authentication is not supported.