1MrmOpenHierarchyPerDisplay(library callM)rmOpenHierarchyPerDisplay(library call)
2
3
4
6 MrmOpenHierarchyPerDisplay — Allocates a hierarchy ID and opens all the
7 UID files in the hierarchy
8
10 #include <Mrm/MrmPublic.h>
11 Cardinal MrmOpenHierarchyPerDisplay(
12 Display *display,
13 MrmCount num_files,
14 String file_names_list[],
15 MrmOsOpenParamPtr *ancillary_structures_list,
16 MrmHierarchy *hierarchy_id);
17
19 MrmOpenHierarchyPerDisplay allows you to specify the list of UID files
20 that MRM searches in subsequent fetch operations. All subsequent fetch
21 operations return the first occurrence of the named item encountered
22 while traversing the UID hierarchy from the first list element (UID
23 file specification) to the last list element. This function also allo‐
24 cates a hierarchy ID and opens all the UID files in the hierarchy. It
25 initializes the optimized search lists in the hierarchy. If MrmOpen‐
26 HierarchyPerDisplay encounters any errors during its execution, any
27 files that were opened are closed.
28
29 The application must call XtAppInitialize before calling MrmOpenHierar‐
30 chyPerDisplay.
31
32 display Specifies the connection to the X server and the value to
33 pass to XtResolvePathname. For more information on the Dis‐
34 play structure, see the Xlib function XOpenDisplay.
35
36 num_files Specifies the number of files in the name list.
37
38 file_names_list
39 Specifies an array of character strings that identify the UID
40 files.
41
42 ancillary_structures_list
43 A list of operating-system-dependent ancillary structures
44 corresponding to items such as filenames, clobber flags, and
45 so forth. This argument should be NULL for most operations.
46 If you need to reference this structure, see the definition
47 of MrmOsOpenParamPtr in the MrmPublic.h header file for more
48 information.
49
50 hierarchy_id
51 Returns the search hierarchy ID. The search hierarchy ID
52 identifies the list of UID files that MRM searches (in order)
53 when performing subsequent fetch calls.
54
55 Each UID file string in file_names_list can specify either a full path‐
56 name or a filename. If a UID file string has a leading / (slash), it
57 specifies a full pathname, and MRM opens the file as specified. Other‐
58 wise, the UID file string specifies a filename. In this case MRM looks
59 for the file along a search path specified by the UIDPATH environment
60 variable or by a default search path, which varies depending on whether
61 or not the XAPPLRESDIR environment variable is set.
62
63 The UIDPATH environment variable specifies a search path and naming
64 conventions associated with UID files. It can contain the substitution
65 field %U, where the UID file string from the file_names_list argument
66 to MrmOpenHierarchyPerDisplay is substituted for %U. It can also con‐
67 tain the substitution fields accepted by XtResolvePathname. The sub‐
68 stitution field %T is always mapped to uid. The entire path is
69 searched first with %S mapped to .uid. If no file is found, it is
70 searched again with %S mapped to NULL. For example, the following UID‐
71 PATH value and MrmOpenHierarchyPerDisplay call cause MRM to open two
72 separate UID files:
73
74 UIDPATH=/uidlib/%L/%U.uid:/uidlib/%U/%L
75 static char *uid_files[] = {"/usr/users/me/test.uid", "test2"};
76 MrmHierarchy *Hierarchy_id;
77 MrmOpenHierarchyPerDisplay((MrmCount)2,uid_files, NULL, Hierarchy_id)
78
79 MRM opens the first file, /usr/users/me/test.uid, as specified in the
80 file_names_list argument to MrmOpenHierarchyPerDisplay, because the UID
81 file string in the file_names_list argument specifies a full pathname.
82 MRM looks for the second file, test2, first as /uidlib/%L/test2.uid and
83 second as /uidlib/test2/%L, where the display's language string is sub‐
84 stituted for %L.
85
86 After MrmOpenHierarchyPerDisplay opens the UID hierarchy, you should
87 not delete or modify the UID files until you close the UID hierarchy by
88 calling MrmCloseHierarchy.
89
90 If UIDPATH is not set, but the environment variable XAPPLRESDIR is set,
91 MRM searches the following pathnames:
92
93 · %U%S
94
95 · $XAPPLRESDIR/%L/uid/%N/%U%S
96
97 · $XAPPLRESDIR/%l/uid/%N/%U%S
98
99 · $XAPPLRESDIR/uid/%N/%U%S
100
101 · $XAPPLRESDIR/%L/uid/%U%S
102
103 · $XAPPLRESDIR/%l/uid/%U%S
104
105 · $XAPPLRESDIR/uid/%U%S
106
107 · $HOME/uid/%U%S
108
109 · $HOME/%U%S
110
111 · /usr/lib/X11/%L/uid/%N/%U%S
112
113 · /usr/lib/X11/%l/uid/%N/%U%S
114
115 · /usr/lib/X11/uid/%N/%U%S
116
117 · /usr/lib/X11/%L/uid/%U%S
118
119 · /usr/lib/X11/%l/uid/%U%S
120
121 · /usr/lib/X11/uid/%U%S
122
123 · /usr/include/X11/uid/%U%S
124
125 If neither UIDPATH nor XAPPLRESDIR is set, MRM searches the following
126 pathnames:
127
128 · %U%S
129
130 · $HOME/%L/uid/%N/%U%S
131
132 · $HOME/%l/uid/%N/%U%S
133
134 · $HOME/uid/%N/%U%S
135
136 · $HOME/%L/uid/%U%S
137
138 · $HOME/%l/uid/%U%S
139
140 · $HOME/uid/%U%S
141
142 · $HOME/%U%S
143
144 · /usr/lib/X11/%L/uid/%N/%U%S
145
146 · /usr/lib/X11/%l/uid/%N/%U%S
147
148 · /usr/lib/X11/uid/%N/%U%S
149
150 · /usr/lib/X11/%L/uid/%U%S
151
152 · /usr/lib/X11/%l/uid/%U%S
153
154 · /usr/lib/X11/uid/%U%S
155
156 · /usr/include/X11/uid/%U%S
157
158 These paths are defaults that vendors may change. For example, a ven‐
159 dor may use different directories for /usr/lib/X11 and
160 /usr/include/X11.
161
162 The following substitutions are used in these paths:
163
164 %U The UID file string, from the file_names_list argument.
165
166 %N The class name of the application.
167
168 %L The display's language string. This string is influenced by
169 XtSetLanguageProc. The default string is determined by call‐
170 ing setlocale(LC_ALL, NULL).
171
172 %l The language component of the display's language string.
173
174 %S The suffix to the filename. The entire path is first
175 searched with a suffix of .uid. If no file is found, it is
176 searched again with a NULL suffix.
177
179 This function returns one of the following status return constants:
180
181 MrmSUCCESS
182 The function executed successfully.
183
184 MrmNOT_FOUND
185 File not found.
186
187 MrmFAILURE
188 The function failed.
189
191 MrmCloseHierarchy(3).
192
193
194
195 MrmOpenHierarchyPerDisplay(library call)