FILE: HFSDOC.TXT

*** VERY ROUGH DRAFT ****
 
              HUB File System, Part of HUB MUD

 Copyright 1996-1997 by Henry McDaniel III.  All rights reserved.
 See NOTICE for further details.

HFS is a security blanket that stands between calls to read/write to the
external filesystem and the internal objects of HUB.  It makes sure that
files outside of the specified library directory are not messed with as
well as performing some other sanity and anti-hacker checks.

ALL file open/stat calls involving potentially untrusted invokers should
be done via hfs_open (and related functions as described below.)  Calls,
where the invoker is wholly trusted are done via the usual system calls
(though some basic unescaping is still performed before writing.)


void *hfs_open( char *FNAME, int MODE, int FTYPE, int get_stat )

FNAME is a filename

MODE is access flag(s), same as for UNIX open()

FTYPE is one of:

  HFS_DIR
  HFS_FILE

hfs_open will return pointers to DIR or regular (int) handles, if
the file path or real file are legal, readable and secure.  Otherwise
error message(s) are placed into hfs_error_buf and hfs_error is set to
the HFS error value from hfs.h.

If FTYPE is DIR(ECTORY) then O_CREAT access means make directory, and
O_TRUNC means remove directory.  A pointer is still returned in the
case of O_CREAT (if successful.)  NULL and hfs_error==0 should be
returned if remove directory is successful.

When used to open for extended access, write(), read(), lseek() and
close() may be used on a file handle. Readdir(), closedir() and rewindir()
on a DIR(ECTORY).

After a call to hfs_open() you must close (or closedir) the handle
appropriately -- except in the case of removing a directory.


The following functions are provided to simplify some common calls:

int hfs_mkdir( fname )    -- create directory
int hfs_rmdir( fname )    -- remove directory
long hfs_size( fname )    -- returns file size
int hfs_exists( fname )   -- does file exist?

Error/fail for above funcs, return <0

struct variable *hfs_stat( fname )    -- returns a variable list containing stat data


END OF HFSDOC.TXT