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

NAME

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

SYNTAX

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

ARGUMENTS

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

DESCRIPTION

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
81       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
88       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
95       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
100       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
104       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
109       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

MATCHING RULES

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
133       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
141       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
146       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
151       3.   An entry preceded by a tight binding takes precedence over entries
152            preceded by a loose binding.
153

SEE ALSO

155       XrmInitialize(3X11), XrmMergeDatabases(3X11), XrmPutResource(3X11),
156       XrmUniqueQuark(3X11)
157       Xlib - C Language X Interface
158
159
160
161X Version 11                     libX11 1.0.3             XrmGetResource(3X11)
Impressum