X/Open message facility - the set of functions catopen(), catclose(), and catgets(), the command line utility gencat, a specification for message catalog source files, and the methodology for using these things.

The purpose of the X/Open message facility is to facilitate the development of application programs that present messages in the user's locale, and to allow the selection of the user's locale at run-time.

message facility - same as X/Open message facility.

message - a null-terminated multibyte string which may be a prompt, error message, status message, or any string which is required to be presented to the user of a program in his locale.

A message is always associated with a locale and is represented in the codeset associated with that locale. A message may also serve as a repository for a string which must be in a run-time selectable locale and is used for comparison with user input.

In the context of the X/Open message facility, all strings are NULL terminated multibyte strings, unless otherwise stated.

translated message - a message resulting from translation. translation - process by which a message represented in locale 1 is transformed into the corresponding message, with the same meaning, represented in locale 2.

AT&T Language Line Services (R) - translation services provided by AT&T.

message extraction - process by which one or more messages are moved or copied from an existing program into a message catalog source file. At the same time, changes are made to the program to allow the program to read the corresponding message catalog binary file at run time.

externalized message - message which has undergone message extraction.

Generally, message extraction is not currently automatable. However, tools have been written to do message extraction in cases where the messages are associated with printf() calls and other standard output functions.

message catalog - a set of logically-related messages, possibly translated, in which each message is associated with a message number and a set number. All of the messages of the same message catalog are represented in the same locale.

catalog name - null terminated string which is the name of the corresponding message catalog.

set of messages - set of logically related messages in a message catalog. There may be more than one set in a message catalog. All of the messages in a set have the same set number. All of the messages in a set must have a unique message number within the set.

set number - integer, greater than zero, associated with a set of messages. Set numbers must be unique within a message catalog.

set identifier - same as set number.

NL_SETD - default value of the set number if none is specified in the message catalog source file, defined in .

Set numbers must be presented in ascending order within a single message catalog source file but need not be contiguous.

NL_SETMAX - maximum allowed set number in a message catalog, defined in .

No fixed usage of the set mechanism is defined by X/Open.

message number - integer, greater than zero, associated with a message in a message catalog. The message numbers must be unique within a set but may or may not be unique within a message catalog.

message identifier - same as message number.

symbolic message number - message number represented as a symbol suitable for inclusion in a header file. Symbolic message numbers are not permitted by X/Open in message catalogs, though AIX supports a version of gencat that permits this.

symbolic set number - set number represented as a symbol suitable for inclusion in a header file. Symbolic set numbers are not permitted by X/Open in message catalogs, though AIX supports a version of gencat that permits this.

NL_MSGMAX - maximum allowed message number in a message catalog, defined in .

NL_TEXTMAX - maximum number of bytes in a given message, including the null byte.

Messages which exceed NL_TEXTMAX bytes in length must be broken down into smaller segments, keeping each segment as logically complete (no hyphens, try not to end sentence in the middle of a printf) as possible. catopen() - opens the specified message catalog binary file for the current locale and returns a catalog descriptor. The value of the environment variable NLSPATH is used to locate the message catalog binary file.

catalog descriptor - a descriptor of type nl_catd which uniquely identifies a successfully opened message catalog binary file. On some systems, a catalog descriptor is an integer, on others it may be a pointer to a structure.

catclose() - closes the message catalog binary file given by the catalog descriptor.

catgets() - Given a catalog descriptor, set number, message number, and default string, catgets() returns a pointer to a message from the message catalog binary file given by the catalog descriptor, or the given default string if the specified message is not available or the message catalog binary file is unreadable. The message is stored in a static buffer which may be overwritten by subsequent calls to catgets().

default string - a NULL terminated string of (potentially) multibyte characters passed to catgets() to be returned by catgets() in case any error occurs during the call. Usually, the default string contains the message in the English or C locale.

The default string should always be used in case the current locale is not supported.

Errors returned from catopen() may be safely ignored since catgets() will return the default string if the specified message catalog binary file is unreadable.

The definition of nl_catd and the prototypes for the cat*() functions are located in .

gencat - command line utility which transforms a message catalog source file into the corresponding message catalog binary file.

message catalog source file - a source file which specifies a message catalog. The messages may be translated messages in a given locale. The codeset used to represent the messages in the message catalog source file should agree with the codeset to be used in the target message catalog binary file.

message catalog binary file - a file containing a message catalog which is opened by catopen() and read by catgets(). The codeset used in the message catalog binary file is the same as that specified by the locale at the time gencat is invoked.

A message catalog source file consists of directives to set the quote character, the current set number, and a series of numbered messages. Each numbered message consists of a message number beginning in column zero, a single space or tab character, and the text of the message. Empty lines are ignored. Single messages longer than one line should escape the newline character. A line beginning with a $, followed by a space or tab character, is treated as a comment.

It is desireable that each message in a catalog have a comment associated with it that gives more detailed information about the meaning of the message and the conditions under which it will appear. This comment makes translation much simpler. The comment should also give the location of the code which presents the message in case locale-dependent bugs are encountered. When gencat is invoked, if the specified message catalog binary file exists, then messages in the given source file are merged into the binary, replacing messages with the same set-number/message-number combination.

The delset directive may be used to delete an entire set from a message catalog binary file.

For reasons of codeset portability, it is suggested that the default strings be in English.

If performance is an issue, messages may be retrieved from a message catalog all at once at the beginning of the program and stored in a static array. Disk I/O buffering may minimize performance problems if catgets() is used on each message retrieval.

Prior to XPG4, the LC_MESSAGES category was not recognized. oflag - the second argument of catopen() which specifies where catopen() looks for the value of the locale-name to substitute for %L in NLSPATH. If oflag is zero, then the value of LANG is used. If oflag is NL_CAT_LOCALE, then the value of LC_MESSAGES is used if it is set, otherwise, the value of LANG is used.

Prior to XPG4, oflag was reserved for future use and was always set to zero.

It is not necessary to call setlocale() to use the X/Open message facility routines catopen(), catclose(), and catgets().

search path - sequence of templates separated by colons.

NLSPATH template - Each NLSPATH template consists of an optional prefix, one or more substitution fields, a file name, and an optional suffix.

NLSPATH - environment variable which gives both the location of message catalogs, in the form of a search path, and naming conventions associated with message catalog files.

%N - NLSPATH substitution field whose value is the name passed to catopen().

%L - NLSPATH substitution field whose value is equal to LC_MESSAGES, or LANG if LC_MESSAGES is not defined, or C if neither is defined.

A leading colon or two adjacent colons in the definition of NLSPATH is equivalent to specifying %N.

For documentation purposes, catalog names should be of the form name.cat.

Names passed to catopen() should not include the ".cat" suffix. Every application must agree on the catalog naming convention used on a particular system.

Since NLSPATH is set once and applies to all applications, every application must also agree on the naming convention of the argument passed to catopen() which may or may not use the .cat suffix.

The developer should not rely on testing to determine whether all messages have been externalized since exhaustive testing is impossible for many types of error messages. Eyeballing the code is much more reliable.

mixed language message - a message displayed to the user which contains portions of the message in the current locale and other portions of the message in the default locale. A mixed language message occurs when messages are composed at run-time by concatenation and one or more of these message segments have not be externalized.