doc/fcatomic.sgml

   1 <!--
   2    fontconfig/doc/func.sgml
   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     <refentry id="FcAtomicCreate">
  25         <refmeta>
  26             <refentrytitle>FcAtomicCreate</refentrytitle>
  27             <manvolnum>3</manvolnum>
  28             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
  29         </refmeta>
  30         <refnamediv>
  31             <refname>FcAtomicCreate</refname>
  32             <refpurpose>create an FcAtomic object</refpurpose>
  33         </refnamediv>
  34         <refsynopsisdiv>
  35         <funcsynopsis>
  36         <funcsynopsisinfo>
  37 #include &lt;fontconfig/fontconfig.h&gt;
  38         </funcsynopsisinfo>
  39         <funcprototype>
  40             <funcdef>FcAtomic * <function>FcAtomicCreate</function></funcdef>
  41                 <paramdef>const FcChar8   *<parameter>file</parameter></paramdef>
  42         </funcprototype>
  43         </funcsynopsis>
  44         </refsynopsisdiv>
  45         <refsect1><title>Description</title>
  46             <para>
  47 Creates a data structure containing data needed to control access to <parameter>file</parameter>.
  48 Writing is done to a separate file.  Once that file is complete, the original
  49 configuration file is atomically replaced so that reading process always see
  50 a consistent and complete file without the need to lock for reading.
  51             </para>
  52         </refsect1>
  53     </refentry>
  54 <!--
  55    fontconfig/doc/func.sgml
  56
  57    Copyright © 2003 Keith Packard
  58
  59    Permission to use, copy, modify, distribute, and sell this software and its
  60    documentation for any purpose is hereby granted without fee, provided that
  61    the above copyright notice appear in all copies and that both that
  62    copyright notice and this permission notice appear in supporting
  63    documentation, and that the name of the author(s) not be used in
  64    advertising or publicity pertaining to distribution of the software without
  65    specific, written prior permission.  The authors make no
  66    representations about the suitability of this software for any purpose.  It
  67    is provided "as is" without express or implied warranty.
  68
  69    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  70    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  71    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  72    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
  73    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  74    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  75    PERFORMANCE OF THIS SOFTWARE.
  76  -->
  77     <refentry id="FcAtomicLock">
  78         <refmeta>
  79             <refentrytitle>FcAtomicLock</refentrytitle>
  80             <manvolnum>3</manvolnum>
  81             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
  82         </refmeta>
  83         <refnamediv>
  84             <refname>FcAtomicLock</refname>
  85             <refpurpose>lock a file</refpurpose>
  86         </refnamediv>
  87         <refsynopsisdiv>
  88         <funcsynopsis>
  89         <funcsynopsisinfo>
  90 #include &lt;fontconfig/fontconfig.h&gt;
  91         </funcsynopsisinfo>
  92         <funcprototype>
  93             <funcdef>FcBool <function>FcAtomicLock</function></funcdef>
  94                 <paramdef>FcAtomic *<parameter>atomic</parameter></paramdef>
  95         </funcprototype>
  96         </funcsynopsis>
  97         </refsynopsisdiv>
  98         <refsect1><title>Description</title>
  99             <para>
 100 Attempts to lock the file referenced by <parameter>atomic</parameter>.
 101 Returns FcFalse if the file is already locked, else returns FcTrue and
 102 leaves the file locked.
 103             </para>
 104         </refsect1>
 105     </refentry>
 106 <!--
 107    fontconfig/doc/func.sgml
 108
 109    Copyright © 2003 Keith Packard
 110
 111    Permission to use, copy, modify, distribute, and sell this software and its
 112    documentation for any purpose is hereby granted without fee, provided that
 113    the above copyright notice appear in all copies and that both that
 114    copyright notice and this permission notice appear in supporting
 115    documentation, and that the name of the author(s) not be used in
 116    advertising or publicity pertaining to distribution of the software without
 117    specific, written prior permission.  The authors make no
 118    representations about the suitability of this software for any purpose.  It
 119    is provided "as is" without express or implied warranty.
 120
 121    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 122    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 123    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 124    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 125    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 126    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 127    PERFORMANCE OF THIS SOFTWARE.
 128  -->
 129     <refentry id="FcAtomicNewFile">
 130         <refmeta>
 131             <refentrytitle>FcAtomicNewFile</refentrytitle>
 132             <manvolnum>3</manvolnum>
 133             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 134         </refmeta>
 135         <refnamediv>
 136             <refname>FcAtomicNewFile</refname>
 137             <refpurpose>return new temporary file name</refpurpose>
 138         </refnamediv>
 139         <refsynopsisdiv>
 140         <funcsynopsis>
 141         <funcsynopsisinfo>
 142 #include &lt;fontconfig/fontconfig.h&gt;
 143         </funcsynopsisinfo>
 144         <funcprototype>
 145             <funcdef>FcChar8 * <function>FcAtomicNewFile</function></funcdef>
 146                 <paramdef>FcAtomic *<parameter>atomic</parameter></paramdef>
 147         </funcprototype>
 148         </funcsynopsis>
 149         </refsynopsisdiv>
 150         <refsect1><title>Description</title>
 151             <para>
 152 Returns the filename for writing a new version of the file referenced
 153 by <parameter>atomic</parameter>.
 154             </para>
 155         </refsect1>
 156     </refentry>
 157 <!--
 158    fontconfig/doc/func.sgml
 159
 160    Copyright © 2003 Keith Packard
 161
 162    Permission to use, copy, modify, distribute, and sell this software and its
 163    documentation for any purpose is hereby granted without fee, provided that
 164    the above copyright notice appear in all copies and that both that
 165    copyright notice and this permission notice appear in supporting
 166    documentation, and that the name of the author(s) not be used in
 167    advertising or publicity pertaining to distribution of the software without
 168    specific, written prior permission.  The authors make no
 169    representations about the suitability of this software for any purpose.  It
 170    is provided "as is" without express or implied warranty.
 171
 172    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 173    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 174    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 175    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 176    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 177    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 178    PERFORMANCE OF THIS SOFTWARE.
 179  -->
 180     <refentry id="FcAtomicOrigFile">
 181         <refmeta>
 182             <refentrytitle>FcAtomicOrigFile</refentrytitle>
 183             <manvolnum>3</manvolnum>
 184             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 185         </refmeta>
 186         <refnamediv>
 187             <refname>FcAtomicOrigFile</refname>
 188             <refpurpose>return original file name</refpurpose>
 189         </refnamediv>
 190         <refsynopsisdiv>
 191         <funcsynopsis>
 192         <funcsynopsisinfo>
 193 #include &lt;fontconfig/fontconfig.h&gt;
 194         </funcsynopsisinfo>
 195         <funcprototype>
 196             <funcdef>FcChar8 * <function>FcAtomicOrigFile</function></funcdef>
 197                 <paramdef>FcAtomic *<parameter>atomic</parameter></paramdef>
 198         </funcprototype>
 199         </funcsynopsis>
 200         </refsynopsisdiv>
 201         <refsect1><title>Description</title>
 202             <para>
 203 Returns the file referenced by <parameter>atomic</parameter>.
 204             </para>
 205         </refsect1>
 206     </refentry>
 207 <!--
 208    fontconfig/doc/func.sgml
 209
 210    Copyright © 2003 Keith Packard
 211
 212    Permission to use, copy, modify, distribute, and sell this software and its
 213    documentation for any purpose is hereby granted without fee, provided that
 214    the above copyright notice appear in all copies and that both that
 215    copyright notice and this permission notice appear in supporting
 216    documentation, and that the name of the author(s) not be used in
 217    advertising or publicity pertaining to distribution of the software without
 218    specific, written prior permission.  The authors make no
 219    representations about the suitability of this software for any purpose.  It
 220    is provided "as is" without express or implied warranty.
 221
 222    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 223    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 224    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 225    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 226    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 227    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 228    PERFORMANCE OF THIS SOFTWARE.
 229  -->
 230     <refentry id="FcAtomicReplaceOrig">
 231         <refmeta>
 232             <refentrytitle>FcAtomicReplaceOrig</refentrytitle>
 233             <manvolnum>3</manvolnum>
 234             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 235         </refmeta>
 236         <refnamediv>
 237             <refname>FcAtomicReplaceOrig</refname>
 238             <refpurpose>replace original with new</refpurpose>
 239         </refnamediv>
 240         <refsynopsisdiv>
 241         <funcsynopsis>
 242         <funcsynopsisinfo>
 243 #include &lt;fontconfig/fontconfig.h&gt;
 244         </funcsynopsisinfo>
 245         <funcprototype>
 246             <funcdef>FcBool <function>FcAtomicReplaceOrig</function></funcdef>
 247                 <paramdef>FcAtomic *<parameter>atomic</parameter></paramdef>
 248         </funcprototype>
 249         </funcsynopsis>
 250         </refsynopsisdiv>
 251         <refsect1><title>Description</title>
 252             <para>
 253 Replaces the original file referenced by <parameter>atomic</parameter> with
 254 the new file. Returns FcFalse if the file cannot be replaced due to
 255 permission issues in the filesystem. Otherwise returns FcTrue.
 256             </para>
 257         </refsect1>
 258     </refentry>
 259 <!--
 260    fontconfig/doc/func.sgml
 261
 262    Copyright © 2003 Keith Packard
 263
 264    Permission to use, copy, modify, distribute, and sell this software and its
 265    documentation for any purpose is hereby granted without fee, provided that
 266    the above copyright notice appear in all copies and that both that
 267    copyright notice and this permission notice appear in supporting
 268    documentation, and that the name of the author(s) not be used in
 269    advertising or publicity pertaining to distribution of the software without
 270    specific, written prior permission.  The authors make no
 271    representations about the suitability of this software for any purpose.  It
 272    is provided "as is" without express or implied warranty.
 273
 274    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 275    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 276    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 277    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 278    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 279    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 280    PERFORMANCE OF THIS SOFTWARE.
 281  -->
 282     <refentry id="FcAtomicDeleteNew">
 283         <refmeta>
 284             <refentrytitle>FcAtomicDeleteNew</refentrytitle>
 285             <manvolnum>3</manvolnum>
 286             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 287         </refmeta>
 288         <refnamediv>
 289             <refname>FcAtomicDeleteNew</refname>
 290             <refpurpose>delete new file</refpurpose>
 291         </refnamediv>
 292         <refsynopsisdiv>
 293         <funcsynopsis>
 294         <funcsynopsisinfo>
 295 #include &lt;fontconfig/fontconfig.h&gt;
 296         </funcsynopsisinfo>
 297         <funcprototype>
 298             <funcdef>void <function>FcAtomicDeleteNew</function></funcdef>
 299                 <paramdef>FcAtomic *<parameter>atomic</parameter></paramdef>
 300         </funcprototype>
 301         </funcsynopsis>
 302         </refsynopsisdiv>
 303         <refsect1><title>Description</title>
 304             <para>
 305 Deletes the new file.  Used in error recovery to back out changes.
 306             </para>
 307         </refsect1>
 308     </refentry>
 309 <!--
 310    fontconfig/doc/func.sgml
 311
 312    Copyright © 2003 Keith Packard
 313
 314    Permission to use, copy, modify, distribute, and sell this software and its
 315    documentation for any purpose is hereby granted without fee, provided that
 316    the above copyright notice appear in all copies and that both that
 317    copyright notice and this permission notice appear in supporting
 318    documentation, and that the name of the author(s) not be used in
 319    advertising or publicity pertaining to distribution of the software without
 320    specific, written prior permission.  The authors make no
 321    representations about the suitability of this software for any purpose.  It
 322    is provided "as is" without express or implied warranty.
 323
 324    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 325    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 326    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 327    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 328    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 329    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 330    PERFORMANCE OF THIS SOFTWARE.
 331  -->
 332     <refentry id="FcAtomicUnlock">
 333         <refmeta>
 334             <refentrytitle>FcAtomicUnlock</refentrytitle>
 335             <manvolnum>3</manvolnum>
 336             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 337         </refmeta>
 338         <refnamediv>
 339             <refname>FcAtomicUnlock</refname>
 340             <refpurpose>unlock a file</refpurpose>
 341         </refnamediv>
 342         <refsynopsisdiv>
 343         <funcsynopsis>
 344         <funcsynopsisinfo>
 345 #include &lt;fontconfig/fontconfig.h&gt;
 346         </funcsynopsisinfo>
 347         <funcprototype>
 348             <funcdef>void <function>FcAtomicUnlock</function></funcdef>
 349                 <paramdef>FcAtomic *<parameter>atomic</parameter></paramdef>
 350         </funcprototype>
 351         </funcsynopsis>
 352         </refsynopsisdiv>
 353         <refsect1><title>Description</title>
 354             <para>
 355 Unlocks the file.
 356             </para>
 357         </refsect1>
 358     </refentry>
 359 <!--
 360    fontconfig/doc/func.sgml
 361
 362    Copyright © 2003 Keith Packard
 363
 364    Permission to use, copy, modify, distribute, and sell this software and its
 365    documentation for any purpose is hereby granted without fee, provided that
 366    the above copyright notice appear in all copies and that both that
 367    copyright notice and this permission notice appear in supporting
 368    documentation, and that the name of the author(s) not be used in
 369    advertising or publicity pertaining to distribution of the software without
 370    specific, written prior permission.  The authors make no
 371    representations about the suitability of this software for any purpose.  It
 372    is provided "as is" without express or implied warranty.
 373
 374    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 375    INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 376    EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 377    CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 378    DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 379    TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 380    PERFORMANCE OF THIS SOFTWARE.
 381  -->
 382     <refentry id="FcAtomicDestroy">
 383         <refmeta>
 384             <refentrytitle>FcAtomicDestroy</refentrytitle>
 385             <manvolnum>3</manvolnum>
 386             <refmiscinfo class="software">Fontconfig &version;</refmiscinfo>
 387         </refmeta>
 388         <refnamediv>
 389             <refname>FcAtomicDestroy</refname>
 390             <refpurpose>destroy an FcAtomic object</refpurpose>
 391         </refnamediv>
 392         <refsynopsisdiv>
 393         <funcsynopsis>
 394         <funcsynopsisinfo>
 395 #include &lt;fontconfig/fontconfig.h&gt;
 396         </funcsynopsisinfo>
 397         <funcprototype>
 398             <funcdef>void <function>FcAtomicDestroy</function></funcdef>
 399                 <paramdef>FcAtomic *<parameter>atomic</parameter></paramdef>
 400         </funcprototype>
 401         </funcsynopsis>
 402         </refsynopsisdiv>
 403         <refsect1><title>Description</title>
 404             <para>
 405 Destroys <parameter>atomic</parameter>.
 406             </para>
 407         </refsect1>
 408     </refentry>