UIL

title: UIL(5)

summary: The user interface language file format

text:
# UIL(5)

## NAME
UIL — The user interface language file format

## SYNOPSIS

```
MODULE module_name
[ NAMES = CASE_INSENSITIVE | CASE_SENSITIVE ]
[ CHARACTER_SET = character_set ]
[ OBJECTS = { widget_name = GADGET | WIDGET; [...] } ]
{ [
[ value_section ] |
[ procedure_section ] |
[ list_section ] |
[ object_section ] |
[ identifier_section ]
[ ... ]
] }
END MODULE;
```

## DESCRIPTION
The UIL language is used for describing the initial state of a user interface for a widget based application. UIL describes the widgets used in the interface, the resources of those widgets, and the callbacks of those widgets. The UIL file is compiled into a UID file using the command uil or by the callable compiler Uil(). The contents of the compiled UID file can then be accessed by the various Motif Resource Management (MRM) functions from within an application program.

The UID file is independent of the platform on which the Motif program will eventually be run. In other words, the same UID file can be used on any system that can run Motif.

### File
A UIL file consists of a single complete module, described in the syntax description above, or, if the file is to be included in a larger UIL file, one complete "section," as described below. UIL uses five different kinds of sections: value, procedure, list, object, and identifier.

UIL is a free-form language. This means that high-level constructs such as object and value declarations do not need to begin in any particular column and can span any number of lines. Low-level constructs such as keywords and punctuation characters can also begin in any column; however, except for string literals and comments, they cannot span lines.

The UIL compiler accepts input lines up to 132 characters in length.

MODULE module_name

The name by which the UIL module is known in the UID file. This name is stored in the UID file for later use in the retrieval of resources by the MRM. This name is always stored in uppercase in the UID file.

NAMES = CASE_INSENSITIVE | CASE_SENSITIVE

Indicates whether names should be treated as case sensitive or case insensitive. The default is case sensitive. The case-sensitivity clause should be the first clause in the module header, and in any case must precede any statement that contains a name. If names are case sensitive in a UIL module, UIL keywords in that module must be in lowercase. Each name is stored in the UIL file in the same case as it appears in the UIL module. If names are case insensitive, then keywords can be in uppercase, lowercase, or mixed case, and the uppercase equivalent of each name is stored in the UID file.

CHARACTER_SET = character_set

Specifies the default character set for string literals in the module that do not explicitly set their character set. The default character set, in the absence of this clause is the codeset component of the LANG environment variable, or the value of XmFALLBACK_CHARSET if LANG is not set or has no codeset component. The value of XmFALLBACK_CHARSET is defined by the UIL supplier, but is usually ISO8859-1 (equivalent to ISO_LATIN1). Use of this clause turns off all localized string literal processing turned on by the compiler flag -s or the Uil_command_type data structure element use_setlocale_flag.

OBJECTS = { widget_name = GADGET | WIDGET; }

Indicates whether the widget or gadget form of the control specified by widget_name is used by default. By default the widget form is used, so the gadget keyword is usually the only one used. The specified control should be one that has both a widget and gadget version: XmCascadeButton, XmLabel, XmPushButton, XmSeparator, and XmToggleButton. The form of more than one control can be specified by delimiting them with semicolons. The gadget or widget form of an instance of a control can be specified with the GADGET and WIDGET keywords in a particular object declaration.

value_section

Provides a way to name a value expression or literal. The value name can then be referred to by declarations that occur elsewhere in the UIL module in any context where a value can be used. Values can be forward referenced. Value sections are described in more detail later in the reference page.

procedure_section

Defines the callback routines used by a widget and the creation routines for user-defined widgets. These definitions are used for error checking. Procedure sections are described in more detail later in the reference page.

list_section

Provides a way to group together a set of arguments, controls (children), callbacks, or procedures for later use in the UIL module. Lists can contain other lists, so that you can set up a hierarchy to clearly show which arguments, controls, callbacks, and procedures are common to which widgets. List sections are described in more detail later in the reference page.

object_section

Defines the objects that make up the user interface of the application. You can reference the object names in declarations that occur elsewhere in the UIL module in any context where an object name can be used (for example, in a controls list, as a symbolic reference to a widget ID, or as the tag_value argument for a callback procedure). Objects can be forward referenced. Object sections are described in more detail later in the reference page.

identifier_section

Defines a run-time binding of data to names that appear in the UIL module. Identifier sections are described in more detail later in the reference page.

The UIL file can also contain comments and include directives, which are described along with the main elements of the UIL file format in the following sections.

### Comments
Comments can take one of two forms, as follows:

•

The comment is introduced with the sequence /* followed by the text of the comment and terminated with the sequence */. This form of comment can span multiple source lines.

•

The comment is introduced with an ! (exclamation point), followed by the text of the comment and terminated by the end of the source line.

Neither form of comment can be nested.

### Value sections
A value section consists of the keyword VALUE followed by a sequence of value declarations. It has the following syntax:

VALUE value_name : [ EXPORTED | PRIVATE ] value_expression | IMPORTED value_type ;

Where value_expression is assigned to value_name or a value_type is assigned to an imported value name. A value declaration provides a way to name a value expression or literal. The value name can be referred to by declarations that occur later in the UIL module in any context where a value can be used. Values can be forward referenced.

EXPORTED

A value that you define as exported is stored in the UID file as a named resource, and therefore can be referenced by name in other UID files. When you define a value as exported, MRM looks outside the module in which the exported value is declared to get its value at run time.

PRIVATE

A private value is a value that is not imported or exported. A value that you define as private is not stored as a distinct resource in the UID file. You can reference a private value only in the UIL module containing the value declaration. The value or object is directly incorporated into anything in the UIL module that references the declaration.

IMPORTED

A value that you define as imported is one that is defined as a named resource in a UID file. MRM resolves this declaration with the corresponding exported declaration at application run time.

By default, values and objects are private. The following is a list of the supported value types in UIL:

•

ANY

•

ARGUMENT

•

BOOLEAN

•

COLOR

•

COLOR_TABLE

•

COMPOUND_STRING

•

FLOAT

•

FONT

•

FONT_TABLE

•

FONTSET

•

ICON

•

INTEGER

•

INTEGER_TABLE

•

KEYSYM

•

REASON

•

SINGLE_FLOAT

•

STRING

•

STRING_TABLE

•

TRANSLATION_TABLE

•

WIDE_CHARACTER

•

WIDGET

### Procedure sections
A procedure section consists of the keyword PROCEDURE followed by a sequence of procedure declarations. It has the following syntax:

```
PROCEDURE

     procedure_name [ ( [ value_type ]) ];
```

Use a procedure declaration to declare

•

A routine that can be used as a callback routine for a widget

•

The creation function for a user-defined widget

You can reference a procedure name in declarations that occur later in the UIL module in any context where a procedure can be used. Procedures can be forward referenced. You cannot use a name you used in another context as a procedure name.

In a procedure declaration, you have the option of specifying that a parameter will be passed to the corresponding callback routine at run time. This parameter is called the callback tag. You can specify the data type of the callback tag by putting the data type in parentheses following the procedure name. When you compile the module, the UIL compiler checks that the argument you specify in references to the procedure is of this type. Note that the data type of the callback tag must be one of the valid UIL data types. You can use a widget as a callback tag, as long as the widget is defined in the same widget hierarchy as the callback, that is they have a common ancestor that is in the same UIL hierarchy.

The following list summarizes how the UIL compiler checks argument type and argument count, depending on the procedure declaration.

No parameters

No argument type or argument count checking occurs. You can supply either 0 or one arguments in the procedure reference.

( )

Checks that the argument count is 0 (zero).

(ANY)

Checks that the argument count is 1. Does not check the argument type. Use the ANY type to prevent type checking on procedure tags.

(type)

Checks for one argument of the specified type.

(class_name)

Checks for one widget argument of the specified widget class.

While it is possible to use any UIL data type to specify the type of a tag in a procedure declaration, you must be able to represent that data type in the programming language you are using. Some data types (such as integer, Boolean, and string) are common data types recognized by most programming languages. Other UIL data types (such as string tables) are more complicated and may require that you set up an appropriate corresponding data structure in the application in order to pass a tag of that type to a callback routine.

You can also use a procedure declaration to specify the creation function for a user-defined widget. In this case, you specify no formal parameters. The procedure is invoked with the standard three arguments passed to all widget creation functions. (See the Motif Toolkit documentation for more information about widget creation functions.)

### List sections
A list section consists of the keyword LIST followed by a sequence of list declarations. It has the following syntax:

```
LIST

     list_name: { list_item; [...] }

     [...]
```

You can also use list sections to group together a set of arguments, controls (children), callbacks, or procedures for later use in the UIL module. Lists can contain other lists, so that you can set up a hierarchy to clearly show which arguments, controls, callbacks, and procedures are common to which widgets. You cannot mix the different types of lists; a list of a particular type cannot contain entries of a different list type or reference the name of a different list type. A list name is always private to the UIL module in which you declare the list and cannot be stored as a named resource in a UID file.

The additional list types are described in the following sections.

Arguments List Structure

An arguments list defines which arguments are to be specified in the arguments list parameter when the creation routine for a particular object is called at run time. An arguments list also specifies the values for those arguments. Argument lists have the following syntax:

```
LIST

     list_name: ARGUMENTS {

          argument_name = value_expression;

          [...] }
[...]
```

The argument name must be either a built-in argument name or a user-defined argument name that is specified with the ARGUMENT function.

If you use a built-in argument name as an arguments list entry in an object definition, the UIL compiler checks the argument name to be sure that it is supported by the type of object that you are defining. If the same argument name appears more than once in a given arguments list, the last entry that uses that argument name supersedes all previous entries with that name, and the compiler issues a message.

Some arguments, such as XmNitems and XmNitemCount, are coupled by the UIL compiler. When you specify one of the arguments, the compiler also sets the other. The coupled argument is not available to you.

The Motif Toolkit and the X Toolkit (intrinsics) support constraint arguments. A constraint argument is one that is passed to children of an object, beyond those arguments normally available. For example, the Form widget grants a set of constraint arguments to its children. These arguments control the position of the children within the Form.

