doc/fcatomic.fncs

   1 /*
   2  * fontconfig/doc/fcatomic.fncs
   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 the author(s) not be used in
  11  * advertising or publicity pertaining to distribution of the software without
  12  * specific, written prior permission.  The authors make 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  * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  17  * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  18  * EVENT SHALL THE AUTHOR(S) 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 referenced 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
  69 the new file. Returns FcFalse if the file cannot be replaced due to
  70 permission issues in the filesystem. Otherwise returns FcTrue.
  71 @@
  72
  73 @RET@           void
  74 @FUNC@          FcAtomicDeleteNew
  75 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  76 @PURPOSE@       delete new file
  77 @DESC@
  78 Deletes the new file.  Used in error recovery to back out changes.
  79 @@
  80
  81 @RET@           void
  82 @FUNC@          FcAtomicUnlock
  83 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  84 @PURPOSE@       unlock a file
  85 @DESC@
  86 Unlocks the file.
  87 @@
  88
  89 @RET@           void
  90 @FUNC@          FcAtomicDestroy
  91 @TYPE1@         FcAtomic *                      @ARG1@          atomic
  92 @PURPOSE@       destroy an FcAtomic object
  93 @DESC@
  94 Destroys <parameter>atomic</parameter>.
  95 @@