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