1XrmGetFileDatabase(3) XLIB FUNCTIONS XrmGetFileDatabase(3)
2
6 XrmGetFileDatabase, XrmPutFileDatabase, XrmGetStringDatabase, XrmLoca‐
7 leOfDatabase, XrmGetDatabase, XrmSetDatabase, XrmDestroyDatabase -
8 retrieve and store resource databases
9
11 #include <X11/Xresource.h>
12 XrmDatabase XrmGetFileDatabase(char *filename);
14 void XrmPutFileDatabase(XrmDatabase database, _Xconst char *stored_db);
16 XrmDatabase XrmGetStringDatabase(_Xconst char *data);
18 const char *XrmLocaleOfDatabase(XrmDatabase database);
20 XrmDatabase XrmGetDatabase(Display *display);
22 void XrmSetDatabase(Display *display, XrmDatabase database);
24 void XrmDestroyDatabase(XrmDatabase database);
26
28 filename Specifies the resource database file name.
29 database Specifies the database that is to be used.
31 stored_db Specifies the file name for the stored database.
33 data Specifies the database contents using a string.
35 database Specifies the resource database.
37 display Specifies the connection to the X server.
39
41 The XrmGetFileDatabase function opens the specified file, creates a new
42 resource database, and loads it with the specifications read in from
43 the specified file. The specified file should contain a sequence of
44 entries in valid ResourceLine format (see section 15.1); the database
45 that results from reading a file with incorrect syntax is implementa‐
46 tion-dependent. The file is parsed in the current locale, and the
47 database is created in the current locale. If it cannot open the spec‐
48 ified file, XrmGetFileDatabase returns NULL.
49 The XrmPutFileDatabase function stores a copy of the specified database
51 in the specified file. Text is written to the file as a sequence of
52 entries in valid ResourceLine format (see section 15.1). The file is
53 written in the locale of the database. Entries containing resource
54 names that are not in the Host Portable Character Encoding or contain‐
55 ing values that are not in the encoding of the database locale, are
56 written in an implementation-dependent manner. The order in which
57 entries are written is implementation-dependent. Entries with repre‐
58 sentation types other than “String” are ignored.
59 The XrmGetStringDatabase function creates a new database and stores the
61 resources specified in the specified null-terminated string. XrmGet‐
62 StringDatabase is similar to XrmGetFileDatabase except that it reads
63 the information out of a string instead of out of a file. The string
64 should contain a sequence of entries in valid ResourceLine format (see
65 section 15.1) terminated by a null character; the database that results
66 from using a string with incorrect syntax is implementation-dependent.
67 The string is parsed in the current locale, and the database is created
68 in the current locale.
69 If database is NULL, XrmDestroyDatabase returns immediately.
71 The XrmLocaleOfDatabase function returns the name of the locale bound
73 to the specified database, as a null-terminated string. The returned
74 locale name string is owned by Xlib and should not be modified or freed
75 by the client. Xlib is not permitted to free the string until the
76 database is destroyed. Until the string is freed, it will not be modi‐
77 fied by Xlib.
78 The XrmGetDatabase function returns the database associated with the
80 specified display. It returns NULL if a database has not yet been set.
81 The XrmSetDatabase function associates the specified resource database
83 (or NULL) with the specified display. The database previously associ‐
84 ated with the display (if any) is not destroyed. A client or toolkit
85 may find this function convenient for retaining a database once it is
86 constructed.
87
89 The syntax of a resource file is a sequence of resource lines termi‐
90 nated by newline characters or the end of the file. The syntax of an
91 individual resource line is:
92 ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line>
94 Comment = "!" {<any character except null or newline>}
95 IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
96 FileName = <valid filename for operating system>
97 ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
98 ResourceName = [Binding] {Component Binding} ComponentName
99 Binding = "." | "*"
100 WhiteSpace = {<space> | <horizontal tab>}
101 Component = "?" | ComponentName
102 ComponentName = NameChar {NameChar}
103 NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
104 Value = {<any character except null or unescaped newline>}
105 Elements separated by vertical bar (|) are alternatives. Curly braces
107 ({...}) indicate zero or more repetitions of the enclosed elements.
108 Square brackets ([...]) indicate that the enclosed element is optional.
109 Quotes ("...") are used around literal characters.
110 IncludeFile lines are interpreted by replacing the line with the con‐
112 tents of the specified file. The word “include” must be in lowercase.
113 The file name is interpreted relative to the directory of the file in
114 which the line occurs (for example, if the file name contains no direc‐
115 tory or contains a relative directory specification).
116 If a ResourceName contains a contiguous sequence of two or more Binding
118 characters, the sequence will be replaced with single “.” character if
119 the sequence contains only “.” characters; otherwise, the sequence will
120 be replaced with a single “*” character.
121 A resource database never contains more than one entry for a given
123 ResourceName. If a resource file contains multiple lines with the same
124 ResourceName, the last line in the file is used.
125 Any white space characters before or after the name or colon in a
127 ResourceSpec are ignored. To allow a Value to begin with white space,
128 the two-character sequence “\space” (backslash followed by space) is
129 recognized and replaced by a space character, and the two-character
130 sequence “\tab” (backslash followed by horizontal tab) is recognized
131 and replaced by a horizontal tab character. To allow a Value to con‐
132 tain embedded newline characters, the two-character sequence “\n” is
133 recognized and replaced by a newline character. To allow a Value to be
134 broken across multiple lines in a text file, the two-character sequence
135 “\newline” (backslash followed by newline) is recognized and removed
136 from the value. To allow a Value to contain arbitrary character codes,
137 the four-character sequence “\nnn”, where each n is a digit character
138 in the range of “0”-“7”, is recognized and replaced with a single byte
139 that contains the octal value specified by the sequence. Finally, the
140 two-character sequence “\\” is recognized and replaced with a single
141 backslash.
142
144 XrmGetResource(3), XrmInitialize(3), XrmPutResource(3)
145 Xlib - C Language X Interface
146X Version 11 libX11 1.6.12 XrmGetFileDatabase(3)