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@
30Creates a data structure containing data needed to control access to <parameter>file</parameter>.
31Writing is done to a separate file.  Once that file is complete, the original
32configuration file is atomically replaced so that reading process always see
33a 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@
41Attempts to lock the file referenced by <parameter>atomic</parameter>.
42Returns FcFalse if the file is already locked, else returns FcTrue and
43leaves 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@
51Returns the filename for writing a new version of the file referenced
52by <parameter>atomic</parameter>.
53@@
54
55@RET@           FcChar8 *
56@FUNC@          FcAtomicOrigFile
57@TYPE1@         FcAtomic *                      @ARG1@          atomic
58@PURPOSE@       return original file name
59@DESC@
60Returns 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@
68Replaces the original file referenced by <parameter>atomic</parameter> with
69the new file. Returns FcFalse if the file cannot be replaced due to
70permission 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@
78Deletes 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@
86Unlocks the file.
87@@
88
89@RET@           void
90@FUNC@          FcAtomicDestroy
91@TYPE1@         FcAtomic *                      @ARG1@          atomic
92@PURPOSE@       destroy an FcAtomic object
93@DESC@
94Destroys <parameter>atomic</parameter>.
95@@
96