doc/fcatomic.fncs

   1 /*
   2  * $Id$
   3  *
   4  * Copyright © 2003 Keith Packard
   5  *
   6  * Permission to use, copy, modify, distribute, and sell this software and its
   7  * documentation for any purpose is hereby granted without fee, provided that
   8  * the above copyright notice appear in all copies and that both that
   9  * copyright notice and this permission notice appear in supporting
  10  * documentation, and that the name of Keith Packard not be used in
  11  * advertising or publicity pertaining to distribution of the software without
  12  * specific, written prior permission.  Keith Packard makes no
  13  * representations about the suitability of this software for any purpose.  It
  14  * is provided "as is" without express or implied warranty.
  15  *
  16  * KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  17  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  18  * EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  19  * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  20  * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  21  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  22  * PERFORMANCE OF THIS SOFTWARE.
  23  */
  24
  25 @RET@           FcAtomic *
  26 @FUNC@          FcAtomicCreate
  27 @TYPE1@         const FcChar8   *               @ARG1@          file
  28 @PURPOSE@       create an FcAtomic object
  29 @DESC@
  30 Creates a data structure containing data needed to control access to <parameter>file</parameter>.
  31 Writing is done to a separate file.  Once that file is complete, the original
  32 configuration file is atomically replaced so that reading process always see
  33 a consistent and complete file without the need to lock for reading.
  34 @@
  35
  36 @RET@           FcBool
  37 @FUNC@          FcAtomicLock
  38 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  39 @PURPOSE@       lock a file
  40 @DESC@
  41 Attempts to lock the file referenced by <parameter>atomic</parameter>.
  42 Returns FcFalse if the file is already locked, else returns FcTrue and
  43 leaves the file locked.
  44 @@
  45
  46 @RET@           FcChar8 *
  47 @FUNC@          FcAtomicNewFile
  48 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  49 @PURPOSE@       return new temporary file name
  50 @DESC@
  51 Returns the filename for writing a new version of the file referenced
  52 by <parameter>atomic</parameter>.
  53 @@
  54
  55 @RET@           FcChar8 *
  56 @FUNC@          FcAtomicOrigFile
  57 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  58 @PURPOSE@       return original file name
  59 @DESC@
  60 Returns the file refernced by <parameter>atomic</parameter>.
  61 @@
  62
  63 @RET@           FcBool
  64 @FUNC@          FcAtomicReplaceOrig
  65 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  66 @PURPOSE@       replace original with new
  67 @DESC@
  68 Replaces the original file referenced by <parameter>atomic</parameter> with the new file.
  69 @@
  70
  71 @RET@           void
  72 @FUNC@          FcAtomicDeleteNew
  73 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  74 @PURPOSE@       delete new file
  75 @DESC@
  76 Deletes the new file.  Used in error recovery to back out changes.
  77 @@
  78
  79 @RET@           void
  80 @FUNC@          FcAtomicUnlock
  81 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  82 @PURPOSE@       unlock a file
  83 @DESC@
  84 Unlocks the file.
  85 @@
  86
  87 @RET@           void
  88 @FUNC@          FcAtomicDestroy
  89 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  90 @PURPOSE@       destroy an FcAtomic object
  91 @DESC@
  92 Destroys <parameter>atomic</parameter>.
  93 @@