XrmGetFileDatabase(3X11)XrmGetFileDatabase(3X11)NAME
XrmGetFileDatabase, XrmPutFileDatabase, XrmGetStringDatabase, XrmLoca‐
leOfDatabase, XrmGetDatabase, XrmSetDatabase, XrmDestroyDatabase -
retrieve and store resource databases
SYNOPSIS
XrmDatabase XrmGetFileDatabase(filename)
char *filename;
void XrmPutFileDatabase(database, stored_db)
XrmDatabase database;
char *stored_db;
XrmDatabase XrmGetStringDatabase(data)
char *data;
char *XrmLocaleOfDatabase(database)
XrmDatabase database;
XrmDatabase XrmGetDatabase(display)
Display *display;
void XrmSetDatabase(display, database)
Display *display;
XrmDatabase database;
void XrmDestroyDatabase(database)
XrmDatabase database;
ARGUMENTS
Specifies the resource database file name. Specifies the database that
is to be used. Specifies the file name for the stored database. Spec‐
ifies the database contents using a string. Specifies the resource
database. 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 implementa‐
tion dependent. The file is parsed in the current locale, and the
database is created in the current locale. If it cannot open the speci‐
fied 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 contain‐
ing 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 repre‐
sentation types other than “String” are ignored.
The XrmGetStringDatabase function creates a new database and stores the
resources specified in the specified null-terminated string. XrmGet‐
StringDatabase 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 data‐
base 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 associ‐
ated 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 termi‐
nated 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 = "#" White‐
Space "include" WhiteSpace FileName
WhiteSpace FileName = <valid file‐
name for operating system> ResourceSpec = WhiteSpace Resource‐
Name WhiteSpace ":" WhiteSpace
Value ResourceName = [Binding] {Compo‐
nent Binding} ComponentName Binding = "." | "*" White‐
Space = {<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 con‐
tents 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 direc‐
tory 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 con‐
tain 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 sin‐
gle backslash.
SEE ALSOXrmGetResource(3X11), XrmInitialize(3X11), XrmPutResource(3X11)
Xlib -- C Language X Interface
XrmGetFileDatabase(3X11)
