2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1998-1999, 2001-2012 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @node Non-ASCII Characters
6 @chapter Non-@acronym{ASCII} Characters
7 @cindex multibyte characters
8 @cindex characters, multi-byte
9 @cindex non-@acronym{ASCII} characters
11 This chapter covers the special issues relating to characters and
12 how they are stored in strings and buffers.
15 * Text Representations:: How Emacs represents text.
16 * Converting Representations:: Converting unibyte to multibyte and vice versa.
17 * Selecting a Representation:: Treating a byte sequence as unibyte or multi.
18 * Character Codes:: How unibyte and multibyte relate to
19 codes of individual characters.
20 * Character Properties:: Character attributes that define their
21 behavior and handling.
22 * Character Sets:: The space of possible character codes
23 is divided into various character sets.
24 * Scanning Charsets:: Which character sets are used in a buffer?
25 * Translation of Characters:: Translation tables are used for conversion.
26 * Coding Systems:: Coding systems are conversions for saving files.
27 * Input Methods:: Input methods allow users to enter various
28 non-ASCII characters without special keyboards.
29 * Locales:: Interacting with the POSIX locale.
32 @node Text Representations
33 @section Text Representations
34 @cindex text representation
36 Emacs buffers and strings support a large repertoire of characters
37 from many different scripts, allowing users to type and display text
38 in almost any known written language.
40 @cindex character codepoint
43 To support this multitude of characters and scripts, Emacs closely
44 follows the @dfn{Unicode Standard}. The Unicode Standard assigns a
45 unique number, called a @dfn{codepoint}, to each and every character.
46 The range of codepoints defined by Unicode, or the Unicode
47 @dfn{codespace}, is @code{0..#x10FFFF} (in hexadecimal notation),
48 inclusive. Emacs extends this range with codepoints in the range
49 @code{#x110000..#x3FFFFF}, which it uses for representing characters
50 that are not unified with Unicode and @dfn{raw 8-bit bytes} that
51 cannot be interpreted as characters. Thus, a character codepoint in
52 Emacs is a 22-bit integer number.
54 @cindex internal representation of characters
55 @cindex characters, representation in buffers and strings
56 @cindex multibyte text
57 To conserve memory, Emacs does not hold fixed-length 22-bit numbers
58 that are codepoints of text characters within buffers and strings.
59 Rather, Emacs uses a variable-length internal representation of
60 characters, that stores each character as a sequence of 1 to 5 8-bit
61 bytes, depending on the magnitude of its codepoint@footnote{
62 This internal representation is based on one of the encodings defined
63 by the Unicode Standard, called @dfn{UTF-8}, for representing any
64 Unicode codepoint, but Emacs extends UTF-8 to represent the additional
65 codepoints it uses for raw 8-bit bytes and characters not unified with
66 Unicode.}. For example, any @acronym{ASCII} character takes up only 1
67 byte, a Latin-1 character takes up 2 bytes, etc. We call this
68 representation of text @dfn{multibyte}.
70 Outside Emacs, characters can be represented in many different
71 encodings, such as ISO-8859-1, GB-2312, Big-5, etc. Emacs converts
72 between these external encodings and its internal representation, as
73 appropriate, when it reads text into a buffer or a string, or when it
74 writes text to a disk file or passes it to some other process.
76 Occasionally, Emacs needs to hold and manipulate encoded text or
77 binary non-text data in its buffers or strings. For example, when
78 Emacs visits a file, it first reads the file's text verbatim into a
79 buffer, and only then converts it to the internal representation.
80 Before the conversion, the buffer holds encoded text.
83 Encoded text is not really text, as far as Emacs is concerned, but
84 rather a sequence of raw 8-bit bytes. We call buffers and strings
85 that hold encoded text @dfn{unibyte} buffers and strings, because
86 Emacs treats them as a sequence of individual bytes. Usually, Emacs
87 displays unibyte buffers and strings as octal codes such as
88 @code{\237}. We recommend that you never use unibyte buffers and
89 strings except for manipulating encoded text or binary non-text data.
91 In a buffer, the buffer-local value of the variable
92 @code{enable-multibyte-characters} specifies the representation used.
93 The representation for a string is determined and recorded in the string
94 when the string is constructed.
96 @defvar enable-multibyte-characters
97 This variable specifies the current buffer's text representation.
98 If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
99 it contains unibyte encoded text or binary non-text data.
101 You cannot set this variable directly; instead, use the function
102 @code{set-buffer-multibyte} to change a buffer's representation.
105 @defun position-bytes position
106 Buffer positions are measured in character units. This function
107 returns the byte-position corresponding to buffer position
108 @var{position} in the current buffer. This is 1 at the start of the
109 buffer, and counts upward in bytes. If @var{position} is out of
110 range, the value is @code{nil}.
113 @defun byte-to-position byte-position
114 Return the buffer position, in character units, corresponding to given
115 @var{byte-position} in the current buffer. If @var{byte-position} is
116 out of range, the value is @code{nil}. In a multibyte buffer, an
117 arbitrary value of @var{byte-position} can be not at character
118 boundary, but inside a multibyte sequence representing a single
119 character; in this case, this function returns the buffer position of
120 the character whose multibyte sequence includes @var{byte-position}.
121 In other words, the value does not change for all byte positions that
122 belong to the same character.
125 @defun multibyte-string-p string
126 Return @code{t} if @var{string} is a multibyte string, @code{nil}
130 @defun string-bytes string
131 @cindex string, number of bytes
132 This function returns the number of bytes in @var{string}.
133 If @var{string} is a multibyte string, this can be greater than
134 @code{(length @var{string})}.
137 @defun unibyte-string &rest bytes
138 This function concatenates all its argument @var{bytes} and makes the
139 result a unibyte string.
142 @node Converting Representations
143 @section Converting Text Representations
145 Emacs can convert unibyte text to multibyte; it can also convert
146 multibyte text to unibyte, provided that the multibyte text contains
147 only @acronym{ASCII} and 8-bit raw bytes. In general, these
148 conversions happen when inserting text into a buffer, or when putting
149 text from several strings together in one string. You can also
150 explicitly convert a string's contents to either representation.
152 Emacs chooses the representation for a string based on the text from
153 which it is constructed. The general rule is to convert unibyte text
154 to multibyte text when combining it with other multibyte text, because
155 the multibyte representation is more general and can hold whatever
156 characters the unibyte text has.
158 When inserting text into a buffer, Emacs converts the text to the
159 buffer's representation, as specified by
160 @code{enable-multibyte-characters} in that buffer. In particular, when
161 you insert multibyte text into a unibyte buffer, Emacs converts the text
162 to unibyte, even though this conversion cannot in general preserve all
163 the characters that might be in the multibyte text. The other natural
164 alternative, to convert the buffer contents to multibyte, is not
165 acceptable because the buffer's representation is a choice made by the
166 user that cannot be overridden automatically.
168 Converting unibyte text to multibyte text leaves @acronym{ASCII}
169 characters unchanged, and converts bytes with codes 128 through 255 to
170 the multibyte representation of raw eight-bit bytes.
172 Converting multibyte text to unibyte converts all @acronym{ASCII}
173 and eight-bit characters to their single-byte form, but loses
174 information for non-@acronym{ASCII} characters by discarding all but
175 the low 8 bits of each character's codepoint. Converting unibyte text
176 to multibyte and back to unibyte reproduces the original unibyte text.
178 The next two functions either return the argument @var{string}, or a
179 newly created string with no text properties.
181 @defun string-to-multibyte string
182 This function returns a multibyte string containing the same sequence
183 of characters as @var{string}. If @var{string} is a multibyte string,
184 it is returned unchanged. The function assumes that @var{string}
185 includes only @acronym{ASCII} characters and raw 8-bit bytes; the
186 latter are converted to their multibyte representation corresponding
187 to the codepoints @code{#x3FFF80} through @code{#x3FFFFF}, inclusive
188 (@pxref{Text Representations, codepoints}).
191 @defun string-to-unibyte string
192 This function returns a unibyte string containing the same sequence of
193 characters as @var{string}. It signals an error if @var{string}
194 contains a non-@acronym{ASCII} character. If @var{string} is a
195 unibyte string, it is returned unchanged. Use this function for
196 @var{string} arguments that contain only @acronym{ASCII} and eight-bit
200 @defun byte-to-string byte
201 @cindex byte to string
202 This function returns a unibyte string containing a single byte of
203 character data, @var{character}. It signals an error if
204 @var{character} is not an integer between 0 and 255.
207 @defun multibyte-char-to-unibyte char
208 This converts the multibyte character @var{char} to a unibyte
209 character, and returns that character. If @var{char} is neither
210 @acronym{ASCII} nor eight-bit, the function returns -1.
213 @defun unibyte-char-to-multibyte char
214 This convert the unibyte character @var{char} to a multibyte
215 character, assuming @var{char} is either @acronym{ASCII} or raw 8-bit
219 @node Selecting a Representation
220 @section Selecting a Representation
222 Sometimes it is useful to examine an existing buffer or string as
223 multibyte when it was unibyte, or vice versa.
225 @defun set-buffer-multibyte multibyte
226 Set the representation type of the current buffer. If @var{multibyte}
227 is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte}
228 is @code{nil}, the buffer becomes unibyte.
230 This function leaves the buffer contents unchanged when viewed as a
231 sequence of bytes. As a consequence, it can change the contents
232 viewed as characters; for instance, a sequence of three bytes which is
233 treated as one character in multibyte representation will count as
234 three characters in unibyte representation. Eight-bit characters
235 representing raw bytes are an exception. They are represented by one
236 byte in a unibyte buffer, but when the buffer is set to multibyte,
237 they are converted to two-byte sequences, and vice versa.
239 This function sets @code{enable-multibyte-characters} to record which
240 representation is in use. It also adjusts various data in the buffer
241 (including overlays, text properties and markers) so that they cover the
242 same text as they did before.
244 You cannot use @code{set-buffer-multibyte} on an indirect buffer,
245 because indirect buffers always inherit the representation of the
249 @defun string-as-unibyte string
250 If @var{string} is already a unibyte string, this function returns
251 @var{string} itself. Otherwise, it returns a new string with the same
252 bytes as @var{string}, but treating each byte as a separate character
253 (so that the value may have more characters than @var{string}); as an
254 exception, each eight-bit character representing a raw byte is
255 converted into a single byte. The newly-created string contains no
259 @defun string-as-multibyte string
260 If @var{string} is a multibyte string, this function returns
261 @var{string} itself. Otherwise, it returns a new string with the same
262 bytes as @var{string}, but treating each multibyte sequence as one
263 character. This means that the value may have fewer characters than
264 @var{string} has. If a byte sequence in @var{string} is invalid as a
265 multibyte representation of a single character, each byte in the
266 sequence is treated as a raw 8-bit byte. The newly-created string
267 contains no text properties.
270 @node Character Codes
271 @section Character Codes
272 @cindex character codes
274 The unibyte and multibyte text representations use different
275 character codes. The valid character codes for unibyte representation
276 range from 0 to @code{#xFF} (255)---the values that can fit in one
277 byte. The valid character codes for multibyte representation range
278 from 0 to @code{#x3FFFFF}. In this code space, values 0 through
279 @code{#x7F} (127) are for @acronym{ASCII} characters, and values
280 @code{#x80} (128) through @code{#x3FFF7F} (4194175) are for
281 non-@acronym{ASCII} characters.
283 Emacs character codes are a superset of the Unicode standard.
284 Values 0 through @code{#x10FFFF} (1114111) correspond to Unicode
285 characters of the same codepoint; values @code{#x110000} (1114112)
286 through @code{#x3FFF7F} (4194175) represent characters that are not
287 unified with Unicode; and values @code{#x3FFF80} (4194176) through
288 @code{#x3FFFFF} (4194303) represent eight-bit raw bytes.
290 @defun characterp charcode
291 This returns @code{t} if @var{charcode} is a valid character, and
292 @code{nil} otherwise.
310 @cindex maximum value of character codepoint
311 @cindex codepoint, largest value
313 This function returns the largest value that a valid character
318 (characterp (max-char))
322 (characterp (1+ (max-char)))
328 @defun get-byte &optional pos string
329 This function returns the byte at character position @var{pos} in the
330 current buffer. If the current buffer is unibyte, this is literally
331 the byte at that position. If the buffer is multibyte, byte values of
332 @acronym{ASCII} characters are the same as character codepoints,
333 whereas eight-bit raw bytes are converted to their 8-bit codes. The
334 function signals an error if the character at @var{pos} is
337 The optional argument @var{string} means to get a byte value from that
338 string instead of the current buffer.
341 @node Character Properties
342 @section Character Properties
343 @cindex character properties
344 A @dfn{character property} is a named attribute of a character that
345 specifies how the character behaves and how it should be handled
346 during text processing and display. Thus, character properties are an
347 important part of specifying the character's semantics.
349 On the whole, Emacs follows the Unicode Standard in its implementation
350 of character properties. In particular, Emacs supports the
351 @uref{http://www.unicode.org/reports/tr23/, Unicode Character Property
352 Model}, and the Emacs character property database is derived from the
353 Unicode Character Database (@acronym{UCD}). See the
354 @uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character
355 Properties chapter of the Unicode Standard}, for a detailed
356 description of Unicode character properties and their meaning. This
357 section assumes you are already familiar with that chapter of the
358 Unicode Standard, and want to apply that knowledge to Emacs Lisp
361 In Emacs, each property has a name, which is a symbol, and a set of
362 possible values, whose types depend on the property; if a character
363 does not have a certain property, the value is @code{nil}. As a
364 general rule, the names of character properties in Emacs are produced
365 from the corresponding Unicode properties by downcasing them and
366 replacing each @samp{_} character with a dash @samp{-}. For example,
367 @code{Canonical_Combining_Class} becomes
368 @code{canonical-combining-class}. However, sometimes we shorten the
369 names to make their use easier.
371 @cindex unassigned character codepoints
372 Some codepoints are left @dfn{unassigned} by the
373 @acronym{UCD}---they don't correspond to any character. The Unicode
374 Standard defines default values of properties for such codepoints;
375 they are mentioned below for each property.
377 Here is the full list of value types for all the character
378 properties that Emacs knows about:
382 Corresponds to the @code{Name} Unicode property. The value is a
383 string consisting of upper-case Latin letters A to Z, digits, spaces,
384 and hyphen @samp{-} characters. For unassigned codepoints, the value
387 @cindex unicode general category
388 @item general-category
389 Corresponds to the @code{General_Category} Unicode property. The
390 value is a symbol whose name is a 2-letter abbreviation of the
391 character's classification. For unassigned codepoints, the value
394 @item canonical-combining-class
395 Corresponds to the @code{Canonical_Combining_Class} Unicode property.
396 The value is an integer number. For unassigned codepoints, the value
399 @cindex bidirectional class of characters
401 Corresponds to the Unicode @code{Bidi_Class} property. The value is a
402 symbol whose name is the Unicode @dfn{directional type} of the
403 character. Emacs uses this property when it reorders bidirectional
404 text for display (@pxref{Bidirectional Display}). For unassigned
405 codepoints, the value depends on the code blocks to which the
406 codepoint belongs: most unassigned codepoints get the value of
407 @code{L} (strong L), but some get values of @code{AL} (Arabic letter)
408 or @code{R} (strong R).
411 Corresponds to the Unicode properties @code{Decomposition_Type} and
412 @code{Decomposition_Value}. The value is a list, whose first element
413 may be a symbol representing a compatibility formatting tag, such as
414 @code{small}@footnote{The Unicode specification writes these tag names
415 inside @samp{<..>} brackets, but the tag names in Emacs do not include
416 the brackets; e.g.@: Unicode specifies @samp{<small>} where Emacs uses
417 @samp{small}. }; the other elements are characters that give the
418 compatibility decomposition sequence of this character. For
419 unassigned codepoints, the value is the character itself.
421 @item decimal-digit-value
422 Corresponds to the Unicode @code{Numeric_Value} property for
423 characters whose @code{Numeric_Type} is @samp{Digit}. The value is an
424 integer number. For unassigned codepoints, the value is @code{nil},
425 which means @acronym{NaN}, or ``not-a-number''.
428 Corresponds to the Unicode @code{Numeric_Value} property for
429 characters whose @code{Numeric_Type} is @samp{Decimal}. The value is
430 an integer number. Examples of such characters include compatibility
431 subscript and superscript digits, for which the value is the
432 corresponding number. For unassigned codepoints, the value is
433 @code{nil}, which means @acronym{NaN}.
436 Corresponds to the Unicode @code{Numeric_Value} property for
437 characters whose @code{Numeric_Type} is @samp{Numeric}. The value of
438 this property is an integer or a floating-point number. Examples of
439 characters that have this property include fractions, subscripts,
440 superscripts, Roman numerals, currency numerators, and encircled
441 numbers. For example, the value of this property for the character
442 @code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. For
443 unassigned codepoints, the value is @code{nil}, which means
446 @cindex mirroring of characters
448 Corresponds to the Unicode @code{Bidi_Mirrored} property. The value
449 of this property is a symbol, either @code{Y} or @code{N}. For
450 unassigned codepoints, the value is @code{N}.
453 Corresponds to the Unicode @code{Bidi_Mirroring_Glyph} property. The
454 value of this property is a character whose glyph represents the
455 mirror image of the character's glyph, or @code{nil} if there's no
456 defined mirroring glyph. All the characters whose @code{mirrored}
457 property is @code{N} have @code{nil} as their @code{mirroring}
458 property; however, some characters whose @code{mirrored} property is
459 @code{Y} also have @code{nil} for @code{mirroring}, because no
460 appropriate characters exist with mirrored glyphs. Emacs uses this
461 property to display mirror images of characters when appropriate
462 (@pxref{Bidirectional Display}). For unassigned codepoints, the value
466 Corresponds to the Unicode @code{Unicode_1_Name} property. The value
467 is a string. For unassigned codepoints, the value is an empty string.
469 @item iso-10646-comment
470 Corresponds to the Unicode @code{ISO_Comment} property. The value is
471 a string. For unassigned codepoints, the value is an empty string.
474 Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property.
475 The value of this property is a single character. For unassigned
476 codepoints, the value is @code{nil}, which means the character itself.
479 Corresponds to the Unicode @code{Simple_Lowercase_Mapping} property.
480 The value of this property is a single character. For unassigned
481 codepoints, the value is @code{nil}, which means the character itself.
484 Corresponds to the Unicode @code{Simple_Titlecase_Mapping} property.
485 @dfn{Title case} is a special form of a character used when the first
486 character of a word needs to be capitalized. The value of this
487 property is a single character. For unassigned codepoints, the value
488 is @code{nil}, which means the character itself.
491 @defun get-char-code-property char propname
492 This function returns the value of @var{char}'s @var{propname} property.
496 (get-char-code-property ? 'general-category)
500 (get-char-code-property ?1 'general-category)
505 (get-char-code-property ?\u2084 'digit-value)
510 (get-char-code-property ?\u2155 'numeric-value)
515 (get-char-code-property ?\u2163 'numeric-value)
521 @defun char-code-property-description prop value
522 This function returns the description string of property @var{prop}'s
523 @var{value}, or @code{nil} if @var{value} has no description.
527 (char-code-property-description 'general-category 'Zs)
528 @result{} "Separator, Space"
531 (char-code-property-description 'general-category 'Nd)
532 @result{} "Number, Decimal Digit"
535 (char-code-property-description 'numeric-value '1/5)
541 @defun put-char-code-property char propname value
542 This function stores @var{value} as the value of the property
543 @var{propname} for the character @var{char}.
546 @defvar unicode-category-table
547 The value of this variable is a char-table (@pxref{Char-Tables}) that
548 specifies, for each character, its Unicode @code{General_Category}
549 property as a symbol.
552 @defvar char-script-table
553 The value of this variable is a char-table that specifies, for each
554 character, a symbol whose name is the script to which the character
555 belongs, according to the Unicode Standard classification of the
556 Unicode code space into script-specific blocks. This char-table has a
557 single extra slot whose value is the list of all script symbols.
560 @defvar char-width-table
561 The value of this variable is a char-table that specifies the width of
562 each character in columns that it will occupy on the screen.
565 @defvar printable-chars
566 The value of this variable is a char-table that specifies, for each
567 character, whether it is printable or not. That is, if evaluating
568 @code{(aref printable-chars char)} results in @code{t}, the character
569 is printable, and if it results in @code{nil}, it is not.
573 @section Character Sets
574 @cindex character sets
577 @cindex coded character set
578 An Emacs @dfn{character set}, or @dfn{charset}, is a set of characters
579 in which each character is assigned a numeric code point. (The
580 Unicode Standard calls this a @dfn{coded character set}.) Each Emacs
581 charset has a name which is a symbol. A single character can belong
582 to any number of different character sets, but it will generally have
583 a different code point in each charset. Examples of character sets
584 include @code{ascii}, @code{iso-8859-1}, @code{greek-iso8859-7}, and
585 @code{windows-1255}. The code point assigned to a character in a
586 charset is usually different from its code point used in Emacs buffers
589 @cindex @code{emacs}, a charset
590 @cindex @code{unicode}, a charset
591 @cindex @code{eight-bit}, a charset
592 Emacs defines several special character sets. The character set
593 @code{unicode} includes all the characters whose Emacs code points are
594 in the range @code{0..#x10FFFF}. The character set @code{emacs}
595 includes all @acronym{ASCII} and non-@acronym{ASCII} characters.
596 Finally, the @code{eight-bit} charset includes the 8-bit raw bytes;
597 Emacs uses it to represent raw bytes encountered in text.
599 @defun charsetp object
600 Returns @code{t} if @var{object} is a symbol that names a character set,
601 @code{nil} otherwise.
605 The value is a list of all defined character set names.
608 @defun charset-priority-list &optional highestp
609 This functions returns a list of all defined character sets ordered by
610 their priority. If @var{highestp} is non-@code{nil}, the function
611 returns a single character set of the highest priority.
614 @defun set-charset-priority &rest charsets
615 This function makes @var{charsets} the highest priority character sets.
618 @defun char-charset character &optional restriction
619 This function returns the name of the character set of highest
620 priority that @var{character} belongs to. @acronym{ASCII} characters
621 are an exception: for them, this function always returns @code{ascii}.
623 If @var{restriction} is non-@code{nil}, it should be a list of
624 charsets to search. Alternatively, it can be a coding system, in
625 which case the returned charset must be supported by that coding
626 system (@pxref{Coding Systems}).
629 @defun charset-plist charset
630 This function returns the property list of the character set
631 @var{charset}. Although @var{charset} is a symbol, this is not the
632 same as the property list of that symbol. Charset properties include
633 important information about the charset, such as its documentation
634 string, short name, etc.
637 @defun put-charset-property charset propname value
638 This function sets the @var{propname} property of @var{charset} to the
642 @defun get-charset-property charset propname
643 This function returns the value of @var{charset}s property
647 @deffn Command list-charset-chars charset
648 This command displays a list of characters in the character set
652 Emacs can convert between its internal representation of a character
653 and the character's codepoint in a specific charset. The following
654 two functions support these conversions.
656 @c FIXME: decode-char and encode-char accept and ignore an additional
657 @c argument @var{restriction}. When that argument actually makes a
658 @c difference, it should be documented here.
659 @defun decode-char charset code-point
660 This function decodes a character that is assigned a @var{code-point}
661 in @var{charset}, to the corresponding Emacs character, and returns
662 it. If @var{charset} doesn't contain a character of that code point,
663 the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp
664 integer (@pxref{Integer Basics, most-positive-fixnum}), it can be
665 specified as a cons cell @code{(@var{high} . @var{low})}, where
666 @var{low} are the lower 16 bits of the value and @var{high} are the
670 @defun encode-char char charset
671 This function returns the code point assigned to the character
672 @var{char} in @var{charset}. If the result does not fit in a Lisp
673 integer, it is returned as a cons cell @code{(@var{high} . @var{low})}
674 that fits the second argument of @code{decode-char} above. If
675 @var{charset} doesn't have a codepoint for @var{char}, the value is
679 The following function comes in handy for applying a certain
680 function to all or part of the characters in a charset:
682 @defun map-charset-chars function charset &optional arg from-code to-code
683 Call @var{function} for characters in @var{charset}. @var{function}
684 is called with two arguments. The first one is a cons cell
685 @code{(@var{from} . @var{to})}, where @var{from} and @var{to}
686 indicate a range of characters contained in charset. The second
687 argument passed to @var{function} is @var{arg}.
689 By default, the range of codepoints passed to @var{function} includes
690 all the characters in @var{charset}, but optional arguments
691 @var{from-code} and @var{to-code} limit that to the range of
692 characters between these two codepoints of @var{charset}. If either
693 of them is @code{nil}, it defaults to the first or last codepoint of
694 @var{charset}, respectively.
697 @node Scanning Charsets
698 @section Scanning for Character Sets
700 Sometimes it is useful to find out which character set a particular
701 character belongs to. One use for this is in determining which coding
702 systems (@pxref{Coding Systems}) are capable of representing all of
703 the text in question; another is to determine the font(s) for
704 displaying that text.
706 @defun charset-after &optional pos
707 This function returns the charset of highest priority containing the
708 character at position @var{pos} in the current buffer. If @var{pos}
709 is omitted or @code{nil}, it defaults to the current value of point.
710 If @var{pos} is out of range, the value is @code{nil}.
713 @defun find-charset-region beg end &optional translation
714 This function returns a list of the character sets of highest priority
715 that contain characters in the current buffer between positions
716 @var{beg} and @var{end}.
718 The optional argument @var{translation} specifies a translation table
719 to use for scanning the text (@pxref{Translation of Characters}). If
720 it is non-@code{nil}, then each character in the region is translated
721 through this table, and the value returned describes the translated
722 characters instead of the characters actually in the buffer.
725 @defun find-charset-string string &optional translation
726 This function returns a list of character sets of highest priority
727 that contain characters in @var{string}. It is just like
728 @code{find-charset-region}, except that it applies to the contents of
729 @var{string} instead of part of the current buffer.
732 @node Translation of Characters
733 @section Translation of Characters
734 @cindex character translation tables
735 @cindex translation tables
737 A @dfn{translation table} is a char-table (@pxref{Char-Tables}) that
738 specifies a mapping of characters into characters. These tables are
739 used in encoding and decoding, and for other purposes. Some coding
740 systems specify their own particular translation tables; there are
741 also default translation tables which apply to all other coding
744 A translation table has two extra slots. The first is either
745 @code{nil} or a translation table that performs the reverse
746 translation; the second is the maximum number of characters to look up
747 for translating sequences of characters (see the description of
748 @code{make-translation-table-from-alist} below).
750 @defun make-translation-table &rest translations
751 This function returns a translation table based on the argument
752 @var{translations}. Each element of @var{translations} should be a
753 list of elements of the form @code{(@var{from} . @var{to})}; this says
754 to translate the character @var{from} into @var{to}.
756 The arguments and the forms in each argument are processed in order,
757 and if a previous form already translates @var{to} to some other
758 character, say @var{to-alt}, @var{from} is also translated to
762 During decoding, the translation table's translations are applied to
763 the characters that result from ordinary decoding. If a coding system
764 has the property @code{:decode-translation-table}, that specifies the
765 translation table to use, or a list of translation tables to apply in
766 sequence. (This is a property of the coding system, as returned by
767 @code{coding-system-get}, not a property of the symbol that is the
768 coding system's name. @xref{Coding System Basics,, Basic Concepts of
769 Coding Systems}.) Finally, if
770 @code{standard-translation-table-for-decode} is non-@code{nil}, the
771 resulting characters are translated by that table.
773 During encoding, the translation table's translations are applied to
774 the characters in the buffer, and the result of translation is
775 actually encoded. If a coding system has property
776 @code{:encode-translation-table}, that specifies the translation table
777 to use, or a list of translation tables to apply in sequence. In
778 addition, if the variable @code{standard-translation-table-for-encode}
779 is non-@code{nil}, it specifies the translation table to use for
780 translating the result.
782 @defvar standard-translation-table-for-decode
783 This is the default translation table for decoding. If a coding
784 systems specifies its own translation tables, the table that is the
785 value of this variable, if non-@code{nil}, is applied after them.
788 @defvar standard-translation-table-for-encode
789 This is the default translation table for encoding. If a coding
790 systems specifies its own translation tables, the table that is the
791 value of this variable, if non-@code{nil}, is applied after them.
794 @defvar translation-table-for-input
795 Self-inserting characters are translated through this translation
796 table before they are inserted. Search commands also translate their
797 input through this table, so they can compare more reliably with
798 what's in the buffer.
800 This variable automatically becomes buffer-local when set.
803 @defun make-translation-table-from-vector vec
804 This function returns a translation table made from @var{vec} that is
805 an array of 256 elements to map bytes (values 0 through #xFF) to
806 characters. Elements may be @code{nil} for untranslated bytes. The
807 returned table has a translation table for reverse mapping in the
808 first extra slot, and the value @code{1} in the second extra slot.
810 This function provides an easy way to make a private coding system
811 that maps each byte to a specific character. You can specify the
812 returned table and the reverse translation table using the properties
813 @code{:decode-translation-table} and @code{:encode-translation-table}
814 respectively in the @var{props} argument to
815 @code{define-coding-system}.
818 @defun make-translation-table-from-alist alist
819 This function is similar to @code{make-translation-table} but returns
820 a complex translation table rather than a simple one-to-one mapping.
821 Each element of @var{alist} is of the form @code{(@var{from}
822 . @var{to})}, where @var{from} and @var{to} are either characters or
823 vectors specifying a sequence of characters. If @var{from} is a
824 character, that character is translated to @var{to} (i.e.@: to a
825 character or a character sequence). If @var{from} is a vector of
826 characters, that sequence is translated to @var{to}. The returned
827 table has a translation table for reverse mapping in the first extra
828 slot, and the maximum length of all the @var{from} character sequences
829 in the second extra slot.
833 @section Coding Systems
835 @cindex coding system
836 When Emacs reads or writes a file, and when Emacs sends text to a
837 subprocess or receives text from a subprocess, it normally performs
838 character code conversion and end-of-line conversion as specified
839 by a particular @dfn{coding system}.
841 How to define a coding system is an arcane matter, and is not
845 * Coding System Basics:: Basic concepts.
846 * Encoding and I/O:: How file I/O functions handle coding systems.
847 * Lisp and Coding Systems:: Functions to operate on coding system names.
848 * User-Chosen Coding Systems:: Asking the user to choose a coding system.
849 * Default Coding Systems:: Controlling the default choices.
850 * Specifying Coding Systems:: Requesting a particular coding system
851 for a single file operation.
852 * Explicit Encoding:: Encoding or decoding text without doing I/O.
853 * Terminal I/O Encoding:: Use of encoding for terminal I/O.
854 * MS-DOS File Types:: How DOS "text" and "binary" files
855 relate to coding systems.
858 @node Coding System Basics
859 @subsection Basic Concepts of Coding Systems
861 @cindex character code conversion
862 @dfn{Character code conversion} involves conversion between the
863 internal representation of characters used inside Emacs and some other
864 encoding. Emacs supports many different encodings, in that it can
865 convert to and from them. For example, it can convert text to or from
866 encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and
867 several variants of ISO 2022. In some cases, Emacs supports several
868 alternative encodings for the same characters; for example, there are
869 three coding systems for the Cyrillic (Russian) alphabet: ISO,
870 Alternativnyj, and KOI8.
872 Every coding system specifies a particular set of character code
873 conversions, but the coding system @code{undecided} is special: it
874 leaves the choice unspecified, to be chosen heuristically for each
875 file, based on the file's data.
877 In general, a coding system doesn't guarantee roundtrip identity:
878 decoding a byte sequence using coding system, then encoding the
879 resulting text in the same coding system, can produce a different byte
880 sequence. But some coding systems do guarantee that the byte sequence
881 will be the same as what you originally decoded. Here are a few
885 iso-8859-1, utf-8, big5, shift_jis, euc-jp
888 Encoding buffer text and then decoding the result can also fail to
889 reproduce the original text. For instance, if you encode a character
890 with a coding system which does not support that character, the result
891 is unpredictable, and thus decoding it using the same coding system
892 may produce a different text. Currently, Emacs can't report errors
893 that result from encoding unsupported characters.
895 @cindex EOL conversion
896 @cindex end-of-line conversion
897 @cindex line end conversion
898 @dfn{End of line conversion} handles three different conventions
899 used on various systems for representing end of line in files. The
900 Unix convention, used on GNU and Unix systems, is to use the linefeed
901 character (also called newline). The DOS convention, used on
902 MS-Windows and MS-DOS systems, is to use a carriage-return and a
903 linefeed at the end of a line. The Mac convention is to use just
906 @cindex base coding system
907 @cindex variant coding system
908 @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
909 conversion unspecified, to be chosen based on the data. @dfn{Variant
910 coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
911 @code{latin-1-mac} specify the end-of-line conversion explicitly as
912 well. Most base coding systems have three corresponding variants whose
913 names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
915 @vindex raw-text@r{ coding system}
916 The coding system @code{raw-text} is special in that it prevents
917 character code conversion, and causes the buffer visited with this
918 coding system to be a unibyte buffer. For historical reasons, you can
919 save both unibyte and multibyte text with this coding system. When
920 you use @code{raw-text} to encode multibyte text, it does perform one
921 character code conversion: it converts eight-bit characters to their
922 single-byte external representation. @code{raw-text} does not specify
923 the end-of-line conversion, allowing that to be determined as usual by
924 the data, and has the usual three variants which specify the
925 end-of-line conversion.
927 @vindex no-conversion@r{ coding system}
928 @vindex binary@r{ coding system}
929 @code{no-conversion} (and its alias @code{binary}) is equivalent to
930 @code{raw-text-unix}: it specifies no conversion of either character
931 codes or end-of-line.
933 @vindex emacs-internal@r{ coding system}
934 @vindex utf-8-emacs@r{ coding system}
935 The coding system @code{utf-8-emacs} specifies that the data is
936 represented in the internal Emacs encoding (@pxref{Text
937 Representations}). This is like @code{raw-text} in that no code
938 conversion happens, but different in that the result is multibyte
939 data. The name @code{emacs-internal} is an alias for
942 @defun coding-system-get coding-system property
943 This function returns the specified property of the coding system
944 @var{coding-system}. Most coding system properties exist for internal
945 purposes, but one that you might find useful is @code{:mime-charset}.
946 That property's value is the name used in MIME for the character coding
947 which this coding system can read and write. Examples:
950 (coding-system-get 'iso-latin-1 :mime-charset)
952 (coding-system-get 'iso-2022-cn :mime-charset)
953 @result{} iso-2022-cn
954 (coding-system-get 'cyrillic-koi8 :mime-charset)
958 The value of the @code{:mime-charset} property is also defined
959 as an alias for the coding system.
962 @defun coding-system-aliases coding-system
963 This function returns the list of aliases of @var{coding-system}.
966 @node Encoding and I/O
967 @subsection Encoding and I/O
969 The principal purpose of coding systems is for use in reading and
970 writing files. The function @code{insert-file-contents} uses a coding
971 system to decode the file data, and @code{write-region} uses one to
972 encode the buffer contents.
974 You can specify the coding system to use either explicitly
975 (@pxref{Specifying Coding Systems}), or implicitly using a default
976 mechanism (@pxref{Default Coding Systems}). But these methods may not
977 completely specify what to do. For example, they may choose a coding
978 system such as @code{undefined} which leaves the character code
979 conversion to be determined from the data. In these cases, the I/O
980 operation finishes the job of choosing a coding system. Very often
981 you will want to find out afterwards which coding system was chosen.
983 @defvar buffer-file-coding-system
984 This buffer-local variable records the coding system used for saving the
985 buffer and for writing part of the buffer with @code{write-region}. If
986 the text to be written cannot be safely encoded using the coding system
987 specified by this variable, these operations select an alternative
988 encoding by calling the function @code{select-safe-coding-system}
989 (@pxref{User-Chosen Coding Systems}). If selecting a different encoding
990 requires to ask the user to specify a coding system,
991 @code{buffer-file-coding-system} is updated to the newly selected coding
994 @code{buffer-file-coding-system} does @emph{not} affect sending text
998 @defvar save-buffer-coding-system
999 This variable specifies the coding system for saving the buffer (by
1000 overriding @code{buffer-file-coding-system}). Note that it is not used
1001 for @code{write-region}.
1003 When a command to save the buffer starts out to use
1004 @code{buffer-file-coding-system} (or @code{save-buffer-coding-system}),
1005 and that coding system cannot handle
1006 the actual text in the buffer, the command asks the user to choose
1007 another coding system (by calling @code{select-safe-coding-system}).
1008 After that happens, the command also updates
1009 @code{buffer-file-coding-system} to represent the coding system that
1013 @defvar last-coding-system-used
1014 I/O operations for files and subprocesses set this variable to the
1015 coding system name that was used. The explicit encoding and decoding
1016 functions (@pxref{Explicit Encoding}) set it too.
1018 @strong{Warning:} Since receiving subprocess output sets this variable,
1019 it can change whenever Emacs waits; therefore, you should copy the
1020 value shortly after the function call that stores the value you are
1024 The variable @code{selection-coding-system} specifies how to encode
1025 selections for the window system. @xref{Window System Selections}.
1027 @defvar file-name-coding-system
1028 The variable @code{file-name-coding-system} specifies the coding
1029 system to use for encoding file names. Emacs encodes file names using
1030 that coding system for all file operations. If
1031 @code{file-name-coding-system} is @code{nil}, Emacs uses a default
1032 coding system determined by the selected language environment. In the
1033 default language environment, any non-@acronym{ASCII} characters in
1034 file names are not encoded specially; they appear in the file system
1035 using the internal Emacs representation.
1038 @strong{Warning:} if you change @code{file-name-coding-system} (or
1039 the language environment) in the middle of an Emacs session, problems
1040 can result if you have already visited files whose names were encoded
1041 using the earlier coding system and are handled differently under the
1042 new coding system. If you try to save one of these buffers under the
1043 visited file name, saving may use the wrong file name, or it may get
1044 an error. If such a problem happens, use @kbd{C-x C-w} to specify a
1045 new file name for that buffer.
1047 @node Lisp and Coding Systems
1048 @subsection Coding Systems in Lisp
1050 Here are the Lisp facilities for working with coding systems:
1052 @cindex list all coding systems
1053 @defun coding-system-list &optional base-only
1054 This function returns a list of all coding system names (symbols). If
1055 @var{base-only} is non-@code{nil}, the value includes only the
1056 base coding systems. Otherwise, it includes alias and variant coding
1060 @defun coding-system-p object
1061 This function returns @code{t} if @var{object} is a coding system
1065 @cindex validity of coding system
1066 @cindex coding system, validity check
1067 @defun check-coding-system coding-system
1068 This function checks the validity of @var{coding-system}. If that is
1069 valid, it returns @var{coding-system}. If @var{coding-system} is
1070 @code{nil}, the function return @code{nil}. For any other values, it
1071 signals an error whose @code{error-symbol} is @code{coding-system-error}
1072 (@pxref{Signaling Errors, signal}).
1075 @cindex eol type of coding system
1076 @defun coding-system-eol-type coding-system
1077 This function returns the type of end-of-line (a.k.a.@: @dfn{eol})
1078 conversion used by @var{coding-system}. If @var{coding-system}
1079 specifies a certain eol conversion, the return value is an integer 0,
1080 1, or 2, standing for @code{unix}, @code{dos}, and @code{mac},
1081 respectively. If @var{coding-system} doesn't specify eol conversion
1082 explicitly, the return value is a vector of coding systems, each one
1083 with one of the possible eol conversion types, like this:
1086 (coding-system-eol-type 'latin-1)
1087 @result{} [latin-1-unix latin-1-dos latin-1-mac]
1091 If this function returns a vector, Emacs will decide, as part of the
1092 text encoding or decoding process, what eol conversion to use. For
1093 decoding, the end-of-line format of the text is auto-detected, and the
1094 eol conversion is set to match it (e.g., DOS-style CRLF format will
1095 imply @code{dos} eol conversion). For encoding, the eol conversion is
1096 taken from the appropriate default coding system (e.g.,
1097 default value of @code{buffer-file-coding-system} for
1098 @code{buffer-file-coding-system}), or from the default eol conversion
1099 appropriate for the underlying platform.
1102 @cindex eol conversion of coding system
1103 @defun coding-system-change-eol-conversion coding-system eol-type
1104 This function returns a coding system which is like @var{coding-system}
1105 except for its eol conversion, which is specified by @code{eol-type}.
1106 @var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
1107 @code{nil}. If it is @code{nil}, the returned coding system determines
1108 the end-of-line conversion from the data.
1110 @var{eol-type} may also be 0, 1 or 2, standing for @code{unix},
1111 @code{dos} and @code{mac}, respectively.
1114 @cindex text conversion of coding system
1115 @defun coding-system-change-text-conversion eol-coding text-coding
1116 This function returns a coding system which uses the end-of-line
1117 conversion of @var{eol-coding}, and the text conversion of
1118 @var{text-coding}. If @var{text-coding} is @code{nil}, it returns
1119 @code{undecided}, or one of its variants according to @var{eol-coding}.
1122 @cindex safely encode region
1123 @cindex coding systems for encoding region
1124 @defun find-coding-systems-region from to
1125 This function returns a list of coding systems that could be used to
1126 encode a text between @var{from} and @var{to}. All coding systems in
1127 the list can safely encode any multibyte characters in that portion of
1130 If the text contains no multibyte characters, the function returns the
1131 list @code{(undecided)}.
1134 @cindex safely encode a string
1135 @cindex coding systems for encoding a string
1136 @defun find-coding-systems-string string
1137 This function returns a list of coding systems that could be used to
1138 encode the text of @var{string}. All coding systems in the list can
1139 safely encode any multibyte characters in @var{string}. If the text
1140 contains no multibyte characters, this returns the list
1144 @cindex charset, coding systems to encode
1145 @cindex safely encode characters in a charset
1146 @defun find-coding-systems-for-charsets charsets
1147 This function returns a list of coding systems that could be used to
1148 encode all the character sets in the list @var{charsets}.
1151 @defun check-coding-systems-region start end coding-system-list
1152 This function checks whether coding systems in the list
1153 @code{coding-system-list} can encode all the characters in the region
1154 between @var{start} and @var{end}. If all of the coding systems in
1155 the list can encode the specified text, the function returns
1156 @code{nil}. If some coding systems cannot encode some of the
1157 characters, the value is an alist, each element of which has the form
1158 @code{(@var{coding-system1} @var{pos1} @var{pos2} @dots{})}, meaning
1159 that @var{coding-system1} cannot encode characters at buffer positions
1160 @var{pos1}, @var{pos2}, @enddots{}.
1162 @var{start} may be a string, in which case @var{end} is ignored and
1163 the returned value references string indices instead of buffer
1167 @defun detect-coding-region start end &optional highest
1168 This function chooses a plausible coding system for decoding the text
1169 from @var{start} to @var{end}. This text should be a byte sequence,
1170 i.e.@: unibyte text or multibyte text with only @acronym{ASCII} and
1171 eight-bit characters (@pxref{Explicit Encoding}).
1173 Normally this function returns a list of coding systems that could
1174 handle decoding the text that was scanned. They are listed in order of
1175 decreasing priority. But if @var{highest} is non-@code{nil}, then the
1176 return value is just one coding system, the one that is highest in
1179 If the region contains only @acronym{ASCII} characters except for such
1180 ISO-2022 control characters ISO-2022 as @code{ESC}, the value is
1181 @code{undecided} or @code{(undecided)}, or a variant specifying
1182 end-of-line conversion, if that can be deduced from the text.
1184 If the region contains null bytes, the value is @code{no-conversion},
1185 even if the region contains text encoded in some coding system.
1188 @defun detect-coding-string string &optional highest
1189 This function is like @code{detect-coding-region} except that it
1190 operates on the contents of @var{string} instead of bytes in the buffer.
1193 @cindex null bytes, and decoding text
1194 @defvar inhibit-null-byte-detection
1195 If this variable has a non-@code{nil} value, null bytes are ignored
1196 when detecting the encoding of a region or a string. This allows to
1197 correctly detect the encoding of text that contains null bytes, such
1198 as Info files with Index nodes.
1201 @defvar inhibit-iso-escape-detection
1202 If this variable has a non-@code{nil} value, ISO-2022 escape sequences
1203 are ignored when detecting the encoding of a region or a string. The
1204 result is that no text is ever detected as encoded in some ISO-2022
1205 encoding, and all escape sequences become visible in a buffer.
1206 @strong{Warning:} @emph{Use this variable with extreme caution,
1207 because many files in the Emacs distribution use ISO-2022 encoding.}
1210 @cindex charsets supported by a coding system
1211 @defun coding-system-charset-list coding-system
1212 This function returns the list of character sets (@pxref{Character
1213 Sets}) supported by @var{coding-system}. Some coding systems that
1214 support too many character sets to list them all yield special values:
1217 If @var{coding-system} supports all the ISO-2022 charsets, the value
1220 If @var{coding-system} supports all Emacs characters, the value is
1223 If @var{coding-system} supports all emacs-mule characters, the value
1224 is @code{emacs-mule}.
1226 If @var{coding-system} supports all Unicode characters, the value is
1231 @xref{Coding systems for a subprocess,, Process Information}, in
1232 particular the description of the functions
1233 @code{process-coding-system} and @code{set-process-coding-system}, for
1234 how to examine or set the coding systems used for I/O to a subprocess.
1236 @node User-Chosen Coding Systems
1237 @subsection User-Chosen Coding Systems
1239 @cindex select safe coding system
1240 @defun select-safe-coding-system from to &optional default-coding-system accept-default-p file
1241 This function selects a coding system for encoding specified text,
1242 asking the user to choose if necessary. Normally the specified text
1243 is the text in the current buffer between @var{from} and @var{to}. If
1244 @var{from} is a string, the string specifies the text to encode, and
1245 @var{to} is ignored.
1247 If the specified text includes raw bytes (@pxref{Text
1248 Representations}), @code{select-safe-coding-system} suggests
1249 @code{raw-text} for its encoding.
1251 If @var{default-coding-system} is non-@code{nil}, that is the first
1252 coding system to try; if that can handle the text,
1253 @code{select-safe-coding-system} returns that coding system. It can
1254 also be a list of coding systems; then the function tries each of them
1255 one by one. After trying all of them, it next tries the current
1256 buffer's value of @code{buffer-file-coding-system} (if it is not
1257 @code{undecided}), then the default value of
1258 @code{buffer-file-coding-system} and finally the user's most
1259 preferred coding system, which the user can set using the command
1260 @code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing
1261 Coding Systems, emacs, The GNU Emacs Manual}).
1263 If one of those coding systems can safely encode all the specified
1264 text, @code{select-safe-coding-system} chooses it and returns it.
1265 Otherwise, it asks the user to choose from a list of coding systems
1266 which can encode all the text, and returns the user's choice.
1268 @var{default-coding-system} can also be a list whose first element is
1269 t and whose other elements are coding systems. Then, if no coding
1270 system in the list can handle the text, @code{select-safe-coding-system}
1271 queries the user immediately, without trying any of the three
1272 alternatives described above.
1274 The optional argument @var{accept-default-p}, if non-@code{nil},
1275 should be a function to determine whether a coding system selected
1276 without user interaction is acceptable. @code{select-safe-coding-system}
1277 calls this function with one argument, the base coding system of the
1278 selected coding system. If @var{accept-default-p} returns @code{nil},
1279 @code{select-safe-coding-system} rejects the silently selected coding
1280 system, and asks the user to select a coding system from a list of
1281 possible candidates.
1283 @vindex select-safe-coding-system-accept-default-p
1284 If the variable @code{select-safe-coding-system-accept-default-p} is
1285 non-@code{nil}, it should be a function taking a single argument.
1286 It is used in place of @var{accept-default-p}, overriding any
1287 value supplied for this argument.
1289 As a final step, before returning the chosen coding system,
1290 @code{select-safe-coding-system} checks whether that coding system is
1291 consistent with what would be selected if the contents of the region
1292 were read from a file. (If not, this could lead to data corruption in
1293 a file subsequently re-visited and edited.) Normally,
1294 @code{select-safe-coding-system} uses @code{buffer-file-name} as the
1295 file for this purpose, but if @var{file} is non-@code{nil}, it uses
1296 that file instead (this can be relevant for @code{write-region} and
1297 similar functions). If it detects an apparent inconsistency,
1298 @code{select-safe-coding-system} queries the user before selecting the
1302 Here are two functions you can use to let the user specify a coding
1303 system, with completion. @xref{Completion}.
1305 @defun read-coding-system prompt &optional default
1306 This function reads a coding system using the minibuffer, prompting with
1307 string @var{prompt}, and returns the coding system name as a symbol. If
1308 the user enters null input, @var{default} specifies which coding system
1309 to return. It should be a symbol or a string.
1312 @defun read-non-nil-coding-system prompt
1313 This function reads a coding system using the minibuffer, prompting with
1314 string @var{prompt}, and returns the coding system name as a symbol. If
1315 the user tries to enter null input, it asks the user to try again.
1316 @xref{Coding Systems}.
1319 @node Default Coding Systems
1320 @subsection Default Coding Systems
1321 @cindex default coding system
1322 @cindex coding system, automatically determined
1324 This section describes variables that specify the default coding
1325 system for certain files or when running certain subprograms, and the
1326 function that I/O operations use to access them.
1328 The idea of these variables is that you set them once and for all to the
1329 defaults you want, and then do not change them again. To specify a
1330 particular coding system for a particular operation in a Lisp program,
1331 don't change these variables; instead, override them using
1332 @code{coding-system-for-read} and @code{coding-system-for-write}
1333 (@pxref{Specifying Coding Systems}).
1335 @cindex file contents, and default coding system
1336 @defopt auto-coding-regexp-alist
1337 This variable is an alist of text patterns and corresponding coding
1338 systems. Each element has the form @code{(@var{regexp}
1339 . @var{coding-system})}; a file whose first few kilobytes match
1340 @var{regexp} is decoded with @var{coding-system} when its contents are
1341 read into a buffer. The settings in this alist take priority over
1342 @code{coding:} tags in the files and the contents of
1343 @code{file-coding-system-alist} (see below). The default value is set
1344 so that Emacs automatically recognizes mail files in Babyl format and
1345 reads them with no code conversions.
1348 @cindex file name, and default coding system
1349 @defopt file-coding-system-alist
1350 This variable is an alist that specifies the coding systems to use for
1351 reading and writing particular files. Each element has the form
1352 @code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular
1353 expression that matches certain file names. The element applies to file
1354 names that match @var{pattern}.
1356 The @sc{cdr} of the element, @var{coding}, should be either a coding
1357 system, a cons cell containing two coding systems, or a function name (a
1358 symbol with a function definition). If @var{coding} is a coding system,
1359 that coding system is used for both reading the file and writing it. If
1360 @var{coding} is a cons cell containing two coding systems, its @sc{car}
1361 specifies the coding system for decoding, and its @sc{cdr} specifies the
1362 coding system for encoding.
1364 If @var{coding} is a function name, the function should take one
1365 argument, a list of all arguments passed to
1366 @code{find-operation-coding-system}. It must return a coding system
1367 or a cons cell containing two coding systems. This value has the same
1368 meaning as described above.
1370 If @var{coding} (or what returned by the above function) is
1371 @code{undecided}, the normal code-detection is performed.
1374 @defopt auto-coding-alist
1375 This variable is an alist that specifies the coding systems to use for
1376 reading and writing particular files. Its form is like that of
1377 @code{file-coding-system-alist}, but, unlike the latter, this variable
1378 takes priority over any @code{coding:} tags in the file.
1381 @cindex program name, and default coding system
1382 @defvar process-coding-system-alist
1383 This variable is an alist specifying which coding systems to use for a
1384 subprocess, depending on which program is running in the subprocess. It
1385 works like @code{file-coding-system-alist}, except that @var{pattern} is
1386 matched against the program name used to start the subprocess. The coding
1387 system or systems specified in this alist are used to initialize the
1388 coding systems used for I/O to the subprocess, but you can specify
1389 other coding systems later using @code{set-process-coding-system}.
1392 @strong{Warning:} Coding systems such as @code{undecided}, which
1393 determine the coding system from the data, do not work entirely reliably
1394 with asynchronous subprocess output. This is because Emacs handles
1395 asynchronous subprocess output in batches, as it arrives. If the coding
1396 system leaves the character code conversion unspecified, or leaves the
1397 end-of-line conversion unspecified, Emacs must try to detect the proper
1398 conversion from one batch at a time, and this does not always work.
1400 Therefore, with an asynchronous subprocess, if at all possible, use a
1401 coding system which determines both the character code conversion and
1402 the end of line conversion---that is, one like @code{latin-1-unix},
1403 rather than @code{undecided} or @code{latin-1}.
1405 @cindex port number, and default coding system
1406 @cindex network service name, and default coding system
1407 @defvar network-coding-system-alist
1408 This variable is an alist that specifies the coding system to use for
1409 network streams. It works much like @code{file-coding-system-alist},
1410 with the difference that the @var{pattern} in an element may be either a
1411 port number or a regular expression. If it is a regular expression, it
1412 is matched against the network service name used to open the network
1416 @defvar default-process-coding-system
1417 This variable specifies the coding systems to use for subprocess (and
1418 network stream) input and output, when nothing else specifies what to
1421 The value should be a cons cell of the form @code{(@var{input-coding}
1422 . @var{output-coding})}. Here @var{input-coding} applies to input from
1423 the subprocess, and @var{output-coding} applies to output to it.
1426 @cindex default coding system, functions to determine
1427 @defopt auto-coding-functions
1428 This variable holds a list of functions that try to determine a
1429 coding system for a file based on its undecoded contents.
1431 Each function in this list should be written to look at text in the
1432 current buffer, but should not modify it in any way. The buffer will
1433 contain undecoded text of parts of the file. Each function should
1434 take one argument, @var{size}, which tells it how many characters to
1435 look at, starting from point. If the function succeeds in determining
1436 a coding system for the file, it should return that coding system.
1437 Otherwise, it should return @code{nil}.
1439 If a file has a @samp{coding:} tag, that takes precedence, so these
1440 functions won't be called.
1443 @defun find-auto-coding filename size
1444 This function tries to determine a suitable coding system for
1445 @var{filename}. It examines the buffer visiting the named file, using
1446 the variables documented above in sequence, until it finds a match for
1447 one of the rules specified by these variables. It then returns a cons
1448 cell of the form @code{(@var{coding} . @var{source})}, where
1449 @var{coding} is the coding system to use and @var{source} is a symbol,
1450 one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist},
1451 @code{:coding}, or @code{auto-coding-functions}, indicating which one
1452 supplied the matching rule. The value @code{:coding} means the coding
1453 system was specified by the @code{coding:} tag in the file
1454 (@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}).
1455 The order of looking for a matching rule is @code{auto-coding-alist}
1456 first, then @code{auto-coding-regexp-alist}, then the @code{coding:}
1457 tag, and lastly @code{auto-coding-functions}. If no matching rule was
1458 found, the function returns @code{nil}.
1460 The second argument @var{size} is the size of text, in characters,
1461 following point. The function examines text only within @var{size}
1462 characters after point. Normally, the buffer should be positioned at
1463 the beginning when this function is called, because one of the places
1464 for the @code{coding:} tag is the first one or two lines of the file;
1465 in that case, @var{size} should be the size of the buffer.
1468 @defun set-auto-coding filename size
1469 This function returns a suitable coding system for file
1470 @var{filename}. It uses @code{find-auto-coding} to find the coding
1471 system. If no coding system could be determined, the function returns
1472 @code{nil}. The meaning of the argument @var{size} is like in
1473 @code{find-auto-coding}.
1476 @defun find-operation-coding-system operation &rest arguments
1477 This function returns the coding system to use (by default) for
1478 performing @var{operation} with @var{arguments}. The value has this
1482 (@var{decoding-system} . @var{encoding-system})
1485 The first element, @var{decoding-system}, is the coding system to use
1486 for decoding (in case @var{operation} does decoding), and
1487 @var{encoding-system} is the coding system for encoding (in case
1488 @var{operation} does encoding).
1490 The argument @var{operation} is a symbol; it should be one of
1491 @code{write-region}, @code{start-process}, @code{call-process},
1492 @code{call-process-region}, @code{insert-file-contents}, or
1493 @code{open-network-stream}. These are the names of the Emacs I/O
1494 primitives that can do character code and eol conversion.
1496 The remaining arguments should be the same arguments that might be given
1497 to the corresponding I/O primitive. Depending on the primitive, one
1498 of those arguments is selected as the @dfn{target}. For example, if
1499 @var{operation} does file I/O, whichever argument specifies the file
1500 name is the target. For subprocess primitives, the process name is the
1501 target. For @code{open-network-stream}, the target is the service name
1504 Depending on @var{operation}, this function looks up the target in
1505 @code{file-coding-system-alist}, @code{process-coding-system-alist},
1506 or @code{network-coding-system-alist}. If the target is found in the
1507 alist, @code{find-operation-coding-system} returns its association in
1508 the alist; otherwise it returns @code{nil}.
1510 If @var{operation} is @code{insert-file-contents}, the argument
1511 corresponding to the target may be a cons cell of the form
1512 @code{(@var{filename} . @var{buffer})}). In that case, @var{filename}
1513 is a file name to look up in @code{file-coding-system-alist}, and
1514 @var{buffer} is a buffer that contains the file's contents (not yet
1515 decoded). If @code{file-coding-system-alist} specifies a function to
1516 call for this file, and that function needs to examine the file's
1517 contents (as it usually does), it should examine the contents of
1518 @var{buffer} instead of reading the file.
1521 @node Specifying Coding Systems
1522 @subsection Specifying a Coding System for One Operation
1524 You can specify the coding system for a specific operation by binding
1525 the variables @code{coding-system-for-read} and/or
1526 @code{coding-system-for-write}.
1528 @defvar coding-system-for-read
1529 If this variable is non-@code{nil}, it specifies the coding system to
1530 use for reading a file, or for input from a synchronous subprocess.
1532 It also applies to any asynchronous subprocess or network stream, but in
1533 a different way: the value of @code{coding-system-for-read} when you
1534 start the subprocess or open the network stream specifies the input
1535 decoding method for that subprocess or network stream. It remains in
1536 use for that subprocess or network stream unless and until overridden.
1538 The right way to use this variable is to bind it with @code{let} for a
1539 specific I/O operation. Its global value is normally @code{nil}, and
1540 you should not globally set it to any other value. Here is an example
1541 of the right way to use the variable:
1544 ;; @r{Read the file with no character code conversion.}
1545 ;; @r{Assume @acronym{crlf} represents end-of-line.}
1546 (let ((coding-system-for-read 'emacs-mule-dos))
1547 (insert-file-contents filename))
1550 When its value is non-@code{nil}, this variable takes precedence over
1551 all other methods of specifying a coding system to use for input,
1552 including @code{file-coding-system-alist},
1553 @code{process-coding-system-alist} and
1554 @code{network-coding-system-alist}.
1557 @defvar coding-system-for-write
1558 This works much like @code{coding-system-for-read}, except that it
1559 applies to output rather than input. It affects writing to files,
1560 as well as sending output to subprocesses and net connections.
1562 When a single operation does both input and output, as do
1563 @code{call-process-region} and @code{start-process}, both
1564 @code{coding-system-for-read} and @code{coding-system-for-write}
1568 @defopt inhibit-eol-conversion
1569 When this variable is non-@code{nil}, no end-of-line conversion is done,
1570 no matter which coding system is specified. This applies to all the
1571 Emacs I/O and subprocess primitives, and to the explicit encoding and
1572 decoding functions (@pxref{Explicit Encoding}).
1575 @cindex priority order of coding systems
1576 @cindex coding systems, priority
1577 Sometimes, you need to prefer several coding systems for some
1578 operation, rather than fix a single one. Emacs lets you specify a
1579 priority order for using coding systems. This ordering affects the
1580 sorting of lists of coding systems returned by functions such as
1581 @code{find-coding-systems-region} (@pxref{Lisp and Coding Systems}).
1583 @defun coding-system-priority-list &optional highestp
1584 This function returns the list of coding systems in the order of their
1585 current priorities. Optional argument @var{highestp}, if
1586 non-@code{nil}, means return only the highest priority coding system.
1589 @defun set-coding-system-priority &rest coding-systems
1590 This function puts @var{coding-systems} at the beginning of the
1591 priority list for coding systems, thus making their priority higher
1595 @defmac with-coding-priority coding-systems &rest body@dots{}
1596 This macro execute @var{body}, like @code{progn} does
1597 (@pxref{Sequencing, progn}), with @var{coding-systems} at the front of
1598 the priority list for coding systems. @var{coding-systems} should be
1599 a list of coding systems to prefer during execution of @var{body}.
1602 @node Explicit Encoding
1603 @subsection Explicit Encoding and Decoding
1604 @cindex encoding in coding systems
1605 @cindex decoding in coding systems
1607 All the operations that transfer text in and out of Emacs have the
1608 ability to use a coding system to encode or decode the text.
1609 You can also explicitly encode and decode text using the functions
1612 The result of encoding, and the input to decoding, are not ordinary
1613 text. They logically consist of a series of byte values; that is, a
1614 series of @acronym{ASCII} and eight-bit characters. In unibyte
1615 buffers and strings, these characters have codes in the range 0
1616 through #xFF (255). In a multibyte buffer or string, eight-bit
1617 characters have character codes higher than #xFF (@pxref{Text
1618 Representations}), but Emacs transparently converts them to their
1619 single-byte values when you encode or decode such text.
1621 The usual way to read a file into a buffer as a sequence of bytes, so
1622 you can decode the contents explicitly, is with
1623 @code{insert-file-contents-literally} (@pxref{Reading from Files});
1624 alternatively, specify a non-@code{nil} @var{rawfile} argument when
1625 visiting a file with @code{find-file-noselect}. These methods result in
1628 The usual way to use the byte sequence that results from explicitly
1629 encoding text is to copy it to a file or process---for example, to write
1630 it with @code{write-region} (@pxref{Writing to Files}), and suppress
1631 encoding by binding @code{coding-system-for-write} to
1632 @code{no-conversion}.
1634 Here are the functions to perform explicit encoding or decoding. The
1635 encoding functions produce sequences of bytes; the decoding functions
1636 are meant to operate on sequences of bytes. All of these functions
1637 discard text properties. They also set @code{last-coding-system-used}
1638 to the precise coding system they used.
1640 @deffn Command encode-coding-region start end coding-system &optional destination
1641 This command encodes the text from @var{start} to @var{end} according
1642 to coding system @var{coding-system}. Normally, the encoded text
1643 replaces the original text in the buffer, but the optional argument
1644 @var{destination} can change that. If @var{destination} is a buffer,
1645 the encoded text is inserted in that buffer after point (point does
1646 not move); if it is @code{t}, the command returns the encoded text as
1647 a unibyte string without inserting it.
1649 If encoded text is inserted in some buffer, this command returns the
1650 length of the encoded text.
1652 The result of encoding is logically a sequence of bytes, but the
1653 buffer remains multibyte if it was multibyte before, and any 8-bit
1654 bytes are converted to their multibyte representation (@pxref{Text
1657 @cindex @code{undecided} coding-system, when encoding
1658 Do @emph{not} use @code{undecided} for @var{coding-system} when
1659 encoding text, since that may lead to unexpected results. Instead,
1660 use @code{select-safe-coding-system} (@pxref{User-Chosen Coding
1661 Systems, select-safe-coding-system}) to suggest a suitable encoding,
1662 if there's no obvious pertinent value for @var{coding-system}.
1665 @defun encode-coding-string string coding-system &optional nocopy buffer
1666 This function encodes the text in @var{string} according to coding
1667 system @var{coding-system}. It returns a new string containing the
1668 encoded text, except when @var{nocopy} is non-@code{nil}, in which
1669 case the function may return @var{string} itself if the encoding
1670 operation is trivial. The result of encoding is a unibyte string.
1673 @deffn Command decode-coding-region start end coding-system &optional destination
1674 This command decodes the text from @var{start} to @var{end} according
1675 to coding system @var{coding-system}. To make explicit decoding
1676 useful, the text before decoding ought to be a sequence of byte
1677 values, but both multibyte and unibyte buffers are acceptable (in the
1678 multibyte case, the raw byte values should be represented as eight-bit
1679 characters). Normally, the decoded text replaces the original text in
1680 the buffer, but the optional argument @var{destination} can change
1681 that. If @var{destination} is a buffer, the decoded text is inserted
1682 in that buffer after point (point does not move); if it is @code{t},
1683 the command returns the decoded text as a multibyte string without
1686 If decoded text is inserted in some buffer, this command returns the
1687 length of the decoded text.
1689 This command puts a @code{charset} text property on the decoded text.
1690 The value of the property states the character set used to decode the
1694 @defun decode-coding-string string coding-system &optional nocopy buffer
1695 This function decodes the text in @var{string} according to
1696 @var{coding-system}. It returns a new string containing the decoded
1697 text, except when @var{nocopy} is non-@code{nil}, in which case the
1698 function may return @var{string} itself if the decoding operation is
1699 trivial. To make explicit decoding useful, the contents of
1700 @var{string} ought to be a unibyte string with a sequence of byte
1701 values, but a multibyte string is also acceptable (assuming it
1702 contains 8-bit bytes in their multibyte form).
1704 If optional argument @var{buffer} specifies a buffer, the decoded text
1705 is inserted in that buffer after point (point does not move). In this
1706 case, the return value is the length of the decoded text.
1708 @cindex @code{charset}, text property
1709 This function puts a @code{charset} text property on the decoded text.
1710 The value of the property states the character set used to decode the
1715 (decode-coding-string "Gr\374ss Gott" 'latin-1)
1716 @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1))
1721 @defun decode-coding-inserted-region from to filename &optional visit beg end replace
1722 This function decodes the text from @var{from} to @var{to} as if
1723 it were being read from file @var{filename} using @code{insert-file-contents}
1724 using the rest of the arguments provided.
1726 The normal way to use this function is after reading text from a file
1727 without decoding, if you decide you would rather have decoded it.
1728 Instead of deleting the text and reading it again, this time with
1729 decoding, you can call this function.
1732 @node Terminal I/O Encoding
1733 @subsection Terminal I/O Encoding
1735 Emacs can decode keyboard input using a coding system, and encode
1736 terminal output. This is useful for terminals that transmit or
1737 display text using a particular encoding such as Latin-1. Emacs does
1738 not set @code{last-coding-system-used} for encoding or decoding of
1741 @defun keyboard-coding-system &optional terminal
1742 This function returns the coding system that is in use for decoding
1743 keyboard input from @var{terminal}---or @code{nil} if no coding system
1744 is to be used for that terminal. If @var{terminal} is omitted or
1745 @code{nil}, it means the selected frame's terminal. @xref{Multiple
1749 @deffn Command set-keyboard-coding-system coding-system &optional terminal
1750 This command specifies @var{coding-system} as the coding system to use
1751 for decoding keyboard input from @var{terminal}. If
1752 @var{coding-system} is @code{nil}, that means do not decode keyboard
1753 input. If @var{terminal} is a frame, it means that frame's terminal;
1754 if it is @code{nil}, that means the currently selected frame's
1755 terminal. @xref{Multiple Terminals}.
1758 @defun terminal-coding-system &optional terminal
1759 This function returns the coding system that is in use for encoding
1760 terminal output from @var{terminal}---or @code{nil} if the output is
1761 not encoded. If @var{terminal} is a frame, it means that frame's
1762 terminal; if it is @code{nil}, that means the currently selected
1766 @deffn Command set-terminal-coding-system coding-system &optional terminal
1767 This command specifies @var{coding-system} as the coding system to use
1768 for encoding terminal output from @var{terminal}. If
1769 @var{coding-system} is @code{nil}, terminal output is not encoded. If
1770 @var{terminal} is a frame, it means that frame's terminal; if it is
1771 @code{nil}, that means the currently selected frame's terminal.
1774 @node MS-DOS File Types
1775 @subsection MS-DOS File Types
1776 @cindex DOS file types
1777 @cindex MS-DOS file types
1778 @cindex Windows file types
1779 @cindex file types on MS-DOS and Windows
1780 @cindex text files and binary files
1781 @cindex binary files and text files
1783 On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
1784 end-of-line conversion for a file by looking at the file's name. This
1785 feature classifies files as @dfn{text files} and @dfn{binary files}. By
1786 ``binary file'' we mean a file of literal byte values that are not
1787 necessarily meant to be characters; Emacs does no end-of-line conversion
1788 and no character code conversion for them. On the other hand, the bytes
1789 in a text file are intended to represent characters; when you create a
1790 new file whose name implies that it is a text file, Emacs uses DOS
1791 end-of-line conversion.
1793 @defvar buffer-file-type
1794 This variable, automatically buffer-local in each buffer, records the
1795 file type of the buffer's visited file. When a buffer does not specify
1796 a coding system with @code{buffer-file-coding-system}, this variable is
1797 used to determine which coding system to use when writing the contents
1798 of the buffer. It should be @code{nil} for text, @code{t} for binary.
1799 If it is @code{t}, the coding system is @code{no-conversion}.
1800 Otherwise, @code{undecided-dos} is used.
1802 Normally this variable is set by visiting a file; it is set to
1803 @code{nil} if the file was visited without any actual conversion.
1805 Its default value is used to decide how to handle files for which
1806 @code{file-name-buffer-file-type-alist} says nothing about the type:
1807 If the default value is non-@code{nil}, then these files are treated as
1808 binary: the coding system @code{no-conversion} is used. Otherwise,
1809 nothing special is done for them---the coding system is deduced solely
1810 from the file contents, in the usual Emacs fashion.
1813 @defopt file-name-buffer-file-type-alist
1814 This variable holds an alist for recognizing text and binary files.
1815 Each element has the form (@var{regexp} . @var{type}), where
1816 @var{regexp} is matched against the file name, and @var{type} may be
1817 @code{nil} for text, @code{t} for binary, or a function to call to
1818 compute which. If it is a function, then it is called with a single
1819 argument (the file name) and should return @code{t} or @code{nil}.
1821 When running on MS-DOS or MS-Windows, Emacs checks this alist to decide
1822 which coding system to use when reading a file. For a text file,
1823 @code{undecided-dos} is used. For a binary file, @code{no-conversion}
1826 If no element in this alist matches a given file name, then
1827 the default value of @code{buffer-file-type} says how to treat the file.
1831 @section Input Methods
1832 @cindex input methods
1834 @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII}
1835 characters from the keyboard. Unlike coding systems, which translate
1836 non-@acronym{ASCII} characters to and from encodings meant to be read by
1837 programs, input methods provide human-friendly commands. (@xref{Input
1838 Methods,,, emacs, The GNU Emacs Manual}, for information on how users
1839 use input methods to enter text.) How to define input methods is not
1840 yet documented in this manual, but here we describe how to use them.
1842 Each input method has a name, which is currently a string;
1843 in the future, symbols may also be usable as input method names.
1845 @defvar current-input-method
1846 This variable holds the name of the input method now active in the
1847 current buffer. (It automatically becomes local in each buffer when set
1848 in any fashion.) It is @code{nil} if no input method is active in the
1852 @defopt default-input-method
1853 This variable holds the default input method for commands that choose an
1854 input method. Unlike @code{current-input-method}, this variable is
1858 @deffn Command set-input-method input-method
1859 This command activates input method @var{input-method} for the current
1860 buffer. It also sets @code{default-input-method} to @var{input-method}.
1861 If @var{input-method} is @code{nil}, this command deactivates any input
1862 method for the current buffer.
1865 @defun read-input-method-name prompt &optional default inhibit-null
1866 This function reads an input method name with the minibuffer, prompting
1867 with @var{prompt}. If @var{default} is non-@code{nil}, that is returned
1868 by default, if the user enters empty input. However, if
1869 @var{inhibit-null} is non-@code{nil}, empty input signals an error.
1871 The returned value is a string.
1874 @defvar input-method-alist
1875 This variable defines all the supported input methods.
1876 Each element defines one input method, and should have the form:
1879 (@var{input-method} @var{language-env} @var{activate-func}
1880 @var{title} @var{description} @var{args}...)
1883 Here @var{input-method} is the input method name, a string;
1884 @var{language-env} is another string, the name of the language
1885 environment this input method is recommended for. (That serves only for
1886 documentation purposes.)
1888 @var{activate-func} is a function to call to activate this method. The
1889 @var{args}, if any, are passed as arguments to @var{activate-func}. All
1890 told, the arguments to @var{activate-func} are @var{input-method} and
1893 @var{title} is a string to display in the mode line while this method is
1894 active. @var{description} is a string describing this method and what
1898 The fundamental interface to input methods is through the
1899 variable @code{input-method-function}. @xref{Reading One Event},
1900 and @ref{Invoking the Input Method}.
1906 POSIX defines a concept of ``locales'' which control which language
1907 to use in language-related features. These Emacs variables control
1908 how Emacs interacts with these features.
1910 @defvar locale-coding-system
1911 @cindex keyboard input decoding on X
1912 This variable specifies the coding system to use for decoding system
1913 error messages and---on X Window system only---keyboard input, for
1914 encoding the format argument to @code{format-time-string}, and for
1915 decoding the return value of @code{format-time-string}.
1918 @defvar system-messages-locale
1919 This variable specifies the locale to use for generating system error
1920 messages. Changing the locale can cause messages to come out in a
1921 different language or in a different orthography. If the variable is
1922 @code{nil}, the locale is specified by environment variables in the
1923 usual POSIX fashion.
1926 @defvar system-time-locale
1927 This variable specifies the locale to use for formatting time values.
1928 Changing the locale can cause messages to appear according to the
1929 conventions of a different language. If the variable is @code{nil}, the
1930 locale is specified by environment variables in the usual POSIX fashion.
1933 @defun locale-info item
1934 This function returns locale data @var{item} for the current POSIX
1935 locale, if available. @var{item} should be one of these symbols:
1939 Return the character set as a string (locale item @code{CODESET}).
1942 Return a 7-element vector of day names (locale items
1943 @code{DAY_1} through @code{DAY_7});
1946 Return a 12-element vector of month names (locale items @code{MON_1}
1947 through @code{MON_12}).
1950 Return a list @code{(@var{width} @var{height})} for the default paper
1951 size measured in millimeters (locale items @code{PAPER_WIDTH} and
1952 @code{PAPER_HEIGHT}).
1955 If the system can't provide the requested information, or if
1956 @var{item} is not one of those symbols, the value is @code{nil}. All
1957 strings in the return value are decoded using
1958 @code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual},
1959 for more information about locales and locale items.