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

NAME

6       XrmGetFileDatabase,  XrmPutFileDatabase, XrmGetStringDatabase, XrmLoca‐
7       leOfDatabase,  XrmGetDatabase,  XrmSetDatabase,  XrmDestroyDatabase   -
8       retrieve and store resource databases
9

SYNTAX

11       #include <X11/Xresource.h>
12
13       XrmDatabase XrmGetFileDatabase(char *filename);
14
15       void XrmPutFileDatabase(XrmDatabase database, _Xconst char *stored_db);
16
17       XrmDatabase XrmGetStringDatabase(_Xconst char *data);
18
19       const char *XrmLocaleOfDatabase(XrmDatabase database);
20
21       XrmDatabase XrmGetDatabase(Display *display);
22
23       void XrmSetDatabase(Display *display, XrmDatabase database);
24
25       void XrmDestroyDatabase(XrmDatabase database);
26

ARGUMENTS

28       filename  Specifies the resource database file name.
29
30       database  Specifies the database that is to be used.
31
32       stored_db Specifies the file name for the stored database.
33
34       data      Specifies the database contents using a string.
35
36       database  Specifies the resource database.
37
38       display   Specifies the connection to the X server.
39

DESCRIPTION

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
50       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
60       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
70       If database is NULL, XrmDestroyDatabase returns immediately.
71
72       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
79       The  XrmGetDatabase  function  returns the database associated with the
80       specified display.  It returns NULL if a database has not yet been set.
81
82       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

FILE SYNTAX

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
93       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
106       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
111       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
117       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
122       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
126       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

SEE ALSO

144       XrmGetResource(3), XrmInitialize(3), XrmPutResource(3)
145       Xlib - C Language X Interface
146
147
148
149X Version 11                     libX11 1.6.12           XrmGetFileDatabase(3)
Impressum