| blob | a9c90abb979080bec7bde85ae63eab052ce1bf39 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
44 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
45 .\"
46 .TH CHARMAP 5 "Dec 1, 2003"
47 .SH NAME
48 charmap \- character set description file
49 .SH DESCRIPTION
50 .sp
51 .LP
52 A character set description file or \fIcharmap\fR defines characteristics for a
53 coded character set. Other information about the coded character set may also
54 be in the file. Coded character set character values are defined using symbolic
55 character names followed by character encoding values.
56 .sp
57 .LP
58 The character set description file provides:
59 .RS +4
60 .TP
61 .ie t \(bu
62 .el o
63 The capability to describe character set attributes (such as collation order or
64 character classes) independent of character set encoding, and using only the
65 characters in the portable character set. This makes it possible to create
66 generic \fBlocaledef\fR(1) source files for all codesets that share the
67 portable character set.
68 .RE
69 .RS +4
70 .TP
71 .ie t \(bu
72 .el o
73 Standardized symbolic names for all characters in the portable character set,
74 making it possible to refer to any such character regardless of encoding.
75 .RE
76 .SS "Symbolic Names"
77 .sp
78 .LP
79 Each symbolic name is included in the file and is mapped to a unique encoding
80 value (except for those symbolic names that are shown with identical glyphs).
81 If the control characters commonly associated with the symbolic names in the
82 following table are supported by the implementation, the symbolic names and
83 their corresponding encoding values are included in the file. Some of the
84 encodings associated with the symbolic names in this table may be the same as
85 characters in the portable character set table.
86 .sp
88 .sp
89 .TS
90 box;
91 l l l l l l
92 l l l l l l .
93 <ACK> <DC2> <ENQ> <FS> <IS4> <SOH>
94 <BEL> <DC3> <EOT> <GS> <LF> <STX>
95 <BS> <DC4> <ESC> <HT> <NAK> <SUB>
96 <CAN> <DEL> <ETB> <IS1> <RS> <SYN>
97 <CR> <DLE> <ETX> <IS2> <SI> <US>
98 <DC1> <EM> <FF> <IS3> <SO> <VT>
99 .TE
101 .SS "Declarations"
102 .sp
103 .LP
104 The following declarations can precede the character definitions. Each must
105 consist of the symbol shown in the following list, starting in column 1,
106 including the surrounding brackets, followed by one or more blank characters,
107 followed by the value to be assigned to the symbol.
108 .sp
109 .ne 2
110 .na
111 \fB<\fIcode_set_name\fR>\fR
112 .ad
113 .RS 19n
114 The name of the coded character set for which the character set description
115 file is defined.
116 .RE
118 .sp
119 .ne 2
120 .na
121 \fB<\fImb_cur_max\fR>\fR
122 .ad
123 .RS 19n
124 The maximum number of bytes in a multi-byte character. This defaults to
125 \fB1\fR.
126 .RE
128 .sp
129 .ne 2
130 .na
131 \fB<\fImb_cur_min\fR>\fR
132 .ad
133 .RS 19n
134 An unsigned positive integer value that defines the minimum number of bytes in
135 a character for the encoded character set.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB<\fIescape_char\fR>\fR
142 .ad
143 .RS 19n
144 The escape character used to indicate that the characters following will be
145 interpreted in a special way, as defined later in this section. This defaults
146 to backslash ('\fB\e\fR\&'), which is the character glyph used in all the
147 following text and examples, unless otherwise noted.
148 .RE
150 .sp
151 .ne 2
152 .na
153 \fB<\fIcomment_char\fR>\fR
154 .ad
155 .RS 19n
156 The character that when placed in column 1 of a charmap line, is used to
157 indicate that the line is to be ignored. The default character is the number
158 sign (#).
159 .RE
161 .SS "Format"
162 .sp
163 .LP
164 The character set mapping definitions will be all the lines immediately
165 following an identifier line containing the string \fBCHARMAP\fR starting in
166 column 1, and preceding a trailer line containing the string \fBEND\fR
167 \fBCHARMAP\fR starting in column 1. Empty lines and lines containing a
168 \fI<comment_char>\fR in the first column will be ignored. Each non-comment line
169 of the character set mapping definition, that is, between the \fBCHARMAP\fR and
170 \fBEND CHARMAP\fR lines of the file), must be in either of two forms:
171 .sp
172 .in +2
173 .nf
174 \fB"%s %s %s\en",\fR<\fIsymbolic-name\fR>,<\fIencoding\fR>,<\fIcomments\fR>
175 .fi
176 .in -2
178 .sp
179 .LP
180 or
181 .sp
182 .in +2
183 .nf
184 \fB"%s...%s %s %s\en",\fR<\fIsymbolic-name\fR>,<\fIsymbolic-name\fR>, <\fIencoding\fR>,\e
185 <\fIcomments\fR>
186 .fi
187 .in -2
189 .sp
190 .LP
191 In the first format, the line in the character set mapping definition defines a
192 single symbolic name and a corresponding encoding. A character following an
193 escape character is interpreted as itself; for example, the sequence
194 "<\fB\e\e\e\fR>>" represents the symbolic name "\fI\e>\fR" enclosed between
195 angle brackets.
196 .sp
197 .LP
198 In the second format, the line in the character set mapping definition defines
199 a range of one or more symbolic names. In this form, the symbolic names must
200 consist of zero or more non-numeric characters, followed by an integer formed
201 by one or more decimal digits. The characters preceding the integer must be
202 identical in the two symbolic names, and the integer formed by the digits in
203 the second symbolic name must be equal to or greater than the integer formed by
204 the digits in the first name. This is interpreted as a series of symbolic names
205 formed from the common part and each of the integers between the first and the
206 second integer, inclusive. As an example, \fB<j0101>...<j0104>\fR is
207 interpreted as the symbolic names \fB<j0101>\fR, \fB<j0102>\fR, \fB<j0103>\fR,
208 and \fB<j0104>\fR, in that order.
209 .sp
210 .LP
211 A character set mapping definition line must exist for all symbolic names and
212 must define the coded character value that corresponds to the character glyph
213 indicated in the table, or the coded character value that corresponds with the
214 control character symbolic name. If the control characters commonly associated
215 with the symbolic names are supported by the implementation, the symbolic name
216 and the corresponding encoding value must be included in the file. Additional
217 unique symbolic names may be included. A coded character value can be
218 represented by more than one symbolic name.
219 .sp
220 .LP
221 The encoding part is expressed as one (for single-byte character values) or
222 more concatenated decimal, octal or hexadecimal constants in the following
223 formats:
224 .sp
225 .in +2
226 .nf
227 \fB"%cd%d",\fR<\fIescape_char\fR>,<\fIdecimal byte value\fR>
229 \fB"%cx%x",\fR<\fIescape_char\fR>,<\fIhexadecimal byte value\fR>
231 \fB"%c%o",\fR<\fIescape_char\fR>,<\fIoctal byte value\fR>
232 .fi
233 .in -2
235 .SS "Decimal Constants"
236 .sp
237 .LP
238 Decimal constants must be represented by two or three decimal digits, preceded
239 by the escape character and the lower-case letter \fBd\fR; for example,
240 \fB\ed05\fR, \fB\ed97\fR, or \fB\ed143\fR\&. Hexadecimal constants must be
241 represented by two hexadecimal digits, preceded by the escape character and the
242 lower-case letter \fBx\fR; for example, \fB\ex05\fR, \fB\ex61\fR, or
243 \fB\ex8f\fR\&. Octal constants must be represented by two or three octal
244 digits, preceded by the escape character; for example, \fB\e05\fR, \fB\e141\fR,
245 or \fB\e217\fR\&. In a portable charmap file, each constant must represent an
246 8-bit byte. Implementations supporting other byte sizes may allow constants to
247 represent values larger than those that can be represented in 8-bit bytes, and
248 to allow additional digits in constants. When constants are concatenated for
249 multi-byte character values, they must be of the same type, and interpreted in
250 byte order from first to last with the least significant byte of the multi-byte
251 character specified by the last constant.
252 .SS "Ranges of Symbolic Names"
253 .sp
254 .LP
255 In lines defining ranges of symbolic names, the encoded value is the value for
256 the first symbolic name in the range (the symbolic name preceding the
257 ellipsis). Subsequent symbolic names defined by the range will have encoding
258 values in increasing order. Bytes are treated as unsigned octets and carry is
259 propagated between the bytes as necessary to represent the range. However,
260 because this causes a null byte in the second or subsequent bytes of a
261 character, such a declaration should not be specified. For example, the line
262 .sp
263 .in +2
264 .nf
265 <j0101>...<j0104> \ed129\ed254
266 .fi
267 .in -2
269 .sp
270 .LP
271 is interpreted as:
272 .sp
273 .in +2
274 .nf
275 <j0101> \ed129\ed254
276 <j0102> \ed129\ed255
277 <j0103> \ed130\ed00
278 <j0104> \ed130\ed01
279 .fi
280 .in -2
282 .sp
283 .LP
284 The expanded declaration of the symbol \fB<j0103>\fR in the above example is an
285 invalid specification, because it contains a null byte in the second byte of a
286 character.
287 .sp
288 .LP
289 The comment is optional.
290 .SS "Width Specification"
291 .sp
292 .LP
293 The following declarations can follow the character set mapping definitions
294 (after the "\fBEND CHARMAP\fR" statement). Each consists of the keyword shown
295 in the following list, starting in column 1, followed by the value(s) to be
296 associated to the keyword, as defined below.
297 .sp
298 .ne 2
299 .na
300 \fB\fBWIDTH\fR\fR
301 .ad
302 .RS 17n
303 A non-negative integer value defining the column width for the printable
304 character in the coded character set mapping definitions. Coded character set
305 character values are defined using symbolic character names followed by column
306 width values. Defining a character with more than one \fBWIDTH\fR produces
307 undefined results. The \fBEND WIDTH\fR keyword is used to terminate the
308 \fBWIDTH\fR definitions. Specifying the width of a non-printable character in a
309 \fBWIDTH\fR declaration produces undefined results.
310 .RE
312 .sp
313 .ne 2
314 .na
315 \fB\fBWIDTH_DEFAULT\fR\fR
316 .ad
317 .RS 17n
318 A non-negative integer value defining the default column width for any
319 printable character not listed by one of the \fBWIDTH\fR keywords. If no
320 \fBWIDTH_DEFAULT\fR keyword is included in the charmap, the default character
321 width is \fB1\fR.
322 .RE
324 .sp
325 .LP
326 Example:
327 .sp
328 .LP
329 After the "\fBEND CHARMAP\fR" statement, a syntax for a width definition would
330 be:
331 .sp
332 .in +2
333 .nf
334 WIDTH
335 <A> 1
336 <B> 1
337 <C>...<Z> 1
338 \&...
339 <fool>...<foon> 2
340 \&...
341 END WIDTH
342 .fi
343 .in -2
344 .sp
346 .sp
347 .LP
348 In this example, the numerical code point values represented by the symbols
349 \fB<A>\fR and \fB<B>\fR are assigned a width of \fB1\fR. The code point values
350 \fB< C>\fR to \fB<Z>\fR inclusive, that is, \fB<C>\fR, \fB<D>\fR, \fB<E>\fR,
351 and so on, are also assigned a width of \fB1\fR. Using \fB<A>...<Z>\fR would
352 have required fewer lines, but the alternative was shown to demonstrate
353 flexibility. The keyword \fBWIDTH_DEFAULT\fR could have been added as
354 appropriate.
355 .SH SEE ALSO
356 .sp
357 .LP
358 \fBlocale\fR(1), \fBlocaledef\fR(1), \fBnl_langinfo\fR(3C),
359 \fBextensions\fR(5), \fBlocale\fR(5)