1GENCAT(1P)                 POSIX Programmer's Manual                GENCAT(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       gencat — generate a formatted message catalog
14

SYNOPSIS

16       gencat catfile msgfile...
17

DESCRIPTION

19       The gencat utility shall merge the message  text  source  file  msgfile
20       into  a  formatted  message catalog catfile.  The file catfile shall be
21       created if it does not already exist. If catfile does exist,  its  mes‐
22       sages shall be included in the new catfile.  If set and message numbers
23       collide, the new message text defined in msgfile shall replace the  old
24       message text currently contained in catfile.
25

OPTIONS

27       None.
28

OPERANDS

30       The following operands shall be supported:
31
32       catfile   A pathname of the formatted message catalog. If '−' is speci‐
33                 fied, standard output shall be used. The format of  the  mes‐
34                 sage catalog produced is unspecified.
35
36       msgfile   A pathname of a message text source file. If '−' is specified
37                 for an instance of msgfile, standard input shall be used. The
38                 format  of  message  text  source  files  is  defined  in the
39                 EXTENDED DESCRIPTION section.
40

STDIN

42       The standard input shall not be used unless a msgfile operand is speci‐
43       fied as '−'.
44

INPUT FILES

46       The input files shall be text files.
47

ENVIRONMENT VARIABLES

49       The  following environment variables shall affect the execution of gen‐
50       cat:
51
52       LANG      Provide a default value for  the  internationalization  vari‐
53                 ables  that are unset or null. (See the Base Definitions vol‐
54                 ume of POSIX.1‐2008, Section 8.2, Internationalization  Vari‐
55                 ables  for  the  precedence of internationalization variables
56                 used to determine the values of locale categories.)
57
58       LC_ALL    If set to a non-empty string value, override  the  values  of
59                 all the other internationalization variables.
60
61       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
62                 bytes of text data as characters (for example, single-byte as
63                 opposed  to  multi-byte  characters  in  arguments  and input
64                 files).
65
66       LC_MESSAGES
67                 Determine the locale that should be used to affect the format
68                 and  contents  of  diagnostic  messages  written  to standard
69                 error.
70
71       NLSPATH   Determine the location of message catalogs for the processing
72                 of LC_MESSAGES.
73

ASYNCHRONOUS EVENTS

75       Default.
76

STDOUT

78       The  standard  output  shall  not be used unless the catfile operand is
79       specified as '−'.
80

STDERR

82       The standard error shall be used only for diagnostic messages.
83

OUTPUT FILES

85       None.
86

EXTENDED DESCRIPTION