Unlike the arguments used to define the attributes of a particular widget, constraint arguments are used exclusively to define additional attributes of the children of a particular widget. These attributes affect the behavior of the children within their parent. To supply constraint arguments to the children, you include the arguments in the arguments list for the child.

See Appendix B for information about which arguments are supported by which widgets. See Appendix C for information about what the valid value type is for each built-in argument.

Callbacks List Structure

Use a callbacks list to define which callback reasons are to be processed by a particular widget at run time. Callback lists have the following syntax:

LIST list_name : CALLBACKS { reason_name = PROCEDURE procedure_name [ ( [ value_expression ] ) ]; | reason_name = procedure_list ; [...] } [...]

For Motif Toolkit widgets, the reason name must be a built-in reason name. For a user-defined widget, you can use a reason name that you previously specified using the REASON function. If you use a built-in reason in an object definition, the UIL compiler ensures that reason is supported by the type of object you are defining. Appendix B shows which reasons each object supports.

If the same reason appears more than once in a callbacks list, the last entry referring to that name supersedes all previous entries using the same reason, and the UIL compiler issues a diagnostic message.

If you specify a named value for the procedure argument (callback tag), the data type of the value must match the type specified for the callback tag in the corresponding procedure declaration. When specifying a widget name as a procedure value expression you must also specify the type of the widget and a space before the name of the widget.

Because the UIL compiler produces a UID file rather than an object module (.o), the binding of the UIL name to the address of the entry point to the procedure is not done by the loader, but is established at run time with the MRM function MrmRegisterNames. You call this function before fetching any objects, giving it both the UIL names and the procedure addresses of each callback. The name you register with MRM in the application program must match the name you specified for the procedure in the UIL module.

Each callback procedure receives three arguments. The first two arguments have the same form for each callback. The form of the third argument varies from object to object.

The first argument is the address of the data structure maintained by the Motif Toolkit for this object instance. This address is called the widget ID for this object.

The second argument is the address of the value you specified in the callbacks list for this procedure. If you do not specify an argument, the address is NULL. Note that, in the case where the value you specified is a string or an XmString, the value specified in the callbacks list already represents an address rather than an actual value. In the case of a simple string, for example, the value is the address of the first character of that string. In these cases, UIL does not add a level of indirection, and the second argument to the callback procedure is simply the value as specified in the callbacks list.

The third argument is the reason name you specified in the callbacks list.

Controls List Structure

A controls list defines which objects are children of, or controlled by, a particular object. Each entry in a controls list has the following syntax:

```
LIST

     list_name: CONTROLS {

          [child_name: ] [MANAGED | UNMANAGED] object_definition;

          [...] }

     [...]
```

If you specify the keyword MANAGED at run time, the object is created and managed; if you specify UNMANAGED at run time, the object is only created. Objects are managed by default.

You can use child_name to specify resources for the automatically created children of a particular control. Names for automatically created children are formed by appending Xm_ to the name of the child widget. This name is specified in the documentation for the parent widget.

Unlike the arguments list and the callbacks list, a controls list entry that is identical to a previous entry does not supersede the previous entry. At run time, each controls list entry causes a child to be created when the parent is created. If the same object definition is used for multiple children, multiple instances of the child are created at run time. See Appendix B for a list of which widget types can be controlled by which other widget types.

Procedures List Structure

You can specify multiple procedures for a callback reason in UIL by defining a procedures list. Just as with other list types, procedures lists can be defined in-line or in a list section and referenced by name.

If you define a reason more than once (for example, when the reason is defined both in a referenced procedures list and in the callbacks list for the object), previous definitions are overridden by the latest definition. The syntax for a procedures list is as follows:

```
LIST

     list_name: PROCEDURES {

          procedure_name [ ( [ value_expression ]) ];

          [...] }

     [...]
```

When specifying a widget name as a procedure value expression you must also specify the type of the widget and a space before the name of the widget.

### Object Sections
An object section consists of the keyword OBJECT followed by a sequence of object declarations. It has the following syntax:

```
OBJECT object_name:

     [ EXPORTED | PRIVATE | IMPORTED ] object_type

          [ PROCEDURE creation_function ]

          [ object_name [ WIDGET | GADGET ] | {list_definitions } ]
```

Use an object declaration to define the objects that are to be stored in the UID file. You can reference the object name in declarations that occur elsewhere in the UIL module in any context where an object name can be used (for example, in a controls list, as a symbolic reference to a widget ID, or as the tag_value argument for a callback procedure). Objects can be forward referenced; that is, you can declare an object name after you reference it. All references to an object name must be consistent with the type of the object, as specified in the object declaration. You can specify an object as exported, imported, or private.

The object definition can contain a sequence of lists that define the arguments, hierarchy, and callbacks for the widget. You can specify only one list of each type for an object. When you declare a user-defined widget, you must include a reference to the widget creation function for the user-defined widget.

Note: Several widgets in the Motif Toolkit actually consist of two linked widgets. For example, XmScrolledText and XmScrolledList each consist of children XmText and XmList widgets under a XmScrolledWindow widget. When such a widget is created, its resources are available to both of the underlying widgets. This can occasionally cause problems, as when the programmer wants a XmNdestroyCallback routine named to act when the widget is destroyed. In this case, the callback resource will be available to both sub-widgets, and will cause an error when the widget is destroyed. To avoid these problems, the programmer should separately create the parent and child widgets, rather than relying on these linked widgets.

Use the GADGET or WIDGET keyword to specify the object type or to override the default variant for this object type. You can use the Motif Toolkit name of an object type that has a gadget variant (for example, XmLabelGadget) as an attribute of an object declaration. The object_type can be any object type, including gadgets. You need to specify the GADGET or WIDGET keyword only in the declaration of an object, not when you reference the object. You cannot specify the GADGET or WIDGET keyword for a user-defined object; user-defined objects are always widgets.

### Identifier sections
The identifier section allows you to define an identifier, a mechanism that achieves run-time binding of data to names that appear in a UIL module. The identifier section consists of the reserved keyword IDENTIFIER, followed by a list of names, each name followed by a semicolon.

IDENTIFIER identifier_name; [...;]

You can later use these names in the UIL module as either the value of an argument to a widget or the tag value to a callback procedure. At run time, you use the MRM functions MrmRegisterNames and MrmRegisterNamesInHierarchy to bind the identifier name with the data (or, in the case of callbacks, with the address of the data) associated with the identifier.

Each UIL module has a single name space; therefore, you cannot use a name you used for a value, object, or procedure as an identifier name in the same module.

The UIL compiler does not do any type checking on the use of identifiers in a UIL module. Unlike a UIL value, an identifier does not have a UIL type associated with it. Regardless of what particular type a widget argument or callback procedure tag is defined to be, you can use an identifier in that context instead of a value of the corresponding type.

To reference these identifier names in a UIL module, you use the name of the identifier wherever you want its value to be used.

### Include directives
The include directive incorporates the contents of a specified file into a UIL module. This mechanism allows several UIL modules to share common definitions. The syntax for the include directive is as follows:

```
INCLUDE FILE file_name;
```

The UIL compiler replaces the include directive with the contents of the include file and processes it as if these contents had appeared in the current UIL source file.

You can nest include files; that is, an include file can contain include directives. The UIL compiler can process up to 100 references (including the file containing the UIL module). Therefore, you can include up to 99 files in a single UIL module, including nested files. Each time a file is opened counts as a reference, so including the same file twice counts as two references.

The file_name is a simple string containing a file specification that identifies the file to be included. The rules for finding the specified file are similar to the rules for finding header, or .h files using the include directive, #include, with a quoted string in C. The UIL uses the -I option for specifying a search directory for include files.

•

If you do not supply a directory, the UIL compiler searches for the include file in the directory of the main source file.

•

If the compiler does not find the include file there, the compiler looks in the same directory as the source file.

•

If you supply a directory, the UIL compiler searches only that directory for the file.

### Names and Strings
Names can consist of any of the characters A to Z, a to z, 0 to 9, $ (dollar sign), and _ (underscore). Names cannot begin with a digit (0 to 9). The maximum length of a name is 31 characters.

UIL gives you a choice of either case-sensitive or case-insensitive names through a clause in the MODULE header. For example, if names are case sensitive, the names "sample" and "Sample" are distinct from each other. If names are case insensitive, these names are treated as the same name and can be used interchangeably. By default, UIL assumes names are case sensitive.

In CASE-INSENSITIVE mode, the compiler outputs all names in the UID file in uppercase form. In CASE-SENSITIVE mode, names appear in the UIL file exactly as they appear in the source.

The following table lists the reserved keywords, which are not available for defining programmer defined names.

Reserved Keywords

ARGUMENTS

CALLBACKS

CONTROLS

END

EXPORTED

FALSE

GADGET

IDENTIFIER

INCLUDE

LIST

MODULE

OFF

ON

OBJECT

PRIVATE

PROCEDURE

PROCEDURES

TRUE

VALUE

WIDGET

The UIL unreserved keywords are described in the following list and table. These keywords can be used as programmer defined names, however, if you use any keyword as a name, you cannot use the UIL-supplied usage of that keyword.

•

Built-in argument names (for example, XmNx, XmNheight)

•

Built-in reason names (for example, XmNactivateCallback, XmNhelpCallback)

•

Character set names (for example, ISO_LATIN1, ISO_HEBREW_LR)

•

Constant value names (for example, XmMENU_OPTION, XmBROWSE_SELECT)

•

Object types (for example, XmPushButton, XmBulletinBoard) Unreserved Keywords

ANY

ARGUMENT

ASCIZ_STRING_TABLE

ASCIZ_TABLE

BACKGROUND

BOOLEAN

CASE_INSENSITIVE

CASE_SENSITIVE

CHARACTER_SET

COLOR

COLOR_TABLE

COMPOUND_STRING

COMPOUND_STRING_COMPONENT

COMPOUND_STRING_TABLE

FILE

FLOAT

FONT

