Next | Prev | Up | Top | Contents | Index

SVR4 MNLS Message Catalogs

There are many ways to use strings from MNLS message catalogs. You can get strings directly and then use them, or you can use output routines that search catalogs.

Putting MNLS Strings Into a Catalog

An MNLS catalog source file contains a list of strings separated by new lines. For an empty string, an empty line is used. Strings are referenced by line number in the original source file.

Applications access the catalog by line number, so it's very important not to change the line numbers of existing catalog entries. This means that, when you want to add a new string to an existing catalog source, you should always append it to the end of the file--if you put it in the middle of the file, then you change the line number for subsequent strings.

The following tools can help you compile MNLS message catalogs:

exstr(1) Searches a C source file for literal strings and lists them, or replaces them with MNLS function calls.
mkmsgs(1) Creates a message catalog for a particular locale, converting source text lines to the form used by exstr.
srchtxt(1) Displays selected strings from a message catalog.

When a file of strings is ready to be compiled, simply run mkmsgs and put the results in the directory /usr/lib/locale/localename/LC_MESSAGES.

Using MNLS in Shell Scripts

One difference between MNLS and XPG/4 catalog functions is that the MNLS catalog can be used from commands, and hence it can be used to internationalize a shell script. The following table summarizes MNLS functions that have both a command line and a function library version:

gettxt(1) Retrieve a string from the catalog.
lfmt(1) Retrieve a format string, insert arguments, display to stderr and to system log or textport.
pfmt(1) Retrieve a format string, insert arguments, display to stderr.

Specifying MNLS Catalogs

MNLS message catalogs do not need to be specifically opened. The catalog of choice can be set explicitly once, or it can be specified every time a string is needed.

To specify the default message catalog to be used by subsequent calls to MNLS functions that reference catalogs, use setcat():

#include <pfmt.h>
char *setcat(const char *catalog);
catalog is limited to 14 characters, and may contain no character equal to zero or to the ASCII codes for slash (/) or colon (:). (See the setcat(3) reference page.)

setcat() doesn't check to see if the catalog name is valid; it just stores the string for future reference. For an example of use, see the following topic. The catalog indicated by the string must be found in the directory /usr/lib/locale/localename/LC_MESSAGES.

Getting Strings From MNLS Message Catalogs

MNLS message catalogs do not need to be specifically opened. The catalog of choice can be set explicitly once, or it can be specified in each reference call. Strings are read from a catalog via gettxt() (see the gettxt(3) reference page):

#include <unistd.h>
char *gettxt(const char *msgid, const char *defaultStr);
msgid is a string containing two fields separated by a colon:

msgfilename:msgnumber
The msgfilename is a catalog name as described previously in the "Specifying MNLS Catalogs". For example, to get message 10 from the MQ catalog, you could use either:

char *str = gettxt("MQ:10", "Hello, world.\n");
or

setcat("MQ");
str = gettxt(":10", "Hello, world.\n");

Using pfmt()

pfmt() is one of the most important routines dealing with MNLS catalogs, because it is used to produce most system diagnostic messages. pfmt() formats like printf() and produces standard error message formats (see the pfmt(3) reference page for the function, or pfmt(1) for shell use). It can usually be used in place of perror(). For example,

pfmt(stderr, MM_ERROR, "MQ:64:Permission denied");
would produce, by default (such as when the Mozambique locale is unavailable),

ERROR: Permission denied.
The syntax of pfmt() is

#include <pfmt.h>
int pfmt(FILE *stream, long flags, char *format, ... );
The flags are used to indicate severity, type, or control details to pfmt(). The format string includes information specifying which message from which catalog to look for. Flag details are discussed in the following section. The format is discussed in the "Format Strings for pfmt()".

Labels, Severity, and Flags

pfmt() flags are composed of several groups; specify no more than one from each group. Specify multiple flags by using OR. The groups are as follows:

output format controlMM_NOSTD, MM_STD
catalog access controlMM_NOGET, MM_GET
severityMM_HALT, MM_ERROR, MM_WARNING, MM_INFO
action message specificationMM_ACTION

pfmt() prints messages in the form label:severity:text. Severity is specified in the flags. The text comes from a message catalog (or a default) as specified in the format, and the label is specified earlier by the application.

In the example above, if no label has been set, we get only the output:

ERROR: Permission denied.
Typically, an application sets the label once early in its life; subsequent error messages have the label prepended. For example

setlabel("UX:myprog");
...
pfmt(stderr, MM_ERROR, "MQ:64:Permission denied");
would produce (by default)

UX:myprog: ERROR: Permission denied.
For details, consult the pfmt(3) and setlabel(3) reference pages.

Format Strings for pfmt()

pfmt() format strings are of this form:

[[catalog:]messagenum:]defaultstring
The catalog field is in the format described in "Specifying MNLS Catalogs". messagenum is the message number in the catalog to use as the format. defaultstring specifies the string to use if the catalog lookup fails for any reason.

An important feature of pfmt() is its ability to refer to format arguments in format-specified order just as printf() does. See "Variably Ordered Referencing of printf() Arguments" for details.

Using fmtmsg()

fmtmsg() is a comprehensive formatter using the MNLS catalogs and "standard" formats. You probably won't need to use it; most applications should get by with pfmt(), gettxt(), and printf(). Consult the fmtmsg(3) reference page for details.

Internationalizing File Typing Rule Strings With MNLS

You can internationalize the strings defined in the LEGEND and MENUCMD rules in the File Typing Rule (FTR) file. To internationalize these rules, precede the string with the following:

:[catalogname:]msgnumber:
catalogname is optional and should be a valid MNLS catalog; msgnumber is the line number in catalogname. If you omit catalogname, the uxsgidesktop catalog is used by default.

You can use these rules to create your own FTR catalog. For example, an entry looks like this:

LEGEND :mycatalog:7:Archive 8mm Tape Drive
This entry uses line 7 from the catalog, mycatalog, as the LEGEND for this FTR. If mycatalog is not available, or line 7 is not accessible from mycatalog, "Archive 8mm Tape Drive" is used as the LEGEND.

LEGEND :7:Archive 8mm Tape Drive
This entry uses line 7 from the uxsgidesktop catalog, if available. Otherwise, "Archive 8mm Tape Drive" is used.

The next example,

MENUCMD \'mycatalog:9:Eject Tape\' /usr/sbin/eject /dev/tape
displays line 9 from mycatalog, if available. Otherwise "Eject Tape" is displayed on the menu that pops up when you click an icon that uses this FTR.

You can internationalize strings in the command part of MENUCMD and CMD rules by using gettxt or any other convenient policy detailed in this section. For example

CMD OPEN xconfirm -t "Tape tool not available"
can be internationalized to

CMD OPEN xconfirm -t "'gettxt mycatalog:376 'Tape tool not available''"
In this example, gettxt is invoked to access line 376 from the catalog, mycatalog, and the string returned by gettxt is passed to xconfirm for display. If line 376 from mycatalog is not accessible, then gettxt returns the string "Tape tool not available."

For more information about FTRs, see the Indigo Magic Desktop Integration Guide.

Next | Prev | Up | Top | Contents | Index