88       The content of a message text file shall be in the  format  defined  as
89       follows.  Note  that the fields of a message text source line are sepa‐
90       rated by a single <blank> character. Any other <blank>  characters  are
91       considered to be part of the subsequent field.
92
93       $set n comment
94                 This  line specifies the set identifier of the following mes‐
95                 sages until the next  $set  or  end-of-file  appears.  The  n
96                 denotes  the  set identifier, which is defined as a number in
97                 the range [1, {NL_SETMAX}] (see the <limits.h> header defined
98                 in the Base Definitions volume of POSIX.1‐2008). The applica‐
99                 tion shall ensure  that  set  identifiers  are  presented  in
100                 ascending  order within a single source file, but need not be
101                 contiguous. Any string following the set identifier shall  be
102                 treated  as a comment. If no $set directive is specified in a
103                 message text source file, all messages shall be located in an
104                 implementation-defined  default  message set NL_SETD (see the
105                 <nl_types.h> header defined in the Base Definitions volume of
106                 POSIX.1‐2008).
107
108       $delset n comment
109                 This line deletes message set n from an existing message cat‐
110                 alog. The n denotes the set  number  [1,  {NL_SETMAX}].   Any
111                 string  following  the  set number shall be treated as a com‐
112                 ment.
113
114       $ comment A line beginning with '$' followed  by  a  <blank>  shall  be
115                 treated as a comment.
116
117       m message-text
118                 The  m  denotes the message identifier, which is defined as a
119                 number in the range  [1,  {NL_MSGMAX}]  (see  the  <limits.h>
120                 header). The message-text shall be stored in the message cat‐
121                 alog with the set  identifier  specified  by  the  last  $set
122                 directive,  and  with  message identifier m.  If the message-
123                 text is empty, and a <blank> field separator is  present,  an
124                 empty  string  shall  be  stored in the message catalog. If a
125                 message source line has a message number, but neither a field
126                 separator  nor  message-text,  the existing message with that
127                 number (if any) shall be deleted from the catalog. The appli‐
128                 cation shall ensure that message identifiers are in ascending
129                 order within a single set, but need not  be  contiguous.  The
130                 application  shall  ensure that the length of message-text is
131                 in the range [0, {NL_TEXTMAX}] (see the <limits.h> header).
132
133       $quote n  This line specifies an optional quote character c, which  can
134                 be  used  to  surround  message-text so that trailing <space>
135                 characters or null (empty) messages are visible in a  message
136                 source  line.  By default, or if an empty $quote directive is
137                 supplied, no quoting of message-text shall be recognized.
138
139       Empty lines in a message text source file shall be ignored. The effects
140       of lines starting with any character other than those defined above are
141       implementation-defined.
142
143       Text strings can contain the special characters  and  escape  sequences
144       defined in the following table:
145
146                       ┌──────────────────┬────────┬──────────┐
147Description    Symbol Sequence 
148                       ├──────────────────┼────────┼──────────┤
149                       │<newline>         │ NL(LF) │ \n       │
150                       │Horizontal-tab    │ HT     │ \t       │
151                       │<vertical-tab>    │ VT     │ \v       │
152                       │<backspace>       │ BS     │ \b       │
153                       │<carriage-return> │ CR     │ \r       │
154                       │<form-feed>       │ FF     │ \f       │
155                       │Backslash         │ \      │ \\       │
156                       │Bit pattern       │ ddd    │ \ddd     │
157                       └──────────────────┴────────┴──────────┘
158       The  escape  sequence  "\ddd"  consists of <backslash> followed by one,
159       two, or three octal digits, which shall be taken to specify  the  value
160       of  the  desired character. If the character following a <backslash> is
161       not one of those specified, the <backslash> shall be ignored.
162
163       A <backslash> followed by a <newline> is also used to continue a string
164       on  the following line. Thus, the following two lines describe a single
165       message string:
166
167           1 This line continues \
168           to the next line
169
170       which shall be equivalent to:
171
172           1 This line continues to the next line
173

EXIT STATUS

175       The following exit values shall be returned:
176
177        0    Successful completion.
178
179       >0    An error occurred.
180

CONSEQUENCES OF ERRORS

182       Default.
183
184       The following sections are informative.
185

APPLICATION USAGE

187       Message catalogs produced by gencat are binary  encoded,  meaning  that
188       their  portability  cannot  be  guaranteed  between  different types of
189       machine. Thus, just as C programs need to be recompiled for  each  type
190       of machine, so message catalogs must be recreated via gencat.
191

EXAMPLES

193       None.
194

RATIONALE

196       None.
197

FUTURE DIRECTIONS

199       None.
200

SEE ALSO

202       iconv
203
204       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
205       Variables, <limits.h>, <nl_types.h>
206
208       Portions of this text are reprinted and reproduced in  electronic  form
209       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
210       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
211       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
212       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
213       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
214       event of any discrepancy between this version and the original IEEE and
215       The  Open Group Standard, the original IEEE and The Open Group Standard
216       is the referee document. The original Standard can be  obtained  online
217       at http://www.unix.org/online.html .
218
219       Any  typographical  or  formatting  errors that appear in this page are
220       most likely to have been introduced during the conversion of the source
221       files  to  man page format. To report such errors, see https://www.ker
222       nel.org/doc/man-pages/reporting_bugs.html .
223
224
225
226IEEE/The Open Group                  2013                           GENCAT(1P)
Impressum