FLOCK DAEMON
                                 ~~~~~~~~~~~~
                       by Robocoder@TMI-2 (Anthon Pang)
                                   06-24-93

Description

    "flock" is a file locking daemon written for the TMI-2 mudlib
    running on MudOS.

    [It may be portable to other mudlibs...but that's an exercise
     for the reader.]


What is File Locking?

    File locking is a mechanism by which an object can lock a file
    for exclusive access.  In LPMud (and MudOS) this usually isn't
    a concern because execution is single threaded.  However, with
    the presence of the 'ed' editor and objects like 'uncompress'
    (which runs on call_outs) exclusive access can be useful in
    avoiding lost changes.

    Consider the following example without external file locking:

      TIME    Wizard A
       ||       ed /std/user.c
       ||       ; pages through code
       \/       ; to find a bug
                                          Wizard B
                                            cp ~/user.c /std/user.c
                                            ; copies over a new version
                                            ; after adding a new feature
                ; installs bug fix
                ; saves and exits editor

    At this point, the feature added by Wizard B has been lost.
    If Wizard B later copies his version of user.c again, Wizard A's
    bug fix will then be lost.  Hopefully, one can see how much
    more problematic this can become with a development mud and more
    wizards.

    Now, to be honest, TMI's 'ed' already prevented two (or more)
    wizards from editing the same file.  However, because file
    locking was internal to the 'ed' object, it couldn't block
    Wizard B (in the above example) from (instead of 'ed')
    overwriting /std/user by copying over a new version from
    his/her own directory.

    Like Unix, "flock" file locks are advisory.  That means, file
    locking is not implicit or automatic--it's up to the individual
    object to obtain a lock and respect the locks of others.

    [File locking is an idea the author borrowed from Unix.]


Logging

    Ah, yes.  "flock" supports the dreaded admin logging.  "flock"'s
    logging complements the ED_LOG.  Where "ed" logs all the files
    whether they're modified or not, "flock" logs only those files
    which have been modified (created, changed, or purged).

    [Logging is enabled in "/include/logs.h" by #define FILE_LOG.]

    Selective logging is enabled by defining NON_CRITICAL_PATHS
    in "/include/flock.h".  This specifies paths which can be ignored
    by the logger, in addition to the player's home directory.


The Code

    The core of "flock" lies in "/adm/daemons/flock.c".  An include
    file in "/include/flock.h" contains the #defines and function
    descriptions.

    [The documentation in those files will always be more up to date
     than this file.  Besides this document is already too long.]


Acknowledgements

    Buddha for his file locking code in /cmds/file/_ed.c.
    Mobydick for instilling the importance of evil admin logging on me.
    Pallando for reminding me to write this doc.
    Watcher who said go for it.