Tribblix: manual page: XrmGetFileDatabase.3

XrmGetFileDatabase(3) XLIB FUNCTIONS XrmGetFileDatabase(3)

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, _Xconst char
*stored_db);

XrmDatabase XrmGetStringDatabase(_Xconst char *data);

const 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.

NAME

SYNTAX

ARGUMENTS

DESCRIPTION

FILE SYNTAX

SEE ALSO