aboutsummaryrefslogtreecommitdiff
path: root/libX11/specs/libX11/CH15.xml
diff options
context:
space:
mode:
Diffstat (limited to 'libX11/specs/libX11/CH15.xml')
-rw-r--r--libX11/specs/libX11/CH15.xml4982
1 files changed, 2491 insertions, 2491 deletions
diff --git a/libX11/specs/libX11/CH15.xml b/libX11/specs/libX11/CH15.xml
index 753dff177..7abc6173e 100644
--- a/libX11/specs/libX11/CH15.xml
+++ b/libX11/specs/libX11/CH15.xml
@@ -1,2491 +1,2491 @@
-<?xml version="1.0" encoding="UTF-8" ?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
- "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="resource_manager_functions">
-<title>Resource Manager Functions</title>
-<!-- .sp 2 -->
-<!-- .nr H1 15 -->
-<!-- .nr H2 0 -->
-<!-- .nr H3 0 -->
-<!-- .nr H4 0 -->
-<!-- .nr H5 0 -->
-<!-- .na -->
-<para>
-<!-- .LP -->
-<!-- .XS -->
-<!-- Chapter 15: Resource Manager Functions -->
-<!-- .XE -->
-A program often needs a variety of options in the X environment
-(for example, fonts, colors, icons, and cursors).
-Specifying all of these options on the command line is awkward
-because users may want to customize many aspects of the program
-and need a convenient way to establish these customizations as
-the default settings.
-The resource manager is provided for this purpose.
-Resource specifications are usually stored in human-readable files
-and in server properties.
-</para>
-<para>
-<!-- .LP -->
-The resource manager is a database manager with a twist.
-In most database systems,
-you perform a query using an imprecise specification,
-and you get back a set of records.
-The resource manager, however, allows you to specify a large
-set of values with an imprecise specification, to query the database
-with a precise specification, and to get back only a single value.
-This should be used by applications that need to know what the
-user prefers for colors, fonts, and other resources.
-It is this use as a database for dealing with X resources that
-inspired the name "Resource Manager,"
-although the resource manager can be and is used in other ways.
-</para>
-<para>
-<!-- .LP -->
-For example,
-a user of your application may want to specify
-that all windows should have a blue background
-but that all mail-reading windows should have a red background.
-With well-engineered and coordinated applications,
-a user can define this information using only two lines of specifications.
-</para>
-<para>
-<!-- .LP -->
-As an example of how the resource manager works,
-consider a mail-reading application called xmh.
-Assume that it is designed so that it uses a
-complex window hierarchy all the way down to individual command buttons,
-which may be actual small subwindows in some toolkits.
-These are often called objects or widgets.
-In such toolkit systems,
-each user interface object can be composed of other objects
-and can be assigned a name and a class.
-Fully qualified names or classes can have arbitrary numbers of component names,
-but a fully qualified name always has the same number of component names as a
-fully qualified class.
-This generally reflects the structure of the application as composed
-of these objects, starting with the application itself.
-</para>
-<para>
-<!-- .LP -->
-For example, the xmh mail program has a name "xmh" and is one
-of a class of "Mail" programs.
-By convention, the first character of class components is capitalized,
-and the first letter of name components is in lowercase.
-Each name and class finally has an attribute
-(for example, "foreground" or "font").
-If each window is properly assigned a name and class,
-it is easy for the user to specify attributes of any portion
-of the application.
-</para>
-<para>
-<!-- .LP -->
-At the top level,
-the application might consist of a paned window (that is, a window divided
-into several sections) named "toc".
-One pane of the paned window is a button box window named "buttons"
-and is filled with command buttons.
-One of these command buttons is used to incorporate
-new mail and has the name "incorporate".
-This window has a fully qualified name, "xmh.toc.buttons.incorporate",
-and a fully qualified class, "Xmh.Paned.Box.Command".
-Its fully qualified name is the name of its parent, "xmh.toc.buttons",
-followed by its name, "incorporate".
-Its class is the class of its parent, "Xmh.Paned.Box",
-followed by its particular class, "Command".
-The fully qualified name of a resource is
-the attribute's name appended to the object's fully qualified
-name, and the fully qualified class is its class appended to the object's
-class.
-</para>
-<para>
-<!-- .LP -->
-The incorporate button might need the following resources:
-Title string,
-Font,
-Foreground color for its inactive state,
-Background color for its inactive state,
-Foreground color for its active state, and
-Background color for its active state.
-Each resource is considered
-to be an attribute of the button and, as such, has a name and a class.
-For example, the foreground color for the button in
-its active state might be named "activeForeground",
-and its class might be "Foreground".
-</para>
-<para>
-<!-- .LP -->
-When an application looks up a resource (for example, a color),
-it passes the complete name and complete class of the resource
-to a look-up routine.
-The resource manager compares this complete specification
-against the incomplete specifications of entries in the resource
-database, finds the best match, and returns the corresponding
-value for that entry.
-</para>
-<para>
-<!-- .LP -->
-The definitions for the resource manager are contained in
-<filename class="headerfile">&lt;X11/Xresource.h&gt;</filename>.
-<indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>
-<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>
-<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>
-</para>
-<sect1 id="Resource_File_Syntax">
-<title>Resource File Syntax</title>
-<!-- .XS -->
-<!-- (SN Resource File Syntax -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-The syntax of a resource file is a sequence of resource lines
-terminated by newline characters or the end of the file.
-The syntax of an individual resource line is:
-</para>
-<para>
-<!-- .LP -->
-<!-- .\" Start marker code here -->
-<literallayout class="monospaced">
-<!-- .TA 1.5i 1.75i -->
-<!-- .ta 1.5i 1.75i -->
-ResourceLine = Comment | IncludeFile | ResourceSpec | &lt;empty line&gt;
-Comment = "!" {&lt;any character except null or newline&gt;}
-IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
-FileName = &lt;valid filename for operating system&gt;
-ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
-ResourceName = [Binding] {Component Binding} ComponentName
-Binding = "." | "*"
-WhiteSpace = {&lt;space&gt; | &lt;horizontal tab&gt;}
-Component = "?" | ComponentName
-ComponentName = NameChar {NameChar}
-NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
-Value = {&lt;any character except null or unescaped newline&gt;}
-</literallayout>
-<!-- .\" End marker code here -->
-</para>
-<para>
-<!-- .LP -->
-Elements separated by vertical bar (|) are alternatives.
-Curly braces ({......}) indicate zero or more repetitions
-of the enclosed elements.
-Square brackets ([......]) indicate that the enclosed element is optional.
-Quotes ("......") are used around literal characters.
-</para>
-<para>
-<!-- .LP -->
-IncludeFile lines are interpreted by replacing the line with the
-contents of the specified file.
-The word "include" must be in lowercase.
-The file name is interpreted relative to the directory of the file in
-which the line occurs (for example, if the file name contains no
-directory or contains a relative directory specification).
-</para>
-<para>
-<!-- .LP -->
-If a ResourceName contains a contiguous sequence of two or more Binding
-characters, the sequence will be replaced with a single ".." character
-if the sequence contains only ".." characters;
-otherwise, the sequence will be replaced with a single "*" character.
-</para>
-<para>
-<!-- .LP -->
-A resource database never contains more than one entry for a given
-ResourceName. If a resource file contains multiple lines with the
-same ResourceName, the last line in the file is used.
-</para>
-<para>
-<!-- .LP -->
-Any white space characters before or after the name or colon in a ResourceSpec
-are ignored.
-To allow a Value to begin with white space,
-the two-character sequence "\\<emphasis remap='I'>space</emphasis>" (backslash followed by space)
-is recognized and replaced by a space character,
-and the two-character sequence "\\<emphasis remap='I'>tab</emphasis>"
-(backslash followed by horizontal tab)
-is recognized and replaced by a horizontal tab character.
-To allow a Value to contain embedded newline characters,
-the two-character sequence "\\n" is recognized and replaced by a
-newline character.
-To allow a Value to be broken across multiple lines in a text file,
-the two-character sequence "\\<emphasis remap='I'>newline</emphasis>"
-(backslash followed by newline) is
-recognized and removed from the value.
-To allow a Value to contain arbitrary character codes,
-the four-character sequence "\\<emphasis remap='I'>nnn</emphasis>",
-where each <emphasis remap='I'>n</emphasis> is a digit character in the range of "0"-"7",
-is recognized and replaced with a single byte that contains
-the octal value specified by the sequence.
-Finally, the two-character sequence "\newline" is recognized
-and replaced with a single backslash.
-</para>
-<para>
-<!-- .LP -->
-As an example of these sequences,
-the following resource line contains a value consisting of four
-characters: a backslash, a null, a "z", and a newline:
-<literallayout class="monospaced">
-magic.values: \\000\
-z\n
-</literallayout>
-</para>
-</sect1>
-<sect1 id="Resource_Manager_Matching_Rules">
-<title>Resource Manager Matching Rules</title>
-<!-- .XS -->
-<!-- (SN Resource Manager Matching Rules -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-The algorithm for determining which resource database entry
-matches a given query is the heart of the resource manager.
-All queries must fully specify the name and class of the desired resource
-(use of the characters "*" and "?" is not permitted).
-The library supports up to 100 components in a full name or class.
-Resources are stored in the database with only partially specified
-names and classes, using pattern matching constructs.
-An asterisk (*) is a loose binding and is used to represent any number
-of intervening components, including none.
-A period (.) is a tight binding and is used to separate immediately
-adjacent components.
-A question mark (?) is used to match any single component name or class.
-A database entry cannot end in a loose binding;
-the final component (which cannot be the character "?") must be specified.
-The lookup algorithm searches the database for the entry that most
-closely matches (is most specific for) the full name and class being queried.
-When more than one database entry matches the full name and class,
-precedence rules are used to select just one.
-</para>
-<para>
-<!-- .LP -->
-The full name and class are scanned from left to right (from highest
-level in the hierarchy to lowest), one component at a time.
-At each level, the corresponding component and/or binding of each
-matching entry is determined, and these matching components and
-bindings are compared according to precedence rules.
-Each of the rules is applied at each level before moving to the next level,
-until a rule selects a single entry over all others.
-The rules, in order of precedence, are:
-</para>
-<itemizedlist>
- <listitem>
- <para>
-An entry that contains a matching component (whether name, class,
-or the character "?")
-takes precedence over entries that elide the level (that is, entries
-that match the level in a loose binding).
- </para>
- </listitem>
- <listitem>
- <para>
-An entry with a matching name takes precedence over both
-entries with a matching class and entries that match using the character "?".
-An entry with a matching class takes precedence over
-entries that match using the character "?".
- </para>
- </listitem>
- <listitem>
- <para>
-An entry preceded by a tight binding takes precedence over entries
-preceded by a loose binding.
- </para>
- </listitem>
-</itemizedlist>
-<para>
-<!-- .LP -->
-To illustrate these rules,
-consider the following resource database entries:
-<literallayout class="monospaced">
-<!-- .TA 2.5i 3.5i -->
-<!-- .ta 2.5i 3.5i -->
-xmh*Paned*activeForeground: red <emphasis remap='I'>(entry A)</emphasis>
-*incorporate.Foreground: blue <emphasis remap='I'>(entry B)</emphasis>
-xmh.toc*Command*activeForeground: green <emphasis remap='I'>(entry C)</emphasis>
-xmh.toc*?.Foreground: white <emphasis remap='I'>(entry D)</emphasis>
-xmh.toc*Command.activeForeground: black <emphasis remap='I'>(entry E)</emphasis>
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-Consider a query for the resource:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-<!-- .TA 3.5i -->
-<!-- .ta 3.5i -->
-xmh.toc.messagefunctions.incorporate.activeForeground <emphasis remap='I'>(name)</emphasis>
-Xmh.Paned.Box.Command.Foreground <emphasis remap='I'>(class)</emphasis>
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-At the first level (xmh, Xmh), rule 1 eliminates entry B.
-At the second level (toc, Paned), rule 2 eliminates entry A.
-At the third level (messagefunctions, Box), no entries are eliminated.
-At the fourth level (incorporate, Command), rule 2 eliminates entry D.
-At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.
-</para>
-</sect1>
-<sect1 id="Quarks">
-<title>Quarks</title>
-<!-- .XS -->
-<!-- (SN Quarks -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-Most uses of the resource manager involve defining names,
-classes, and representation types as string constants.
-However, always referring to strings in the resource manager can be slow,
-because it is so heavily used in some toolkits.
-To solve this problem,
-a shorthand for a string is used in place of the string
-in many of the resource manager functions.
-Simple comparisons can be performed rather than string comparisons.
-The shorthand name for a string is called a quark and is the
-type
-<type>XrmQuark</type>.
-On some occasions,
-you may want to allocate a quark that has no string equivalent.
-</para>
-<para>
-<!-- .LP -->
-A quark is to a string what an atom is to a string in the server,
-but its use is entirely local to your application.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To allocate a new quark, use
-<function>XrmUniqueQuark</function>.
-</para>
-<indexterm significance="preferred"><primary>XrmUniqueQuark</primary></indexterm>
-<!-- .sM -->
-<para>XrmQuark XrmUniqueQuark()</para>
-<!-- .FN -->
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmUniqueQuark</function>
-function allocates a quark that is guaranteed not to represent any string that
-is known to the resource manager.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-Each name, class, and representation type is typedef'd as an
-<type>XrmQuark</type>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
-<literallayout class="monospaced">
-typedef int XrmQuark, *XrmQuarkList;
-typedef XrmQuark XrmName;
-typedef XrmQuark XrmClass;
-typedef XrmQuark XrmRepresentation;
-#define NULLQUARK ((XrmQuark) 0)
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Lists are represented as null-terminated arrays of quarks.
-The size of the array must be large enough for the number of components used.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sM -->
-<literallayout class="monospaced">
-typedef XrmQuarkList XrmNameList;
-typedef XrmQuarkList XrmClassList;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To convert a string to a quark, use
-<function>XrmStringToQuark</function>
-or
-<function>XrmPermStringToQuark</function>.
-</para>
-<literallayout class="monospaced">
-#define XrmStringToName(string) XrmStringToQuark(string)
-#define XrmStringToClass(string) XrmStringToQuark(string)
-#define XrmStringToRepresentation(string) XrmStringToQuark(string)
-</literallayout>
-
-<indexterm significance="preferred"><primary>XrmStringToQuark</primary></indexterm>
-<indexterm significance="preferred"><primary>XrmPermStringToQuark</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XrmQuark <function>XrmStringToQuark</function></funcdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<!-- .ds Ql -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the string for which a quark(Ql is to be allocated.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-These functions can be used to convert from string to quark representation.
-If the string is not in the Host Portable Character Encoding,
-the conversion is implementation-dependent.
-The string argument to
-<function>XrmStringToQuark</function>
-need not be permanently allocated storage.
-<function>XrmPermStringToQuark</function>
-is just like
-<function>XrmStringToQuark</function>,
-except that Xlib is permitted to assume the string argument is permanently
-allocated,
-and, hence, that it can be used as the value to be returned by
-<function>XrmQuarkToString</function>.
-</para>
-<para>
-<!-- .LP -->
-For any given quark, if
-<function>XrmStringToQuark</function>
-returns a non-NULL value,
-all future calls will return the same value (identical address).
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To convert a quark to a string, use
-<function>XrmQuarkToString</function>.
-</para>
-
-<literallayout class="monospaced">
-#define XrmNameToString(name) XrmQuarkToString(name)
-#define XrmClassToString(class) XrmQuarkToString(name)
-#define XrmRepresentationToString(type) XrmQuarkToString(type)
-</literallayout>
-<indexterm significance="preferred"><primary>XrmQuarkToString</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char *<function>XrmQuarkToString</function></funcdef>
- <paramdef>XrmQuark<parameter> quark</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>quark</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the quark for which the equivalent string is desired.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-<!-- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -->
-<para>
-These functions can be used to convert from quark representation to string.
-The string pointed to by the return value must not be modified or freed.
-The returned string is byte-for-byte equal to the original
-string passed to one of the string-to-quark routines.
-If no string exists for that quark,
-<function>XrmQuarkToString</function>
-returns NULL.
-For any given quark, if
-<function>XrmQuarkToString</function>
-returns a non-NULL value,
-all future calls will return the same value (identical address).
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To convert a string with one or more components to a quark list, use
-<function>XrmStringToQuarkList</function>.
-</para>
-
-<literallayout class="monospaced">
-#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name))
-#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
-</literallayout>
-
-<indexterm significance="preferred"><primary>XrmStringToQuarkList</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmStringToQuarkList</function></funcdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
- <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<!-- .ds Ql \ list -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the string for which a quark(Ql is to be allocated.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>quarks_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the list of quarks.
-The caller must allocate sufficient space for the quarks list before calling
-<function>XrmStringToQuarkList</function>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmStringToQuarkList</function>
-function converts the null-terminated string (generally a fully qualified name)
-to a list of quarks.
-Note that the string must be in the valid ResourceName format
-(see section 15.1).
-If the string is not in the Host Portable Character Encoding,
-the conversion is implementation-dependent.
-</para>
-<para>
-<!-- .LP -->
-A binding list is a list of type
-<type>XrmBindingList</type>
-and indicates if components of name or class lists are bound tightly or loosely
-(that is, if wildcarding of intermediate components is specified).
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<constant>XrmBindTightly</constant>
-indicates that a period separates the components, and
-<constant>XrmBindLoosely</constant>
-indicates that an asterisk separates the components.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To convert a string with one or more components to a binding list
-and a quark list, use
-<function>XrmStringToBindingQuarkList</function>.
-<indexterm significance="preferred"><primary>XrmStringToBindingQuarkList</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef><function>XrmStringToBindingQuarkList</function></funcdef>
- <paramdef>char<parameter> *string</parameter></paramdef>
- <paramdef>XrmBindingList<parameter> bindings_return</parameter></paramdef>
- <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<!-- .ds Ql \ list -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>string</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the string for which a quark(Ql is to be allocated.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>bindings_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the binding list.
-The caller must allocate sufficient space for the binding list before calling
-<function>XrmStringToBindingQuarkList</function>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>quarks_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the list of quarks.
-The caller must allocate sufficient space for the quarks list before calling
-<function>XrmStringToBindingQuarkList</function>.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Component names in the list are separated by a period or
-an asterisk character.
-The string must be in the format of a valid ResourceName (see section 15.1).
-If the string does not start with a period or an asterisk,
-a tight binding is assumed.
-For example, the string ``*a.b*c'' becomes:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-<!-- .TA .75i 1.5i 2.25i -->
-<!-- .ta .75i 1.5i 2.25i -->
-quarks: a b c
-bindings: loose tight loose
-</literallayout>
-</para>
-</sect1>
-<sect1 id="Creating_and_Storing_Databases">
-<title>Creating and Storing Databases</title>
-<!-- .XS -->
-<!-- (SN Creating and Storing Databases -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XrmDatabase</primary></indexterm>
-A resource database is an opaque type,
-<type>XrmDatabase</type>.
-Each database value is stored in an
-<type>XrmValue</type>
-structure.
-This structure consists of a size, an address, and a representation type.
-The size is specified in bytes.
-The representation type is a way for you to store data tagged by some
-application-defined type (for example, the strings ``font'' or ``color'').
-It has nothing to do with the C data type or with its class.
-The
-<type>XrmValue</type>
-structure is defined as:
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XrmValue</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-typedef struct {
- unsigned int size;
- XPointer addr;
-} XrmValue, *XrmValuePtr;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To initialize the resource manager, use
-<function>XrmInitialize</function>.
-<indexterm significance="preferred"><primary>XrmInitialize</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmInitialize</function></funcdef>
- <paramdef>void<parameter> XrmInitialize(\|)</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-To retrieve a database from disk, use
-<function>XrmGetFileDatabase</function>.
-<indexterm significance="preferred"><primary>XrmGetFileDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XrmDatabase <function>XrmGetFileDatabase</function></funcdef>
- <paramdef>char<parameter> *filename</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>filename</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database file name.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmGetFileDatabase</function>
-function opens the specified file,
-creates a new resource database, and loads it with the specifications
-read in from the specified file.
-The specified file should contain a sequence of entries in valid ResourceLine
-format (see section 15.1); the database that results from reading a file
-with incorrect syntax is implementation-dependent.
-The file is parsed in the current locale,
-and the database is created in the current locale.
-If it cannot open the specified file,
-<function>XrmGetFileDatabase</function>
-returns NULL.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To store a copy of a database to disk, use
-<function>XrmPutFileDatabase</function>.
-<indexterm significance="preferred"><primary>XrmPutFileDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmPutFileDatabase</function></funcdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
- <paramdef>char<parameter> *stored_db</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the database that is to be used.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>stored_db</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the file name for the stored database.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmPutFileDatabase</function>
-function stores a copy of the specified database in the specified file.
-Text is written to the file as a sequence of entries in valid
-ResourceLine format (see section 15.1).
-The file is written in the locale of the database.
-Entries containing resource names that are not in the Host Portable Character
-Encoding or containing values that are not in the encoding of the database
-locale, are written in an implementation-dependent manner.
-The order in which entries are written is implementation-dependent.
-Entries with representation types other than ``String'' are ignored.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain a pointer to the screen-independent resources of a display, use
-<function>XResourceManagerString</function>.
-<indexterm significance="preferred"><primary>XResourceManagerString</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char *<function>XResourceManagerString</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XResourceManagerString</function>
-function returns the RESOURCE_MANAGER property from the server's root
-window of screen zero, which was returned when the connection was opened using
-<function>XOpenDisplay</function>.
-The property is converted from type STRING to the current locale.
-The conversion is identical to that produced by
-<function>XmbTextPropertyToTextList</function>
-for a single element STRING property.
-The returned string is owned by Xlib and should not be freed by the client.
-The property value must be in a format that is acceptable to
-<function>XrmGetStringDatabase</function>.
-If no property exists, NULL is returned.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain a pointer to the screen-specific resources of a screen, use
-<function>XScreenResourceString</function>.
-<indexterm significance="preferred"><primary>XScreenResourceString</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char *<function>XScreenResourceString</function></funcdef>
- <paramdef>Screen<parameter> *screen</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>screen</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the screen.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XScreenResourceString</function>
-function returns the SCREEN_RESOURCES property from the root window of the
-specified screen.
-The property is converted from type STRING to the current locale.
-The conversion is identical to that produced by
-<function>XmbTextPropertyToTextList</function>
-for a single element STRING property.
-The property value must be in a format that is acceptable to
-<function>XrmGetStringDatabase</function>.
-If no property exists, NULL is returned.
-The caller is responsible for freeing the returned string by using
-<function>XFree</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To create a database from a string, use
-<function>XrmGetStringDatabase</function>.
-<indexterm significance="preferred"><primary>XrmGetStringDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XrmDatabase <function>XrmGetStringDatabase</function></funcdef>
- <paramdef>char<parameter> *data</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>data</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the database contents using a string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmGetStringDatabase</function>
-function creates a new database and stores the resources specified
-in the specified null-terminated string.
-<function>XrmGetStringDatabase</function>
-is similar to
-<function>XrmGetFileDatabase</function>
-except that it reads the information out of a string instead of out of a file.
-The string should contain a sequence of entries in valid ResourceLine
-format (see section 15.1) terminated by a null character;
-the database that results from using a string
-with incorrect syntax is implementation-dependent.
-The string is parsed in the current locale,
-and the database is created in the current locale.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain the locale name of a database, use
-<function>XrmLocaleOfDatabase</function>.
-<indexterm significance="preferred"><primary>XrmLocaleOfDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>char *<function>XrmLocaleOfDatabase</function></funcdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmLocaleOfDatabase</function>
-function returns the name of the locale bound to the specified
-database, as a null-terminated string.
-The returned locale name string is owned by Xlib and should not be
-modified or freed by the client.
-Xlib is not permitted to free the string until the database is destroyed.
-Until the string is freed,
-it will not be modified by Xlib.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To destroy a resource database and free its allocated memory, use
-<function>XrmDestroyDatabase</function>.
-<indexterm significance="preferred"><primary>XrmDestroyDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmDestroyDatabase</function></funcdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If database is NULL,
-<function>XrmDestroyDatabase</function>
-returns immediately.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To associate a resource database with a display, use
-<function>XrmSetDatabase</function>.
-<indexterm significance="preferred"><primary>XrmSetDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmSetDatabase</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmSetDatabase</function>
-function associates the specified resource database (or NULL)
-with the specified display.
-The database previously associated with the display (if any) is not destroyed.
-A client or toolkit may find this function convenient for retaining a database
-once it is constructed.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To get the resource database associated with a display, use
-<function>XrmGetDatabase</function>.
-<indexterm significance="preferred"><primary>XrmGetDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>XrmDatabase <function>XrmGetDatabase</function></funcdef>
- <paramdef>Display<parameter> *display</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>display</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the connection to the X server.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmGetDatabase</function>
-function returns the database associated with the specified display.
-It returns NULL if a database has not yet been set.
-</para>
-</sect1>
-<sect1 id="Merging_Resource_Databases">
-<title>Merging Resource Databases</title>
-<!-- .XS -->
-<!-- (SN Merging Resource Databases -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To merge the contents of a resource file into a database, use
-<function>XrmCombineFileDatabase</function>.
-<indexterm significance="preferred"><primary>XrmCombineFileDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Status <function>XrmCombineFileDatabase</function></funcdef>
- <paramdef>char<parameter> *filename</parameter></paramdef>
- <paramdef>XrmDatabase<parameter> *target_db</parameter></paramdef>
- <paramdef>Bool<parameter> override</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>filename</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database file name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>target_db</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database into which the source
-database is to be merged.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>override</emphasis>
- </term>
- <listitem>
- <para>
-Specifies whether source entries override target ones.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmCombineFileDatabase</function>
-function merges the contents of a resource file into a database.
-If the same specifier is used for an entry in both the file and
-the database,
-the entry in the file will replace the entry in the database
-if override is
-<symbol>True</symbol>;
-otherwise, the entry in the file is discarded.
-The file is parsed in the current locale.
-If the file cannot be read,
-a zero status is returned;
-otherwise, a nonzero status is returned.
-If target_db contains NULL,
-<function>XrmCombineFileDatabase</function>
-creates and returns a new database to it.
-Otherwise, the database pointed to by target_db is not destroyed by the merge.
-The database entries are merged without changing values or types,
-regardless of the locale of the database.
-The locale of the target database is not modified.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To merge the contents of one database into another database, use
-<function>XrmCombineDatabase</function>.
-<indexterm significance="preferred"><primary>XrmCombineDatabase</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmCombineDatabase</function></funcdef>
- <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
- <paramdef>Bool<parameter> override</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>source_db</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database that is to be merged into the target database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>target_db</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database into which the source
-database is to be merged.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>override</emphasis>
- </term>
- <listitem>
- <para>
-Specifies whether source entries override target ones.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmCombineDatabase</function>
-function merges the contents of one database into another.
-If the same specifier is used for an entry in both databases,
-the entry in the source_db will replace the entry in the target_db
-if override is
-<symbol>True</symbol>;
-otherwise, the entry in source_db is discarded.
-If target_db contains NULL,
-<function>XrmCombineDatabase</function>
-simply stores source_db in it.
-Otherwise, source_db is destroyed by the merge, but the database pointed
-to by target_db is not destroyed.
-The database entries are merged without changing values or types,
-regardless of the locales of the databases.
-The locale of the target database is not modified.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To merge the contents of one database into another database with override
-semantics, use
-<function>XrmMergeDatabases</function>.
-<indexterm significance="preferred"><primary>XrmMergeDatabases</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmMergeDatabases</function></funcdef>
- <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>source_db</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database that is to be merged into the target database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>target_db</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database into which the source
-database is to be merged.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Calling the
-<function>XrmMergeDatabases</function>
-function is equivalent to calling the
-<function>XrmCombineDatabase</function>
-function with an override argument of
-<symbol>True</symbol>.
-</para>
-</sect1>
-<sect1 id="Looking_Up_Resources">
-<title>Looking Up Resources</title>
-<!-- .XS -->
-<!-- (SN Looking Up Resources -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To retrieve a resource from a resource database, use
-<function>XrmGetResource</function>,
-<function>XrmQGetResource</function>,
-or
-<function>XrmQGetSearchResource</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-<indexterm significance="preferred"><primary>XrmGetResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>XrmGetResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
- <paramdef>char<parameter> *str_name</parameter></paramdef>
- <paramdef>char<parameter> *str_class</parameter></paramdef>
- <paramdef>char<parameter> **str_type_return</parameter></paramdef>
- <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the database that is to be used.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>str_name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the fully qualified name of the value being retrieved (as a string).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>str_class</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the fully qualified class of the value being retrieved (as a string).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>str_type_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the representation type of the destination (as a string).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value in the database.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-<indexterm significance="preferred"><primary>XrmQGetResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>XrmQGetResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
- <paramdef>XrmNameList<parameter> quark_name</parameter></paramdef>
- <paramdef>XrmClassList<parameter> quark_class</parameter></paramdef>
- <paramdef>XrmRepresentation<parameter> *quark_type_return</parameter></paramdef>
- <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the database that is to be used.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>quark_name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the fully qualified name of the value being retrieved (as a quark).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>quark_class</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the fully qualified class of the value being retrieved (as a quark).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>quark_type_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the representation type of the destination (as a quark).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value in the database.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmGetResource</function>
-and
-<function>XrmQGetResource</function>
-functions retrieve a resource from the specified database.
-Both take a fully qualified name/class pair, a destination
-resource representation, and the address of a value
-(size/address pair).
-The value and returned type point into database memory;
-therefore, you must not modify the data.
-</para>
-<para>
-<!-- .LP -->
-The database only frees or overwrites entries on
-<function>XrmPutResource</function>,
-<function>XrmQPutResource</function>,
-or
-<function>XrmMergeDatabases</function>.
-A client that is not storing new values into the database or
-is not merging the database should be safe using the address passed
-back at any time until it exits.
-If a resource was found, both
-<function>XrmGetResource</function>
-and
-<function>XrmQGetResource</function>
-return
-<symbol>True</symbol>;
-otherwise, they return
-<symbol>False</symbol>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-Most applications and toolkits do not make random probes
-into a resource database to fetch resources.
-The X toolkit access pattern for a resource database is quite stylized.
-A series of from 1 to 20 probes is made with only the
-last name/class differing in each probe.
-The
-<function>XrmGetResource</function>
-function is at worst a
-2<superscript><emphasis remap='I'>n</emphasis></superscript> algorithm,
-where <emphasis remap='I'>n</emphasis> is the length of the name/class list.
-This can be improved upon by the application programmer by prefetching a list
-of database levels that might match the first part of a name/class list.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To obtain a list of database levels, use
-<function>XrmQGetSearchList</function>.
-<indexterm significance="preferred"><primary>XrmQGetSearchList</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
- <paramdef>XrmNameList<parameter> names</parameter></paramdef>
- <paramdef>XrmClassList<parameter> classes</parameter></paramdef>
- <paramdef>XrmSearchList<parameter> list_return</parameter></paramdef>
- <paramdef>int<parameter> list_length</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the database that is to be used.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>names</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a list of resource names.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>classes</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a list of resource classes.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>list_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns a search list for further use.
-The caller must allocate sufficient space for the list before calling
-<function>XrmQGetSearchList</function>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>list_length</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of entries (not the byte size) allocated for list_return.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmQGetSearchList</function>
-function takes a list of names and classes
-and returns a list of database levels where a match might occur.
-The returned list is in best-to-worst order and
-uses the same algorithm as
-<function>XrmGetResource</function>
-for determining precedence.
-If list_return was large enough for the search list,
-<function>XrmQGetSearchList</function>
-returns
-<symbol>True</symbol>;
-otherwise, it returns
-<symbol>False</symbol>.
-</para>
-<para>
-<!-- .LP -->
-The size of the search list that the caller must allocate is
-dependent upon the number of levels and wildcards in the resource specifiers
-that are stored in the database.
-The worst case length is
-3<superscript><emphasis remap='I'>n</emphasis></superscript>,
-where <emphasis remap='I'>n</emphasis> is the number of name or class
-components in names or classes.
-</para>
-<para>
-<!-- .LP -->
-When using
-<function>XrmQGetSearchList</function>
-followed by multiple probes for resources with a common name and class prefix,
-only the common prefix should be specified in the name and class list to
-<function>XrmQGetSearchList</function>.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To search resource database levels for a given resource, use
-<function>XrmQGetSearchResource</function>.
-<indexterm significance="preferred"><primary>XrmQGetSearchResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
- <paramdef>XrmSearchList<parameter> list</parameter></paramdef>
- <paramdef>XrmName<parameter> name</parameter></paramdef>
- <paramdef>XrmClass<parameter> class</parameter></paramdef>
- <paramdef>XrmRepresentation<parameter> *type_return</parameter></paramdef>
- <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>list</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the search list returned by
-<function>XrmQGetSearchList</function>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>class</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource class.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>type_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns data representation type.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value_return</emphasis>
- </term>
- <listitem>
- <para>
-Returns the value in the database.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmQGetSearchResource</function>
-function searches the specified database levels for the resource
-that is fully identified by the specified name and class.
-The search stops with the first match.
-<function>XrmQGetSearchResource</function>
-returns
-<symbol>True</symbol>
-if the resource was found;
-otherwise, it returns
-<symbol>False</symbol>.
-</para>
-<para>
-<!-- .LP -->
-A call to
-<function>XrmQGetSearchList</function>
-with a name and class list containing all but the last component
-of a resource name followed by a call to
-<function>XrmQGetSearchResource</function>
-with the last component name and class returns the same database entry as
-<function>XrmGetResource</function>
-and
-<function>XrmQGetResource</function>
-with the fully qualified name and class.
-</para>
-</sect1>
-<sect1 id="Storing_into_a_Resource_Database">
-<title>Storing into a Resource Database</title>
-<!-- .XS -->
-<!-- (SN Storing into a Resource Database -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To store resources into the database, use
-<function>XrmPutResource</function>
-or
-<function>XrmQPutResource</function>.
-Both functions take a partial resource specification, a
-representation type, and a value.
-This value is copied into the specified database.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-<indexterm significance="preferred"><primary>XrmPutResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmPutResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
- <paramdef>char<parameter> *specifier</parameter></paramdef>
- <paramdef>char<parameter> *type</parameter></paramdef>
- <paramdef>XrmValue<parameter> *value</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>specifier</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a complete or partial specification of the resource.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>type</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the type of the resource.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the value of the resource, which is specified as a string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If database contains NULL,
-<function>XrmPutResource</function>
-creates a new database and returns a pointer to it.
-<function>XrmPutResource</function>
-is a convenience function that calls
-<function>XrmStringToBindingQuarkList</function>
-followed by:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
-</literallayout>
-If the specifier and type are not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-The value is stored in the database without modification.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-<indexterm significance="preferred"><primary>XrmQPutResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmQPutResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
- <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
- <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
- <paramdef>XrmRepresentation<parameter> type</parameter></paramdef>
- <paramdef>XrmValue<parameter> *value</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>bindings</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a list of bindings.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>quarks</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the complete or partial name or the class list of the resource.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>type</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the type of the resource.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the value of the resource, which is specified as a string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If database contains NULL,
-<function>XrmQPutResource</function>
-creates a new database and returns a pointer to it.
-If a resource entry with the identical bindings and quarks already
-exists in the database, the previous type and value are replaced by the new
-specified type and value.
-The value is stored in the database without modification.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add a resource that is specified as a string, use
-<function>XrmPutStringResource</function>.
-<indexterm significance="preferred"><primary>XrmPutStringResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmPutStringResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
- <paramdef>char<parameter> *specifier</parameter></paramdef>
- <paramdef>char<parameter> *value</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>specifier</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a complete or partial specification of the resource.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the value of the resource, which is specified as a string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If database contains NULL,
-<function>XrmPutStringResource</function>
-creates a new database and returns a pointer to it.
-<function>XrmPutStringResource</function>
-adds a resource with the specified value to the specified database.
-<function>XrmPutStringResource</function>
-is a convenience function that first calls
-<function>XrmStringToBindingQuarkList</function>
-on the specifier and then calls
-<function>XrmQPutResource</function>,
-using a ``String'' representation type.
-If the specifier is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-The value is stored in the database without modification.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add a string resource using quarks as a specification, use
-<function>XrmQPutStringResource</function>.
-<indexterm significance="preferred"><primary>XrmQPutStringResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmQPutStringResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
- <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
- <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
- <paramdef>char<parameter> *value</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>bindings</emphasis>
- </term>
- <listitem>
- <para>
-Specifies a list of bindings.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>quarks</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the complete or partial name or the class list of the resource.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>value</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the value of the resource, which is specified as a string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If database contains NULL,
-<function>XrmQPutStringResource</function>
-creates a new database and returns a pointer to it.
-<function>XrmQPutStringResource</function>
-is a convenience routine that constructs an
-<type>XrmValue</type>
-for the value string (by calling
-<function>strlen</function>
-to compute the size) and
-then calls
-<function>XrmQPutResource</function>,
-using a ``String'' representation type.
-The value is stored in the database without modification.
-</para>
-<para>
-<!-- .LP -->
-<!-- .sp -->
-To add a single resource entry that is specified as a string that contains
-both a name and a value, use
-<function>XrmPutLineResource</function>.
-<indexterm significance="preferred"><primary>XrmPutLineResource</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmPutLineResource</function></funcdef>
- <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
- <paramdef>char<parameter> *line</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>line</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource name and value pair as a single string.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-If database contains NULL,
-<function>XrmPutLineResource</function>
-creates a new database and returns a pointer to it.
-<function>XrmPutLineResource</function>
-adds a single resource entry to the specified database.
-The line should be in valid ResourceLine format (see section 15.1)
-terminated by a newline or null character;
-the database that results from using a string
-with incorrect syntax is implementation-dependent.
-The string is parsed in the locale of the database.
-If the
-<replaceable>ResourceName</replaceable>
-is not in the Host Portable Character Encoding,
-the result is implementation-dependent.
-Note that comment lines are not stored.
-</para>
-</sect1>
-<sect1 id="Enumerating_Database_Entries">
-<title>Enumerating Database Entries</title>
-<!-- .XS -->
-<!-- (SN Enumerating Database Entries -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-To enumerate the entries of a database, use
-<function>XrmEnumerateDatabase</function>.
-<indexterm significance="preferred"><primary>XrmEnumerateDatabase</primary></indexterm>
-<!-- .sM -->
-</para>
-
-<literallayout class="monospaced">
-#define XrmEnumAllLevels 0
-#define XrmEnumOneLevel 0
-</literallayout>
-
-<funcsynopsis>
-<funcprototype>
- <funcdef>Bool <function>XrmEnumerateDatabase</function></funcdef>
- <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
- <paramdef>XrmNameList<parameter> name_prefix</parameter></paramdef>
- <paramdef>XrmClassList<parameter> class_prefix</parameter></paramdef>
- <paramdef>int<parameter> mode</parameter></paramdef>
- <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>
- <paramdef>XPointer<parameter> arg</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>name_prefix</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource name prefix.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>class_prefix</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource class prefix.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>mode</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of levels to enumerate.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>proc</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the procedure that is to be called for each matching entry.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>arg</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the user-supplied argument that will be passed to the procedure.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmEnumerateDatabase</function>
-function calls the specified procedure for each resource in the database
-that would match some completion of the given name/class resource prefix.
-The order in which resources are found is implementation-dependent.
-If mode is
-<symbol>XrmEnumOneLevel</symbol>,
-a resource must match the given name/class prefix with
-just a single name and class appended. If mode is
-<symbol>XrmEnumAllLevels</symbol>,
-the resource must match the given name/class prefix with one or more names and
-classes appended.
-If the procedure returns
-<symbol>True</symbol>,
-the enumeration terminates and the function returns
-<symbol>True</symbol>.
-If the procedure always returns
-<symbol>False</symbol>,
-all matching resources are enumerated and the function returns
-<symbol>False</symbol>.
-</para>
-<para>
-<!-- .LP -->
-The procedure is called with the following arguments:
-</para>
-<para>
-<!-- .LP -->
-<!-- .\" Start marker code here -->
-<literallayout class="monospaced">
-<!-- .TA .5i 3i -->
-<!-- .ta .5i 3i -->
-(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>database</emphasis>, <emphasis remap='I'>bindings</emphasis>, <emphasis remap='I'>quarks</emphasis>, <emphasis remap='I'>type</emphasis>, <emphasis remap='I'>value</emphasis>, <emphasis remap='I'>arg</emphasis>)
- XrmDatabase *<emphasis remap='I'>database</emphasis>;
- XrmBindingList <emphasis remap='I'>bindings</emphasis>;
- XrmQuarkList <emphasis remap='I'>quarks</emphasis>;
- XrmRepresentation *<emphasis remap='I'>type</emphasis>;
- XrmValue *<emphasis remap='I'>value</emphasis>;
- XPointer <emphasis remap='I'>arg</emphasis>;
-</literallayout>
-<!-- .\" End marker code here -->
-</para>
-<para>
-<!-- .LP -->
-The bindings and quarks lists are terminated by
-<symbol>NULLQUARK</symbol>.
-Note that pointers
-to the database and type are passed, but these values should not be modified.
-</para>
-<para>
-<!-- .LP -->
-The procedure must not modify the database.
-If Xlib has been initialized for threads, the procedure is called with
-the database locked and the result of a call by the procedure to any
-Xlib function using the same database is not defined.
-</para>
-</sect1>
-<sect1 id="Parsing_Command_Line_Options">
-<title>Parsing Command Line Options</title>
-<!-- .XS -->
-<!-- (SN Parsing Command Line Options -->
-<!-- .XE -->
-<para>
-<!-- .LP -->
-The
-<function>XrmParseCommand</function>
-function can be used to parse the command line arguments to a program
-and modify a resource database with selected entries from the command line.
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XrmOptionKind</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i 2.5i -->
-<!-- .ta .5i 2.5i -->
-typedef enum {
- XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value */
- XrmoptionIsArg, /* Value is the option string itself */
- XrmoptionStickyArg, /* Value is characters immediately following option */
- XrmoptionSepArg, /* Value is next argument in argv */
- XrmoptionResArg, /* Resource and value in next argument in argv */
- XrmoptionSkipArg, /* Ignore this option and the next argument in argv */
- XrmoptionSkipLine, /* Ignore this option and the rest of argv */
- XrmoptionSkipNArgs /* Ignore this option and the next
- \ \ \ XrmOptionDescRec.value arguments in argv */
-} XrmOptionKind;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-Note that
-<constant>XrmoptionSkipArg</constant>
-is equivalent to
-<constant>XrmoptionSkipNArgs</constant>
-with the
-<structname>XrmOptionDescRec</structname>.<structfield>value</structfield>
-field containing the value one.
-Note also that the value zero for
-<constant>XrmoptionSkipNArgs</constant>
-indicates that only the option itself is to be skipped.
-</para>
-<para>
-<!-- .LP -->
-<indexterm significance="preferred"><primary>XrmOptionDescRec</primary></indexterm>
-<!-- .sM -->
-<literallayout class="monospaced">
-<!-- .TA .5i 2.5i -->
-<!-- .ta .5i 2.5i -->
-typedef struct {
- char *option; /* Option specification string in argv */
- char *specifier; /* Binding and resource name (sans application name) */
- XrmOptionKind argKind; /* Which style of option it is */
- XPointer value; /* Value to provide if XrmoptionNoArg or
- \ \ \ XrmoptionSkipNArgs */
-} XrmOptionDescRec, *XrmOptionDescList;
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-<!-- .sp -->
-To load a resource database from a C command line, use
-<function>XrmParseCommand</function>.
-<indexterm significance="preferred"><primary>XrmParseCommand</primary></indexterm>
-<!-- .sM -->
-<funcsynopsis>
-<funcprototype>
- <funcdef>void <function>XrmParseCommand</function></funcdef>
- <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
- <paramdef>XrmOptionDescList<parameter> table</parameter></paramdef>
- <paramdef>int<parameter> table_count</parameter></paramdef>
- <paramdef>char<parameter> *name</parameter></paramdef>
- <paramdef>int<parameter> *argc_in_out</parameter></paramdef>
- <paramdef>char<parameter> **argv_in_out</parameter></paramdef>
-</funcprototype>
-</funcsynopsis>
-<!-- .FN -->
-<variablelist>
- <varlistentry>
- <term>
- <emphasis remap='I'>database</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the resource database.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>table</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the table of command line arguments to be parsed.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>table_count</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of entries in the table.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>name</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the application name.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>argc_in_out</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the number of arguments and returns the number of remaining arguments.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <emphasis remap='I'>argv_in_out</emphasis>
- </term>
- <listitem>
- <para>
-Specifies the command line arguments
-and returns the remaining arguments.
- </para>
- </listitem>
- </varlistentry>
-</variablelist>
-</para>
-<para>
-<!-- .LP -->
-<!-- .eM -->
-The
-<function>XrmParseCommand</function>
-function parses an (argc, argv) pair according to the specified option table,
-loads recognized options into the specified database with type ``String,''
-and modifies the (argc, argv) pair to remove all recognized options.
-If database contains NULL,
-<function>XrmParseCommand</function>
-creates a new database and returns a pointer to it.
-Otherwise, entries are added to the database specified.
-If a database is created, it is created in the current locale.
-</para>
-<para>
-<!-- .LP -->
-The specified table is used to parse the command line.
-Recognized options in the table are removed from argv,
-and entries are added to the specified resource database
-in the order they occur in argv.
-The table entries contain information on the option string,
-the option name, the style of option,
-and a value to provide if the option kind is
-<constant>XrmoptionNoArg</constant>.
-The option names are compared byte-for-byte to arguments in argv,
-independent of any locale.
-The resource values given in the table are stored in the resource database
-without modification.
-All resource database entries are created
-using a ``String'' representation type.
-The argc argument specifies the number of arguments in argv
-and is set on return to the remaining number of arguments that were not parsed.
-The name argument should be the name of your application
-for use in building the database entry.
-The name argument is prefixed to the resourceName in the option table
-before storing a database entry.
-The name argument is treated as a single component, even if it
-has embedded periods.
-No separating (binding) character is inserted,
-so the table must contain either a period (.) or an asterisk (*)
-as the first character in each resourceName entry.
-To specify a more completely qualified resource name,
-the resourceName entry can contain multiple components.
-If the name argument and the resourceNames are not in the
-Host Portable Character Encoding,
-the result is implementation-dependent.
-</para>
-<para>
-<!-- .LP -->
-The following provides a sample option table:
-</para>
-<para>
-<!-- .LP -->
-<literallayout class="monospaced">
-<!-- .TA 1.25i 3.25i 4.75i -->
-<!-- .ta 1.25i 3.25i 4.75i -->
-static XrmOptionDescRec opTable[] = {
-{"-background", "*background", XrmoptionSepArg, (XPointer) NULL},
-{"-bd", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
-{"-bg", "*background", XrmoptionSepArg, (XPointer) NULL},
-{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
-{"-bordercolor", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
-{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
-{"-display", ".display", XrmoptionSepArg, (XPointer) NULL},
-{"-fg", "*foreground", XrmoptionSepArg, (XPointer) NULL},
-{"-fn", "*font", XrmoptionSepArg, (XPointer) NULL},
-{"-font", "*font", XrmoptionSepArg, (XPointer) NULL},
-{"-foreground", "*foreground", XrmoptionSepArg, (XPointer) NULL},
-{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (XPointer) NULL},
-{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (XPointer) "on"},
-{"-name", ".name", XrmoptionSepArg, (XPointer) NULL},
-{"-reverse", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
-{"-rv", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
-{"-synchronous", "*synchronous", XrmoptionNoArg, (XPointer) "on"},
-{"-title", ".TopLevelShell.title", XrmoptionSepArg, (XPointer) NULL},
-{"-xrm", NULL, XrmoptionResArg, (XPointer) NULL},
-};
-</literallayout>
-</para>
-<para>
-<!-- .LP -->
-In this table, if the -background (or -bg) option is used to set
-background colors, the stored resource specifier matches all
-resources of attribute background.
-If the -borderwidth option is used,
-the stored resource specifier applies only to border width
-attributes of class TopLevelShell (that is, outer-most windows, including
-pop-up windows).
-If the -title option is used to set a window name,
-only the topmost application windows receive the resource.
-</para>
-<para>
-<!-- .LP -->
-When parsing the command line,
-any unique unambiguous abbreviation for an option name in the table is
-considered a match for the option.
-Note that uppercase and lowercase matter.
-<!-- .bp -->
-
-</para>
-</sect1>
-</chapter>
+<?xml version="1.0" encoding="UTF-8" ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<chapter id="resource_manager_functions">
+<title>Resource Manager Functions</title>
+<!-- .sp 2 -->
+<!-- .nr H1 15 -->
+<!-- .nr H2 0 -->
+<!-- .nr H3 0 -->
+<!-- .nr H4 0 -->
+<!-- .nr H5 0 -->
+<!-- .na -->
+<para>
+<!-- .LP -->
+<!-- .XS -->
+<!-- Chapter 15: Resource Manager Functions -->
+<!-- .XE -->
+A program often needs a variety of options in the X environment
+(for example, fonts, colors, icons, and cursors).
+Specifying all of these options on the command line is awkward
+because users may want to customize many aspects of the program
+and need a convenient way to establish these customizations as
+the default settings.
+The resource manager is provided for this purpose.
+Resource specifications are usually stored in human-readable files
+and in server properties.
+</para>
+<para>
+<!-- .LP -->
+The resource manager is a database manager with a twist.
+In most database systems,
+you perform a query using an imprecise specification,
+and you get back a set of records.
+The resource manager, however, allows you to specify a large
+set of values with an imprecise specification, to query the database
+with a precise specification, and to get back only a single value.
+This should be used by applications that need to know what the
+user prefers for colors, fonts, and other resources.
+It is this use as a database for dealing with X resources that
+inspired the name "Resource Manager,"
+although the resource manager can be and is used in other ways.
+</para>
+<para>
+<!-- .LP -->
+For example,
+a user of your application may want to specify
+that all windows should have a blue background
+but that all mail-reading windows should have a red background.
+With well-engineered and coordinated applications,
+a user can define this information using only two lines of specifications.
+</para>
+<para>
+<!-- .LP -->
+As an example of how the resource manager works,
+consider a mail-reading application called xmh.
+Assume that it is designed so that it uses a
+complex window hierarchy all the way down to individual command buttons,
+which may be actual small subwindows in some toolkits.
+These are often called objects or widgets.
+In such toolkit systems,
+each user interface object can be composed of other objects
+and can be assigned a name and a class.
+Fully qualified names or classes can have arbitrary numbers of component names,
+but a fully qualified name always has the same number of component names as a
+fully qualified class.
+This generally reflects the structure of the application as composed
+of these objects, starting with the application itself.
+</para>
+<para>
+<!-- .LP -->
+For example, the xmh mail program has a name "xmh" and is one
+of a class of "Mail" programs.
+By convention, the first character of class components is capitalized,
+and the first letter of name components is in lowercase.
+Each name and class finally has an attribute
+(for example, "foreground" or "font").
+If each window is properly assigned a name and class,
+it is easy for the user to specify attributes of any portion
+of the application.
+</para>
+<para>
+<!-- .LP -->
+At the top level,
+the application might consist of a paned window (that is, a window divided
+into several sections) named "toc".
+One pane of the paned window is a button box window named "buttons"
+and is filled with command buttons.
+One of these command buttons is used to incorporate
+new mail and has the name "incorporate".
+This window has a fully qualified name, "xmh.toc.buttons.incorporate",
+and a fully qualified class, "Xmh.Paned.Box.Command".
+Its fully qualified name is the name of its parent, "xmh.toc.buttons",
+followed by its name, "incorporate".
+Its class is the class of its parent, "Xmh.Paned.Box",
+followed by its particular class, "Command".
+The fully qualified name of a resource is
+the attribute's name appended to the object's fully qualified
+name, and the fully qualified class is its class appended to the object's
+class.
+</para>
+<para>
+<!-- .LP -->
+The incorporate button might need the following resources:
+Title string,
+Font,
+Foreground color for its inactive state,
+Background color for its inactive state,
+Foreground color for its active state, and
+Background color for its active state.
+Each resource is considered
+to be an attribute of the button and, as such, has a name and a class.
+For example, the foreground color for the button in
+its active state might be named "activeForeground",
+and its class might be "Foreground".
+</para>
+<para>
+<!-- .LP -->
+When an application looks up a resource (for example, a color),
+it passes the complete name and complete class of the resource
+to a look-up routine.
+The resource manager compares this complete specification
+against the incomplete specifications of entries in the resource
+database, finds the best match, and returns the corresponding
+value for that entry.
+</para>
+<para>
+<!-- .LP -->
+The definitions for the resource manager are contained in
+<filename class="headerfile">&lt;X11/Xresource.h&gt;</filename>.
+<indexterm type="file"><primary><filename class="headerfile">X11/Xresource.h</filename></primary></indexterm>
+<indexterm><primary>Files</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>
+<indexterm><primary>Headers</primary><secondary><filename class="headerfile">&lt;X11/Xresource.h&gt;</filename></secondary></indexterm>
+</para>
+<sect1 id="Resource_File_Syntax">
+<title>Resource File Syntax</title>
+<!-- .XS -->
+<!-- (SN Resource File Syntax -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The syntax of a resource file is a sequence of resource lines
+terminated by newline characters or the end of the file.
+The syntax of an individual resource line is:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA 1.5i 1.75i -->
+<!-- .ta 1.5i 1.75i -->
+ResourceLine = Comment | IncludeFile | ResourceSpec | &lt;empty line&gt;
+Comment = "!" {&lt;any character except null or newline&gt;}
+IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
+FileName = &lt;valid filename for operating system&gt;
+ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
+ResourceName = [Binding] {Component Binding} ComponentName
+Binding = "." | "*"
+WhiteSpace = {&lt;space&gt; | &lt;horizontal tab&gt;}
+Component = "?" | ComponentName
+ComponentName = NameChar {NameChar}
+NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
+Value = {&lt;any character except null or unescaped newline&gt;}
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+Elements separated by vertical bar (|) are alternatives.
+Curly braces ({......}) indicate zero or more repetitions
+of the enclosed elements.
+Square brackets ([......]) indicate that the enclosed element is optional.
+Quotes ("......") are used around literal characters.
+</para>
+<para>
+<!-- .LP -->
+IncludeFile lines are interpreted by replacing the line with the
+contents of the specified file.
+The word "include" must be in lowercase.
+The file name is interpreted relative to the directory of the file in
+which the line occurs (for example, if the file name contains no
+directory or contains a relative directory specification).
+</para>
+<para>
+<!-- .LP -->
+If a ResourceName contains a contiguous sequence of two or more Binding
+characters, the sequence will be replaced with a single ".." character
+if the sequence contains only ".." characters;
+otherwise, the sequence will be replaced with a single "*" character.
+</para>
+<para>
+<!-- .LP -->
+A resource database never contains more than one entry for a given
+ResourceName. If a resource file contains multiple lines with the
+same ResourceName, the last line in the file is used.
+</para>
+<para>
+<!-- .LP -->
+Any white space characters before or after the name or colon in a ResourceSpec
+are ignored.
+To allow a Value to begin with white space,
+the two-character sequence "\\<emphasis remap='I'>space</emphasis>" (backslash followed by space)
+is recognized and replaced by a space character,
+and the two-character sequence "\\<emphasis remap='I'>tab</emphasis>"
+(backslash followed by horizontal tab)
+is recognized and replaced by a horizontal tab character.
+To allow a Value to contain embedded newline characters,
+the two-character sequence "\\n" is recognized and replaced by a
+newline character.
+To allow a Value to be broken across multiple lines in a text file,
+the two-character sequence "\\<emphasis remap='I'>newline</emphasis>"
+(backslash followed by newline) is
+recognized and removed from the value.
+To allow a Value to contain arbitrary character codes,
+the four-character sequence "\\<emphasis remap='I'>nnn</emphasis>",
+where each <emphasis remap='I'>n</emphasis> is a digit character in the range of "0"-"7",
+is recognized and replaced with a single byte that contains
+the octal value specified by the sequence.
+Finally, the two-character sequence "\newline" is recognized
+and replaced with a single backslash.
+</para>
+<para>
+<!-- .LP -->
+As an example of these sequences,
+the following resource line contains a value consisting of four
+characters: a backslash, a null, a "z", and a newline:
+<literallayout class="monospaced">
+magic.values: \\000\
+z\n
+</literallayout>
+</para>
+</sect1>
+<sect1 id="Resource_Manager_Matching_Rules">
+<title>Resource Manager Matching Rules</title>
+<!-- .XS -->
+<!-- (SN Resource Manager Matching Rules -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The algorithm for determining which resource database entry
+matches a given query is the heart of the resource manager.
+All queries must fully specify the name and class of the desired resource
+(use of the characters "*" and "?" is not permitted).
+The library supports up to 100 components in a full name or class.
+Resources are stored in the database with only partially specified
+names and classes, using pattern matching constructs.
+An asterisk (*) is a loose binding and is used to represent any number
+of intervening components, including none.
+A period (.) is a tight binding and is used to separate immediately
+adjacent components.
+A question mark (?) is used to match any single component name or class.
+A database entry cannot end in a loose binding;
+the final component (which cannot be the character "?") must be specified.
+The lookup algorithm searches the database for the entry that most
+closely matches (is most specific for) the full name and class being queried.
+When more than one database entry matches the full name and class,
+precedence rules are used to select just one.
+</para>
+<para>
+<!-- .LP -->
+The full name and class are scanned from left to right (from highest
+level in the hierarchy to lowest), one component at a time.
+At each level, the corresponding component and/or binding of each
+matching entry is determined, and these matching components and
+bindings are compared according to precedence rules.
+Each of the rules is applied at each level before moving to the next level,
+until a rule selects a single entry over all others.
+The rules, in order of precedence, are:
+</para>
+<itemizedlist>
+ <listitem>
+ <para>
+An entry that contains a matching component (whether name, class,
+or the character "?")
+takes precedence over entries that elide the level (that is, entries
+that match the level in a loose binding).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An entry with a matching name takes precedence over both
+entries with a matching class and entries that match using the character "?".
+An entry with a matching class takes precedence over
+entries that match using the character "?".
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+An entry preceded by a tight binding takes precedence over entries
+preceded by a loose binding.
+ </para>
+ </listitem>
+</itemizedlist>
+<para>
+<!-- .LP -->
+To illustrate these rules,
+consider the following resource database entries:
+<literallayout class="monospaced">
+<!-- .TA 2.5i 3.5i -->
+<!-- .ta 2.5i 3.5i -->
+xmh*Paned*activeForeground: red <emphasis remap='I'>(entry A)</emphasis>
+*incorporate.Foreground: blue <emphasis remap='I'>(entry B)</emphasis>
+xmh.toc*Command*activeForeground: green <emphasis remap='I'>(entry C)</emphasis>
+xmh.toc*?.Foreground: white <emphasis remap='I'>(entry D)</emphasis>
+xmh.toc*Command.activeForeground: black <emphasis remap='I'>(entry E)</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+Consider a query for the resource:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 3.5i -->
+<!-- .ta 3.5i -->
+xmh.toc.messagefunctions.incorporate.activeForeground <emphasis remap='I'>(name)</emphasis>
+Xmh.Paned.Box.Command.Foreground <emphasis remap='I'>(class)</emphasis>
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+At the first level (xmh, Xmh), rule 1 eliminates entry B.
+At the second level (toc, Paned), rule 2 eliminates entry A.
+At the third level (messagefunctions, Box), no entries are eliminated.
+At the fourth level (incorporate, Command), rule 2 eliminates entry D.
+At the fifth level (activeForeground, Foreground), rule 3 eliminates entry C.
+</para>
+</sect1>
+<sect1 id="Quarks">
+<title>Quarks</title>
+<!-- .XS -->
+<!-- (SN Quarks -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+Most uses of the resource manager involve defining names,
+classes, and representation types as string constants.
+However, always referring to strings in the resource manager can be slow,
+because it is so heavily used in some toolkits.
+To solve this problem,
+a shorthand for a string is used in place of the string
+in many of the resource manager functions.
+Simple comparisons can be performed rather than string comparisons.
+The shorthand name for a string is called a quark and is the
+type
+<type>XrmQuark</type>.
+On some occasions,
+you may want to allocate a quark that has no string equivalent.
+</para>
+<para>
+<!-- .LP -->
+A quark is to a string what an atom is to a string in the server,
+but its use is entirely local to your application.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To allocate a new quark, use
+<function>XrmUniqueQuark</function>.
+</para>
+<indexterm significance="preferred"><primary>XrmUniqueQuark</primary></indexterm>
+<!-- .sM -->
+<para>XrmQuark XrmUniqueQuark()</para>
+<!-- .FN -->
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmUniqueQuark</function>
+function allocates a quark that is guaranteed not to represent any string that
+is known to the resource manager.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Each name, class, and representation type is typedef'd as an
+<type>XrmQuark</type>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef int XrmQuark, *XrmQuarkList;
+typedef XrmQuark XrmName;
+typedef XrmQuark XrmClass;
+typedef XrmQuark XrmRepresentation;
+#define NULLQUARK ((XrmQuark) 0)
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Lists are represented as null-terminated arrays of quarks.
+The size of the array must be large enough for the number of components used.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sM -->
+<literallayout class="monospaced">
+typedef XrmQuarkList XrmNameList;
+typedef XrmQuarkList XrmClassList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To convert a string to a quark, use
+<function>XrmStringToQuark</function>
+or
+<function>XrmPermStringToQuark</function>.
+</para>
+<literallayout class="monospaced">
+#define XrmStringToName(string) XrmStringToQuark(string)
+#define XrmStringToClass(string) XrmStringToQuark(string)
+#define XrmStringToRepresentation(string) XrmStringToQuark(string)
+</literallayout>
+
+<indexterm significance="preferred"><primary>XrmStringToQuark</primary></indexterm>
+<indexterm significance="preferred"><primary>XrmPermStringToQuark</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmstringtoquark'>
+<funcprototype>
+ <funcdef>XrmQuark <function>XrmStringToQuark</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string for which a quark(Ql is to be allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+These functions can be used to convert from string to quark representation.
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+The string argument to
+<function>XrmStringToQuark</function>
+need not be permanently allocated storage.
+<function>XrmPermStringToQuark</function>
+is just like
+<function>XrmStringToQuark</function>,
+except that Xlib is permitted to assume the string argument is permanently
+allocated,
+and, hence, that it can be used as the value to be returned by
+<function>XrmQuarkToString</function>.
+</para>
+<para>
+<!-- .LP -->
+For any given quark, if
+<function>XrmStringToQuark</function>
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a quark to a string, use
+<function>XrmQuarkToString</function>.
+</para>
+
+<literallayout class="monospaced">
+#define XrmNameToString(name) XrmQuarkToString(name)
+#define XrmClassToString(class) XrmQuarkToString(name)
+#define XrmRepresentationToString(type) XrmQuarkToString(type)
+</literallayout>
+<indexterm significance="preferred"><primary>XrmQuarkToString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmquarktostring'>
+<funcprototype>
+ <funcdef>char *<function>XrmQuarkToString</function></funcdef>
+ <paramdef>XrmQuark<parameter> quark</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the quark for which the equivalent string is desired.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+<!-- AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA -->
+<para>
+These functions can be used to convert from quark representation to string.
+The string pointed to by the return value must not be modified or freed.
+The returned string is byte-for-byte equal to the original
+string passed to one of the string-to-quark routines.
+If no string exists for that quark,
+<function>XrmQuarkToString</function>
+returns NULL.
+For any given quark, if
+<function>XrmQuarkToString</function>
+returns a non-NULL value,
+all future calls will return the same value (identical address).
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a string with one or more components to a quark list, use
+<function>XrmStringToQuarkList</function>.
+</para>
+
+<literallayout class="monospaced">
+#define XrmStringToNameList(str,name) XrmStringToQuarkList((str), (name))
+#define XrmStringToClassList(str,class) XrmStringToQuarkList((str), (class))
+</literallayout>
+
+<indexterm significance="preferred"><primary>XrmStringToQuarkList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmstringtoquarklist'>
+<funcprototype>
+ <funcdef>void <function>XrmStringToQuarkList</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql \ list -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string for which a quark(Ql is to be allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling
+<function>XrmStringToQuarkList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmStringToQuarkList</function>
+function converts the null-terminated string (generally a fully qualified name)
+to a list of quarks.
+Note that the string must be in the valid ResourceName format
+(see section 15.1).
+If the string is not in the Host Portable Character Encoding,
+the conversion is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+A binding list is a list of type
+<type>XrmBindingList</type>
+and indicates if components of name or class lists are bound tightly or loosely
+(that is, if wildcarding of intermediate components is specified).
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+typedef enum {XrmBindTightly, XrmBindLoosely} XrmBinding, *XrmBindingList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<constant>XrmBindTightly</constant>
+indicates that a period separates the components, and
+<constant>XrmBindLoosely</constant>
+indicates that an asterisk separates the components.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To convert a string with one or more components to a binding list
+and a quark list, use
+<function>XrmStringToBindingQuarkList</function>.
+<indexterm significance="preferred"><primary>XrmStringToBindingQuarkList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmstringtobindingquarklist'>
+<funcprototype>
+ <funcdef><function>XrmStringToBindingQuarkList</function></funcdef>
+ <paramdef>char<parameter> *string</parameter></paramdef>
+ <paramdef>XrmBindingList<parameter> bindings_return</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<!-- .ds Ql \ list -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>string</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the string for which a quark(Ql is to be allocated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bindings_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the binding list.
+The caller must allocate sufficient space for the binding list before calling
+<function>XrmStringToBindingQuarkList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the list of quarks.
+The caller must allocate sufficient space for the quarks list before calling
+<function>XrmStringToBindingQuarkList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Component names in the list are separated by a period or
+an asterisk character.
+The string must be in the format of a valid ResourceName (see section 15.1).
+If the string does not start with a period or an asterisk,
+a tight binding is assumed.
+For example, the string ``*a.b*c'' becomes:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA .75i 1.5i 2.25i -->
+<!-- .ta .75i 1.5i 2.25i -->
+quarks: a b c
+bindings: loose tight loose
+</literallayout>
+</para>
+</sect1>
+<sect1 id="Creating_and_Storing_Databases">
+<title>Creating and Storing Databases</title>
+<!-- .XS -->
+<!-- (SN Creating and Storing Databases -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmDatabase</primary></indexterm>
+A resource database is an opaque type,
+<type>XrmDatabase</type>.
+Each database value is stored in an
+<type>XrmValue</type>
+structure.
+This structure consists of a size, an address, and a representation type.
+The size is specified in bytes.
+The representation type is a way for you to store data tagged by some
+application-defined type (for example, the strings ``font'' or ``color'').
+It has nothing to do with the C data type or with its class.
+The
+<type>XrmValue</type>
+structure is defined as:
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmValue</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+typedef struct {
+ unsigned int size;
+ XPointer addr;
+} XrmValue, *XrmValuePtr;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To initialize the resource manager, use
+<function>XrmInitialize</function>.
+<indexterm significance="preferred"><primary>XrmInitialize</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrminitialize'>
+<funcprototype>
+ <funcdef>void <function>XrmInitialize</function></funcdef>
+ <paramdef>void<parameter> XrmInitialize(\|)</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+To retrieve a database from disk, use
+<function>XrmGetFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetfiledatabase'>
+<funcprototype>
+ <funcdef>XrmDatabase <function>XrmGetFileDatabase</function></funcdef>
+ <paramdef>char<parameter> *filename</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database file name.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetFileDatabase</function>
+function opens the specified file,
+creates a new resource database, and loads it with the specifications
+read in from the specified file.
+The specified file should contain a sequence of entries in valid ResourceLine
+format (see section 15.1); the database that results from reading a file
+with incorrect syntax is implementation-dependent.
+The file is parsed in the current locale,
+and the database is created in the current locale.
+If it cannot open the specified file,
+<function>XrmGetFileDatabase</function>
+returns NULL.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To store a copy of a database to disk, use
+<function>XrmPutFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmPutFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputfiledatabase'>
+<funcprototype>
+ <funcdef>void <function>XrmPutFileDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>char<parameter> *stored_db</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>stored_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the file name for the stored database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmPutFileDatabase</function>
+function stores a copy of the specified database in the specified file.
+Text is written to the file as a sequence of entries in valid
+ResourceLine format (see section 15.1).
+The file is written in the locale of the database.
+Entries containing resource names that are not in the Host Portable Character
+Encoding or containing values that are not in the encoding of the database
+locale, are written in an implementation-dependent manner.
+The order in which entries are written is implementation-dependent.
+Entries with representation types other than ``String'' are ignored.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pointer to the screen-independent resources of a display, use
+<function>XResourceManagerString</function>.
+<indexterm significance="preferred"><primary>XResourceManagerString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xresourcemanagerstring'>
+<funcprototype>
+ <funcdef>char *<function>XResourceManagerString</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XResourceManagerString</function>
+function returns the RESOURCE_MANAGER property from the server's root
+window of screen zero, which was returned when the connection was opened using
+<function>XOpenDisplay</function>.
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by
+<function>XmbTextPropertyToTextList</function>
+for a single element STRING property.
+The returned string is owned by Xlib and should not be freed by the client.
+The property value must be in a format that is acceptable to
+<function>XrmGetStringDatabase</function>.
+If no property exists, NULL is returned.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a pointer to the screen-specific resources of a screen, use
+<function>XScreenResourceString</function>.
+<indexterm significance="preferred"><primary>XScreenResourceString</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xscreenresourcestring'>
+<funcprototype>
+ <funcdef>char *<function>XScreenResourceString</function></funcdef>
+ <paramdef>Screen<parameter> *screen</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>screen</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the screen.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XScreenResourceString</function>
+function returns the SCREEN_RESOURCES property from the root window of the
+specified screen.
+The property is converted from type STRING to the current locale.
+The conversion is identical to that produced by
+<function>XmbTextPropertyToTextList</function>
+for a single element STRING property.
+The property value must be in a format that is acceptable to
+<function>XrmGetStringDatabase</function>.
+If no property exists, NULL is returned.
+The caller is responsible for freeing the returned string by using
+<function>XFree</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To create a database from a string, use
+<function>XrmGetStringDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetStringDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetstringdatabase'>
+<funcprototype>
+ <funcdef>XrmDatabase <function>XrmGetStringDatabase</function></funcdef>
+ <paramdef>char<parameter> *data</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>data</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database contents using a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetStringDatabase</function>
+function creates a new database and stores the resources specified
+in the specified null-terminated string.
+<function>XrmGetStringDatabase</function>
+is similar to
+<function>XrmGetFileDatabase</function>
+except that it reads the information out of a string instead of out of a file.
+The string should contain a sequence of entries in valid ResourceLine
+format (see section 15.1) terminated by a null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the current locale,
+and the database is created in the current locale.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain the locale name of a database, use
+<function>XrmLocaleOfDatabase</function>.
+<indexterm significance="preferred"><primary>XrmLocaleOfDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmlocaleofdatabase'>
+<funcprototype>
+ <funcdef>char *<function>XrmLocaleOfDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmLocaleOfDatabase</function>
+function returns the name of the locale bound to the specified
+database, as a null-terminated string.
+The returned locale name string is owned by Xlib and should not be
+modified or freed by the client.
+Xlib is not permitted to free the string until the database is destroyed.
+Until the string is freed,
+it will not be modified by Xlib.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To destroy a resource database and free its allocated memory, use
+<function>XrmDestroyDatabase</function>.
+<indexterm significance="preferred"><primary>XrmDestroyDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmdestroydatabase'>
+<funcprototype>
+ <funcdef>void <function>XrmDestroyDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database is NULL,
+<function>XrmDestroyDatabase</function>
+returns immediately.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To associate a resource database with a display, use
+<function>XrmSetDatabase</function>.
+<indexterm significance="preferred"><primary>XrmSetDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmsetdatabase'>
+<funcprototype>
+ <funcdef>void <function>XrmSetDatabase</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmSetDatabase</function>
+function associates the specified resource database (or NULL)
+with the specified display.
+The database previously associated with the display (if any) is not destroyed.
+A client or toolkit may find this function convenient for retaining a database
+once it is constructed.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To get the resource database associated with a display, use
+<function>XrmGetDatabase</function>.
+<indexterm significance="preferred"><primary>XrmGetDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetdatabase'>
+<funcprototype>
+ <funcdef>XrmDatabase <function>XrmGetDatabase</function></funcdef>
+ <paramdef>Display<parameter> *display</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>display</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the connection to the X server.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetDatabase</function>
+function returns the database associated with the specified display.
+It returns NULL if a database has not yet been set.
+</para>
+</sect1>
+<sect1 id="Merging_Resource_Databases">
+<title>Merging Resource Databases</title>
+<!-- .XS -->
+<!-- (SN Merging Resource Databases -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To merge the contents of a resource file into a database, use
+<function>XrmCombineFileDatabase</function>.
+<indexterm significance="preferred"><primary>XrmCombineFileDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmcombinefiledatabase'>
+<funcprototype>
+ <funcdef>Status <function>XrmCombineFileDatabase</function></funcdef>
+ <paramdef>char<parameter> *filename</parameter></paramdef>
+ <paramdef>XrmDatabase<parameter> *target_db</parameter></paramdef>
+ <paramdef>Bool<parameter> override</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>filename</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database file name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database into which the source
+database is to be merged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>override</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether source entries override target ones.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmCombineFileDatabase</function>
+function merges the contents of a resource file into a database.
+If the same specifier is used for an entry in both the file and
+the database,
+the entry in the file will replace the entry in the database
+if override is
+<symbol>True</symbol>;
+otherwise, the entry in the file is discarded.
+The file is parsed in the current locale.
+If the file cannot be read,
+a zero status is returned;
+otherwise, a nonzero status is returned.
+If target_db contains NULL,
+<function>XrmCombineFileDatabase</function>
+creates and returns a new database to it.
+Otherwise, the database pointed to by target_db is not destroyed by the merge.
+The database entries are merged without changing values or types,
+regardless of the locale of the database.
+The locale of the target database is not modified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To merge the contents of one database into another database, use
+<function>XrmCombineDatabase</function>.
+<indexterm significance="preferred"><primary>XrmCombineDatabase</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmcombinedatabase'>
+<funcprototype>
+ <funcdef>void <function>XrmCombineDatabase</function></funcdef>
+ <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
+ <paramdef>Bool<parameter> override</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database that is to be merged into the target database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database into which the source
+database is to be merged.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>override</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies whether source entries override target ones.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmCombineDatabase</function>
+function merges the contents of one database into another.
+If the same specifier is used for an entry in both databases,
+the entry in the source_db will replace the entry in the target_db
+if override is
+<symbol>True</symbol>;
+otherwise, the entry in source_db is discarded.
+If target_db contains NULL,
+<function>XrmCombineDatabase</function>
+simply stores source_db in it.
+Otherwise, source_db is destroyed by the merge, but the database pointed
+to by target_db is not destroyed.
+The database entries are merged without changing values or types,
+regardless of the locales of the databases.
+The locale of the target database is not modified.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To merge the contents of one database into another database with override
+semantics, use
+<function>XrmMergeDatabases</function>.
+<indexterm significance="preferred"><primary>XrmMergeDatabases</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmmergedatabases'>
+<funcprototype>
+ <funcdef>void <function>XrmMergeDatabases</function></funcdef>
+ <paramdef>XrmDatabasesource_db,<parameter> *target_db</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>source_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database that is to be merged into the target database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>target_db</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database into which the source
+database is to be merged.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Calling the
+<function>XrmMergeDatabases</function>
+function is equivalent to calling the
+<function>XrmCombineDatabase</function>
+function with an override argument of
+<symbol>True</symbol>.
+</para>
+</sect1>
+<sect1 id="Looking_Up_Resources">
+<title>Looking Up Resources</title>
+<!-- .XS -->
+<!-- (SN Looking Up Resources -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To retrieve a resource from a resource database, use
+<function>XrmGetResource</function>,
+<function>XrmQGetResource</function>,
+or
+<function>XrmQGetSearchResource</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmGetResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmgetresource'>
+<funcprototype>
+ <funcdef>Bool <function>XrmGetResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>char<parameter> *str_name</parameter></paramdef>
+ <paramdef>char<parameter> *str_class</parameter></paramdef>
+ <paramdef>char<parameter> **str_type_return</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>str_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified name of the value being retrieved (as a string).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>str_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified class of the value being retrieved (as a string).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>str_type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the representation type of the destination (as a string).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmQGetResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqgetresource'>
+<funcprototype>
+ <funcdef>Bool <function>XrmQGetResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>XrmNameList<parameter> quark_name</parameter></paramdef>
+ <paramdef>XrmClassList<parameter> quark_class</parameter></paramdef>
+ <paramdef>XrmRepresentation<parameter> *quark_type_return</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark_name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified name of the value being retrieved (as a quark).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark_class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the fully qualified class of the value being retrieved (as a quark).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quark_type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the representation type of the destination (as a quark).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmGetResource</function>
+and
+<function>XrmQGetResource</function>
+functions retrieve a resource from the specified database.
+Both take a fully qualified name/class pair, a destination
+resource representation, and the address of a value
+(size/address pair).
+The value and returned type point into database memory;
+therefore, you must not modify the data.
+</para>
+<para>
+<!-- .LP -->
+The database only frees or overwrites entries on
+<function>XrmPutResource</function>,
+<function>XrmQPutResource</function>,
+or
+<function>XrmMergeDatabases</function>.
+A client that is not storing new values into the database or
+is not merging the database should be safe using the address passed
+back at any time until it exits.
+If a resource was found, both
+<function>XrmGetResource</function>
+and
+<function>XrmQGetResource</function>
+return
+<symbol>True</symbol>;
+otherwise, they return
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+Most applications and toolkits do not make random probes
+into a resource database to fetch resources.
+The X toolkit access pattern for a resource database is quite stylized.
+A series of from 1 to 20 probes is made with only the
+last name/class differing in each probe.
+The
+<function>XrmGetResource</function>
+function is at worst a
+2<superscript><emphasis remap='I'>n</emphasis></superscript> algorithm,
+where <emphasis remap='I'>n</emphasis> is the length of the name/class list.
+This can be improved upon by the application programmer by prefetching a list
+of database levels that might match the first part of a name/class list.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To obtain a list of database levels, use
+<function>XrmQGetSearchList</function>.
+<indexterm significance="preferred"><primary>XrmQGetSearchList</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqgetsearchlist'>
+<funcprototype>
+ <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>XrmNameList<parameter> names</parameter></paramdef>
+ <paramdef>XrmClassList<parameter> classes</parameter></paramdef>
+ <paramdef>XrmSearchList<parameter> list_return</parameter></paramdef>
+ <paramdef>int<parameter> list_length</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the database that is to be used.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>names</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of resource names.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>classes</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of resource classes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns a search list for further use.
+The caller must allocate sufficient space for the list before calling
+<function>XrmQGetSearchList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list_length</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries (not the byte size) allocated for list_return.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmQGetSearchList</function>
+function takes a list of names and classes
+and returns a list of database levels where a match might occur.
+The returned list is in best-to-worst order and
+uses the same algorithm as
+<function>XrmGetResource</function>
+for determining precedence.
+If list_return was large enough for the search list,
+<function>XrmQGetSearchList</function>
+returns
+<symbol>True</symbol>;
+otherwise, it returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The size of the search list that the caller must allocate is
+dependent upon the number of levels and wildcards in the resource specifiers
+that are stored in the database.
+The worst case length is
+3<superscript><emphasis remap='I'>n</emphasis></superscript>,
+where <emphasis remap='I'>n</emphasis> is the number of name or class
+components in names or classes.
+</para>
+<para>
+<!-- .LP -->
+When using
+<function>XrmQGetSearchList</function>
+followed by multiple probes for resources with a common name and class prefix,
+only the common prefix should be specified in the name and class list to
+<function>XrmQGetSearchList</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To search resource database levels for a given resource, use
+<function>XrmQGetSearchResource</function>.
+<indexterm significance="preferred"><primary>XrmQGetSearchResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqgetsearchresource'>
+<funcprototype>
+ <funcdef>Bool <function>XrmQGetSearchResource</function></funcdef>
+ <paramdef>XrmSearchList<parameter> list</parameter></paramdef>
+ <paramdef>XrmName<parameter> name</parameter></paramdef>
+ <paramdef>XrmClass<parameter> class</parameter></paramdef>
+ <paramdef>XrmRepresentation<parameter> *type_return</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value_return</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>list</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the search list returned by
+<function>XrmQGetSearchList</function>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns data representation type.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value_return</emphasis>
+ </term>
+ <listitem>
+ <para>
+Returns the value in the database.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmQGetSearchResource</function>
+function searches the specified database levels for the resource
+that is fully identified by the specified name and class.
+The search stops with the first match.
+<function>XrmQGetSearchResource</function>
+returns
+<symbol>True</symbol>
+if the resource was found;
+otherwise, it returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+A call to
+<function>XrmQGetSearchList</function>
+with a name and class list containing all but the last component
+of a resource name followed by a call to
+<function>XrmQGetSearchResource</function>
+with the last component name and class returns the same database entry as
+<function>XrmGetResource</function>
+and
+<function>XrmQGetResource</function>
+with the fully qualified name and class.
+</para>
+</sect1>
+<sect1 id="Storing_into_a_Resource_Database">
+<title>Storing into a Resource Database</title>
+<!-- .XS -->
+<!-- (SN Storing into a Resource Database -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To store resources into the database, use
+<function>XrmPutResource</function>
+or
+<function>XrmQPutResource</function>.
+Both functions take a partial resource specification, a
+representation type, and a value.
+This value is copied into the specified database.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmPutResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputresource'>
+<funcprototype>
+ <funcdef>void <function>XrmPutResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>char<parameter> *specifier</parameter></paramdef>
+ <paramdef>char<parameter> *type</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>specifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a complete or partial specification of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutResource</function>
+is a convenience function that calls
+<function>XrmStringToBindingQuarkList</function>
+followed by:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+XrmQPutResource(database, bindings, quarks, XrmStringToQuark(type), value)
+</literallayout>
+If the specifier and type are not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<indexterm significance="preferred"><primary>XrmQPutResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqputresource'>
+<funcprototype>
+ <funcdef>void <function>XrmQPutResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
+ <paramdef>XrmRepresentation<parameter> type</parameter></paramdef>
+ <paramdef>XrmValue<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bindings</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of bindings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the complete or partial name or the class list of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>type</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the type of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmQPutResource</function>
+creates a new database and returns a pointer to it.
+If a resource entry with the identical bindings and quarks already
+exists in the database, the previous type and value are replaced by the new
+specified type and value.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a resource that is specified as a string, use
+<function>XrmPutStringResource</function>.
+<indexterm significance="preferred"><primary>XrmPutStringResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputstringresource'>
+<funcprototype>
+ <funcdef>void <function>XrmPutStringResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>char<parameter> *specifier</parameter></paramdef>
+ <paramdef>char<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>specifier</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a complete or partial specification of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutStringResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutStringResource</function>
+adds a resource with the specified value to the specified database.
+<function>XrmPutStringResource</function>
+is a convenience function that first calls
+<function>XrmStringToBindingQuarkList</function>
+on the specifier and then calls
+<function>XrmQPutResource</function>,
+using a ``String'' representation type.
+If the specifier is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a string resource using quarks as a specification, use
+<function>XrmQPutStringResource</function>.
+<indexterm significance="preferred"><primary>XrmQPutStringResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmqputstringresource'>
+<funcprototype>
+ <funcdef>void <function>XrmQPutStringResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>XrmBindingList<parameter> bindings</parameter></paramdef>
+ <paramdef>XrmQuarkList<parameter> quarks</parameter></paramdef>
+ <paramdef>char<parameter> *value</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>bindings</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies a list of bindings.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>quarks</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the complete or partial name or the class list of the resource.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>value</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the value of the resource, which is specified as a string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmQPutStringResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmQPutStringResource</function>
+is a convenience routine that constructs an
+<type>XrmValue</type>
+for the value string (by calling
+<function>strlen</function>
+to compute the size) and
+then calls
+<function>XrmQPutResource</function>,
+using a ``String'' representation type.
+The value is stored in the database without modification.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+To add a single resource entry that is specified as a string that contains
+both a name and a value, use
+<function>XrmPutLineResource</function>.
+<indexterm significance="preferred"><primary>XrmPutLineResource</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmputlineresource'>
+<funcprototype>
+ <funcdef>void <function>XrmPutLineResource</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>char<parameter> *line</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>line</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name and value pair as a single string.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+If database contains NULL,
+<function>XrmPutLineResource</function>
+creates a new database and returns a pointer to it.
+<function>XrmPutLineResource</function>
+adds a single resource entry to the specified database.
+The line should be in valid ResourceLine format (see section 15.1)
+terminated by a newline or null character;
+the database that results from using a string
+with incorrect syntax is implementation-dependent.
+The string is parsed in the locale of the database.
+If the
+<replaceable>ResourceName</replaceable>
+is not in the Host Portable Character Encoding,
+the result is implementation-dependent.
+Note that comment lines are not stored.
+</para>
+</sect1>
+<sect1 id="Enumerating_Database_Entries">
+<title>Enumerating Database Entries</title>
+<!-- .XS -->
+<!-- (SN Enumerating Database Entries -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+To enumerate the entries of a database, use
+<function>XrmEnumerateDatabase</function>.
+<indexterm significance="preferred"><primary>XrmEnumerateDatabase</primary></indexterm>
+<!-- .sM -->
+</para>
+
+<literallayout class="monospaced">
+#define XrmEnumAllLevels 0
+#define XrmEnumOneLevel 0
+</literallayout>
+
+<funcsynopsis id='xrmenumeratedatabase'>
+<funcprototype>
+ <funcdef>Bool <function>XrmEnumerateDatabase</function></funcdef>
+ <paramdef>XrmDatabase<parameter> database</parameter></paramdef>
+ <paramdef>XrmNameList<parameter> name_prefix</parameter></paramdef>
+ <paramdef>XrmClassList<parameter> class_prefix</parameter></paramdef>
+ <paramdef>int<parameter> mode</parameter></paramdef>
+ <paramdef>Bool<parameter> (*proc)()</parameter></paramdef>
+ <paramdef>XPointer<parameter> arg</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name_prefix</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource name prefix.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>class_prefix</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource class prefix.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>mode</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of levels to enumerate.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>proc</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the procedure that is to be called for each matching entry.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>arg</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the user-supplied argument that will be passed to the procedure.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmEnumerateDatabase</function>
+function calls the specified procedure for each resource in the database
+that would match some completion of the given name/class resource prefix.
+The order in which resources are found is implementation-dependent.
+If mode is
+<symbol>XrmEnumOneLevel</symbol>,
+a resource must match the given name/class prefix with
+just a single name and class appended. If mode is
+<symbol>XrmEnumAllLevels</symbol>,
+the resource must match the given name/class prefix with one or more names and
+classes appended.
+If the procedure returns
+<symbol>True</symbol>,
+the enumeration terminates and the function returns
+<symbol>True</symbol>.
+If the procedure always returns
+<symbol>False</symbol>,
+all matching resources are enumerated and the function returns
+<symbol>False</symbol>.
+</para>
+<para>
+<!-- .LP -->
+The procedure is called with the following arguments:
+</para>
+<para>
+<!-- .LP -->
+<!-- .\" Start marker code here -->
+<literallayout class="monospaced">
+<!-- .TA .5i 3i -->
+<!-- .ta .5i 3i -->
+(*<emphasis remap='I'>proc</emphasis>)(<emphasis remap='I'>database</emphasis>, <emphasis remap='I'>bindings</emphasis>, <emphasis remap='I'>quarks</emphasis>, <emphasis remap='I'>type</emphasis>, <emphasis remap='I'>value</emphasis>, <emphasis remap='I'>arg</emphasis>)
+ XrmDatabase *<emphasis remap='I'>database</emphasis>;
+ XrmBindingList <emphasis remap='I'>bindings</emphasis>;
+ XrmQuarkList <emphasis remap='I'>quarks</emphasis>;
+ XrmRepresentation *<emphasis remap='I'>type</emphasis>;
+ XrmValue *<emphasis remap='I'>value</emphasis>;
+ XPointer <emphasis remap='I'>arg</emphasis>;
+</literallayout>
+<!-- .\" End marker code here -->
+</para>
+<para>
+<!-- .LP -->
+The bindings and quarks lists are terminated by
+<symbol>NULLQUARK</symbol>.
+Note that pointers
+to the database and type are passed, but these values should not be modified.
+</para>
+<para>
+<!-- .LP -->
+The procedure must not modify the database.
+If Xlib has been initialized for threads, the procedure is called with
+the database locked and the result of a call by the procedure to any
+Xlib function using the same database is not defined.
+</para>
+</sect1>
+<sect1 id="Parsing_Command_Line_Options">
+<title>Parsing Command Line Options</title>
+<!-- .XS -->
+<!-- (SN Parsing Command Line Options -->
+<!-- .XE -->
+<para>
+<!-- .LP -->
+The
+<function>XrmParseCommand</function>
+function can be used to parse the command line arguments to a program
+and modify a resource database with selected entries from the command line.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmOptionKind</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef enum {
+ XrmoptionNoArg, /* Value is specified in XrmOptionDescRec.value */
+ XrmoptionIsArg, /* Value is the option string itself */
+ XrmoptionStickyArg, /* Value is characters immediately following option */
+ XrmoptionSepArg, /* Value is next argument in argv */
+ XrmoptionResArg, /* Resource and value in next argument in argv */
+ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */
+ XrmoptionSkipLine, /* Ignore this option and the rest of argv */
+ XrmoptionSkipNArgs /* Ignore this option and the next
+ \ \ \ XrmOptionDescRec.value arguments in argv */
+} XrmOptionKind;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+Note that
+<constant>XrmoptionSkipArg</constant>
+is equivalent to
+<constant>XrmoptionSkipNArgs</constant>
+with the
+<structname>XrmOptionDescRec</structname>.<structfield>value</structfield>
+field containing the value one.
+Note also that the value zero for
+<constant>XrmoptionSkipNArgs</constant>
+indicates that only the option itself is to be skipped.
+</para>
+<para>
+<!-- .LP -->
+<indexterm significance="preferred"><primary>XrmOptionDescRec</primary></indexterm>
+<!-- .sM -->
+<literallayout class="monospaced">
+<!-- .TA .5i 2.5i -->
+<!-- .ta .5i 2.5i -->
+typedef struct {
+ char *option; /* Option specification string in argv */
+ char *specifier; /* Binding and resource name (sans application name) */
+ XrmOptionKind argKind; /* Which style of option it is */
+ XPointer value; /* Value to provide if XrmoptionNoArg or
+ \ \ \ XrmoptionSkipNArgs */
+} XrmOptionDescRec, *XrmOptionDescList;
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+<!-- .sp -->
+To load a resource database from a C command line, use
+<function>XrmParseCommand</function>.
+<indexterm significance="preferred"><primary>XrmParseCommand</primary></indexterm>
+<!-- .sM -->
+<funcsynopsis id='xrmparsecommand'>
+<funcprototype>
+ <funcdef>void <function>XrmParseCommand</function></funcdef>
+ <paramdef>XrmDatabase<parameter> *database</parameter></paramdef>
+ <paramdef>XrmOptionDescList<parameter> table</parameter></paramdef>
+ <paramdef>int<parameter> table_count</parameter></paramdef>
+ <paramdef>char<parameter> *name</parameter></paramdef>
+ <paramdef>int<parameter> *argc_in_out</parameter></paramdef>
+ <paramdef>char<parameter> **argv_in_out</parameter></paramdef>
+</funcprototype>
+</funcsynopsis>
+<!-- .FN -->
+<variablelist>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>database</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the resource database.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the table of command line arguments to be parsed.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>table_count</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of entries in the table.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>name</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the application name.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argc_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the number of arguments and returns the number of remaining arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>
+ <emphasis remap='I'>argv_in_out</emphasis>
+ </term>
+ <listitem>
+ <para>
+Specifies the command line arguments
+and returns the remaining arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+</variablelist>
+</para>
+<para>
+<!-- .LP -->
+<!-- .eM -->
+The
+<function>XrmParseCommand</function>
+function parses an (argc, argv) pair according to the specified option table,
+loads recognized options into the specified database with type ``String,''
+and modifies the (argc, argv) pair to remove all recognized options.
+If database contains NULL,
+<function>XrmParseCommand</function>
+creates a new database and returns a pointer to it.
+Otherwise, entries are added to the database specified.
+If a database is created, it is created in the current locale.
+</para>
+<para>
+<!-- .LP -->
+The specified table is used to parse the command line.
+Recognized options in the table are removed from argv,
+and entries are added to the specified resource database
+in the order they occur in argv.
+The table entries contain information on the option string,
+the option name, the style of option,
+and a value to provide if the option kind is
+<constant>XrmoptionNoArg</constant>.
+The option names are compared byte-for-byte to arguments in argv,
+independent of any locale.
+The resource values given in the table are stored in the resource database
+without modification.
+All resource database entries are created
+using a ``String'' representation type.
+The argc argument specifies the number of arguments in argv
+and is set on return to the remaining number of arguments that were not parsed.
+The name argument should be the name of your application
+for use in building the database entry.
+The name argument is prefixed to the resourceName in the option table
+before storing a database entry.
+The name argument is treated as a single component, even if it
+has embedded periods.
+No separating (binding) character is inserted,
+so the table must contain either a period (.) or an asterisk (*)
+as the first character in each resourceName entry.
+To specify a more completely qualified resource name,
+the resourceName entry can contain multiple components.
+If the name argument and the resourceNames are not in the
+Host Portable Character Encoding,
+the result is implementation-dependent.
+</para>
+<para>
+<!-- .LP -->
+The following provides a sample option table:
+</para>
+<para>
+<!-- .LP -->
+<literallayout class="monospaced">
+<!-- .TA 1.25i 3.25i 4.75i -->
+<!-- .ta 1.25i 3.25i 4.75i -->
+static XrmOptionDescRec opTable[] = {
+{"-background", "*background", XrmoptionSepArg, (XPointer) NULL},
+{"-bd", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
+{"-bg", "*background", XrmoptionSepArg, (XPointer) NULL},
+{"-borderwidth", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
+{"-bordercolor", "*borderColor", XrmoptionSepArg, (XPointer) NULL},
+{"-bw", "*TopLevelShell.borderWidth", XrmoptionSepArg, (XPointer) NULL},
+{"-display", ".display", XrmoptionSepArg, (XPointer) NULL},
+{"-fg", "*foreground", XrmoptionSepArg, (XPointer) NULL},
+{"-fn", "*font", XrmoptionSepArg, (XPointer) NULL},
+{"-font", "*font", XrmoptionSepArg, (XPointer) NULL},
+{"-foreground", "*foreground", XrmoptionSepArg, (XPointer) NULL},
+{"-geometry", ".TopLevelShell.geometry", XrmoptionSepArg, (XPointer) NULL},
+{"-iconic", ".TopLevelShell.iconic", XrmoptionNoArg, (XPointer) "on"},
+{"-name", ".name", XrmoptionSepArg, (XPointer) NULL},
+{"-reverse", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
+{"-rv", "*reverseVideo", XrmoptionNoArg, (XPointer) "on"},
+{"-synchronous", "*synchronous", XrmoptionNoArg, (XPointer) "on"},
+{"-title", ".TopLevelShell.title", XrmoptionSepArg, (XPointer) NULL},
+{"-xrm", NULL, XrmoptionResArg, (XPointer) NULL},
+};
+</literallayout>
+</para>
+<para>
+<!-- .LP -->
+In this table, if the -background (or -bg) option is used to set
+background colors, the stored resource specifier matches all
+resources of attribute background.
+If the -borderwidth option is used,
+the stored resource specifier applies only to border width
+attributes of class TopLevelShell (that is, outer-most windows, including
+pop-up windows).
+If the -title option is used to set a window name,
+only the topmost application windows receive the resource.
+</para>
+<para>
+<!-- .LP -->
+When parsing the command line,
+any unique unambiguous abbreviation for an option name in the table is
+considered a match for the option.
+Note that uppercase and lowercase matter.
+<!-- .bp -->
+
+</para>
+</sect1>
+</chapter>
generated by cgit v1.2.3 (git 2.25.1) at 2024-07-20 19:07:53 +0000