NAME
XrmGetFileDatabase, XrmPutFileDatabase, XrmGetStringDatabase,
XrmLocaleOfDatabase, XrmGetDatabase, XrmSetDatabase, XrmDestroyDatabase -
retrieve and store resource databases
SYNTAX
#include
<X11/Xresource.h>
XrmDatabase
XrmGetFileDatabase(char * filename);
void
XrmPutFileDatabase(XrmDatabase database, char *
stored_db);
XrmDatabase
XrmGetStringDatabase(char * data,
char
*XrmLocaleOfDatabase(XrmDatabase database);
XrmDatabase
XrmGetDatabase(Display * display);
void
XrmSetDatabase(Display * display, XrmDatabase database);
void
XrmDestroyDatabase(XrmDatabase database);
ARGUMENTS
- filename
- Specifies the resource database file name.
- database
- Specifies the database that is to be used.
- stored_db
- Specifies the file name for the stored database.
- data
- Specifies the database contents using a string.
- database
- Specifies the resource database.
- display
- Specifies the connection to the X server.
DESCRIPTION
The
XrmGetFileDatabase function opens the specified file, creates a new
resource database, and loads it with the specifications read in from the
specified file. The specified file should contain a sequence of entries in
valid ResourceLine format (see section 15.1); the database that results from
reading a file with incorrect syntax is implementation-dependent. The file is
parsed in the current locale, and the database is created in the current
locale. If it cannot open the specified file,
XrmGetFileDatabase
returns NULL.
The
XrmPutFileDatabase function stores a copy of the specified database
in the specified file. Text is written to the file as a sequence of entries in
valid ResourceLine format (see section 15.1). The file is written in the
locale of the database. Entries containing resource names that are not in the
Host Portable Character Encoding or containing values that are not in the
encoding of the database locale, are written in an implementation-dependent
manner. The order in which entries are written is implementation-dependent.
Entries with representation types other than ``String'' are ignored.
The
XrmGetStringDatabase function creates a new database and stores the
resources specified in the specified null-terminated string.
XrmGetStringDatabase is similar to
XrmGetFileDatabase except
that it reads the information out of a string instead of out of a file. The
string should contain a sequence of entries in valid ResourceLine format (see
section 15.1) terminated by a null character; the database that results from
using a string with incorrect syntax is implementation-dependent. The string
is parsed in the current locale, and the database is created in the current
locale.
If database is NULL,
XrmDestroyDatabase returns immediately.
The
XrmLocaleOfDatabase function returns the name of the locale bound to
the specified database, as a null-terminated string. The returned locale name
string is owned by Xlib and should not be modified or freed by the client.
Xlib is not permitted to free the string until the database is destroyed.
Until the string is freed, it will not be modified by Xlib.
The
XrmGetDatabase function returns the database associated with the
specified display. It returns NULL if a database has not yet been set.
The
XrmSetDatabase function associates the specified resource database
(or NULL) with the specified display. The database previously associated with
the display (if any) is not destroyed. A client or toolkit may find this
function convenient for retaining a database once it is constructed.
FILE SYNTAX
The syntax of a resource file is a sequence of resource lines terminated by
newline characters or the end of the file. The syntax of an individual
resource line is:
ResourceLine = Comment | IncludeFile | ResourceSpec | <empty line>
Comment = "!" {<any character except null or newline>}
IncludeFile = "#" WhiteSpace "include" WhiteSpace FileName WhiteSpace
FileName = <valid filename for operating system>
ResourceSpec = WhiteSpace ResourceName WhiteSpace ":" WhiteSpace Value
ResourceName = [Binding] {Component Binding} ComponentName
Binding = "." | "*"
WhiteSpace = {<space> | <horizontal tab>}
Component = "?" | ComponentName
ComponentName = NameChar {NameChar}
NameChar = "a"-"z" | "A"-"Z" | "0"-"9" | "_" | "-"
Value = {<any character except null or unescaped newline>}
Elements separated by vertical bar (|) are alternatives. Curly braces ({...})
indicate zero or more repetitions of the enclosed elements. Square brackets
([...]) indicate that the enclosed element is optional. Quotes
("...") are used around literal characters.
IncludeFile lines are interpreted by replacing the line with the contents of the
specified file. The word ``include'' must be in lowercase. The file name is
interpreted relative to the directory of the file in which the line occurs
(for example, if the file name contains no directory or contains a relative
directory specification).
If a ResourceName contains a contiguous sequence of two or more Binding
characters, the sequence will be replaced with single ``.'' character if the
sequence contains only ``.'' characters; otherwise, the sequence will be
replaced with a single ``*'' character.
A resource database never contains more than one entry for a given ResourceName.
If a resource file contains multiple lines with the same ResourceName, the
last line in the file is used.
Any white space characters before or after the name or colon in a ResourceSpec
are ignored. To allow a Value to begin with white space, the two-character
sequence ``\
space'' (backslash followed by space) is recognized and
replaced by a space character, and the two-character sequence ``\
tab''
(backslash followed by horizontal tab) is recognized and replaced by a
horizontal tab character. To allow a Value to contain embedded newline
characters, the two-character sequence ``\n'' is recognized and replaced by a
newline character. To allow a Value to be broken across multiple lines in a
text file, the two-character sequence ``\
newline'' (backslash followed
by newline) is recognized and removed from the value. To allow a Value to
contain arbitrary character codes, the four-character sequence ``\
nnn'', where each
n is a digit character in the range of
``0''-``7'', is recognized and replaced with a single byte that contains the
octal value specified by the sequence. Finally, the two-character sequence
``\\'' is recognized and replaced with a single backslash.
SEE ALSO
XrmGetResource(3), XrmInitialize(3), XrmPutResource(3)
Xlib - C Language X Interface