diff options
Diffstat (limited to 'libX11/specs/libX11/CH15.xml')
| -rw-r--r-- | libX11/specs/libX11/CH15.xml | 2485 |
1 files changed, 2485 insertions, 0 deletions
diff --git a/libX11/specs/libX11/CH15.xml b/libX11/specs/libX11/CH15.xml new file mode 100644 index 000000000..299a1196f --- /dev/null +++ b/libX11/specs/libX11/CH15.xml @@ -0,0 +1,2485 @@ +<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
+<!-- .hN X11/Xresource.h . -->
+</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 | <empty line>
+Comment = "!" {<any character except null or newline>}
+IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
+FileName = <valid filename for operating system>
+ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
+ResourceName = [Binding] {Component Binding} ComponentName
+Binding = "." | "*"
+WhiteSpace = {<space> | <horizontal tab>}
+Component = "?" | ComponentName
+ComponentName = NameChar {NameChar}
+NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
+Value = {<any character except null or unescaped newline>}
+</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
+<function>XrmQuark</function>.
+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
+<function>XrmQuark</function>.
+</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
+<function>XrmBindingList</function>
+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 -->
+<function>XrmBindTightly</function>
+indicates that a period separates the components, and
+<function>XrmBindLoosely</function>
+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,
+<function>XrmDatabase</function>.
+Each database value is stored in an
+<function>XrmValue </function>
+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
+<function>XrmValue </function>
+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
+<function>True</function>;
+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
+<function>True</function>;
+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
+<function>True</function>.
+</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
+<function>True</function>;
+otherwise, they return
+<function>False</function>.
+</para>
+<para>
+<!-- .LP -->
+<!-- .sp -->
+<!-- .EQ -->
+<!-- delim %% -->
+<!-- .EN -->
+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 sup n% algorithm, <!-- FIXME: log(n) ? -->
+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
+<function>True</function>;
+otherwise, it returns
+<function>False</function>.
+</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 sup n%,
+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
+<function>True </function>
+if the resource was found;
+otherwise, it returns
+<function>False</function>.
+</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
+<function>XrmValue</function>
+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
+<function>ResourceName</function>
+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
+<function>XrmEnumOneLevel</function>,
+a resource must match the given name/class prefix with
+just a single name and class appended. If mode is
+<function>XrmEnumAllLevels</function>,
+the resource must match the given name/class prefix with one or more names and
+classes appended.
+If the procedure returns
+<function>True</function>,
+the enumeration terminates and the function returns
+<function>True</function>.
+If the procedure always returns
+<function>False</function>,
+all matching resources are enumerated and the function returns
+<function>False</function>.
+</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
+<function>NULLQUARK</function>.
+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
+<function>XrmoptionSkipArg</function>
+is equivalent to
+<function>XrmoptionSkipNArgs</function>
+with the
+<function>XrmOptionDescRec.value</function>
+field containing the value one.
+Note also that the value zero for
+<function>XrmoptionSkipNArgs</function>
+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
+<function>XrmoptionNoArg</function>.
+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>
|