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, Xr‐
17              mValue *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 re‐
50                 trieved (as a quark).
51
52       quark_name
53                 Specifies the fully qualified name of  the  value  being  re‐
54                 trieved (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  re‐
61                 trieved (as a string).
62
63       str_name  Specifies  the  fully  qualified  name of the value being re‐
64                 trieved (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, 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
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 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
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  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

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  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
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  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
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 entries
151            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.8.1                XrmGetResource(3)
Impressum