FONT_TABLE

FONTSET

FOREGROUND

ICON

IMPORTED

INTEGER

INTEGER_TABLE

KEYSYM

MANAGED

NAMES

OBJECTS

REASON

RGB

RIGHT_TO_LEFT

SINGLE_FLOAT

STRING

STRING_TABLE

TRANSLATION_TABLE

UNMANAGED

USER_DEFINED

VERSION

WIDE_CHARACTER

WIDGET

XBITMAPFILE

String literals can be composed of the uppercase and lowercase letters, digits, and punctuation characters. Spaces, tabs, and comments are special elements in the language. They are a means of delimiting other elements, such as two names. One or more of these elements can appear before or after any other element in the language. However, spaces, tabs, and comments that appear in string literals are treated as character sequences rather than delimiters.

### Data Types
UIL provides literals for several of the value types it supports. Some of the value types are not supported as literals (for example, pixmaps and string tables). You can specify values for these types by using functions described in the Functions section. UIL directly supports the following literal types:

•

String literal

•

Integer literal

•

Boolean literal

•

Floating-point literal

UIL also includes the data type ANY, which is used to turn off compile time checking of data types.

### String Literals
A string literal is a sequence of zero or more 8-bit or 16-bit characters or a combination delimited by ' (single quotation marks) or " (double quotation marks). String literals can also contain multibyte characters delimited with double quotation marks. String literals can be no more than 2000 characters long.

A single-quoted string literal can span multiple source lines. To continue a single-quoted string literal, terminate the continued line with a \ (backslash). The literal continues with the first character on the next line.

Double-quoted string literals cannot span multiple source lines. (Because double-quoted strings can contain escape sequences and other special characters, you cannot use the backslash character to designate continuation of the string.) To build a string value that must span multiple source lines, use the concatenation operator described later in this section.

The syntax of a string literal is one of the following:

```
'[character_string]'
[#char_set]"[character_string]"
```

Both string forms associate a character set with a string value. UIL uses the following rules to determine the character set and storage format for string literals:

•

A string declared as 'string' is equivalent to #cur_charset"string", where cur_charset will be the codeset portion of the value of the LANG environment variable if it is set or the value of XmFALLBACK_CHARSET if LANG is not set or has no codeset component. By default, XmFALLBACK_CHARSET is ISO8859-1 (equivalent to ISO_LATIN1), but vendors may define a different default.

•

A string declared as "string" is equivalent to #char_set"string" if you specified char_set as the default character set for the module. If no default character set has been specified for the module, then if the -s option is provided to the uil command or the use_setlocale_flag is set for the callable compiler, Uil(), the string will be interpreted to be a string in the current locale. This means that the string is parsed in the locale of the user by calling setlocale, its charset is XmFONTLIST_DEFAULT_TAG, and that if the string is converted to a compound string, it is stored as a locale encoded text segment. Otherwise, "string" is equivalent to #cur_charset"string", where cur_charset is interpreted as described for single quoted strings.

•

A string of the form "string" or #char_set"string" is stored as a null-terminated string.

If the char_set in a string specified in the form above is not a built-in charset, and is not a user-defined charset, the charset of the string will be set to XmFONTLIST_DEFAULT_TAG, and an informational message will be issued to the user to note that this substitution has been made.

The following table lists the character sets supported by the UIL compiler for string literals. Note that several UIL names map to the same character set. In some cases, the UIL name influences how string literals are read. For example, strings identified by a UIL character set name ending in _LR are read left-to-right. Names that end in a different number reflect different fonts (for example, ISO_LATIN1 or ISO_LATIN6). All character sets in this table are represented by 8 bits.

Supported Character Sets

UIL Name

Description

ISO_LATIN1

GL: ASCII, GR: Latin-1 Supplement

ISO_LATIN2

GL: ASCII, GR: Latin-2 Supplement

ISO_ARABIC

GL: ASCII, GR: Latin-Arabic Supplement

ISO_LATIN6

GL: ASCII, GR: Latin-Arabic Supplement

ISO_GREEK

GL: ASCII, GR: Latin-Greek Supplement

ISO_LATIN7

GL: ASCII, GR: Latin-Greek Supplement

ISO_HEBREW

GL: ASCII, GR: Latin-Hebrew Supplement

ISO_LATIN8

GL: ASCII, GR: Latin-Hebrew Supplement

ISO_HEBREW_LR

GL: ASCII, GR: Latin-Hebrew Supplement

ISO_LATIN8_LR

GL: ASCII, GR: Latin-Hebrew Supplement

JIS_KATAKANA

GL: JIS Roman, GR: JIS Katakana

Following are the parsing rules for each of the character sets:

All character sets

Character codes in the range 00...1F, 7F, and 80...9F are control characters including both bytes of 16-bit characters. The compiler flags these as illegal characters.

ISO_LATIN1 ISO_LATIN2 ISO_LATIN3 ISO_GREEK ISO_LATIN4

These sets are parsed from left to right. The escape sequences for null-terminated strings are also supported by these character sets.

ISO_HEBREW ISO_ARABIC ISO_LATIN8

These sets are parsed from right to left. For example, the string #ISO_HEBREW"012345" will generate a primitive string of "543210" with character set ISO_HEBREW. The string direction for such a string would be right-to-left, so when rendered, the string will appear as "012345." The escape sequences for null-terminated strings are also supported by these character sets, and the characters that compose the escape sequences are in left-to-right order. For example, you would enter \n, not n\.

ISO_HEBREW_LR ISO_ARABIC_LR ISO_LATIN8_LR

These sets are parsed from left to right. For example, the string #ISO_HEBREW_LR"012345" generates a primitive string "012345" with character set ISO_HEBREW. The string direction for such a string would still be right-to-left, however, so when rendered, it will appear as "543210." In other words, the characters were originally typed in the same order in which they would have been typed in Hebrew (although in Hebrew, the typist would have been using a text editor that went from right to left). The escape sequences for null-terminated strings are also supported by these character sets.

JIS_KATAKANA

This set is parsed from left to right. The escape sequences for null-terminated strings are also supported by this character set. Note that the \ (backslash) may be displayed as a yen symbol.

In addition to designating parsing rules for strings, character set information remains an attribute of a compound string. If the string is included in a string consisting of several concatenated segments, the character set information is included with that string segment. This gives the Motif Toolkit the information it needs to decipher the compound string and choose a font to display the string.

For an application interface displayed only in English, UIL lets you ignore the distinctions between the two uses of strings. The compiler recognizes by context when a string must be passed as a null-terminated string or as a compound string.

The UIL compiler recognizes enough about the various character sets to correctly parse string literals. The compiler also issues errors if you use a compound string in a context that supports only null-terminated strings.

Since the character set names are keywords, you must put them in lowercase if case-sensitive names are in force. If names are case insensitive, character set names can be uppercase, lowercase, or mixed case.

In addition to the built-in character sets recognized by UIL, you can define your own character sets with the CHARACTER_SET function. You can use the CHARACTER_SET function anywhere a character set can be specified.

String literals can contain characters with the eighth (high-order) bit set. You cannot type control characters (00-1F, 7F, and 80-9F) directly in a single-quoted string literal. However, you can represent these characters with escape sequences. The following list shows the escape sequences for special characters.

\b

Backspace

\f

Form-feed

\n

Newline

\r

Carriage return

\t

Horizontal tab

\v

Vertical tab

\'

Single quotation mark

\"

Double quotation mark

\\

Backslash

\integer\

Character whose internal representation is given by integer (in the range 0 to 255 decimal)

Note that escape sequences are processed literally in strings that are parsed in the current locale (localized strings).

The UIL compiler does not process newline characters in compound strings. The effect of a newline character in a compound string depends only on the character set of the string, and the result is not guaranteed to be a multiline string.

Compound String Literals

A compound string consists of a string of 8-bit, 16-bit, or multibyte characters, a named character set, and a writing direction. Its UIL data type is compound_string.

The writing direction of a compound string is implied by the character set specified for the string. You can explicitly set the writing direction for a compound string by using the COMPOUND_STRING function.

A compound string can consist of a sequence of concatenated compound strings, null-terminated strings, or a combination of both, each of which can have a different character set property and writing direction. Use the concatenation operator & (ampersand) to create a sequence of compound strings.

Each string in the sequence is stored, including the character set and writing direction information.

Generally, a string literal is stored in the UID file as a compound string when the literal consists of concatenated strings having different character sets or writing directions, or when you use the string to specify a value for an argument that requires a compound string value. If you want to guarantee that a string literal is stored as a compound string, you must use the COMPOUND_STRING function.

Data Storage Consumption for String Literals

The way a string literal is stored in the UID file depends on how you declare and use the string. The UIL compiler automatically converts a null-terminated string to a compound string if you use the string to specify the value of an argument that requires a compound string. However, this conversion is costly in terms of storage consumption.

PRIVATE, EXPORTED, and IMPORTED string literals require storage for a single allocation when the literal is declared; thereafter, storage is required for each reference to the literal. Literals declared in-line require storage for both an allocation and a reference.

The following table summarizes data storage consumption for string literals. The storage requirement for an allocation consists of a fixed portion and a variable portion. The fixed portion of an allocation is roughly the same as the storage requirement for a reference (a few bytes). The storage consumed by the variable portion depends on the size of the literal value (that is, the length of the string). To conserve storage space, avoid making string literal declarations that result in an allocation per use.

Data Storage Consumption for String Literals

Storage Requirements

Per Use

An allocation and a reference (within the module)

A reference (within the module)

A reference (within the UID hierarchy)

A reference (within the UID hierarchy)

An allocation and a reference (within the module)

An allocation and a reference (within the module)

A reference (within the UID hierarchy)

A reference (within the UID hierarchy)

An allocation and a reference (within the module)

A reference (within the module)

A reference (within the UID hierarchy)

A reference (within the UID hierarchy)

### Integer Literals
An integer literal represents the value of a whole number. Integer literals have the form of an optional sign followed by one or more decimal digits. An integer literal must not contain embedded spaces or commas.

