1XrmGetResource(3)               XLIB FUNCTIONS               XrmGetResource(3)
2
3
4

NAME

6       XrmGetResource, XrmQGetResource, XrmQGetSearchList, XrmQGetSearchRe‐
7       source - retrieve database resources and search lists
8

SYNTAX

10       #include <X11/Xresource.h>
11
12       Bool XrmGetResource(XrmDatabase database, char *str_name, char
13              *str_class, char **str_type_return, XrmValue *value_return);
14
15       Bool XrmQGetResource(XrmDatabase database, XrmNameList quark_name, Xrm‐
16              ClassList quark_class, XrmRepresentation *quark_type_return,
17              XrmValue *value_return);
18
19       typedef XrmHashTable *XrmSearchList;
20
21              Bool XrmQGetSearchList(XrmDatabase database, XrmNameList names,
22              XrmClassList classes, XrmSearchList list_return, int
23              list_length);
24
25       Bool XrmQGetSearchResource(XrmSearchList list, XrmName name, XrmClass
26              class, XrmRepresentation *type_return, XrmValue *value_return);
27

ARGUMENTS

29       class     Specifies the resource class.
30
31       classes   Specifies a list of resource classes.
32
33       database  Specifies the database that is to be used.
34
35       list      Specifies the search list returned by XrmQGetSearchList.
36
37       list_length
38                 Specifies the number of entries (not the byte size) allocated
39                 for list_return.
40
41       list_return
42                 Returns a search list for further use.
43
44       name      Specifies the resource name.
45
46       names     Specifies a list of resource names.
47
48       quark_class
49                 Specifies the fully qualified class of the value being
50                 retrieved (as a quark).
51
52       quark_name
53                 Specifies the fully qualified name of the value being
54                 retrieved (as a quark).
55
56       quark_type_return
57                 Returns the representation type of the destination (as a
58                 quark).
59
60       str_class Specifies the fully qualified class of the value being
61                 retrieved (as a string).
62
63       str_name  Specifies the fully qualified name of the value being
64                 retrieved (as a string).
65
66       str_type_return
67                 Returns the representation type of the destination (as a
68                 string).
69
70       type_return
71                 Returns data representation type.
72
73       value_return
74                 Returns the value in the database.
75

DESCRIPTION

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
83       The database only frees or overwrites entries on XrmPutResource,
84       XrmQPutResource, or XrmMergeDatabases.  A client that is not storing
85       new values into the database or is not merging the database should be
86       safe using the address passed back at any time until it exits.  If a
87       resource was found, both XrmGetResource and XrmQGetResource return
88       True; otherwise, they return False.
89
90       The XrmQGetSearchList function takes a list of names and classes and
91       returns a list of database levels where a match might occur.  The
92       returned 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
97       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
102       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
106       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
111       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
113       XrmQGetSearchResource with the last component name and class returns
114       the same database entry as XrmGetResource and XrmQGetResource with the
115       fully qualified name and class.
116

MATCHING RULES

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
122       to 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
126       period (.) 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 spec‐
130       ified.  The lookup algorithm searches the database for the entry that
131       most closely matches (is most specific for) the full name and class
132       being queried.  When more than one database entry matches the full name
133       and class, precedence rules are used to select just one.
134
135       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
138       entry is determined, and these matching components and bindings are
139       compared according to precedence rules.  Each of the rules is applied
140       at each level before moving to the next level, until a rule selects a
141       single entry over all others.  The rules, in order of precedence, are:
142
143       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
148       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
151            entries that match using the character ``?''.
152
153       3.   An entry preceded by a tight binding takes precedence over entries
154            preceded by a loose binding.
155

SEE ALSO

157       XrmInitialize(3), XrmMergeDatabases(3), XrmPutResource(3), XrmUnique‐
158       Quark(3)
159       Xlib - C Language X Interface
160
161
162
163X Version 11                     libX11 1.6.5                XrmGetResource(3)
Impressum