NAME

gencat - generate a formatted message catalogue

 SYNOPSIS

gencat catfile msgfile... 

 DESCRIPTION

The gencat utility merges the message text source files msgfile into a formatted message catalogue catfile. The file catfile will be created if it does not already exist. If catfile does exist, its messages will be included in the new catfile. If set and message numbers collide, the new message text defined in msgfile will replace the old message text currently contained in catfile.

 OPTIONS

None.

 OPERANDS

The following operands are supported:

catfile

A pathname of the formatted message catalogue. If "-" is specified, standard output is used. The format of the message catalogue produced is unspecified.

msgfile

A pathname of a message text source file. If "-" is specified for an instance of msgfile, standard input is used. The format of message text source files is defined in the EXTENDED DESCRIPTION section.

 STDIN

The standard input is not used unless a msgfile operand is specified as "-".

 INPUT FILES

The input files are text files.

 ENVIRONMENT VARIABLES

The following environment variables affect the execution of gencat:

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation 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 internationalisation 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).

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 catalogues for the processing of LC_MESSAGES .

 ASYNCHRONOUS EVENTS

Default.

 STDOUT

The standard output is not used unless the catfile operand is specified as -.

 STDERR

Used only for diagnostic messages.

 OUTPUT FILES

None.

 EXTENDED DESCRIPTION

The format of a message text source file is defined as follows. Note that the fields of a message text source line are separated by a single blank character. Any other blank characters are considered as being part of the subsequent field.

$set  n comment

This line specifies the set identifier of the following messages until the next $set or end-of-file appears. The n denotes the set identifier, which is defined as a number in the range [1, {NL_SETMAX}] (see the XSH specification, <limits.h>). Set identifiers must be presented in ascending order within a single source file but need not be contiguous. Any string following the set identifier is treated as a comment. If no $set directive is specified in a message text source file, all messages will be located in an implementation-dependent default message set NL_SETD (see the XSH specification, <nl_types.h>).

$delset  n comment

This line deletes message set n from an existing message catalogue. The n denotes the set number [1, {NL_SETMAX}]. Any string following the set number is treated as a comment.

$ comment

A line beginning with "$" followed by a blank character is treated as a comment.

m message-text

The m denotes the message identifier, which is defined as a number in the range [1, {NL_MSGMAX}] (see the XSH specification, <limits.h>). The message-text is stored in the message catalogue with the set identifier specified by the last $set directive, and with message identifier m. If the message-text is empty, and a blank character field separator is present, an empty string is stored in the message catalogue. If a message source line has a message number, but neither a field separator nor message-text, the existing message with that number (if any) is deleted from the catalogue. Message identifiers must be in ascending order within a single set, but need not be contiguous. The length of message-text must be in the range [0, {NL_TEXTMAX}] (see the XSH specification, <limits.h>).

$quote  n

This line specifies an optional quote character c, which can be used to surround message-text so that trailing spaces or null (empty) messages are visible in a message source line. By default, or if an empty $quote directive is supplied, no quoting of message-text will be recognised.

Empty lines in a message text source file are ignored. The effects of lines starting with any character other than those defined above are implementation-dependent.

Text strings can contain the special characters and escape sequences defined in the following table:

Description	Symbol	Sequence
newline	NL(LF)	\n
horizontal tab	HT	\t
vertical-tab	VT	\v
backspace	BS	\b
carriage-return	CR	\r
form-feed	FF	\f
backslash	\	\\
bit pattern	ddd	\ddd

The escape sequence \ddd consists of backslash followed by one, two or three octal digits, which are taken to specify the value of the desired character. If the character following a backslash is not one of those specified, the backslash is ignored.

Backslash (\) followed by a newline character is also used to continue a string on the following line. Thus, the following two lines describe a single message string:

1 This line continues \
to the next line

which is equivalent to:

1 This line continues to the next line

 EXIT STATUS

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

 CONSEQUENCES OF ERRORS

Default.

 APPLICATION USAGE

Message catalogues produced by gencat are binary encoded, meaning 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, so message catalogues must be recreated via gencat.

 EXAMPLES

None.

 FUTURE DIRECTIONS

None.

 SEE ALSO

iconv, the XSH specification description of <limits.h>.