
FILE *fsetlockfile (char *filename, double timeout, int type, int *state);
   
 set a lockfile on [path]/filename.  

 we allow three types of locks: 
 LCK_HARD - exclusive lock with persistent lock file
 LCK_XCLD - exclusive lock, no persistent lock file
 LCK_SOFT - shared lock

 all three types of locks set a filesystem lock (using NFS lockd) on
 the given file, using an exclusive lock for HARD and XCLD and a
 shared lock for SOFT locks.  

 a HARD lock also uses a lockfile to make the lock persistent in the
 event the calling program crashes: the lockfile must be actively
 removed and will not vanish even if the locking program dies

 SOFT and XCLD locks will vanish if the locking program dies.

 if a HARD or XCLD lock is set, HARD, XCLD & SOFT locks will block

 if a SOFT lock is set, HARD and XCLD locks will block, but not a SOFT
 lock

 the hard lockfile uses the file [path]/.filename.lck

 this function locks and opens the file, returning the file pointer to
 the now opened file.  the file is either opened for reading and
 writing (HARD, XCLD == r+) or just reading (SOFT).

 Error Conditions:

 on error, fsetlockfile returns NULL and clears the lock state of the
 file

 - invalid type 
 - SOFT and file does not exist
 - file not accessible (cannot be opened)
 - lockfile not accessible
 - cannot lock lockfile (held by another user)
 - lockfile says 'BUSY' (previous holder crashed)
 - cannot unlock lockfile (file system error)
 - error writing 'BUSY' to lockfile