Integer literals are stored in the UID file as 32-bit integers. Exported and imported integer literals require a single allocation when the literal is declared; thereafter, a few bytes of storage are required for each reference to the literal. Private integer literals and those declared in-line require allocation and reference storage per use. To conserve storage space, avoid making integer literal declarations that result in an allocation per use.

The following table shows data storage consumption for integer literals.

Data Storage Consumption for Integer Literals

Declaration

Storage Requirements Per Use

In-line

An allocation and a reference (within the module)

Private

An allocation and a reference (within the module)

Exported

A reference (within the UID hierarchy)

Imported

A reference (within the UID hierarchy)

### Boolean Literal
A Boolean literal represents the value True (reserved keyword TRUE or On) or False (reserved keyword FALSE or Off). These keywords are subject to case-sensitivity rules.

In a UID file, TRUE is represented by the integer value 1 and FALSE is represented by the integer value 0 (zero).

Data storage consumption for Boolean literals is the same as that for integer literals.

### Floating-Point Literal
A floating-point literal represents the value of a real (or float) number. Floating-point literals have the following form:

```
[+|-][integer].integer[E|e[+|-]exponent]
```

For maximum portability, a floating-point literal can represent values in the range 1.0E-37 to 1.0E+37 with at least 6 significant digits. On many machines this range will be wider, with more significant digits. A floating-point literal must not contain embedded spaces or commas.

Floating-point literals are stored in the UID file as double-precision, floating-point numbers. The following table gives examples of valid and invalid floating-point notation for the UIL compiler.

Floating Point Literals

Valid Floating-Point Literals

Invalid Floating-Point Literals

1.0

1e1 (no decimal point)

3.1415E-2 (equals .031415)

2.87 e6 (embedded blanks)

-6.29e7 (equals -62900000)

2.0e100 (out of range)

Data storage consumption for floating-point literals is the same as that for integer literals.

The purpose of the ANY data type is to shut off the data-type checking feature of the UIL compiler. You can use the ANY data type for the following:

•

Specifying the type of a callback procedure tag

•

Specifying the type of a user-defined argument

You can use the ANY data type when you need to use a type not supported by the UIL compiler or when you want the data-type restrictions imposed by the compiler to be relaxed. For example, you might want to define a widget having an argument that can accept different types of values, depending on run-time circumstances.

If you specify that an argument takes an ANY value, the compiler does not check the type of the value specified for that argument; therefore, you need to take care when specifying a value for an argument of type ANY. You could get unexpected results at run time if you pass a value having a data type that the widget does not support for that argument.

### Expressions
UIL includes compile-time value expressions. These expressions can contain references to other UIL values, but cannot be forward referenced.

The following table lists the set of operators in UIL that allow you to create integer, real, and Boolean values based on other values defined with the UIL module. In the table, a precedence of 1 is the highest.

Valid Operators

Operator

Operand Types

Meaning

Precedence

~

Boolean

NOT

1

integer

One's complement

-

float

Negate

1

integer

Negate

+

float

NOP

1

integer

NOP

*

float,float

Multiply

2

integer,integer

Multiply

/

float,float

Divide

2

integer,integer

Divide

+

float,float

Add

3

integer,integer

Add

-

float,float

Subtract

3

integer,integer

Subtract

>>

integer,integer

Shift right

4

<<

integer,integer

Shift left

4

&

Boolean,Boolean

AND

5

integer,integer

Bitwise AND

string,string

Concatenate

|

Boolean,Boolean

OR

6

integer,integer

Bitwise OR

^

Boolean,Boolean

XOR

6

integer,integer

Bitwise XOR

A string can be either a single compound string or a sequence of compound strings. If the two concatenated strings have different properties (such as writing direction or character set), the result of the concatenation is a multisegment compound string.

The string resulting from the concatenation is a null-terminated string unless one or more of the following conditions exists:

•

One of the operands is a compound string

•

The operands have different character set properties

•

The operands have different writing directions

Then the resulting string is a compound string. You cannot use imported or exported values as operands of the concatenation operator.

The result of each operator has the same type as its operands. You cannot mix types in an expression without using conversion routines.

You can use parentheses to override the normal precedence of operators. In a sequence of unary operators, the operations are performed in right-to-left order. For example, - + -A is equivalent to -(+(-A)). In a sequence of binary operators of the same precedence, the operations are performed in left-to-right order. For example, A*B/C*D is equivalent to ((A*B)/C)*D.

A value declaration gives a value a name. You cannot redefine the value of that name in a subsequent value declaration. You can use a value containing operators and functions anywhere you can use a value in a UIL module. You cannot use imported values as operands in expressions.

Several of the binary operators are defined for multiple data types. For example, the operator for multiplication (*) is defined for both floating-point and integer operands.

For the UIL compiler to perform these binary operations, both operands must be of the same type. If you supply operands of different data types, the UIL compiler automatically converts one of the operands to the type of the other according to the following conversions rules:

•

If the operands are an integer and a Boolean, the Boolean is converted to an integer.

•

If the operands are an integer and a floating-point, the integer is converted to an floating-point.

•

If the operands are a floating-point and a Boolean, the Boolean is converted to a floating-point.

You can also explicitly convert the data type of a value by using one of the conversion functions INTEGER, FLOAT or SINGLE_FLOAT.

### Functions
UIL provides functions to generate the following types of values:

•

Character sets

•

Keysyms

•

Colors

•

Pixmaps

•

Single-precision, floating-point numbers

•

Double-precision, floating-point numbers

•

Fonts

•

Fontsets

•

Font tables

•

Compound strings

•

Compound string tables

•

ASCIZ (null-terminated) string tables

•

Wide character strings

•

Widget class names

•

Integer tables

•

Arguments

•

Reasons

•

Translation tables

Remember that all examples in the following sections assume case-insensitive mode. Keywords are shown in uppercase letters to distinguish them from user-specified names, which are shown in lowercase letters. This use of uppercase letters is not required in case-insensitive mode. In case-sensitive mode, keywords must be in lowercase letters.

CHARACTER_SET(string_expression[, property[, ...]])

You can define your own character sets with the CHARACTER_SET function. You can use the CHARACTER_SET function anywhere a character set can be specified.

The result of the CHARACTER_SET function is a character set with the name string_expression and the properties you specify. string_expression must be a null-terminated string. You can optionally include one or both of the following clauses to specify properties for the resulting character set:

```
RIGHT_TO_LEFT = boolean_expression
SIXTEEN_BIT = boolean_expression
```

The RIGHT_TO_LEFT clause sets the default writing direction of the string from right to left if boolean_expression is True, and right to left otherwise.

The SIXTEEN_BIT clause allows the strings associated with this character set to be interpreted as 16-bit characters if boolean_expression is True, and 8-bit characters otherwise.

KEYSYM(string_literal)

The KEYSYM function is used to specify a keysym for a mnemonic resource. string_literal must contain a valid KeySym name. (See XStringToKeysym(3 X11) for more information.)

COLOR(string_expression[,FOREGROUND|BACKGROUND])

The COLOR function supports the definition of colors. Using the COLOR function, you can designate a value to specify a color and then use that value for arguments requiring a color value. The string expression names the color you want to define; the optional keywords FOREGROUND and BACKGROUND identify how the color is to be displayed on a monochrome device when the color is used in the definition of a color table.

The UIL compiler does not have built-in color names. Colors are a server-dependent attribute of an object. Colors are defined on each server and may have different red-green-blue (RGB) values on each server. The string you specify as the color argument must be recognized by the server on which your application runs.

In a UID file, UIL represents a color as a character string. MRM calls X translation routines that convert a color string to the device-specific pixel value. If you are running on a monochrome server, all colors translate to black or white. If you are on a color server, the color names translate to their proper colors if the following conditions are met:

•

The color is defined.

•

The color map is not yet full.

If the color map is full, even valid colors translate to black or white (foreground or background).

Interfaces do not, in general, specify colors for widgets, so that the selection of colors can be controlled by the user through the .Xdefaults file.

To write an application that runs on both monochrome and color devices, you need to specify which colors in a color table (defined with the COLOR_TABLE function) map to the background and which colors map to the foreground. UIL lets you use the COLOR function to designate this mapping in the definition of the color. The following example shows how to use the COLOR function to map the color red to the background color on a monochrome device:

```
VALUE c: COLOR ( 'red',BACKGROUND );
```

The mapping comes into play only when the MRM is given a color and the application is to be displayed on a monochrome device. In this case, each color is considered to be in one of the following three categories:

•

The color is mapped to the background color on the monochrome device.

•

The color is mapped to the foreground color on the monochrome device.

•

Monochrome mapping is undefined for this color.

If the color is mapped to the foreground or background color, MRM substitutes the foreground or background color, respectively. If you do not specify the monochrome mapping for a color, MRM passes the color string to the Motif Toolkit for mapping to the foreground or background color.

RGB(red_integer, green_integer, blue_integer)

The three integers define the values for the red, green, and blue components of the color, in that order. The values of these components can range from 0 to 65,535, inclusive. The values may be represented as integer expressions.

In a UID file, UIL represents an RGB value as three integers. MRM calls X translation routines that convert the integers to the device-specific pixel value. If you are running on a monochrome server, all colors translate to black or white. If you are on a color server, RGB values translate to their proper colors if the colormap is not yet full. If the colormap is full, values translate to black or white (foreground or background).

COLOR_TABLE(color_expression='character'[,...])

The color expression is a previously defined color, a color defined in line with the COLOR function, or the phrase BACKGROUND COLOR or FOREGROUND COLOR. The character can be any valid UIL character.

The COLOR_TABLE function provides a device-independent way to specify a set of colors. The COLOR_TABLE function accepts either previously defined UIL color names or in line color definitions (using the COLOR function). A color table must be private because its contents must be known by the UIL compiler to construct an icon. The colors within a color table, however, can be imported, exported, or private.

The single letter associated with each color is the character you use to represent that color when creating an icon. Each letter used to represent a color must be unique within the color table.

