XrmGetFileDatabase(3X11) XLIB FUNCTIONS XrmGetFileDatabase(3X11)
NAME
XrmGetFileDatabase, XrmPutFileDatabase, XrmGetString-
Database, XrmLocaleOfDatabase, XrmGetDatabase, XrmSet-
Database, XrmDestroyDatabase - retrieve and store resource
databases
SYNTAX
XrmDatabase XrmGetFileDatabase(filename)
char *filename;
void XrmPutFileDatabase(database, storeddb)
XrmDatabase database;
char *storeddb;
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
filename Specifies the resource database file name.
database Specifies the database that is to be used.
storeddb 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 spec-
ified file must contain a sequence of entries in valid
ResourceLine format (see section 15.1). 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
X Version 11 Release 5 1
XrmGetFileDatabase(3X11) XLIB FUNCTIONS XrmGetFileDatabase(3X11)
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 must
contain a sequence of entries in valid ResourceLine format
(see section 15.1). The string is parsed in the current
locale, and the database is created in the current locale.
If database is NULL, XrmDestroyDatabase returns immedi-
ately.
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 associ-
ated 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 end of 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 = "." | "*"
X Version 11 Release 5 2
XrmGetFileDatabase(3X11) XLIB FUNCTIONS XrmGetFileDatabase(3X11)
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 filename is inter-
preted relative to the directory of the file in which the
line occurs (for example, if the filename 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 multi-
ple lines with the same ResourceName, the last line in the
file is used.
Any whitespace character before or after the name or colon
in a ResourceSpec are ignored. To allow a Value to begin
with whitespace, 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 recog-
nized 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(3X11), XrmInitialize(3X11), XrmPutRe-
source(3X11)
Xlib - C Language X Interface
X Version 11 Release 5 3