gencat - generate a formatted message catalog

The gencat utility merges the contents of a message text source file into a binary encoded message catalog.

The message catalog is created if it does not already exist. If it does exist, its messages are included in the new message catalog. If the set numbers and message numbers of existing and newly defined message texts match, gencat replaces the old message texts currently contained in the message catalog with the new message texts defined in the message text file.

Message catalogs produced by gencat are binary encoded, which means that their portability cannot be guaranteed between different types of machine. Thus, just as C programs need to be recompiled for each type of machine, message catalogs must be recreated with gencat.

A message text source file can contain either set and message numbers or simply message numbers. In the later case, the set NL_SETD is assumed for the set numbers.

Syntax

gencat[ -lm] catfile[ msgfile...]

-l

If catfile already exists, information on messages contained in it will be written to standard output in the following format:

SET set_num, MESSAGE mesg_num, OFFSET offset, LENGTH msg_len,
message_txt
*

offset indicates the distance from the beginning of the file to the start of the message text, i.e.

• first message: offset (1) = 0

• n th message: offset (n) = offset (n-1) + msg_len (n)

-m

The -m option ensures compliance with the X/Open Standard.

The -m option is supplied for compatibility with previous versions of gencat released in a number of specialized internationalization products. This option will cause gencat to build a single file catfile which is compatible with the format catalogs produced by the earlier versions. The retrieval routines detect the type of catalog they are using and act appropriately.

The -m option corresponds to the default behavior of gencat and need not be explicitly set.

No option specified

gencat behaves as described under the -m option.

catfile

Name of the binary encoded message catalog that gencat is to generate from the message text file msgfile.

If a dash (-) is specified for catfile, gencat prints to standard output.

msgfile

Name of the message text source file. gencat generates a binary encoded message catalog from this file. If a dash (-) is specified for msgfile, gencat reads from standard input.

More than one message text file may be specified.

Format of a message catalog

A message catalog created by gencat with the option -m contains the following structures in the given order:

• The catalog header, CAT_HDR, consisting of:

  • the file's magic number

  • the number of sets in the message file

  • the space (in bytes) needed to load the file, excluding the length of the file header

  • the position at which the message headers begin, excluding the length of the file header

  • the position at which the message texts begin, excluding the length of the file header

• A set header, CAT_SET_HDR, for each existing set. This header consists of:

  • the set number

  • the number of messages in the set

  • the initial offset in the table

• A message header, CAT_MSG_HDR, for each existing message. This header consists of:

  • the message number

  • the length of the message in bytes

  • the message offset in the table

• The individual message texts, delimited by \0.

Locale

The following environment variables affect the execution of gencat:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the classification of characters as upper- to lower-case, and the mapping of characters from one case to the other.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example

Generating a binary encoded message catalog en_wc.cat from the English message text file en_wc.msf for the wc command.

The contents of the message text file are as follow:

1 wc: cannot open %s \n
2 together \n
3 Syntax: wc[ -c| -m][ -lw][ file...] \n

The following command generates the message catalog:

$ gencat en_wc.cat en_wc.msf

See also

iconv
catopen(), catgets(), catclose(), limits.h, nl_types.h [4]