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 This function signals an error if the buffer is narrowed, since the
245 narrowing might have occurred in the middle of multibyte character
248 This function also signals an error if the buffer is an indirect
249 buffer. An indirect buffer always inherits the representation of its
253 @defun string-as-unibyte string
254 If @var{string} is already a unibyte string, this function returns
255 @var{string} itself. Otherwise, it returns a new string with the same
256 bytes as @var{string}, but treating each byte as a separate character
257 (so that the value may have more characters than @var{string}); as an
258 exception, each eight-bit character representing a raw byte is
259 converted into a single byte. The newly-created string contains no
263 @defun string-as-multibyte string
264 If @var{string} is a multibyte string, this function returns
265 @var{string} itself. Otherwise, it returns a new string with the same
266 bytes as @var{string}, but treating each multibyte sequence as one
267 character. This means that the value may have fewer characters than
268 @var{string} has. If a byte sequence in @var{string} is invalid as a
269 multibyte representation of a single character, each byte in the
270 sequence is treated as a raw 8-bit byte. The newly-created string
271 contains no text properties.
274 @node Character Codes
275 @section Character Codes
276 @cindex character codes
278 The unibyte and multibyte text representations use different
279 character codes. The valid character codes for unibyte representation
280 range from 0 to @code{#xFF} (255)---the values that can fit in one
281 byte. The valid character codes for multibyte representation range
282 from 0 to @code{#x3FFFFF}. In this code space, values 0 through
283 @code{#x7F} (127) are for @acronym{ASCII} characters, and values
284 @code{#x80} (128) through @code{#x3FFF7F} (4194175) are for
285 non-@acronym{ASCII} characters.
287 Emacs character codes are a superset of the Unicode standard.
288 Values 0 through @code{#x10FFFF} (1114111) correspond to Unicode
289 characters of the same codepoint; values @code{#x110000} (1114112)
290 through @code{#x3FFF7F} (4194175) represent characters that are not
291 unified with Unicode; and values @code{#x3FFF80} (4194176) through
292 @code{#x3FFFFF} (4194303) represent eight-bit raw bytes.
294 @defun characterp charcode
295 This returns @code{t} if @var{charcode} is a valid character, and
296 @code{nil} otherwise.
314 @cindex maximum value of character codepoint
315 @cindex codepoint, largest value
317 This function returns the largest value that a valid character
322 (characterp (max-char))
326 (characterp (1+ (max-char)))
332 @defun get-byte &optional pos string
333 This function returns the byte at character position @var{pos} in the
334 current buffer. If the current buffer is unibyte, this is literally
335 the byte at that position. If the buffer is multibyte, byte values of
336 @acronym{ASCII} characters are the same as character codepoints,
337 whereas eight-bit raw bytes are converted to their 8-bit codes. The
338 function signals an error if the character at @var{pos} is
341 The optional argument @var{string} means to get a byte value from that
342 string instead of the current buffer.
345 @node Character Properties
346 @section Character Properties
347 @cindex character properties
348 A @dfn{character property} is a named attribute of a character that
349 specifies how the character behaves and how it should be handled
350 during text processing and display. Thus, character properties are an
351 important part of specifying the character's semantics.
353 On the whole, Emacs follows the Unicode Standard in its implementation
354 of character properties. In particular, Emacs supports the
355 @uref{http://www.unicode.org/reports/tr23/, Unicode Character Property
356 Model}, and the Emacs character property database is derived from the
357 Unicode Character Database (@acronym{UCD}). See the
358 @uref{http://www.unicode.org/versions/Unicode5.0.0/ch04.pdf, Character
359 Properties chapter of the Unicode Standard}, for a detailed
360 description of Unicode character properties and their meaning. This
361 section assumes you are already familiar with that chapter of the
362 Unicode Standard, and want to apply that knowledge to Emacs Lisp
365 In Emacs, each property has a name, which is a symbol, and a set of
366 possible values, whose types depend on the property; if a character
367 does not have a certain property, the value is @code{nil}. As a
368 general rule, the names of character properties in Emacs are produced
369 from the corresponding Unicode properties by downcasing them and
370 replacing each @samp{_} character with a dash @samp{-}. For example,
371 @code{Canonical_Combining_Class} becomes
372 @code{canonical-combining-class}. However, sometimes we shorten the
373 names to make their use easier.
375 @cindex unassigned character codepoints
376 Some codepoints are left @dfn{unassigned} by the
377 @acronym{UCD}---they don't correspond to any character. The Unicode
378 Standard defines default values of properties for such codepoints;
379 they are mentioned below for each property.
381 Here is the full list of value types for all the character
382 properties that Emacs knows about:
386 Corresponds to the @code{Name} Unicode property. The value is a
387 string consisting of upper-case Latin letters A to Z, digits, spaces,
388 and hyphen @samp{-} characters. For unassigned codepoints, the value
391 @cindex unicode general category
392 @item general-category
393 Corresponds to the @code{General_Category} Unicode property. The
394 value is a symbol whose name is a 2-letter abbreviation of the
395 character's classification. For unassigned codepoints, the value
398 @item canonical-combining-class
399 Corresponds to the @code{Canonical_Combining_Class} Unicode property.
400 The value is an integer number. For unassigned codepoints, the value
403 @cindex bidirectional class of characters
405 Corresponds to the Unicode @code{Bidi_Class} property. The value is a
406 symbol whose name is the Unicode @dfn{directional type} of the
407 character. Emacs uses this property when it reorders bidirectional
408 text for display (@pxref{Bidirectional Display}). For unassigned
409 codepoints, the value depends on the code blocks to which the
410 codepoint belongs: most unassigned codepoints get the value of
411 @code{L} (strong L), but some get values of @code{AL} (Arabic letter)
412 or @code{R} (strong R).
415 Corresponds to the Unicode properties @code{Decomposition_Type} and
416 @code{Decomposition_Value}. The value is a list, whose first element
417 may be a symbol representing a compatibility formatting tag, such as
418 @code{small}@footnote{The Unicode specification writes these tag names
419 inside @samp{<..>} brackets, but the tag names in Emacs do not include
420 the brackets; e.g.@: Unicode specifies @samp{<small>} where Emacs uses
421 @samp{small}. }; the other elements are characters that give the
422 compatibility decomposition sequence of this character. For
423 unassigned codepoints, the value is the character itself.
425 @item decimal-digit-value
426 Corresponds to the Unicode @code{Numeric_Value} property for
427 characters whose @code{Numeric_Type} is @samp{Digit}. The value is an
428 integer number. For unassigned codepoints, the value is @code{nil},
429 which means @acronym{NaN}, or ``not-a-number''.
432 Corresponds to the Unicode @code{Numeric_Value} property for
433 characters whose @code{Numeric_Type} is @samp{Decimal}. The value is
434 an integer number. Examples of such characters include compatibility
435 subscript and superscript digits, for which the value is the
436 corresponding number. For unassigned codepoints, the value is
437 @code{nil}, which means @acronym{NaN}.
440 Corresponds to the Unicode @code{Numeric_Value} property for
441 characters whose @code{Numeric_Type} is @samp{Numeric}. The value of
442 this property is an integer or a floating-point number. Examples of
443 characters that have this property include fractions, subscripts,
444 superscripts, Roman numerals, currency numerators, and encircled
445 numbers. For example, the value of this property for the character
446 @code{U+2155} (@sc{vulgar fraction one fifth}) is @code{0.2}. For
447 unassigned codepoints, the value is @code{nil}, which means
450 @cindex mirroring of characters
452 Corresponds to the Unicode @code{Bidi_Mirrored} property. The value
453 of this property is a symbol, either @code{Y} or @code{N}. For
454 unassigned codepoints, the value is @code{N}.
457 Corresponds to the Unicode @code{Bidi_Mirroring_Glyph} property. The
458 value of this property is a character whose glyph represents the
459 mirror image of the character's glyph, or @code{nil} if there's no
460 defined mirroring glyph. All the characters whose @code{mirrored}
461 property is @code{N} have @code{nil} as their @code{mirroring}
462 property; however, some characters whose @code{mirrored} property is
463 @code{Y} also have @code{nil} for @code{mirroring}, because no
464 appropriate characters exist with mirrored glyphs. Emacs uses this
465 property to display mirror images of characters when appropriate
466 (@pxref{Bidirectional Display}). For unassigned codepoints, the value
470 Corresponds to the Unicode @code{Unicode_1_Name} property. The value
471 is a string. For unassigned codepoints, the value is an empty string.
473 @item iso-10646-comment
474 Corresponds to the Unicode @code{ISO_Comment} property. The value is
475 a string. For unassigned codepoints, the value is an empty string.
478 Corresponds to the Unicode @code{Simple_Uppercase_Mapping} property.
479 The value of this property is a single character. For unassigned
480 codepoints, the value is @code{nil}, which means the character itself.
483 Corresponds to the Unicode @code{Simple_Lowercase_Mapping} property.
484 The value of this property is a single character. For unassigned
485 codepoints, the value is @code{nil}, which means the character itself.
488 Corresponds to the Unicode @code{Simple_Titlecase_Mapping} property.
489 @dfn{Title case} is a special form of a character used when the first
490 character of a word needs to be capitalized. The value of this
491 property is a single character. For unassigned codepoints, the value
492 is @code{nil}, which means the character itself.
495 @defun get-char-code-property char propname
496 This function returns the value of @var{char}'s @var{propname} property.
500 (get-char-code-property ? 'general-category)
504 (get-char-code-property ?1 'general-category)
509 (get-char-code-property ?\u2084 'digit-value)
514 (get-char-code-property ?\u2155 'numeric-value)
519 (get-char-code-property ?\u2163 'numeric-value)
525 @defun char-code-property-description prop value
526 This function returns the description string of property @var{prop}'s
527 @var{value}, or @code{nil} if @var{value} has no description.
531 (char-code-property-description 'general-category 'Zs)
532 @result{} "Separator, Space"
535 (char-code-property-description 'general-category 'Nd)
536 @result{} "Number, Decimal Digit"
539 (char-code-property-description 'numeric-value '1/5)
545 @defun put-char-code-property char propname value
546 This function stores @var{value} as the value of the property
547 @var{propname} for the character @var{char}.
550 @defvar unicode-category-table
551 The value of this variable is a char-table (@pxref{Char-Tables}) that
552 specifies, for each character, its Unicode @code{General_Category}
553 property as a symbol.
556 @defvar char-script-table
557 The value of this variable is a char-table that specifies, for each
558 character, a symbol whose name is the script to which the character
559 belongs, according to the Unicode Standard classification of the
560 Unicode code space into script-specific blocks. This char-table has a
561 single extra slot whose value is the list of all script symbols.
564 @defvar char-width-table
565 The value of this variable is a char-table that specifies the width of
566 each character in columns that it will occupy on the screen.
569 @defvar printable-chars
570 The value of this variable is a char-table that specifies, for each
571 character, whether it is printable or not. That is, if evaluating
572 @code{(aref printable-chars char)} results in @code{t}, the character
573 is printable, and if it results in @code{nil}, it is not.
577 @section Character Sets
578 @cindex character sets
581 @cindex coded character set
582 An Emacs @dfn{character set}, or @dfn{charset}, is a set of characters
583 in which each character is assigned a numeric code point. (The
584 Unicode Standard calls this a @dfn{coded character set}.) Each Emacs
585 charset has a name which is a symbol. A single character can belong
586 to any number of different character sets, but it will generally have
587 a different code point in each charset. Examples of character sets
588 include @code{ascii}, @code{iso-8859-1}, @code{greek-iso8859-7}, and
589 @code{windows-1255}. The code point assigned to a character in a
590 charset is usually different from its code point used in Emacs buffers
593 @cindex @code{emacs}, a charset
594 @cindex @code{unicode}, a charset
595 @cindex @code{eight-bit}, a charset
596 Emacs defines several special character sets. The character set
597 @code{unicode} includes all the characters whose Emacs code points are
598 in the range @code{0..#x10FFFF}. The character set @code{emacs}
599 includes all @acronym{ASCII} and non-@acronym{ASCII} characters.
600 Finally, the @code{eight-bit} charset includes the 8-bit raw bytes;
601 Emacs uses it to represent raw bytes encountered in text.
603 @defun charsetp object
604 Returns @code{t} if @var{object} is a symbol that names a character set,
605 @code{nil} otherwise.
609 The value is a list of all defined character set names.
612 @defun charset-priority-list &optional highestp
613 This function returns a list of all defined character sets ordered by
614 their priority. If @var{highestp} is non-@code{nil}, the function
615 returns a single character set of the highest priority.
618 @defun set-charset-priority &rest charsets
619 This function makes @var{charsets} the highest priority character sets.
622 @defun char-charset character &optional restriction
623 This function returns the name of the character set of highest
624 priority that @var{character} belongs to. @acronym{ASCII} characters
625 are an exception: for them, this function always returns @code{ascii}.
627 If @var{restriction} is non-@code{nil}, it should be a list of
628 charsets to search. Alternatively, it can be a coding system, in
629 which case the returned charset must be supported by that coding
630 system (@pxref{Coding Systems}).
633 @defun charset-plist charset
634 This function returns the property list of the character set
635 @var{charset}. Although @var{charset} is a symbol, this is not the
636 same as the property list of that symbol. Charset properties include
637 important information about the charset, such as its documentation
638 string, short name, etc.
641 @defun put-charset-property charset propname value
642 This function sets the @var{propname} property of @var{charset} to the
646 @defun get-charset-property charset propname
647 This function returns the value of @var{charset}s property
651 @deffn Command list-charset-chars charset
652 This command displays a list of characters in the character set
656 Emacs can convert between its internal representation of a character
657 and the character's codepoint in a specific charset. The following
658 two functions support these conversions.
660 @c FIXME: decode-char and encode-char accept and ignore an additional
661 @c argument @var{restriction}. When that argument actually makes a
662 @c difference, it should be documented here.
663 @defun decode-char charset code-point
664 This function decodes a character that is assigned a @var{code-point}
665 in @var{charset}, to the corresponding Emacs character, and returns
666 it. If @var{charset} doesn't contain a character of that code point,
667 the value is @code{nil}. If @var{code-point} doesn't fit in a Lisp
668 integer (@pxref{Integer Basics, most-positive-fixnum}), it can be
669 specified as a cons cell @code{(@var{high} . @var{low})}, where
670 @var{low} are the lower 16 bits of the value and @var{high} are the
674 @defun encode-char char charset
675 This function returns the code point assigned to the character
676 @var{char} in @var{charset}. If the result does not fit in a Lisp
677 integer, it is returned as a cons cell @code{(@var{high} . @var{low})}
678 that fits the second argument of @code{decode-char} above. If
679 @var{charset} doesn't have a codepoint for @var{char}, the value is
683 The following function comes in handy for applying a certain
684 function to all or part of the characters in a charset:
686 @defun map-charset-chars function charset &optional arg from-code to-code
687 Call @var{function} for characters in @var{charset}. @var{function}
688 is called with two arguments. The first one is a cons cell
689 @code{(@var{from} . @var{to})}, where @var{from} and @var{to}
690 indicate a range of characters contained in charset. The second
691 argument passed to @var{function} is @var{arg}.
693 By default, the range of codepoints passed to @var{function} includes
694 all the characters in @var{charset}, but optional arguments
695 @var{from-code} and @var{to-code} limit that to the range of
696 characters between these two codepoints of @var{charset}. If either
697 of them is @code{nil}, it defaults to the first or last codepoint of
698 @var{charset}, respectively.
701 @node Scanning Charsets
702 @section Scanning for Character Sets
704 Sometimes it is useful to find out which character set a particular
705 character belongs to. One use for this is in determining which coding
706 systems (@pxref{Coding Systems}) are capable of representing all of
707 the text in question; another is to determine the font(s) for
708 displaying that text.
710 @defun charset-after &optional pos
711 This function returns the charset of highest priority containing the
712 character at position @var{pos} in the current buffer. If @var{pos}
713 is omitted or @code{nil}, it defaults to the current value of point.
714 If @var{pos} is out of range, the value is @code{nil}.
717 @defun find-charset-region beg end &optional translation
718 This function returns a list of the character sets of highest priority
719 that contain characters in the current buffer between positions
720 @var{beg} and @var{end}.
722 The optional argument @var{translation} specifies a translation table
723 to use for scanning the text (@pxref{Translation of Characters}). If
724 it is non-@code{nil}, then each character in the region is translated
725 through this table, and the value returned describes the translated
726 characters instead of the characters actually in the buffer.
729 @defun find-charset-string string &optional translation
730 This function returns a list of character sets of highest priority
731 that contain characters in @var{string}. It is just like
732 @code{find-charset-region}, except that it applies to the contents of
733 @var{string} instead of part of the current buffer.
736 @node Translation of Characters
737 @section Translation of Characters
738 @cindex character translation tables
739 @cindex translation tables
741 A @dfn{translation table} is a char-table (@pxref{Char-Tables}) that
742 specifies a mapping of characters into characters. These tables are
743 used in encoding and decoding, and for other purposes. Some coding
744 systems specify their own particular translation tables; there are
745 also default translation tables which apply to all other coding
748 A translation table has two extra slots. The first is either
749 @code{nil} or a translation table that performs the reverse
750 translation; the second is the maximum number of characters to look up
751 for translating sequences of characters (see the description of
752 @code{make-translation-table-from-alist} below).
754 @defun make-translation-table &rest translations
755 This function returns a translation table based on the argument
756 @var{translations}. Each element of @var{translations} should be a
757 list of elements of the form @code{(@var{from} . @var{to})}; this says
758 to translate the character @var{from} into @var{to}.
760 The arguments and the forms in each argument are processed in order,
761 and if a previous form already translates @var{to} to some other
762 character, say @var{to-alt}, @var{from} is also translated to
766 During decoding, the translation table's translations are applied to
767 the characters that result from ordinary decoding. If a coding system
768 has the property @code{:decode-translation-table}, that specifies the
769 translation table to use, or a list of translation tables to apply in
770 sequence. (This is a property of the coding system, as returned by
771 @code{coding-system-get}, not a property of the symbol that is the
772 coding system's name. @xref{Coding System Basics,, Basic Concepts of
773 Coding Systems}.) Finally, if
774 @code{standard-translation-table-for-decode} is non-@code{nil}, the
775 resulting characters are translated by that table.
777 During encoding, the translation table's translations are applied to
778 the characters in the buffer, and the result of translation is
779 actually encoded. If a coding system has property
780 @code{:encode-translation-table}, that specifies the translation table
781 to use, or a list of translation tables to apply in sequence. In
782 addition, if the variable @code{standard-translation-table-for-encode}
783 is non-@code{nil}, it specifies the translation table to use for
784 translating the result.
786 @defvar standard-translation-table-for-decode
787 This is the default translation table for decoding. If a coding
788 systems specifies its own translation tables, the table that is the
789 value of this variable, if non-@code{nil}, is applied after them.
792 @defvar standard-translation-table-for-encode
793 This is the default translation table for encoding. If a coding
794 systems specifies its own translation tables, the table that is the
795 value of this variable, if non-@code{nil}, is applied after them.
798 @defvar translation-table-for-input
799 Self-inserting characters are translated through this translation
800 table before they are inserted. Search commands also translate their
801 input through this table, so they can compare more reliably with
802 what's in the buffer.
804 This variable automatically becomes buffer-local when set.
807 @defun make-translation-table-from-vector vec
808 This function returns a translation table made from @var{vec} that is
809 an array of 256 elements to map bytes (values 0 through #xFF) to
810 characters. Elements may be @code{nil} for untranslated bytes. The
811 returned table has a translation table for reverse mapping in the
812 first extra slot, and the value @code{1} in the second extra slot.
814 This function provides an easy way to make a private coding system
815 that maps each byte to a specific character. You can specify the
816 returned table and the reverse translation table using the properties
817 @code{:decode-translation-table} and @code{:encode-translation-table}
818 respectively in the @var{props} argument to
819 @code{define-coding-system}.
822 @defun make-translation-table-from-alist alist
823 This function is similar to @code{make-translation-table} but returns
824 a complex translation table rather than a simple one-to-one mapping.
825 Each element of @var{alist} is of the form @code{(@var{from}
826 . @var{to})}, where @var{from} and @var{to} are either characters or
827 vectors specifying a sequence of characters. If @var{from} is a
828 character, that character is translated to @var{to} (i.e.@: to a
829 character or a character sequence). If @var{from} is a vector of
830 characters, that sequence is translated to @var{to}. The returned
831 table has a translation table for reverse mapping in the first extra
832 slot, and the maximum length of all the @var{from} character sequences
833 in the second extra slot.
837 @section Coding Systems
839 @cindex coding system
840 When Emacs reads or writes a file, and when Emacs sends text to a
841 subprocess or receives text from a subprocess, it normally performs
842 character code conversion and end-of-line conversion as specified
843 by a particular @dfn{coding system}.
845 How to define a coding system is an arcane matter, and is not
849 * Coding System Basics:: Basic concepts.
850 * Encoding and I/O:: How file I/O functions handle coding systems.
851 * Lisp and Coding Systems:: Functions to operate on coding system names.
852 * User-Chosen Coding Systems:: Asking the user to choose a coding system.
853 * Default Coding Systems:: Controlling the default choices.
854 * Specifying Coding Systems:: Requesting a particular coding system
855 for a single file operation.
856 * Explicit Encoding:: Encoding or decoding text without doing I/O.
857 * Terminal I/O Encoding:: Use of encoding for terminal I/O.
858 * MS-DOS File Types:: How DOS "text" and "binary" files
859 relate to coding systems.
862 @node Coding System Basics
863 @subsection Basic Concepts of Coding Systems
865 @cindex character code conversion
866 @dfn{Character code conversion} involves conversion between the
867 internal representation of characters used inside Emacs and some other
868 encoding. Emacs supports many different encodings, in that it can
869 convert to and from them. For example, it can convert text to or from
870 encodings such as Latin 1, Latin 2, Latin 3, Latin 4, Latin 5, and
871 several variants of ISO 2022. In some cases, Emacs supports several
872 alternative encodings for the same characters; for example, there are
873 three coding systems for the Cyrillic (Russian) alphabet: ISO,
874 Alternativnyj, and KOI8.
876 Every coding system specifies a particular set of character code
877 conversions, but the coding system @code{undecided} is special: it
878 leaves the choice unspecified, to be chosen heuristically for each
879 file, based on the file's data.
881 In general, a coding system doesn't guarantee roundtrip identity:
882 decoding a byte sequence using coding system, then encoding the
883 resulting text in the same coding system, can produce a different byte
884 sequence. But some coding systems do guarantee that the byte sequence
885 will be the same as what you originally decoded. Here are a few
889 iso-8859-1, utf-8, big5, shift_jis, euc-jp
892 Encoding buffer text and then decoding the result can also fail to
893 reproduce the original text. For instance, if you encode a character
894 with a coding system which does not support that character, the result
895 is unpredictable, and thus decoding it using the same coding system
896 may produce a different text. Currently, Emacs can't report errors
897 that result from encoding unsupported characters.
899 @cindex EOL conversion
900 @cindex end-of-line conversion
901 @cindex line end conversion
902 @dfn{End of line conversion} handles three different conventions
903 used on various systems for representing end of line in files. The
904 Unix convention, used on GNU and Unix systems, is to use the linefeed
905 character (also called newline). The DOS convention, used on
906 MS-Windows and MS-DOS systems, is to use a carriage-return and a
907 linefeed at the end of a line. The Mac convention is to use just
910 @cindex base coding system
911 @cindex variant coding system
912 @dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
913 conversion unspecified, to be chosen based on the data. @dfn{Variant
914 coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
915 @code{latin-1-mac} specify the end-of-line conversion explicitly as
916 well. Most base coding systems have three corresponding variants whose
917 names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
919 @vindex raw-text@r{ coding system}
920 The coding system @code{raw-text} is special in that it prevents
921 character code conversion, and causes the buffer visited with this
922 coding system to be a unibyte buffer. For historical reasons, you can
923 save both unibyte and multibyte text with this coding system. When
924 you use @code{raw-text} to encode multibyte text, it does perform one
925 character code conversion: it converts eight-bit characters to their
926 single-byte external representation. @code{raw-text} does not specify
927 the end-of-line conversion, allowing that to be determined as usual by
928 the data, and has the usual three variants which specify the
929 end-of-line conversion.
931 @vindex no-conversion@r{ coding system}
932 @vindex binary@r{ coding system}
933 @code{no-conversion} (and its alias @code{binary}) is equivalent to
934 @code{raw-text-unix}: it specifies no conversion of either character
935 codes or end-of-line.
937 @vindex emacs-internal@r{ coding system}
938 @vindex utf-8-emacs@r{ coding system}
939 The coding system @code{utf-8-emacs} specifies that the data is
940 represented in the internal Emacs encoding (@pxref{Text
941 Representations}). This is like @code{raw-text} in that no code
942 conversion happens, but different in that the result is multibyte
943 data. The name @code{emacs-internal} is an alias for
946 @defun coding-system-get coding-system property
947 This function returns the specified property of the coding system
948 @var{coding-system}. Most coding system properties exist for internal
949 purposes, but one that you might find useful is @code{:mime-charset}.
950 That property's value is the name used in MIME for the character coding
951 which this coding system can read and write. Examples:
954 (coding-system-get 'iso-latin-1 :mime-charset)
956 (coding-system-get 'iso-2022-cn :mime-charset)
957 @result{} iso-2022-cn
958 (coding-system-get 'cyrillic-koi8 :mime-charset)
962 The value of the @code{:mime-charset} property is also defined
963 as an alias for the coding system.
966 @defun coding-system-aliases coding-system
967 This function returns the list of aliases of @var{coding-system}.
970 @node Encoding and I/O
971 @subsection Encoding and I/O
973 The principal purpose of coding systems is for use in reading and
974 writing files. The function @code{insert-file-contents} uses a coding
975 system to decode the file data, and @code{write-region} uses one to
976 encode the buffer contents.
978 You can specify the coding system to use either explicitly
979 (@pxref{Specifying Coding Systems}), or implicitly using a default
980 mechanism (@pxref{Default Coding Systems}). But these methods may not
981 completely specify what to do. For example, they may choose a coding
982 system such as @code{undefined} which leaves the character code
983 conversion to be determined from the data. In these cases, the I/O
984 operation finishes the job of choosing a coding system. Very often
985 you will want to find out afterwards which coding system was chosen.
987 @defvar buffer-file-coding-system
988 This buffer-local variable records the coding system used for saving the
989 buffer and for writing part of the buffer with @code{write-region}. If
990 the text to be written cannot be safely encoded using the coding system
991 specified by this variable, these operations select an alternative
992 encoding by calling the function @code{select-safe-coding-system}
993 (@pxref{User-Chosen Coding Systems}). If selecting a different encoding
994 requires to ask the user to specify a coding system,
995 @code{buffer-file-coding-system} is updated to the newly selected coding
998 @code{buffer-file-coding-system} does @emph{not} affect sending text
1002 @defvar save-buffer-coding-system
1003 This variable specifies the coding system for saving the buffer (by
1004 overriding @code{buffer-file-coding-system}). Note that it is not used
1005 for @code{write-region}.
1007 When a command to save the buffer starts out to use
1008 @code{buffer-file-coding-system} (or @code{save-buffer-coding-system}),
1009 and that coding system cannot handle
1010 the actual text in the buffer, the command asks the user to choose
1011 another coding system (by calling @code{select-safe-coding-system}).
1012 After that happens, the command also updates
1013 @code{buffer-file-coding-system} to represent the coding system that
1017 @defvar last-coding-system-used
1018 I/O operations for files and subprocesses set this variable to the
1019 coding system name that was used. The explicit encoding and decoding
1020 functions (@pxref{Explicit Encoding}) set it too.
1022 @strong{Warning:} Since receiving subprocess output sets this variable,
1023 it can change whenever Emacs waits; therefore, you should copy the
1024 value shortly after the function call that stores the value you are
1028 The variable @code{selection-coding-system} specifies how to encode
1029 selections for the window system. @xref{Window System Selections}.
1031 @defvar file-name-coding-system
1032 The variable @code{file-name-coding-system} specifies the coding
1033 system to use for encoding file names. Emacs encodes file names using
1034 that coding system for all file operations. If
1035 @code{file-name-coding-system} is @code{nil}, Emacs uses a default
1036 coding system determined by the selected language environment. In the
1037 default language environment, any non-@acronym{ASCII} characters in
1038 file names are not encoded specially; they appear in the file system
1039 using the internal Emacs representation.
1042 @strong{Warning:} if you change @code{file-name-coding-system} (or
1043 the language environment) in the middle of an Emacs session, problems
1044 can result if you have already visited files whose names were encoded
1045 using the earlier coding system and are handled differently under the
1046 new coding system. If you try to save one of these buffers under the
1047 visited file name, saving may use the wrong file name, or it may get
1048 an error. If such a problem happens, use @kbd{C-x C-w} to specify a
1049 new file name for that buffer.
1051 @node Lisp and Coding Systems
1052 @subsection Coding Systems in Lisp
1054 Here are the Lisp facilities for working with coding systems:
1056 @cindex list all coding systems
1057 @defun coding-system-list &optional base-only
1058 This function returns a list of all coding system names (symbols). If
1059 @var{base-only} is non-@code{nil}, the value includes only the
1060 base coding systems. Otherwise, it includes alias and variant coding
1064 @defun coding-system-p object
1065 This function returns @code{t} if @var{object} is a coding system
1069 @cindex validity of coding system
1070 @cindex coding system, validity check
1071 @defun check-coding-system coding-system
1072 This function checks the validity of @var{coding-system}. If that is
1073 valid, it returns @var{coding-system}. If @var{coding-system} is
1074 @code{nil}, the function return @code{nil}. For any other values, it
1075 signals an error whose @code{error-symbol} is @code{coding-system-error}
1076 (@pxref{Signaling Errors, signal}).
1079 @cindex eol type of coding system
1080 @defun coding-system-eol-type coding-system
1081 This function returns the type of end-of-line (a.k.a.@: @dfn{eol})
1082 conversion used by @var{coding-system}. If @var{coding-system}
1083 specifies a certain eol conversion, the return value is an integer 0,
1084 1, or 2, standing for @code{unix}, @code{dos}, and @code{mac},
1085 respectively. If @var{coding-system} doesn't specify eol conversion
1086 explicitly, the return value is a vector of coding systems, each one
1087 with one of the possible eol conversion types, like this:
1090 (coding-system-eol-type 'latin-1)
1091 @result{} [latin-1-unix latin-1-dos latin-1-mac]
1095 If this function returns a vector, Emacs will decide, as part of the
1096 text encoding or decoding process, what eol conversion to use. For
1097 decoding, the end-of-line format of the text is auto-detected, and the
1098 eol conversion is set to match it (e.g., DOS-style CRLF format will
1099 imply @code{dos} eol conversion). For encoding, the eol conversion is
1100 taken from the appropriate default coding system (e.g.,
1101 default value of @code{buffer-file-coding-system} for
1102 @code{buffer-file-coding-system}), or from the default eol conversion
1103 appropriate for the underlying platform.
1106 @cindex eol conversion of coding system
1107 @defun coding-system-change-eol-conversion coding-system eol-type
1108 This function returns a coding system which is like @var{coding-system}
1109 except for its eol conversion, which is specified by @code{eol-type}.
1110 @var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
1111 @code{nil}. If it is @code{nil}, the returned coding system determines
1112 the end-of-line conversion from the data.
1114 @var{eol-type} may also be 0, 1 or 2, standing for @code{unix},
1115 @code{dos} and @code{mac}, respectively.
1118 @cindex text conversion of coding system
1119 @defun coding-system-change-text-conversion eol-coding text-coding
1120 This function returns a coding system which uses the end-of-line
1121 conversion of @var{eol-coding}, and the text conversion of
1122 @var{text-coding}. If @var{text-coding} is @code{nil}, it returns
1123 @code{undecided}, or one of its variants according to @var{eol-coding}.
1126 @cindex safely encode region
1127 @cindex coding systems for encoding region
1128 @defun find-coding-systems-region from to
1129 This function returns a list of coding systems that could be used to
1130 encode a text between @var{from} and @var{to}. All coding systems in
1131 the list can safely encode any multibyte characters in that portion of
1134 If the text contains no multibyte characters, the function returns the
1135 list @code{(undecided)}.
1138 @cindex safely encode a string
1139 @cindex coding systems for encoding a string
1140 @defun find-coding-systems-string string
1141 This function returns a list of coding systems that could be used to
1142 encode the text of @var{string}. All coding systems in the list can
1143 safely encode any multibyte characters in @var{string}. If the text
1144 contains no multibyte characters, this returns the list
1148 @cindex charset, coding systems to encode
1149 @cindex safely encode characters in a charset
1150 @defun find-coding-systems-for-charsets charsets
1151 This function returns a list of coding systems that could be used to
1152 encode all the character sets in the list @var{charsets}.
1155 @defun check-coding-systems-region start end coding-system-list
1156 This function checks whether coding systems in the list
1157 @code{coding-system-list} can encode all the characters in the region
1158 between @var{start} and @var{end}. If all of the coding systems in
1159 the list can encode the specified text, the function returns
1160 @code{nil}. If some coding systems cannot encode some of the
1161 characters, the value is an alist, each element of which has the form
1162 @code{(@var{coding-system1} @var{pos1} @var{pos2} @dots{})}, meaning
1163 that @var{coding-system1} cannot encode characters at buffer positions
1164 @var{pos1}, @var{pos2}, @enddots{}.
1166 @var{start} may be a string, in which case @var{end} is ignored and
1167 the returned value references string indices instead of buffer
1171 @defun detect-coding-region start end &optional highest
1172 This function chooses a plausible coding system for decoding the text
1173 from @var{start} to @var{end}. This text should be a byte sequence,
1174 i.e.@: unibyte text or multibyte text with only @acronym{ASCII} and
1175 eight-bit characters (@pxref{Explicit Encoding}).
1177 Normally this function returns a list of coding systems that could
1178 handle decoding the text that was scanned. They are listed in order of
1179 decreasing priority. But if @var{highest} is non-@code{nil}, then the
1180 return value is just one coding system, the one that is highest in
1183 If the region contains only @acronym{ASCII} characters except for such
1184 ISO-2022 control characters ISO-2022 as @code{ESC}, the value is
1185 @code{undecided} or @code{(undecided)}, or a variant specifying
1186 end-of-line conversion, if that can be deduced from the text.
1188 If the region contains null bytes, the value is @code{no-conversion},
1189 even if the region contains text encoded in some coding system.
1192 @defun detect-coding-string string &optional highest
1193 This function is like @code{detect-coding-region} except that it
1194 operates on the contents of @var{string} instead of bytes in the buffer.
1197 @cindex null bytes, and decoding text
1198 @defvar inhibit-null-byte-detection
1199 If this variable has a non-@code{nil} value, null bytes are ignored
1200 when detecting the encoding of a region or a string. This allows to
1201 correctly detect the encoding of text that contains null bytes, such
1202 as Info files with Index nodes.
1205 @defvar inhibit-iso-escape-detection
1206 If this variable has a non-@code{nil} value, ISO-2022 escape sequences
1207 are ignored when detecting the encoding of a region or a string. The
1208 result is that no text is ever detected as encoded in some ISO-2022
1209 encoding, and all escape sequences become visible in a buffer.
1210 @strong{Warning:} @emph{Use this variable with extreme caution,
1211 because many files in the Emacs distribution use ISO-2022 encoding.}
1214 @cindex charsets supported by a coding system
1215 @defun coding-system-charset-list coding-system
1216 This function returns the list of character sets (@pxref{Character
1217 Sets}) supported by @var{coding-system}. Some coding systems that
1218 support too many character sets to list them all yield special values:
1221 If @var{coding-system} supports all the ISO-2022 charsets, the value
1224 If @var{coding-system} supports all Emacs characters, the value is
1227 If @var{coding-system} supports all emacs-mule characters, the value
1228 is @code{emacs-mule}.
1230 If @var{coding-system} supports all Unicode characters, the value is
1235 @xref{Coding systems for a subprocess,, Process Information}, in
1236 particular the description of the functions
1237 @code{process-coding-system} and @code{set-process-coding-system}, for
1238 how to examine or set the coding systems used for I/O to a subprocess.
1240 @node User-Chosen Coding Systems
1241 @subsection User-Chosen Coding Systems
1243 @cindex select safe coding system
1244 @defun select-safe-coding-system from to &optional default-coding-system accept-default-p file
1245 This function selects a coding system for encoding specified text,
1246 asking the user to choose if necessary. Normally the specified text
1247 is the text in the current buffer between @var{from} and @var{to}. If
1248 @var{from} is a string, the string specifies the text to encode, and
1249 @var{to} is ignored.
1251 If the specified text includes raw bytes (@pxref{Text
1252 Representations}), @code{select-safe-coding-system} suggests
1253 @code{raw-text} for its encoding.
1255 If @var{default-coding-system} is non-@code{nil}, that is the first
1256 coding system to try; if that can handle the text,
1257 @code{select-safe-coding-system} returns that coding system. It can
1258 also be a list of coding systems; then the function tries each of them
1259 one by one. After trying all of them, it next tries the current
1260 buffer's value of @code{buffer-file-coding-system} (if it is not
1261 @code{undecided}), then the default value of
1262 @code{buffer-file-coding-system} and finally the user's most
1263 preferred coding system, which the user can set using the command
1264 @code{prefer-coding-system} (@pxref{Recognize Coding,, Recognizing
1265 Coding Systems, emacs, The GNU Emacs Manual}).
1267 If one of those coding systems can safely encode all the specified
1268 text, @code{select-safe-coding-system} chooses it and returns it.
1269 Otherwise, it asks the user to choose from a list of coding systems
1270 which can encode all the text, and returns the user's choice.
1272 @var{default-coding-system} can also be a list whose first element is
1273 t and whose other elements are coding systems. Then, if no coding
1274 system in the list can handle the text, @code{select-safe-coding-system}
1275 queries the user immediately, without trying any of the three
1276 alternatives described above.
1278 The optional argument @var{accept-default-p}, if non-@code{nil},
1279 should be a function to determine whether a coding system selected
1280 without user interaction is acceptable. @code{select-safe-coding-system}
1281 calls this function with one argument, the base coding system of the
1282 selected coding system. If @var{accept-default-p} returns @code{nil},
1283 @code{select-safe-coding-system} rejects the silently selected coding
1284 system, and asks the user to select a coding system from a list of
1285 possible candidates.
1287 @vindex select-safe-coding-system-accept-default-p
1288 If the variable @code{select-safe-coding-system-accept-default-p} is
1289 non-@code{nil}, it should be a function taking a single argument.
1290 It is used in place of @var{accept-default-p}, overriding any
1291 value supplied for this argument.
1293 As a final step, before returning the chosen coding system,
1294 @code{select-safe-coding-system} checks whether that coding system is
1295 consistent with what would be selected if the contents of the region
1296 were read from a file. (If not, this could lead to data corruption in
1297 a file subsequently re-visited and edited.) Normally,
1298 @code{select-safe-coding-system} uses @code{buffer-file-name} as the
1299 file for this purpose, but if @var{file} is non-@code{nil}, it uses
1300 that file instead (this can be relevant for @code{write-region} and
1301 similar functions). If it detects an apparent inconsistency,
1302 @code{select-safe-coding-system} queries the user before selecting the
1306 Here are two functions you can use to let the user specify a coding
1307 system, with completion. @xref{Completion}.
1309 @defun read-coding-system prompt &optional default
1310 This function reads a coding system using the minibuffer, prompting with
1311 string @var{prompt}, and returns the coding system name as a symbol. If
1312 the user enters null input, @var{default} specifies which coding system
1313 to return. It should be a symbol or a string.
1316 @defun read-non-nil-coding-system prompt
1317 This function reads a coding system using the minibuffer, prompting with
1318 string @var{prompt}, and returns the coding system name as a symbol. If
1319 the user tries to enter null input, it asks the user to try again.
1320 @xref{Coding Systems}.
1323 @node Default Coding Systems
1324 @subsection Default Coding Systems
1325 @cindex default coding system
1326 @cindex coding system, automatically determined
1328 This section describes variables that specify the default coding
1329 system for certain files or when running certain subprograms, and the
1330 function that I/O operations use to access them.
1332 The idea of these variables is that you set them once and for all to the
1333 defaults you want, and then do not change them again. To specify a
1334 particular coding system for a particular operation in a Lisp program,
1335 don't change these variables; instead, override them using
1336 @code{coding-system-for-read} and @code{coding-system-for-write}
1337 (@pxref{Specifying Coding Systems}).
1339 @cindex file contents, and default coding system
1340 @defopt auto-coding-regexp-alist
1341 This variable is an alist of text patterns and corresponding coding
1342 systems. Each element has the form @code{(@var{regexp}
1343 . @var{coding-system})}; a file whose first few kilobytes match
1344 @var{regexp} is decoded with @var{coding-system} when its contents are
1345 read into a buffer. The settings in this alist take priority over
1346 @code{coding:} tags in the files and the contents of
1347 @code{file-coding-system-alist} (see below). The default value is set
1348 so that Emacs automatically recognizes mail files in Babyl format and
1349 reads them with no code conversions.
1352 @cindex file name, and default coding system
1353 @defopt file-coding-system-alist
1354 This variable is an alist that specifies the coding systems to use for
1355 reading and writing particular files. Each element has the form
1356 @code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular
1357 expression that matches certain file names. The element applies to file
1358 names that match @var{pattern}.
1360 The @sc{cdr} of the element, @var{coding}, should be either a coding
1361 system, a cons cell containing two coding systems, or a function name (a
1362 symbol with a function definition). If @var{coding} is a coding system,
1363 that coding system is used for both reading the file and writing it. If
1364 @var{coding} is a cons cell containing two coding systems, its @sc{car}
1365 specifies the coding system for decoding, and its @sc{cdr} specifies the
1366 coding system for encoding.
1368 If @var{coding} is a function name, the function should take one
1369 argument, a list of all arguments passed to
1370 @code{find-operation-coding-system}. It must return a coding system
1371 or a cons cell containing two coding systems. This value has the same
1372 meaning as described above.
1374 If @var{coding} (or what returned by the above function) is
1375 @code{undecided}, the normal code-detection is performed.
1378 @defopt auto-coding-alist
1379 This variable is an alist that specifies the coding systems to use for
1380 reading and writing particular files. Its form is like that of
1381 @code{file-coding-system-alist}, but, unlike the latter, this variable
1382 takes priority over any @code{coding:} tags in the file.
1385 @cindex program name, and default coding system
1386 @defvar process-coding-system-alist
1387 This variable is an alist specifying which coding systems to use for a
1388 subprocess, depending on which program is running in the subprocess. It
1389 works like @code{file-coding-system-alist}, except that @var{pattern} is
1390 matched against the program name used to start the subprocess. The coding
1391 system or systems specified in this alist are used to initialize the
1392 coding systems used for I/O to the subprocess, but you can specify
1393 other coding systems later using @code{set-process-coding-system}.
1396 @strong{Warning:} Coding systems such as @code{undecided}, which
1397 determine the coding system from the data, do not work entirely reliably
1398 with asynchronous subprocess output. This is because Emacs handles
1399 asynchronous subprocess output in batches, as it arrives. If the coding
1400 system leaves the character code conversion unspecified, or leaves the
1401 end-of-line conversion unspecified, Emacs must try to detect the proper
1402 conversion from one batch at a time, and this does not always work.
1404 Therefore, with an asynchronous subprocess, if at all possible, use a
1405 coding system which determines both the character code conversion and
1406 the end of line conversion---that is, one like @code{latin-1-unix},
1407 rather than @code{undecided} or @code{latin-1}.
1409 @cindex port number, and default coding system
1410 @cindex network service name, and default coding system
1411 @defvar network-coding-system-alist
1412 This variable is an alist that specifies the coding system to use for
1413 network streams. It works much like @code{file-coding-system-alist},
1414 with the difference that the @var{pattern} in an element may be either a
1415 port number or a regular expression. If it is a regular expression, it
1416 is matched against the network service name used to open the network
1420 @defvar default-process-coding-system
1421 This variable specifies the coding systems to use for subprocess (and
1422 network stream) input and output, when nothing else specifies what to
1425 The value should be a cons cell of the form @code{(@var{input-coding}
1426 . @var{output-coding})}. Here @var{input-coding} applies to input from
1427 the subprocess, and @var{output-coding} applies to output to it.
1430 @cindex default coding system, functions to determine
1431 @defopt auto-coding-functions
1432 This variable holds a list of functions that try to determine a
1433 coding system for a file based on its undecoded contents.
1435 Each function in this list should be written to look at text in the
1436 current buffer, but should not modify it in any way. The buffer will
1437 contain undecoded text of parts of the file. Each function should
1438 take one argument, @var{size}, which tells it how many characters to
1439 look at, starting from point. If the function succeeds in determining
1440 a coding system for the file, it should return that coding system.
1441 Otherwise, it should return @code{nil}.
1443 If a file has a @samp{coding:} tag, that takes precedence, so these
1444 functions won't be called.
1447 @defun find-auto-coding filename size
1448 This function tries to determine a suitable coding system for
1449 @var{filename}. It examines the buffer visiting the named file, using
1450 the variables documented above in sequence, until it finds a match for
1451 one of the rules specified by these variables. It then returns a cons
1452 cell of the form @code{(@var{coding} . @var{source})}, where
1453 @var{coding} is the coding system to use and @var{source} is a symbol,
1454 one of @code{auto-coding-alist}, @code{auto-coding-regexp-alist},
1455 @code{:coding}, or @code{auto-coding-functions}, indicating which one
1456 supplied the matching rule. The value @code{:coding} means the coding
1457 system was specified by the @code{coding:} tag in the file
1458 (@pxref{Specify Coding,, coding tag, emacs, The GNU Emacs Manual}).
1459 The order of looking for a matching rule is @code{auto-coding-alist}
1460 first, then @code{auto-coding-regexp-alist}, then the @code{coding:}
1461 tag, and lastly @code{auto-coding-functions}. If no matching rule was
1462 found, the function returns @code{nil}.
1464 The second argument @var{size} is the size of text, in characters,
1465 following point. The function examines text only within @var{size}
1466 characters after point. Normally, the buffer should be positioned at
1467 the beginning when this function is called, because one of the places
1468 for the @code{coding:} tag is the first one or two lines of the file;
1469 in that case, @var{size} should be the size of the buffer.
1472 @defun set-auto-coding filename size
1473 This function returns a suitable coding system for file
1474 @var{filename}. It uses @code{find-auto-coding} to find the coding
1475 system. If no coding system could be determined, the function returns
1476 @code{nil}. The meaning of the argument @var{size} is like in
1477 @code{find-auto-coding}.
1480 @defun find-operation-coding-system operation &rest arguments
1481 This function returns the coding system to use (by default) for
1482 performing @var{operation} with @var{arguments}. The value has this
1486 (@var{decoding-system} . @var{encoding-system})
1489 The first element, @var{decoding-system}, is the coding system to use
1490 for decoding (in case @var{operation} does decoding), and
1491 @var{encoding-system} is the coding system for encoding (in case
1492 @var{operation} does encoding).
1494 The argument @var{operation} is a symbol; it should be one of
1495 @code{write-region}, @code{start-process}, @code{call-process},
1496 @code{call-process-region}, @code{insert-file-contents}, or
1497 @code{open-network-stream}. These are the names of the Emacs I/O
1498 primitives that can do character code and eol conversion.
1500 The remaining arguments should be the same arguments that might be given
1501 to the corresponding I/O primitive. Depending on the primitive, one
1502 of those arguments is selected as the @dfn{target}. For example, if
1503 @var{operation} does file I/O, whichever argument specifies the file
1504 name is the target. For subprocess primitives, the process name is the
1505 target. For @code{open-network-stream}, the target is the service name
1508 Depending on @var{operation}, this function looks up the target in
1509 @code{file-coding-system-alist}, @code{process-coding-system-alist},
1510 or @code{network-coding-system-alist}. If the target is found in the
1511 alist, @code{find-operation-coding-system} returns its association in
1512 the alist; otherwise it returns @code{nil}.
1514 If @var{operation} is @code{insert-file-contents}, the argument
1515 corresponding to the target may be a cons cell of the form
1516 @code{(@var{filename} . @var{buffer})}). In that case, @var{filename}
1517 is a file name to look up in @code{file-coding-system-alist}, and
1518 @var{buffer} is a buffer that contains the file's contents (not yet
1519 decoded). If @code{file-coding-system-alist} specifies a function to
1520 call for this file, and that function needs to examine the file's
1521 contents (as it usually does), it should examine the contents of
1522 @var{buffer} instead of reading the file.
1525 @node Specifying Coding Systems
1526 @subsection Specifying a Coding System for One Operation
1528 You can specify the coding system for a specific operation by binding
1529 the variables @code{coding-system-for-read} and/or
1530 @code{coding-system-for-write}.
1532 @defvar coding-system-for-read
1533 If this variable is non-@code{nil}, it specifies the coding system to
1534 use for reading a file, or for input from a synchronous subprocess.
1536 It also applies to any asynchronous subprocess or network stream, but in
1537 a different way: the value of @code{coding-system-for-read} when you
1538 start the subprocess or open the network stream specifies the input
1539 decoding method for that subprocess or network stream. It remains in
1540 use for that subprocess or network stream unless and until overridden.
1542 The right way to use this variable is to bind it with @code{let} for a
1543 specific I/O operation. Its global value is normally @code{nil}, and
1544 you should not globally set it to any other value. Here is an example
1545 of the right way to use the variable:
1548 ;; @r{Read the file with no character code conversion.}
1549 ;; @r{Assume @acronym{crlf} represents end-of-line.}
1550 (let ((coding-system-for-read 'emacs-mule-dos))
1551 (insert-file-contents filename))
1554 When its value is non-@code{nil}, this variable takes precedence over
1555 all other methods of specifying a coding system to use for input,
1556 including @code{file-coding-system-alist},
1557 @code{process-coding-system-alist} and
1558 @code{network-coding-system-alist}.
1561 @defvar coding-system-for-write
1562 This works much like @code{coding-system-for-read}, except that it
1563 applies to output rather than input. It affects writing to files,
1564 as well as sending output to subprocesses and net connections.
1566 When a single operation does both input and output, as do
1567 @code{call-process-region} and @code{start-process}, both
1568 @code{coding-system-for-read} and @code{coding-system-for-write}
1572 @defopt inhibit-eol-conversion
1573 When this variable is non-@code{nil}, no end-of-line conversion is done,
1574 no matter which coding system is specified. This applies to all the
1575 Emacs I/O and subprocess primitives, and to the explicit encoding and
1576 decoding functions (@pxref{Explicit Encoding}).
1579 @cindex priority order of coding systems
1580 @cindex coding systems, priority
1581 Sometimes, you need to prefer several coding systems for some
1582 operation, rather than fix a single one. Emacs lets you specify a
1583 priority order for using coding systems. This ordering affects the
1584 sorting of lists of coding systems returned by functions such as
1585 @code{find-coding-systems-region} (@pxref{Lisp and Coding Systems}).
1587 @defun coding-system-priority-list &optional highestp
1588 This function returns the list of coding systems in the order of their
1589 current priorities. Optional argument @var{highestp}, if
1590 non-@code{nil}, means return only the highest priority coding system.
1593 @defun set-coding-system-priority &rest coding-systems
1594 This function puts @var{coding-systems} at the beginning of the
1595 priority list for coding systems, thus making their priority higher
1599 @defmac with-coding-priority coding-systems &rest body@dots{}
1600 This macro execute @var{body}, like @code{progn} does
1601 (@pxref{Sequencing, progn}), with @var{coding-systems} at the front of
1602 the priority list for coding systems. @var{coding-systems} should be
1603 a list of coding systems to prefer during execution of @var{body}.
1606 @node Explicit Encoding
1607 @subsection Explicit Encoding and Decoding
1608 @cindex encoding in coding systems
1609 @cindex decoding in coding systems
1611 All the operations that transfer text in and out of Emacs have the
1612 ability to use a coding system to encode or decode the text.
1613 You can also explicitly encode and decode text using the functions
1616 The result of encoding, and the input to decoding, are not ordinary
1617 text. They logically consist of a series of byte values; that is, a
1618 series of @acronym{ASCII} and eight-bit characters. In unibyte
1619 buffers and strings, these characters have codes in the range 0
1620 through #xFF (255). In a multibyte buffer or string, eight-bit
1621 characters have character codes higher than #xFF (@pxref{Text
1622 Representations}), but Emacs transparently converts them to their
1623 single-byte values when you encode or decode such text.
1625 The usual way to read a file into a buffer as a sequence of bytes, so
1626 you can decode the contents explicitly, is with
1627 @code{insert-file-contents-literally} (@pxref{Reading from Files});
1628 alternatively, specify a non-@code{nil} @var{rawfile} argument when
1629 visiting a file with @code{find-file-noselect}. These methods result in
1632 The usual way to use the byte sequence that results from explicitly
1633 encoding text is to copy it to a file or process---for example, to write
1634 it with @code{write-region} (@pxref{Writing to Files}), and suppress
1635 encoding by binding @code{coding-system-for-write} to
1636 @code{no-conversion}.
1638 Here are the functions to perform explicit encoding or decoding. The
1639 encoding functions produce sequences of bytes; the decoding functions
1640 are meant to operate on sequences of bytes. All of these functions
1641 discard text properties. They also set @code{last-coding-system-used}
1642 to the precise coding system they used.
1644 @deffn Command encode-coding-region start end coding-system &optional destination
1645 This command encodes the text from @var{start} to @var{end} according
1646 to coding system @var{coding-system}. Normally, the encoded text
1647 replaces the original text in the buffer, but the optional argument
1648 @var{destination} can change that. If @var{destination} is a buffer,
1649 the encoded text is inserted in that buffer after point (point does
1650 not move); if it is @code{t}, the command returns the encoded text as
1651 a unibyte string without inserting it.
1653 If encoded text is inserted in some buffer, this command returns the
1654 length of the encoded text.
1656 The result of encoding is logically a sequence of bytes, but the
1657 buffer remains multibyte if it was multibyte before, and any 8-bit
1658 bytes are converted to their multibyte representation (@pxref{Text
1661 @cindex @code{undecided} coding-system, when encoding
1662 Do @emph{not} use @code{undecided} for @var{coding-system} when
1663 encoding text, since that may lead to unexpected results. Instead,
1664 use @code{select-safe-coding-system} (@pxref{User-Chosen Coding
1665 Systems, select-safe-coding-system}) to suggest a suitable encoding,
1666 if there's no obvious pertinent value for @var{coding-system}.
1669 @defun encode-coding-string string coding-system &optional nocopy buffer
1670 This function encodes the text in @var{string} according to coding
1671 system @var{coding-system}. It returns a new string containing the
1672 encoded text, except when @var{nocopy} is non-@code{nil}, in which
1673 case the function may return @var{string} itself if the encoding
1674 operation is trivial. The result of encoding is a unibyte string.
1677 @deffn Command decode-coding-region start end coding-system &optional destination
1678 This command decodes the text from @var{start} to @var{end} according
1679 to coding system @var{coding-system}. To make explicit decoding
1680 useful, the text before decoding ought to be a sequence of byte
1681 values, but both multibyte and unibyte buffers are acceptable (in the
1682 multibyte case, the raw byte values should be represented as eight-bit
1683 characters). Normally, the decoded text replaces the original text in
1684 the buffer, but the optional argument @var{destination} can change
1685 that. If @var{destination} is a buffer, the decoded text is inserted
1686 in that buffer after point (point does not move); if it is @code{t},
1687 the command returns the decoded text as a multibyte string without
1690 If decoded text is inserted in some buffer, this command returns the
1691 length of the decoded text.
1693 This command puts a @code{charset} text property on the decoded text.
1694 The value of the property states the character set used to decode the
1698 @defun decode-coding-string string coding-system &optional nocopy buffer
1699 This function decodes the text in @var{string} according to
1700 @var{coding-system}. It returns a new string containing the decoded
1701 text, except when @var{nocopy} is non-@code{nil}, in which case the
1702 function may return @var{string} itself if the decoding operation is
1703 trivial. To make explicit decoding useful, the contents of
1704 @var{string} ought to be a unibyte string with a sequence of byte
1705 values, but a multibyte string is also acceptable (assuming it
1706 contains 8-bit bytes in their multibyte form).
1708 If optional argument @var{buffer} specifies a buffer, the decoded text
1709 is inserted in that buffer after point (point does not move). In this
1710 case, the return value is the length of the decoded text.
1712 @cindex @code{charset}, text property
1713 This function puts a @code{charset} text property on the decoded text.
1714 The value of the property states the character set used to decode the
1719 (decode-coding-string "Gr\374ss Gott" 'latin-1)
1720 @result{} #("Gr@"uss Gott" 0 9 (charset iso-8859-1))
1725 @defun decode-coding-inserted-region from to filename &optional visit beg end replace
1726 This function decodes the text from @var{from} to @var{to} as if
1727 it were being read from file @var{filename} using @code{insert-file-contents}
1728 using the rest of the arguments provided.
1730 The normal way to use this function is after reading text from a file
1731 without decoding, if you decide you would rather have decoded it.
1732 Instead of deleting the text and reading it again, this time with
1733 decoding, you can call this function.
1736 @node Terminal I/O Encoding
1737 @subsection Terminal I/O Encoding
1739 Emacs can decode keyboard input using a coding system, and encode
1740 terminal output. This is useful for terminals that transmit or
1741 display text using a particular encoding such as Latin-1. Emacs does
1742 not set @code{last-coding-system-used} for encoding or decoding of
1745 @defun keyboard-coding-system &optional terminal
1746 This function returns the coding system that is in use for decoding
1747 keyboard input from @var{terminal}---or @code{nil} if no coding system
1748 is to be used for that terminal. If @var{terminal} is omitted or
1749 @code{nil}, it means the selected frame's terminal. @xref{Multiple
1753 @deffn Command set-keyboard-coding-system coding-system &optional terminal
1754 This command specifies @var{coding-system} as the coding system to use
1755 for decoding keyboard input from @var{terminal}. If
1756 @var{coding-system} is @code{nil}, that means do not decode keyboard
1757 input. If @var{terminal} is a frame, it means that frame's terminal;
1758 if it is @code{nil}, that means the currently selected frame's
1759 terminal. @xref{Multiple Terminals}.
1762 @defun terminal-coding-system &optional terminal
1763 This function returns the coding system that is in use for encoding
1764 terminal output from @var{terminal}---or @code{nil} if the output is
1765 not encoded. If @var{terminal} is a frame, it means that frame's
1766 terminal; if it is @code{nil}, that means the currently selected
1770 @deffn Command set-terminal-coding-system coding-system &optional terminal
1771 This command specifies @var{coding-system} as the coding system to use
1772 for encoding terminal output from @var{terminal}. If
1773 @var{coding-system} is @code{nil}, terminal output is not encoded. If
1774 @var{terminal} is a frame, it means that frame's terminal; if it is
1775 @code{nil}, that means the currently selected frame's terminal.
1778 @node MS-DOS File Types
1779 @subsection MS-DOS File Types
1780 @cindex DOS file types
1781 @cindex MS-DOS file types
1782 @cindex Windows file types
1783 @cindex file types on MS-DOS and Windows
1784 @cindex text files and binary files
1785 @cindex binary files and text files
1787 On MS-DOS and Microsoft Windows, Emacs guesses the appropriate
1788 end-of-line conversion for a file by looking at the file's name. This
1789 feature classifies files as @dfn{text files} and @dfn{binary files}. By
1790 ``binary file'' we mean a file of literal byte values that are not
1791 necessarily meant to be characters; Emacs does no end-of-line conversion
1792 and no character code conversion for them. On the other hand, the bytes
1793 in a text file are intended to represent characters; when you create a
1794 new file whose name implies that it is a text file, Emacs uses DOS
1795 end-of-line conversion.
1797 @defvar buffer-file-type
1798 This variable, automatically buffer-local in each buffer, records the
1799 file type of the buffer's visited file. When a buffer does not specify
1800 a coding system with @code{buffer-file-coding-system}, this variable is
1801 used to determine which coding system to use when writing the contents
1802 of the buffer. It should be @code{nil} for text, @code{t} for binary.
1803 If it is @code{t}, the coding system is @code{no-conversion}.
1804 Otherwise, @code{undecided-dos} is used.
1806 Normally this variable is set by visiting a file; it is set to
1807 @code{nil} if the file was visited without any actual conversion.
1809 Its default value is used to decide how to handle files for which
1810 @code{file-name-buffer-file-type-alist} says nothing about the type:
1811 If the default value is non-@code{nil}, then these files are treated as
1812 binary: the coding system @code{no-conversion} is used. Otherwise,
1813 nothing special is done for them---the coding system is deduced solely
1814 from the file contents, in the usual Emacs fashion.
1817 @defopt file-name-buffer-file-type-alist
1818 This variable holds an alist for recognizing text and binary files.
1819 Each element has the form (@var{regexp} . @var{type}), where
1820 @var{regexp} is matched against the file name, and @var{type} may be
1821 @code{nil} for text, @code{t} for binary, or a function to call to
1822 compute which. If it is a function, then it is called with a single
1823 argument (the file name) and should return @code{t} or @code{nil}.
1825 When running on MS-DOS or MS-Windows, Emacs checks this alist to decide
1826 which coding system to use when reading a file. For a text file,
1827 @code{undecided-dos} is used. For a binary file, @code{no-conversion}
1830 If no element in this alist matches a given file name, then
1831 the default value of @code{buffer-file-type} says how to treat the file.
1835 @section Input Methods
1836 @cindex input methods
1838 @dfn{Input methods} provide convenient ways of entering non-@acronym{ASCII}
1839 characters from the keyboard. Unlike coding systems, which translate
1840 non-@acronym{ASCII} characters to and from encodings meant to be read by
1841 programs, input methods provide human-friendly commands. (@xref{Input
1842 Methods,,, emacs, The GNU Emacs Manual}, for information on how users
1843 use input methods to enter text.) How to define input methods is not
1844 yet documented in this manual, but here we describe how to use them.
1846 Each input method has a name, which is currently a string;
1847 in the future, symbols may also be usable as input method names.
1849 @defvar current-input-method
1850 This variable holds the name of the input method now active in the
1851 current buffer. (It automatically becomes local in each buffer when set
1852 in any fashion.) It is @code{nil} if no input method is active in the
1856 @defopt default-input-method
1857 This variable holds the default input method for commands that choose an
1858 input method. Unlike @code{current-input-method}, this variable is
1862 @deffn Command set-input-method input-method
1863 This command activates input method @var{input-method} for the current
1864 buffer. It also sets @code{default-input-method} to @var{input-method}.
1865 If @var{input-method} is @code{nil}, this command deactivates any input
1866 method for the current buffer.
1869 @defun read-input-method-name prompt &optional default inhibit-null
1870 This function reads an input method name with the minibuffer, prompting
1871 with @var{prompt}. If @var{default} is non-@code{nil}, that is returned
1872 by default, if the user enters empty input. However, if
1873 @var{inhibit-null} is non-@code{nil}, empty input signals an error.
1875 The returned value is a string.
1878 @defvar input-method-alist
1879 This variable defines all the supported input methods.
1880 Each element defines one input method, and should have the form:
1883 (@var{input-method} @var{language-env} @var{activate-func}
1884 @var{title} @var{description} @var{args}...)
1887 Here @var{input-method} is the input method name, a string;
1888 @var{language-env} is another string, the name of the language
1889 environment this input method is recommended for. (That serves only for
1890 documentation purposes.)
1892 @var{activate-func} is a function to call to activate this method. The
1893 @var{args}, if any, are passed as arguments to @var{activate-func}. All
1894 told, the arguments to @var{activate-func} are @var{input-method} and
1897 @var{title} is a string to display in the mode line while this method is
1898 active. @var{description} is a string describing this method and what
1902 The fundamental interface to input methods is through the
1903 variable @code{input-method-function}. @xref{Reading One Event},
1904 and @ref{Invoking the Input Method}.
1910 POSIX defines a concept of ``locales'' which control which language
1911 to use in language-related features. These Emacs variables control
1912 how Emacs interacts with these features.
1914 @defvar locale-coding-system
1915 @cindex keyboard input decoding on X
1916 This variable specifies the coding system to use for decoding system
1917 error messages and---on X Window system only---keyboard input, for
1918 encoding the format argument to @code{format-time-string}, and for
1919 decoding the return value of @code{format-time-string}.
1922 @defvar system-messages-locale
1923 This variable specifies the locale to use for generating system error
1924 messages. Changing the locale can cause messages to come out in a
1925 different language or in a different orthography. If the variable is
1926 @code{nil}, the locale is specified by environment variables in the
1927 usual POSIX fashion.
1930 @defvar system-time-locale
1931 This variable specifies the locale to use for formatting time values.
1932 Changing the locale can cause messages to appear according to the
1933 conventions of a different language. If the variable is @code{nil}, the
1934 locale is specified by environment variables in the usual POSIX fashion.
1937 @defun locale-info item
1938 This function returns locale data @var{item} for the current POSIX
1939 locale, if available. @var{item} should be one of these symbols:
1943 Return the character set as a string (locale item @code{CODESET}).
1946 Return a 7-element vector of day names (locale items
1947 @code{DAY_1} through @code{DAY_7});
1950 Return a 12-element vector of month names (locale items @code{MON_1}
1951 through @code{MON_12}).
1954 Return a list @code{(@var{width} @var{height})} for the default paper
1955 size measured in millimeters (locale items @code{PAPER_WIDTH} and
1956 @code{PAPER_HEIGHT}).
1959 If the system can't provide the requested information, or if
1960 @var{item} is not one of those symbols, the value is @code{nil}. All
1961 strings in the return value are decoded using
1962 @code{locale-coding-system}. @xref{Locales,,, libc, The GNU Libc Manual},
1963 for more information about locales and locale items.