[fontconfig.git] / doc / fcatomic.fncs

/*
 * fontconfig/doc/fcatomic.fncs
 *
 * Copyright © 2003 Keith Packard
 *
 * Permission to use, copy, modify, distribute, and sell this software and its
 * documentation for any purpose is hereby granted without fee, provided that
 * the above copyright notice appear in all copies and that both that
 * copyright notice and this permission notice appear in supporting
 * documentation, and that the name of the author(s) not be used in
 * advertising or publicity pertaining to distribution of the software without
 * specific, written prior permission.  The authors make no
 * representations about the suitability of this software for any purpose.  It
 * is provided "as is" without express or implied warranty.
 *
 * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
 * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
 * PERFORMANCE OF THIS SOFTWARE.
 */

@RET@           FcAtomic *
@FUNC@          FcAtomicCreate
@TYPE1@         const FcChar8   *           	@ARG1@          file
@PURPOSE@	create an FcAtomic object
@DESC@
Creates a data structure containing data needed to control access to <parameter>file</parameter>.
Writing is done to a separate file.  Once that file is complete, the original
configuration file is atomically replaced so that reading process always see
a consistent and complete file without the need to lock for reading.
@@

@RET@           FcBool
@FUNC@          FcAtomicLock
@TYPE1@         FcAtomic *                      @ARG1@          atomic
@PURPOSE@	lock a file
@DESC@
Attempts to lock the file referenced by <parameter>atomic</parameter>.
Returns FcFalse if the file is already locked, else returns FcTrue and
leaves the file locked.
@@

@RET@           FcChar8 *
@FUNC@          FcAtomicNewFile
@TYPE1@         FcAtomic *                      @ARG1@          atomic
@PURPOSE@	return new temporary file name 
@DESC@
Returns the filename for writing a new version of the file referenced
by <parameter>atomic</parameter>.
@@

@RET@           FcChar8 *
@FUNC@          FcAtomicOrigFile
@TYPE1@         FcAtomic *                      @ARG1@          atomic
@PURPOSE@	return original file name
@DESC@
Returns the file referenced by <parameter>atomic</parameter>.
@@

@RET@           FcBool
@FUNC@          FcAtomicReplaceOrig
@TYPE1@         FcAtomic *                      @ARG1@          atomic
@PURPOSE@	replace original with new
@DESC@
Replaces the original file referenced by <parameter>atomic</parameter> with
the new file. Returns FcFalse if the file cannot be replaced due to
permission issues in the filesystem. Otherwise returns FcTrue.
@@

@RET@           void
@FUNC@          FcAtomicDeleteNew
@TYPE1@         FcAtomic *                      @ARG1@          atomic
@PURPOSE@	delete new file
@DESC@
Deletes the new file.  Used in error recovery to back out changes.
@@

@RET@           void
@FUNC@          FcAtomicUnlock
@TYPE1@         FcAtomic *                      @ARG1@          atomic
@PURPOSE@	unlock a file
@DESC@
Unlocks the file.
@@

@RET@           void
@FUNC@          FcAtomicDestroy
@TYPE1@         FcAtomic *                      @ARG1@          atomic
@PURPOSE@	destroy an FcAtomic object
@DESC@
Destroys <parameter>atomic</parameter>.
@@
Commit	Line	Data
39381776	1	/*
e690fbb2	2	* fontconfig/doc/fcatomic.fncs
39381776	3	*
46b51147	4	* Copyright © 2003 Keith Packard
39381776 KP	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
5aaf466d	10	* documentation, and that the name of the author(s) not be used in
39381776	11	* advertising or publicity pertaining to distribution of the software without
5aaf466d	12	* specific, written prior permission. The authors make no
39381776 KP	13	* representations about the suitability of this software for any purpose. It
	14	* is provided "as is" without express or implied warranty.
	15	*
3074a73b	16	* THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
39381776	17	* INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
3074a73b	18	* EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR
39381776 KP	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@
910db318 KP	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.
39381776 KP	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@
7baa20c7	60	Returns the file referenced by <parameter>atomic</parameter>.
39381776 KP	61	@@
	62
	63	@RET@ FcBool
	64	@FUNC@ FcAtomicReplaceOrig
	65	@TYPE1@ FcAtomic * @ARG1@ atomic
	66	@PURPOSE@ replace original with new
	67	@DESC@
fab44f3c KP	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.
39381776 KP	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	@@