1XrmGetResource(3) XLIB FUNCTIONS XrmGetResource(3)
2
6 XrmGetResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchRe‐
7 source - retrieve database resources and search lists
8
10 #include <X11/Xresource.h>
11 Bool XrmGetResource(XrmDatabase database, char *str_name, char
13 *str_class, char **str_type_return, XrmValue *value_return);
14 Bool XrmQGetResource(XrmDatabase database, XrmNameList quark_name, Xrm‐
16 ClassList quark_class, XrmRepresentation *quark_type_return, Xr‐
17 mValue *value_return);
18 typedef XrmHashTable *XrmSearchList;
20 Bool XrmQGetSearchList(XrmDatabase database, XrmNameList names,
22 XrmClassList classes, XrmSearchList list_return, int
23 list_length);
24 Bool XrmQGetSearchResource(XrmSearchList list, XrmName name, XrmClass
26 class, XrmRepresentation *type_return, XrmValue *value_return);
27
29 class Specifies the resource class.
30 classes Specifies a list of resource classes.
32 database Specifies the database that is to be used.
34 list Specifies the search list returned by XrmQGetSearchList.
36 list_length
38 Specifies the number of entries (not the byte size) allocated
39 for list_return.
40 list_return
42 Returns a search list for further use.
43 name Specifies the resource name.
45 names Specifies a list of resource names.
47 quark_class
49 Specifies the fully qualified class of the value being re‐
50 trieved (as a quark).
51 quark_name
53 Specifies the fully qualified name of the value being re‐
54 trieved (as a quark).
55 quark_type_return
57 Returns the representation type of the destination (as a
58 quark).
59 str_class Specifies the fully qualified class of the value being re‐
61 trieved (as a string).
62 str_name Specifies the fully qualified name of the value being re‐
64 trieved (as a string).
65 str_type_return
67 Returns the representation type of the destination (as a
68 string).
69 type_return
71 Returns data representation type.
72 value_return
74 Returns the value in the database.
75
77 The XrmGetResource and XrmQGetResource functions retrieve a resource
78 from the specified database. Both take a fully qualified name/class
79 pair, a destination resource representation, and the address of a value
80 (size/address pair). The value and returned type point into database
81 memory; therefore, you must not modify the data.
82 The database only frees or overwrites entries on XrmPutResource, Xr‐
84 mQPutResource, or XrmMergeDatabases. A client that is not storing new
85 values into the database or is not merging the database should be safe
86 using the address passed back at any time until it exits. If a re‐
87 source was found, both XrmGetResource and XrmQGetResource return True;
88 otherwise, they return False.
89 The XrmQGetSearchList function takes a list of names and classes and
91 returns a list of database levels where a match might occur. The re‐
92 turned list is in best-to-worst order and uses the same algorithm as
93 XrmGetResource for determining precedence. If list_return was large
94 enough for the search list, XrmQGetSearchList returns True; otherwise,
95 it returns False.
96 The size of the search list that the caller must allocate is dependent
98 upon the number of levels and wildcards in the resource specifiers that
99 are stored in the database. The worst case length is %3 sup n%, where
100 n is the number of name or class components in names or classes.
101 When using XrmQGetSearchList followed by multiple probes for resources
103 with a common name and class prefix, only the common prefix should be
104 specified in the name and class list to XrmQGetSearchList.
105 The XrmQGetSearchResource function searches the specified database lev‐
107 els for the resource that is fully identified by the specified name and
108 class. The search stops with the first match. XrmQGetSearchResource
109 returns True if the resource was found; otherwise, it returns False.
110 A call to XrmQGetSearchList with a name and class list containing all
112 but the last component of a resource name followed by a call to Xr‐
113 mQGetSearchResource with the last component name and class returns the
114 same database entry as XrmGetResource and XrmQGetResource with the
115 fully qualified name and class.
116
118 The algorithm for determining which resource database entry matches a
119 given query is the heart of the resource manager. All queries must
120 fully specify the name and class of the desired resource (use of the
121 characters “*” and “?” are not permitted). The library supports up to
122 100 components in a full name or class. Resources are stored in the
123 database with only partially specified names and classes, using pattern
124 matching constructs. An asterisk (*) is a loose binding and is used to
125 represent any number of intervening components, including none. A pe‐
126 riod (.) is a tight binding and is used to separate immediately adja‐
127 cent components. A question mark (?) is used to match any single com‐
128 ponent name or class. A database entry cannot end in a loose binding;
129 the final component (which cannot be the character “?”) must be speci‐
130 fied. The lookup algorithm searches the database for the entry that
131 most closely matches (is most specific for) the full name and class be‐
132 ing queried. When more than one database entry matches the full name
133 and class, precedence rules are used to select just one.
134 The full name and class are scanned from left to right (from highest
136 level in the hierarchy to lowest), one component at a time. At each
137 level, the corresponding component and/or binding of each matching en‐
138 try is determined, and these matching components and bindings are com‐
139 pared according to precedence rules. Each of the rules is applied at
140 each level before moving to the next level, until a rule selects a sin‐
141 gle entry over all others. The rules, in order of precedence, are:
142 1. An entry that contains a matching component (whether name, class,
144 or the character “?”) takes precedence over entries that elide
145 the level (that is, entries that match the level in a loose bind‐
146 ing).
147 2. An entry with a matching name takes precedence over both entries
149 with a matching class and entries that match using the character
150 “?”. An entry with a matching class takes precedence over entries
151 that match using the character “?”.
152 3. An entry preceded by a tight binding takes precedence over entries
154 preceded by a loose binding.
155
157 XrmInitialize(3), XrmMergeDatabases(3), XrmPutResource(3), XrmUnique‐
158 Quark(3)
159 Xlib - C Language X Interface
160X Version 11 libX11 1.8.7 XrmGetResource(3)