ICON([COLOR_TABLE=color_table_name,] row[,...)

color-table-name must refer to a previously defined color table, and row is a character expression giving one row of the icon.

The ICON function describes a rectangular icon that is x pixels wide and y pixels high. The strings surrounded by single quotation marks describe the icon. Each string represents a row in the icon; each character in the string represents a pixel.

The first row in an icon definition determines the width of the icon. All rows must have the same number of characters as the first row. The height of the icon is dictated by the number of rows. The maximum number of rows is 999.

The first argument of the ICON function (the color table specification) is optional and identifies the colors that are available in this icon. By using the single letter associated with each color, you can specify the color of each pixel in the icon. The icon must be constructed of characters defined in the specified color table.

A default color table is used if you omit the argument specifying the color table. To make use of the default color table, the rows of your icon must contain only spaces and asterisks. The default color table is defined as follows:

```
COLOR_TABLE( BACKGROUND COLOR = ' ', FOREGROUND COLOR = '*')
```

You can define other characters to represent the background color and foreground color by replacing the space and asterisk in the BACKGROUND COLOR and FOREGROUND COLOR clauses shown in the previous statement. You can specify icons as private, imported, or exported. Use the MRM function MrmFetchIconLiteral to retrieve an exported icon at run time.

XBITMAPFILE(string_expression)

The XBITMAPFILE function is similar to the ICON function in that both describe a rectangular icon that is x pixels wide and y pixels high. However, XBITMAPFILE allows you to specify an external file containing the definition of an X bitmap, whereas all ICON function definitions must be coded directly within UIL. X bitmap files can be generated by many different X applications. UIL reads these files through the XBITMAPFILE function, but does not support creation of these files. The X bitmap file specified as the argument to the XBITMAPFILE function is read at application run time by MRM.

The XBITMAPFILE function returns a value of type pixmap and can be used anywhere a pixmap data type is expected.

SINGLE_FLOAT(real_number_literal)

The SINGLE_FLOAT function lets you store floating-point literals in UIL files as single-precision, floating-point numbers. Single-precision floating-point numbers can often be stored using less memory than double-precision, floating-point numbers. The real_number_literal can be either an integer literal or a floating-point literal.

FLOAT(real_number_literal)

The FLOAT function lets you store floating-point literals in UIL files as double-precision, floating-point numbers. The real_number_literal can be either an integer literal or a floating-point literal.

FONT(string_expression[, CHARACTER_SET=char_set])

You define fonts with the FONT function. Using the FONT function, you designate a value to specify a font and then use that value for arguments that require a font value. The UIL compiler has no built-in fonts.

Each font makes sense only in the context of a character set. The FONT function has an additional parameter to let you specify the character set for the font. This parameter is optional; if you omit it, the default character set depends on the value of the LANG environment variable if it is set, or on the value of XmFALLBACK_CHARSET if LANG is not set.

string_expression specifies the name of the font and the clause CHARACTER_SET = char_set specifies the character set for the font. The string expression used in the FONT function cannot be a compound string.

FONTSET(string_expression[,...][, CHARACTER_SET=charset])

You define fontsets with the FONTSET function. Using the FONTSET function, you designate a set of values to specify fonts and then use those values for arguments that require a fontset. The UIL compiler has no built-in fonts.

Each font makes sense only in the context of a character set. The FONTSET function has an additional parameter to let you specify the character set for the font. This parameter is optional; if you omit it, the default character set depends on the value of the LANG environment variable if it is set, or on the value of XmFALLBACK_CHARSET if LANG is not set.

The string expression specifies the name of the font and the clause CHARACTER_SET = char_set specifies the character set for the font. The string expression used in the FONTSET function cannot be a compound string.

FONT_TABLE(font_expression[,...])

A font table is a sequence of pairs of fonts and character sets. At run time, when an object needs to display a string, the object scans the font table for the character set that matches the character set of the string to be displayed. UIL provides the FONT_TABLE function to let you supply such an argument. font_expression is created with the FONT and FONTSET functions.

If you specify a single font value to specify an argument that requires a font table, the UIL compiler automatically converts a font value to a font table.

COMPOUND_STRING(string_expression[,property[,...]])

Use the COMPOUND_STRING function to set properties of a null-terminated string and to convert it into a compound string. The properties you can set are the writing direction and separator.

The result of the COMPOUND_STRING function is a compound string with the string expression as its value. You can optionally include one or more of the following clauses to specify properties for the resulting compound string:

RIGHT_TO_LEFT = boolean_expression SEPARATE = boolean_expression

The RIGHT_TO_LEFT clause sets the writing direction of the string from right to left if boolean_expression is True, and left to right otherwise. Specifying this argument does not cause the value of the string expression to change. If you omit the RIGHT_TO_LEFT argument, the resulting string has the same writing direction as string_expression.

The SEPARATE clause appends a separator to the end of the compound string if boolean_expression is True. If you omit the SEPARATE clause, the resulting string does not have a separator.

You cannot use imported or exported values as the operands of the COMPOUND_STRING function.

COMPOUND_STRING_COMPONENT(component_type [, {string | enumval}])

Use the COMPOUND_STRING_COMPONENT function to create compound strings in UIL consisting of single components. This function is analagous to XmStringComponentCreate. This function lets you create simple compound strings containing components such as XmSTRING_COMPONENT_TAB and XmSTRING_COMPONENT_RENDITION_BEGIN which are not produced by the COMPOUND_STRING function. These components can then be concatenated to other compound strings to build more complex compound strings.

The first argument must be an XmStringComponentType enumerated constant. The type and interpretation of the second argument depends on the first argument. For example, if you specify any of the following enumerated constants for the first argument, then you should not specify a second argument: XmSTRING_COMPONENT_SEPARATOR, XmSTRING_COMPONENT_LAYOUT_POP, XmSTRING_COMPONENT_TAB, and XmSTRING_COMPONENT_LOCALE. However, if you specify an enumerated constant from the following group, then you must supply a string as the second argument: XmSTRING_COMPONENT_CHARSET, XmSTRING_COMPONENT_TEXT, XmSTRING_COMPONENT_LOCALE_TEXT, XmSTRING_COMPONENT_WIDECHAR_TEXT, XmSTRING_COMPONENT_RENDITION_BEGIN, and XmSTRING_COMPONENT_RENDITION_END. If you specify XmSTRING_COMPONENT_DIRECTION as the first argument, then you must specify an XmStringDirection enumerated constant as the second argument. Finally, if you specify XmSTRING_COMPONENT_LAYOUT_PUSH as the first argument, then you must specify an XmDirection enumerated constant as the second argument.

The compound string components XmSTRING_COMPONENT_RENDITION_BEGIN, and XmSTRING_COMPONENT_RENDITION_END take, for their argument, the "tag," or name, of a rendition from the current render table. See the following section for more information about how to specify a render table.

COMPOUND_STRING_TABLE(string_expression[,...])

A compound string table is an array of compound strings. Objects requiring a list of string values, such as the XmNitems and XmNselectedItems arguments for the list widget, use string table values. The COMPOUND_STRING_TABLE function builds the values for these two arguments of the list widget. The COMPOUND_STRING_TABLE function generates a value of type string_table. The name STRING_TABLE is a synonym for COMPOUND_STRING_TABLE.

The strings inside the string table must be simple strings, which the UIL compiler automatically converts to compound strings.

ASCIZ_STRING_TABLE(string_expression[,...])

An ASCIZ string table is an array of ASCIZ (null-terminated) string values separated by commas. This function allows you to pass more than one ASCIZ string as a callback tag value. The ASCIZ_STRING_TABLE function generates a value of type asciz_table. The name ASCIZ_TABLE is a synonym for ASCIZ_STRING_TABLE.

WIDE_CHARACTER(string_expression)

Use the WIDE_CHARACTER function to generate a wide character string from null-terminated string in the current locale.

CLASS_REC_NAME(string_expression)

Use the CLASS_REC_NAME function to generate a widget class name. For a widget class defined by the toolkit, the string argument is the name of the class. For a user-defined widget, the string argument is the name of the creation routine for the widget.

INTEGER_TABLE(integer_expression[,...])

An integer table is an array of integer values separated by commas. This function allows you to pass more than one integer per callback tag value. The INTEGER_TABLE function generates a value of type integer_table.

ARGUMENT(string_expression[, argument_type])

The ARGUMENT function defines the arguments to a user-defined widget. Each of the objects that can be described by UIL permits a set of arguments, listed in Appendix B. For example, XmNheight is an argument to most objects and has an integer data type. To specify height for a user-defined widget, you can use the built-in argument name XmNheight, and specify an integer value when you declare the user-defined widget. You do not use the ARGUMENT function to specify arguments that are built into the UIL compiler.

The string_expression name is the name the UIL compiler uses for the argument in the UID file. argument_type is the type of value that can be associated with the argument. If you omit the second argument, the default type is ANY and no value type checking occurs. Use one of the following keywords to specify the argument type:

•

ANY

•

ASCIZ_TABLE

•

BOOLEAN

•

COLOR

•

COMPOUND_STRING

•

FLOAT

•

FONT

•

FONT_TABLE

•

FONTSET

•

ICON

•

INTEGER

•

INTEGER_TABLE

•

KEYSYM

•

PIXMAP

•

REASON

•

SINGLE_FLOAT

•

STRING

•

STRING_TABLE

•

TRANSLATION_TABLE

•

WIDE_CHARACTER

•

WIDGET

You can use the ARGUMENT function to allow the UIL compiler to recognize extensions to the Motif Toolkit. For example, an existing widget may accept a new argument. Using the ARGUMENT function, you can make this new argument available to the UIL compiler before the updated version of the compiler is released.

REASON(string_expression)

The REASON function is useful for defining new reasons for user-defined widgets.

Each of the objects in the Motif Toolkit defines a set of conditions under which it calls a user-defined function. These conditions are known as callback reasons. The user-defined functions are termed callback procedures. In a UIL module, you use a callbacks list to specify which user-defined functions are to be called for which reasons.

Appendix B lists the callback reasons supported by the Motif Toolkit objects.

When you declare a user-defined widget, you can define callback reasons for that widget using the REASON function. The string expression specifies the argument name stored in the UID file for the reason. This reason name is supplied to the widget creation routine at run time.

TRANSLATION_TABLE(string_expression[,...])

Each of the Motif Toolkit widgets has a translation table that maps X events (for example, mouse button 1 being pressed) to a sequence of actions. Through widget arguments, such as the common translations argument, you can specify an alternate set of events or actions for a particular widget. The TRANSLATION_TABLE function creates a translation table that can be used as the value of an argument that is of the data type translation_table.

You can use one of the following translation table directives with the TRANSLATION_TABLE function: #override, #augment, or #replace. The default is #replace. If you specify one of these directives, it must be the first entry in the translation table.

The #override directive causes any duplicate translations to be ignored. For example, if a translation for <Btn1Down> is already defined in the current translations for a PushButton, the translation defined by new_translations overrides the current definition. If the #augment directive is specified, the current definition takes precedence. The #replace directive replaces all current translations with those specified in the XmNtranslations resource.

### Renditions and Render Tables
In addition to the string direction, each compound string carries a great deal of information about how its text is to be rendered. Each compound string contains a "tag," identifying the "rendition" to be used to draw that string. The rendition contains such information as the font, the size, the color, whether the text is to be underlined or crossed out, and the position and style of any tab stops. Many renditions are combined into a "render table," which is specified to any widget with the XmNrenderTable resource, and in the widget's controls list.

UIL implements render tables, renditions, tab lists, and tab stops as a special class of objects, in a form similar to the widget class. These objects are not themselves widgets or gadgets, but the format used by UIL to specify widget resources provides a convenient way to specify the qualities and dependencies of these objects.

For example, a render table, included in some widget's controls list, must also have a controls list in its specification, containing the names of its member renditions. Each rendition, in its specification, will contain an arguments list specifying such qualities as the font, the color, and whether the text is to be underlined. Any of the renditions may also control a tablist, which will itself control one or more tab stops.

Please refer to the Motif Programmer's Guide for a complete description of renditions and render tables, and for an example of how to use them in UIL.

## RELATED INFORMATION
uil(1), Uil(3)


WML

package: openmotif-clients

title: WML(5)

text:
# WML(5)

## NAME
WML — The widget meta-language file format for creating uil compilers

## DESCRIPTION
The widget meta-language facility (WML) is used to generate the components of the user interface language (UIL) compiler that can change depending on the widget set. Using WML you can add support in UIL for new widgets to the Motif widget set or for a totally new widget set.

### File
WML files are ASCII files that you can modify with any standard text editor. They are accessed in the tools/wml directory by WML. By convention WML files have the suffix .wml. The Motif widget set is described in the motif.wml file. This is also the default WML file when using the WML facility.

When adding new widgets or changing widget characteristics, you should start with a copy of the motif.wml file. If you are creating a new widget set for use with UIL, you should start from scratch. In either case the motif.wml file is a good example of WML syntax, and you should familiarize yourself with it before writing your own WML file.

WML files have a simple syntax, similar in structure to UIL. It is made up of the following elements:

•

Comments

•

Data Type Definitions

•

Character Set Definitions

•

Enumeration Set Definitions

•

Control List Definitions

•

Class Definitions

•

Child Definitions

•

Resource Definitions

You can use space, tabs, or newlines anywhere in the syntax, as long as you do not split up keywords or strings, except that comments end at a newline. The order of elements is not important to the syntax.

This description uses the following additional conventions to describe the syntax of the widget meta-language:

[ ]

Indicates optional elements.

...

Indicates where an element of syntax can be repeated.

|

Indicates a choice among multiple items.

### Comments
You can include comments in the WML file. Comments have the following syntax:

```
[any.element]!any.comment
```

Comments begin with an exclamation point and extend to the end of the line. A comment can begin on a line by itself or follow any part of another element. A comment does not change the meaning of any other element. For example:

```
!This is a comment
!  that spans two lines.
DataType    !This is a comment following code.
```

### Data Type Definitions
Data type definitions register all the resource data types used in the file. You must register all the data types used in your WML file. Data type definitions have the following syntax:

```
DataType

     any.datatype [{ InternalLiteral = internal.name |

          DocName = "string"; [...]}];

     [...]
```

A data type definition begins with the keyword DataType. Following the DataType keyword is a list of data types that can be further modified with

InternalLiteral

This forces the value of the internal symbol table literal definition of the data type name. This modifier is only used to get around symbol table definitions hard coded into the UIL compiler. It should rarely be used.

DocName

This gives an arbitrary string for use in the documentation. This string is meant to supply a different name for the data type for use in the documentation, or a single name for the data type if the data type has aliases.

For example:

```
DataType OddNumber {DocName="OddNumber";};

         NewString;
```

### Character Set Definitions
Character set definitions register the Motif Toolkit name and other information for the character set names used in UIL. Character set definitions have the following syntax:

```
CharacterSet

     any.character.set

          { [ FontListElementTag | XmStringCharsetName ] = "string";

               [ Alias = "string" ...; |

               Direction = [ LeftToRight | RightToLeft ]; |

               ParseDirection = [ LeftToRight | RightToLeft ]; |

               CharacterSize = [ OneByte | TwoByte ]; ]

               [ ... ] };

     [ ... ]
```

A character set definition begins with the keyword CharacterSet. Following the CharacterSet keyword is a list of character sets that can be further modified with

FontListElementTag | XmStringCharsetName

Specifies the name of the character set, which will become the character set component of a compound string segment created using this character set. This modifier is required.

Alias

Specifies one or more aliases for the character set name. Each alias can be used within UIL to refer to the same character set.

Direction

Specifies the direction of a compound string segment created using this character set. The default is LeftToRight.

ParseDirection

Specifies the direction in which an input string is parsed when a compound string segment is created using this character set. The default is whatever Direction is specified.

CharacterSize

Specifies the number of bytes in each character of a compound string segment created using this character set. The default is OneByte.

For example:

```
CharacterSet

  iso_latin1

    { XmStringCharsetName = "ISO8859-1";

      Alias = "ISOLatin1"; };

  iso_hebrew_lr

    { XmStringCharsetName = "ISO8859-8";

      Alias = "iso_latin8_lr";

      Direction = RightToLeft;

      ParseDirection = LeftToRight; };

  ksc_korean

    { XmStringCharsetName = "KSC5601.1987-0";

      CharacterSize = TwoByte; };
```

### Enumeration Set Definitions
Enumeration set definitions register the named constants used in the Motif Toolkit to specify some resource values. Enumeration set definitions have the following syntax:

```
EnumerationSet

     resource.name: resource.type

          { enum.value.name; [ ... ] };
```

An enumeration set definition begins with the keyword EnumerationSet. For each enumeration set defined, the name and type of the resource are listed. The resource name is the Motif Toolkit resource name, with the beginning XmN removed and with the initial letter capitalized. For example, the name of the Motif Toolkit resource XmNrowColumnType is RowColumnType. The resource type is the data type for the resource; for most resources, this is integer. Following the resource name and type is a list of names of enumeration values that can be used as settings for the resource. These names are the same as those in the Motif Toolkit.

For example:

```
EnumerationSet

  RowColumnType: integer

    { XmWORK_AREA; XmMENU_BAR; XmMENU_POPUP;

      XmMENU_PULLDOWN; XmMENU_OPTION; };
```

Enumeration sets also support Boolean values.

### Control List Definitions
Control list definitions assign a name to groups of controls. You can use these control lists later in class definitions to simplify the structure of your WML file. Control list definitions have the following syntax:

```
ControlList

     any.control.list [{ any.control; [...]}];
```

A control list definition starts with the ControlList keyword. Following the ControlList keyword are any number of control list definitions. Control list definitions are made up of a control list name followed by the set of controls it represents. For example:

```
ControlList

        Buttons {PushButton;

                 RadioButton;

                 CascadeButton;

                 NewCascadebutton;};
```

Each control specified in the control list must be defined as a class in the file.

### Class Definitions
Class definitions describe a particular widget class including its position in the class hierarchy, toolkit convenience function, resources, and controls. There should be one class definition for each widget or gadget in the widget set you want to support in UIL. Class definitions have the following syntax:

```
Class class.name: MetaClass | Widget | Gadget

     [{[

     SuperClass = class.name; |

     ParentClass = parent.class.name; |

     InternalLiteral = internal.name; |

     Alias = alias; |

     ConvenienceFunction = convenience.function; |

     WidgetClass = widget.class; |

     DocName = "string"; |

     DialogClass = True | False; |

     Resources { any.resource.name [{

               Default = new.default.value; |

               Exclude = True |

               False;

               [...]} ];

          [...]}; |

     Controls { any.control.name; [...]};

     Children { any.child.name; [...] };

     [...]

     ]}];
```

Class definitions start with the Class keyword. For each class defined, the name of the class and whether the class is a metaclass, widget, or gadget is listed. Each class definition can be further modified with the keywords described in the following list.

SuperClass

This indicates the name of the parent class. Only the root of the hierarchy does not specify a SuperClass.

ParentClass

This indicates the name of the widget's automatically created parent class if one exists. This allows resources for that automatically created class to be used in instances of this class. For example, XmBulletinBoardDialog creates both an XmBulletinBoard and an XmDialogShell. To access the resources of the XmDialogShell parent class it must be specified here.

InternalLiteral

This forces the value of the internal symbol table literal definition of the class name. This modifier is only used to get around symbol table definitions hard coded into the UIL compiler. It should rarely be used.

Alias

This indicates alternate names for the class for use in a UIL specification.

ConvenienceFunction

This indicates the name of the creation convenience function for this class. All widget and gadget classes must have a ConvenienceFunction.

WidgetClass

This indicates the associated widget class of gadget type classes. Presently, nothing is done with this value.

DocName

This defines an arbitrary string for use in the documentation. Presently, nothing is done with this value.

DialogClass

This indicates whether the class is a dialog class. Presently, nothing is done with this value.

Resources

This lists the resources of the widget class. This keyword can be further modified with

Default

This specifies a new default value for this resource. Resource default values are usually set in the resource definition. If an inherited resource's default value is changed by the class, the new default value should be noted here.

Exclude

This specifies whether an inherited resource should be excluded from the resource list of the class. Exclude is False by default.

Children

This lists the names of the automatically created children of this class, so that those children can be accessed in the UIL file.

Controls

This lists the controls that the widget class allows. The controls can be other classes or a control list from the control list definition.

The following example uses the examples from the data type definitions and control list definitions above.

```
Class

     TopLevelWidget: MetaClass

          {

          Resources

               {

               XtbNfirstResource;

               XtbNsecondResource;

               };

          };

     NewWidget: Widget

          {

          SuperClass = TopLevelWidget;

          ConvenienceFunction =

              XtbCreateNewWidget;

          Resources

               {

               XtbNnewResource;

               XtbNfirstResource

                  {Default="XtbNEW_VALUE";};

               XtbNsecondResource

                  {Exclude=True;};

               };

          Controls

               {

               NewWidget;

               Buttons;

               };

          };
```

### Child Definitions
Child definitions register the classes of automatically created children. Automatically created children are referenced elsewhere in a uil file using the Children keyword within a class definition. Child definitions have the following syntax:

Child child.name : class.name; [...]

Where child.name is the name of the automatically created child and class.name is the name of the class of that child.

### Resource Definitions
Resource definitions describe a particular resource including its type, and default value. There should be a resource definition for each new resource referenced in the class definitions. Resource definitions have the following syntax:

```
Resource

     resource.name: Argument | Reason | Constraint | SubResource

          [{[

          Type = type;

          [ResourceLiteral = resource.literal; ]

          [InternalLiteral = internal.name; ]

          [Alias = alias; ]

          [Related = related; ]

          [Default = default; ]

          [DocName = doc.name; ]

          [...]}]

     [...]
```

Resource definitions start with the Resource keyword. For each resource definition, the name of the resource and whether the resource is an argument, reason, constraint or subresource is listed.

Argument

Indicates a standard resource

Reason

Indicates a callback resource

Constraint

Indicates a constraint resource

SubResource

Presently, nothing is done with this value

The resource definition can be further modified with the following keywords:

Type

This indicates the data type of the resource. It must be listed in the data type definition.

ResourceLiteral

This indicates the keyword used in the UIL file to reference the resource. In Motif, the resource name is the same as the ResourceLiteral.

InternalLiteral

This forces the value of the internal symbol table literal definition of the resource name. This modifier is only used to get around symbol table definitions hard coded into the UIL compiler. It should rarely be used.

Alias

This indicates alternate names for the resource for use in a UIL specification.

Related

This is a special purpose field that allows resources that act as a counter for the current resources to be related to the resource. UIL automatically sets the value of this related resource to the number of items in the compiled instance of type resource.name.

Default

This indicates the default value of the resource.

DocName

This defines an arbitrary string for use in the documentation. Presently, nothing is done with this value.

The following example uses the examples from the data type definitions, control list definitions and class definitions above.

```
Resource

     XtbNfirstResource: Argument

          { Type = OddNumber;

            Default = "XtbOLD_VALUE";};

     XtbNsecondResource: Argument

          { Type = NewString;

            Default = "XtbNEW_STRING"; };

     XtbNnewResource: Argument

          { Type = OddNumber;

            Default = "XtbODD_NUMBER"; };
```


ntpd.conf

package: openntpd

title: ntpd.conf(5)

text:
# ntpd.conf(5)

## NAME
ntpd.conf - Network Time Protocol daemon configuration file

## DESCRIPTION
This manual page describes the format of the ntpd(8) configuration file. It has the following format:

Empty lines and lines beginning with the `#' character are ignored.

Keywords may be specified multiple times within the configuration file. They are as follows:

listen on address

Specify a local IP address or a hostname the ntpd(8) daemon should listen on. If it appears multiple times, ntpd(8) will listen on each given address. If `*' is given as an address, ntpd(8) will listen on all local addresses. ntpd(8) does not listen on any address by default. For example: listen on *

listen on 127.0.0.1

listen on ::1

server address

Specify the IP address or the hostname of an NTP server to synchronize to. If it appears multiple times, ntpd(8) will try to synchronize to all of the servers specified. If a hostname resolves to multiple IPv4 and/or IPv6 addresses, ntpd(8) uses the first address. If it does not get a reply, ntpd(8) retries with the next address and continues to do so until a working address is found. For example: server 10.0.0.2

server ntp.example.org

To provide redundancy, it is good practice to configure multiple servers. In general, best accuracy is obtained by using servers that have a low network latency.

servers address

As with server, specify the IP address or hostname of an NTP server to synchronize to. If it appears multiple times, ntpd(8) will try to synchronize to all of the servers specified. Should the hostname resolve to multiple IP addresses, ntpd(8) will try to synchronize to all of them. For example: servers pool.ntp.org

## FILES
/etc/ntpd.conf

default ntpd(8) configuration file

## SEE ALSO
ntpd(8)

## HISTORY
The ntpd.conf file format first appeared in OpenBSD 3.6 .


title: r2test.conf(5)

text:
# r2test.conf(5)

## NAME
r2test.conf - OpenR2 r2test program configuration file

## SYNOPSIS
/etc/openr2/r2test.conf

## DESCRIPTION
This file defines the behavior of the r2test program

This file works pretty much like Asterisk zapata.conf file, the channel parameter will create a R2 context with the specified range of channels and will take all the preceding parameters as configuration.

## SYNTAX
No spaces are allowed in parameter definition, lines starting with # or spaces will be ignored

This definition will not be read properly

param = value

This definition will be read fine

param=value

## OPTIONS
category=<NATIONAL_SUBSCRIBER, NATIONAL_PRIORITY_SUBSCRIBER, INTERNATIONAL_SUBSCRIBER, INTERNATIONAL_PRIORITY_SUBSCRIBER>

Defines the call category of subscriber. Defaults to NATIONAL_SUBSCRIBER

loglevel=<all,error,warning,debug,notice,cas,mf,stack,nothing>

Defines the log level for debugging purposes. Defaults to all error, warning, debug, notice These options are self-descriptive

cas is for logging ABCD CAS tx and rx

mf is for logging of the Multi Frequency tones

stack is for very verbose output of the channel and context call stack, only useful if you are debugging a crash or want to learn how the library works. The stack logging will be only enabled if the OpenR2 library was compiled with -DOR2_TRACE_STACKS

all is a special value to log all the activity

nothing is a clean-up value, in case you want to not log any activity for a channel or group of channels

You can mix up values, like: loglevel=error,debug,mf to log just error, debug and multi frequency messages

callfile=<yes|no>

Call files useful to debug signaling issues are dumped in the current directory if this parameter is enabled. Defaults to no

variant=<br,mx,ar,itu>

R2 country variant. Defaults to mx

maxani

How much ANI to expect. Defaults to 10

maxdnis

How much DNIS to expect. Defaults to 4

getanifirst=<yes|no>

Whether or not we want to request ANI first. Defaults to no

usedahdimf=<yes|no>

Whether to use the built-in OpenR2 MF tone generation or DAHDI MF tone generation. DAHDI is faster since it does not require to copy user space buffers to the kernel, however this option will only be available when the configure script detects DAHDI support for MF R2 tone generation. Defaults to no

mfthreshold

MF threshold in milliseconds. This is the amount of time a R2 MF signal is required to be ON or OFF after has been detected to be handled. 0 means as soon as we detect a signal we handle it. This aids when a buggy generator or detector causes small false positives. Defaults to 0

mfbacktimeout

MF backward timeout in milliseconds to use OpenR2 default just specify any negative number or comment this line. Defaults to -1

meteringpulsetimeout

Value in milliseconds for the metering pulse timeout, any negative value means default. Defaults to -1

collectcalls=<yes|no>

Whether to accept collect calls (see also doubleanswer). Defaults to no

chargecalls=<yes|no>

Wheter to charge calls. Defaults to no

doubleanswer=<yes|no>

This option are related but independent of collectcalls. If you have problems to block collect calls using Group B signals (collectcalls), enable this option. Defaults to no

immediateaccept=<yes|no>

Whether to skip Group B/II signals and go directly to the accepted state for an incoming call. Defaults to no

advancedprotocolfile

This option is for advanced users only! Define a file that contains hacks to R2 protocol. This allow advanced users to fine tune the library or make test with specific scenarios to include in the library in the future.

playaudio=<yes|no>

This feature allows you to play an alaw audio file for incoming/outgoing calls. Defaults to no

audiofile

If you set playaudio=yes you should provide the path to the audio file

channel

Define range of channels to configure using previous options. The channel range must be specified, unless you will use only one channel. If this option is specified after dnid, cid and caller that options will be used. Defaults to channel=1-15

channel=17-31

dnid

Defines the destination number. Only used if .B caller = yes

cid

Defines the caller id number. Only used if .B caller = yes

caller=<yes|no>

Whether or not the group of channels will start a call to the specified dnid. Defaults to yes

## FILES
/etc/openr2/r2test.conf

/etc/openr2/r2proto.conf

## SEE ALSO
r2test(8)

## AUTHOR
This manual page was written by Alexandre Cavalcante Alencar

<alexandre.alencar@gmail.com>

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 any later version published by the Free Software Foundation.


razer.conf

package: openrazer-daemon

title: razer.conf(5)

text:
# razer.conf(5)

## NAME
razer.conf - configuration file for the OpenRazer Daemon

## DESCRIPTION
The ~/.config/openrazer/razer.conf ($XDG_CONFIG_HOME is respected, if set) file configures some startup and runtime options of the openrazer-daemon(8). openrazer-daemon(8) is able to use configuration files specified in non-standard locations by providing the --config argument.

The configuration file is formatted like a .INI file and is parsed by Python's ConfigParser.

## EXAMPLE
An example file should be installed under /usr/share/openrazer/razer.conf.example.

## SECTIONS

### GENERAL
The first section in the configuration file is a [General] section. This section contains miscellaneous options.

verbose_logging bool

This flag specifies if the daemon is to output detailed logging information. This value acts the same as if -v or --verbose was passed at the command line.

### STARTUP
The [Startup] section in the configuration file contains values to be used during startup, for example it can decide if syncing effects will be active when started.

sync_effects_enabled bool

This flag specifies if the effects syncing logic is active when the daemon is started, not having to wait for the user to activate them.

devices_off_on_screensaver bool

This flag specifies if the functionality to turn off razer devices when the screensaver is activated is active when the daemon starts.

battery_notifier bool

This flag specifies that notifications should be shown regularly with the remaining battery level.

battery_notifier_freq int

This flag specifies how often the notification with the remaining battery level should be shown.

battery_notifier_percent int

This flag specifies what battery percentage the device should reach before sending notifications.

restore_persistence bool

This flag specifies whether effects saved in persistence.conf should be applied when the daemon starts.

## SEE ALSO
openrazer-daemon(8)


resolvconf.conf

package: openresolv

title: resolvconf.conf(5)

summary: resolvconf configuration file

text:
# resolvconf.conf(5)

## NAME
resolvconf.conf — resolvconf configuration file

## DESCRIPTION
resolvconf.conf is the configuration file for resolvconf(8). The resolvconf.conf file is a shell script that is sourced by resolvconf(8), meaning that resolvconf.conf must contain valid shell commands. Listed below are the standard resolvconf.conf variables that may be set. If the values contain whitespace, wildcards or other special shell characters, ensure they are quoted and escaped correctly. See the replace variable for an example on quoting.

After updating this file, you may wish to run resolvconf -u to apply the new configuration.

When a dynamically generated list is appended or prepended to, the whole is made unique where left-most wins.

## RESOLVCONF OPTIONS
resolvconf

Set to NO to disable resolvconf from running any subscribers. Defaults to YES.

allow_interfaces

If set, only these interfaces will be processed.

deny_interfaces

If set, these interfaces will not be processed.

interface_order

These interfaces will always be processed first. If unset, defaults to the following:-

```
lo lo[0-9]* lo.*
```

dynamic_order

These interfaces will be processed next, unless they have a metric. If unset, defaults to the following:-

```
tap[0-9]* tun[0-9]* vpn vpn[0-9]* wg[0-9]* ppp[0-9]* ippp[0-9]*
```

inclusive_interfaces

Ignore any exclusive marking for these interfaces. This is handy when 3rd party integrations force the resolvconf -x option and you want to disable it easily.

local_nameservers

If unset, defaults to the following:-

```
127.* 0.0.0.0 255.255.255.255 ::1
```

search_domains

Prepend search domains to the dynamically generated list.

search_domains_append

Append search domains to the dynamically generated list.

domain_blacklist

A list of domains to be removed from consideration. To remove a domain, you can use foo.* To remove a sub domain, you can use *.bar

name_servers

Prepend name servers to the dynamically generated list. You should set this to 127.0.0.1 if you use a local name server other than libc.

name_servers_append

Append name servers to the dynamically generated list.

name_server_blacklist

A list of name servers to be removed from consideration. The default is 0.0.0.0 as some faulty routers send it via DHCP. To remove a block, you can use 192.168.*

private_interfaces

These interfaces name servers will only be queried for the domains listed in their resolv.conf. Useful for VPN domains. Setting private_interfaces="*" will stop the forwarding of the root zone and allows the local resolver to recursively query the root servers directly. Requires a local nameserver other than libc. This is equivalent to the resolvconf -p option.

public_interfaces

Force these interface to be public, overriding the private marking. This is handy when 3rd party integrations force the resolvconf -p option and you want to disable it easily.

replace

Is a space separated list of replacement keywords. The syntax is this: $keyword/$match/$replacement Example, given this resolv.conf:

```
domain foo.org
search foo.org dead.beef
nameserver 1.2.3.4
nameserver 2.3.4.5
```

and this configuaration:

```
replace="search/foo*/bar.com"
replace="$replace nameserver/1.2.3.4/5.6.7.8"
replace="$replace nameserver/2.3.4.5/"
```

you would get this resolv.conf instead:

```
domain foo.org
search bar.com
nameserver 5.6.7.8
```

replace_sub

Works the same way as replace except it works on each space separated value rather than the whole line, so it's useful for the replacing a single domain within the search directive. Using the same example resolv.conf and changing replace to replace_sub, you would get this resolv.conf instead:

```
domain foo.org
search bar.com dead.beef
nameserver 5.6.7.8
```

state_dir

Override the default state directory of /var/run/resolvconf. This should not be changed once resolvconf is in use unless the old directory is copied to the new one.

## LIBC OPTIONS
The following variables affect resolv.conf(5) directly:-

resolv_conf

Defaults to /etc/resolv.conf if not set.

resolv_conf_options

A list of libc resolver options, as specified in resolv.conf(5).

resolv_conf_passthrough

When set to YES the latest resolv.conf is written to resolv_conf without any alteration. When set to /dev/null or NULL, resolv_conf_local_only is defaulted to NO, local_nameservers is unset unless overridden and only the information set in resolvconf.conf is written to resolv_conf.

resolv_conf_sortlist

A libc resolver sortlist, as specified in resolv.conf(5).

resolv_conf_local_only

If a local name server is configured then the default is just to specify that and ignore all other entries as they will be configured for the local name server. Set this to NO to also list non-local nameservers. This will give you working DNS even if the local nameserver stops functioning at the expense of duplicated server queries.

append_nameservers

Append name servers to the dynamically generated list.

prepend_nameservers

Prepend name servers to the dynamically generated list.

append_search

Append search domains to the dynamically generated list.

prepend_search

Prepend search domains to the dynamically generated list.

## SUBSCRIBER OPTIONS
openresolv ships with subscribers for the name servers dnsmasq(8), named(8), pdnsd(8), pdns_recursor(1), and unbound(8). Each subscriber can create configuration files which should be included in the subscribers main configuration file.

To disable a subscriber, simply set it's name to NO. For example, to disable the libc subscriber you would set:

```
libc=NO
```

dnsmasq_conf

This file tells dnsmasq which name servers to use for specific domains.

dnsmasq_resolv

This file tells dnsmasq which name servers to use for global lookups. Example resolvconf.conf for dnsmasq:

```
name_servers=127.0.0.1
dnsmasq_conf=/etc/dnsmasq-conf.conf
dnsmasq_resolv=/etc/dnsmasq-resolv.conf
```

Example dnsmasq.conf:

```
listen-address=127.0.0.1
# If dnsmasq is compiled for DBus then we can take
# advantage of not having to restart dnsmasq.
enable-dbus
conf-file=/etc/dnsmasq-conf.conf
resolv-file=/etc/dnsmasq-resolv.conf
```

named_options

Include this file in the named options block. This file tells named which name servers to use for global lookups.

named_zones

Include this file in the named global scope, after the options block. This file tells named which name servers to use for specific domains. Example resolvconf.conf for named:

```
name_servers=127.0.0.1
named_options=/etc/named-options.conf
named_zones=/etc/named-zones.conf
```

Example named.conf:

```
options {
	listen-on { 127.0.0.1; };
	include "/etc/named-options.conf";
};

include "/etc/named-zones.conf";
```

pdnsd_conf

This is the main pdnsd configuration file which we modify to add our forward domains to. If this variable is not set then we rely on the pdnsd configuration file setup to read pdnsd_resolv as documented below.

pdnsd_resolv

This file tells pdnsd about global name servers. If this variable is not set then it's written to pdnsd_conf. Example resolvconf.conf for pdnsd:

```
name_servers=127.0.0.1
pdnsd_conf=/etc/pdnsd.conf
# pdnsd_resolv=/etc/pdnsd-resolv.conf
```

Example pdnsd.conf:

```
global {
	server_ip = 127.0.0.1;
	status_ctl = on;
}
server {
	# A server definition is required, even if empty.
	label="empty";
	proxy_only=on;
	# file="/etc/pdnsd-resolv.conf";
}
```

pdns_zones

This file tells pdns_recursor about specific and global name servers. Example resolvconf.conf for pdns_recursor:

```
name_servers=127.0.0.1
pdns_zones=/etc/pdns/recursor-zones.conf
```

Example recursor.conf:

```
allow-from=127.0.0.0/8, ::1/128
forward-zones-file=/etc/pdns/recursor-zones.conf
```

unbound_conf

This file tells unbound about specific and global name servers.

unbound_insecure

When set to YES, unbound marks the domains as insecure, thus ignoring DNSSEC. Example resolvconf.conf for unbound:

```
name_servers=127.0.0.1
unbound_conf=/etc/unbound-resolvconf.conf
```

Example unbound.conf:

```
include: /etc/unbound-resolvconf.conf
```

## SUBSCRIBER INTEGRATION
Not all distributions store the files the subscribers need in the same locations. For example, named service scripts have been called named, bind and rc.bind and they could be located in a directory called /etc/rc.d, /etc/init.d or similar. Each subscriber attempts to automatically configure itself, but not every distribution has been catered for. Also, users could equally want to use a different version from the one installed by default, such as bind8 and bind9. To accommodate this, the subscribers have these files in configurable variables, documented below.

dnsmasq_service

Name of the dnsmasq service.

dnsmasq_restart

Command to restart the dnsmasq service.

dnsmasq_pid

Location of the dnsmasq pidfile.

libc_service

Name of the libc service.

libc_restart

Command to restart the libc service.

named_service

Name of the named service.

named_restart

Command to restart the named service.

pdnsd_restart

Command to restart the pdnsd service.

pdns_service

Command to restart the pdns_recursor service.

pdns_restart

Command to restart the pdns_recursor service.

unbound_service

Name of the unbound service.

unbound_restart

Command to restart the unbound service.

unbound_pid

Location of the unbound pidfile.

## SEE ALSO
sh(1), resolv.conf(5), resolvconf(8)

## AUTHORS
Roy Marples <roy@marples.name>

## BUGS
Each distribution is a special snowflake and likes to name the same thing differently, namely the named service script.

Please report them to http://roy.marples.name/projects/openresolv