mirror of https://github.com/mkerrisk/man-pages
238 lines
7.7 KiB
Groff
238 lines
7.7 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "GENCAT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" gencat
|
|
.SH NAME
|
|
gencat \- generate a formatted message catalog
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBgencat\fP \fIcatfile msgfile\fP\fB... \fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIgencat\fP utility shall merge the message text source file
|
|
\fImsgfile\fP into a formatted message catalog
|
|
\fIcatfile\fP. The file \fIcatfile\fP shall be created if it does
|
|
not already exist. If \fIcatfile\fP does exist, its messages
|
|
shall be included in the new \fIcatfile\fP. If set and message numbers
|
|
collide, the new message text defined in \fImsgfile\fP
|
|
shall replace the old message text currently contained in \fIcatfile\fP.
|
|
.SH OPTIONS
|
|
.LP
|
|
None.
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operands shall be supported:
|
|
.TP 7
|
|
\fIcatfile\fP
|
|
A pathname of the formatted message catalog. If \fB'-'\fP is specified,
|
|
standard output shall be used. The format of the
|
|
message catalog produced is unspecified.
|
|
.TP 7
|
|
\fImsgfile\fP
|
|
A pathname of a message text source file. If \fB'-'\fP is specified
|
|
for an instance of \fImsgfile\fP, standard input shall
|
|
be used. The format of message text source files is defined in the
|
|
EXTENDED DESCRIPTION section.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
The standard input shall not be used unless a \fImsgfile\fP operand
|
|
is specified as \fB'-'\fP .
|
|
.SH INPUT FILES
|
|
.LP
|
|
The input files shall be text files.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fIgencat\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
Provide a default value for the internationalization variables that
|
|
are unset or null. (See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
for
|
|
the precedence of internationalization variables used to determine
|
|
the values of locale categories.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments and input files).
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic messages written to standard
|
|
error.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
The standard output shall not be used unless the \fIcatfile\fP operand
|
|
is specified as \fB'-'\fP .
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used only for diagnostic messages.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
The content of a message text file shall be in the format defined
|
|
as follows. Note that the fields of a message text source line
|
|
are separated by a single <blank>. Any other <blank>s are considered
|
|
to be part of the subsequent field.
|
|
.TP 7
|
|
\fB$set\ \fP \fIn\ comment\fP
|
|
.sp
|
|
This line specifies the set identifier of the following messages until
|
|
the next \fB$set\fP or end-of-file appears. The \fIn\fP
|
|
denotes the set identifier, which is defined as a number in the range
|
|
[1, {NL_SETMAX}] (see the \fI<limits.h>\fP header defined in the Base
|
|
Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001). The application shall ensure that set identifiers
|
|
are presented in ascending order within a single
|
|
source file, but need not be contiguous. Any string following the
|
|
set identifier shall be treated as a comment. If no \fB$set\fP
|
|
directive is specified in a message text source file, all messages
|
|
shall be located in an implementation-defined default message
|
|
set NL_SETD (see the \fI<nl_types.h>\fP header defined in the Base
|
|
Definitions
|
|
volume of IEEE\ Std\ 1003.1-2001).
|
|
.TP 7
|
|
\fB$delset\ \fP \fIn\ comment\fP
|
|
.sp
|
|
This line deletes message set \fIn\fP from an existing message catalog.
|
|
The \fIn\fP denotes the set number [1, {NL_SETMAX}]. Any
|
|
string following the set number shall be treated as a comment.
|
|
.TP 7
|
|
\fB$\ \fP \fIcomment\fP
|
|
A line beginning with \fB'$'\fP followed by a <blank> shall be treated
|
|
as a comment.
|
|
.TP 7
|
|
\fIm\ message-text\fP
|
|
.sp
|
|
The \fIm\fP denotes the message identifier, which is defined as a
|
|
number in the range [1, {NL_MSGMAX}] (see the \fI<limits.h>\fP header).
|
|
The \fImessage-text\fP shall be stored in the message catalog
|
|
with the set identifier specified by the last \fB$set\fP directive,
|
|
and with message identifier \fIm\fP. If the
|
|
\fImessage-text\fP is empty, and a <blank> field separator is present,
|
|
an empty string shall be stored in the message
|
|
catalog. If a message source line has a message number, but neither
|
|
a field separator nor \fImessage-text\fP, the existing message
|
|
with that number (if any) shall be deleted from the catalog. The application
|
|
shall ensure that message identifiers are in ascending
|
|
order within a single set, but need not be contiguous. The application
|
|
shall ensure that the length of \fImessage-text\fP is in
|
|
the range [0, {NL_TEXTMAX}] (see the \fI<limits.h>\fP header).
|
|
.TP 7
|
|
\fB$quote\ \fP \fIn\fP
|
|
This line specifies an optional quote character \fIc\fP, which can
|
|
be used to surround \fImessage-text\fP so that trailing
|
|
spaces or null (empty) messages are visible in a message source line.
|
|
By default, or if an empty \fB$quote\fP directive is
|
|
supplied, no quoting of \fImessage-text\fP shall be recognized.
|
|
.sp
|
|
.LP
|
|
Empty lines in a message text source file shall be ignored. The effects
|
|
of lines starting with any character other than those
|
|
defined above are implementation-defined.
|
|
.LP
|
|
Text strings can contain the special characters and escape sequences
|
|
defined in the following table:
|
|
.TS C
|
|
center; l l l.
|
|
\fBDescription\fP \fBSymbol\fP \fBSequence\fP
|
|
<newline> NL(LF) \\n
|
|
Horizontal-tab HT \\t
|
|
<vertical-tab> VT \\v
|
|
<backspace> BS \\b
|
|
<carriage-return> CR \\r
|
|
<form-feed> FF \\f
|
|
Backslash \fB\\\fP \\\\
|
|
Bit pattern \fBddd\fP \\ddd
|
|
.TE
|
|
.LP
|
|
The escape sequence \fB"\\ddd"\fP consists of backslash followed by
|
|
one, two, or three octal digits, which shall be taken to
|
|
specify the value of the desired character. If the character following
|
|
a backslash is not one of those specified, the backslash
|
|
shall be ignored.
|
|
.LP
|
|
Backslash ( \fB'\\'\fP ) followed by a <newline> is also used to continue
|
|
a string on the following line. Thus, the
|
|
following two lines describe a single message string:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB1 This line continues \\
|
|
to the next line
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
which shall be equivalent to:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB1 This line continues to the next line
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
Successful completion.
|
|
.TP 7
|
|
>0
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
Default.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
Message catalogs produced by \fIgencat\fP 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 catalogs must be
|
|
recreated via \fIgencat\fP.
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIiconv\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<limits.h>\fP, \fI<nl_types.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version and the original IEEE and
|
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
is the referee document. The original Standard can be obtained online at
|
|
http://www.opengroup.org/unix/online.html .
|