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