are following:

-c, --auto-convert

Equivalent to calling Enca as enconv. If no output type selector is specified, detect file encodings, guess your preferred charset from locales, and convert files to it (only available with +target-charset-auto feature).

-g, --guess

Equivalent to calling Enca as enca. If no output type selector is specified, detect file encodings and report them.

select what action Enca will take when it determines the encoding; most of them just choose between different names, formats and conventions how encodings can be printed, but one of them (-x) is special: it tells Enca to recode files to some other encoding ENC. These options are mutually exclusive; if you specify more than one output type selector the last one takes precedence. Several output types represent charset name used by some other program, but not all these programs know all the charsets which Enca recognises. Be warned, Enca makes no difference between unrecognised charset and charset having no name in given namespace in such situations.

-d, --details

It used to print a few pages of details about the guessing process, but since Enca is just a program linked against Enca library, this is not possible and this option is roughly equivalent to --human-readable, except it reports failure reason when Enca doesn't recoginize the encoding.

-e, --enca-name

Prints Enca's nice name of the charset, i.e., perhaps the most generally accepted and more or less human-readable charset identifier, with surfaces appended. This name is used when calling an external convertor, too.

-f, --human-readable

Prints verbal description of the detected charset and surfaces--something a human understands best. This is the default behaviour. The precise format is following: the first line contains charset name alone, and it's followed by zero or more indented lines containing names of detected surfaces. This format is not, however, suitable or intended for further machine-processing, and the verbal charset descriptions are like to change in the future.

-i, --iconv-name

Prints how iconv(3) (and/or iconv(1)) calls the detected charset. More precisely, it prints one, more or less arbitrarily chosen, alias accepted by iconv. A charset unknown to iconv counts as unknown. This output type makes sense only when Enca is compiled with iconv support (feature +iconv-interface).

-r, --rfc1345-name

Prints RFC~1345 charset name. When such a name doesn't exist because RFC~1345 doesn't define given encoding, some other name defined in some other RFC or just the name which author consideres `the most canonical', is printed. Since RFC~1345 doesn't define surfaces, no surface info is appended.

-m, --mime-name

Prints preferred MIME name of detected charset. This is the name you should normally use when fixing e-mails or web pages. A charset not present in http://www.iana.org/assignments/character-sets counts as unknown.

-s, --cstocs-name

Prints how cstocs(1) calls the detected charset. A charset unknown to cstocs counts as unknown.

-n, --name=WORD

Prints charset (encoding) name selected by WORD (can be abbreviated as long as is unambiguous). For names listed above, --name=WORD is equivalent to --WORD. Using aliases as the output type causes Enca to print list of all accepted aliases of detected charset.

-x, --convert-to=[..]ENC

Converts file to encoding ENC. The optional `..' before encoding name has no special meaning, except you can use it to remind yourself that, unlike in recode(1), you should specify desired encoding, instead of current. You can use recode(1) recoding chains or any other kind of braindead recoding specification for ENC, provided that you tell Enca to use some tool understanding it for conversion (see section CONVERSION). When Enca fails to determine the encoding, it prints a warning and leaves the the file as is; when it is run as a filter it tries to do its best to copy standard input to standard output unchanged. Nevertheless, you should not rely on it and do backup.

There's only one: -L setting language of input files. This option is mandatory (but see below).

-L, --language=LANG

Sets language of input files to LANG. More precisely, LANG can be any valid locale name (or alias with +locale-alias feature) of some supported language. You can also specify `none' as language name, only multibyte encodings are recognised then. Run enca --list languages to get list of supported languages. When you don't specify any language Enca tries to guess your language from locale settings and assumes input files use this language. See section LANGUAGES for details.

give you finer control of how charset conversion will be performed. They don't affect anything when -x is not specified as output type. Please see section CONVERSION for the gory conversion details.

-C, --try-convertors=LIST

Appends comma separated LIST to the list of convertors that will be tried when you ask for conversion. Their names can be abbreviated as long as they are unambiguous. Run enca --list convertors to get list of all valid convertor names (and see section CONVERSION for their description). The default list depends on how Enca has been compiled, run enca --help to find out default convertor list. Note the default list is used only when you don't specify -C at all. Otherwise, the list is built as if it were initially empty and every -C adds new convertor(s) to it. Moreover, specifying none as convertor name causes clearing the convertor list.

-E, --external-convertor-program=PATH

Sets external convertor program name to PATH. Default external convertor depends on how enca has been complied, and the possibility to use external convertors may not be available at all. Run enca --help to find out default convertor program in your enca build.

don't fit to other option categories...

-p, --with-filename

Forces Enca to prefix each result with corresponding file name. By default, Enca prefixes results with filenames when run on multiple files. Standard input is printed as STDIN and standard output as STDOUT (the latter can be probably seen in error messages only).

-P, --no-filename

Forces Enca to not prefix results with file names. By default, Enca doesn't prefix result with file name when run on a single file (including standard input).

-V, --verbose

Increases verbosity level (each use increases it by one). Currently this option in not very useful because different parts of Enca respond differently to the same verbosity level, mostly not at all.

are all terminal, i.e. when Enca encounters some of them it prints the required listing and terminates without processing any following options.

-h, --help

Prints brief usage help.

-G, --license

Prints full Enca license (through a pager, if possible).

-l, --list=WORD

Prints list specified by WORD (can be abbreviated as long as it is unambiguous). Available lists include: built-in-charsets. All encodings convertible by built-in convertor, by group (both input and output encoding must be from this list and belong to the same group for internal conversion). built-in-encodings. Equivalent to built-in-charsets, but considered obsolete; will be accepted with a warning, for a while. convertors. All valid convertor names (to be used with -C). charsets. All encodings (charsets). You can select what names will be printed with --name or any name output type selector (of course, only encodings having a name in given namespace will be printed then), the selector must be specified before --list. encodings. Equivalent to charsets, but considered obsolete; will be accepted with a warning, for a while. languages. All supported languages together with charsets belonging to them. Note output type selects language name style, not charset name style here. names. All possible values of --name option. lists. All possible values of this option. (Crazy?) surfaces. All surfaces Enca recognises.

-v, --version

Prints program version and list of features (see section FEATURES).

is the simplest and far the fastest of all, can perform only a few byte-to-byte conversions and modifies files directly in place (may be considered dangerous, but is pretty efficient). You can get list of all encodings it can convert with Beside speed, its main advantage (and also disadvantage) is that it doesn't care: it simply converts characters having a representation in target encoding, doesn't touch anything else and never prints any error message. This convertor can be specified as built-in with -C.

is an interface to GNU recode library, that does the actual recoding job. It may or may not be compiled in; run to find out its availability in your enca build (feature +librecode-interface). You should be familiar with recode(1) before using it, since recode is a quite sophisticated and powerful charset conversion tool. You may run into problems using it together with Enca particularly because Enca's support for surfaces not 100% compatible, because recode tries too hard to make the transformation reversible, because it sometimes silently ignores I/O errors, and because it's incredibily buggy. Please see GNU recode info pages for details about recode library. This convertor can be specified as librecode with -C.

is an interface to the UNIX98 iconv(3) conversion functions, that do the actual recoding job. It may or may not be compiled in; run to find out its availability in your enca build (feature +iconv-interface). While iconv is present on most today systems it only rarely offer some useful set of available conversions, the only notable exception being iconv from GNU libc. It is usually quite picky about surfaces, too (while, at the same time, not implementing surface conversion). It however probably represents the only standard(ized) tool able to perform conversion from/to Unicode. Please see iconv documentation about for details about its capabilities on your particular system. This convertor can be specified as iconv with -C.

is an arbitrary external conversion tool that can be specified with -E option (at most one can be defined simultaneously). There are some standard, provided together with enca: cstocs, recode, map, umap, and piconv. All are wrapper scripts: for cstocs(1), recode(1), map(1), umap(1), and piconv(1). Please note enca has little control what the external convertor really does. If you set it to /bin/rm you are fully responsible for the consequences. If you want to make your own convertor to use with enca, you should know it is always called where CONVERTOR is what has been set by -E, ENC_CURRENT is detected encoding, ENC is what has been specified with -x, and FILE is the file to convert, i.e. it is called for each file separately. The optional fourth parameter, -, should cause (when present) sending result of conversion to standard output instead of overwriting the file FILE. The convertor should also take care of not changing file permissions, returning error code~1 when it fails and cleaning its temporary files. Please see the standard external convertors for examples. This convertor can be specified as extern with -C.

The starightforward way of specifying target charset is the -x option, which overrides any defaults. When Enca is called as enconv, default target charset is selected exactly the same way as recode(1) does it.

If the DEFAULT_CHARSET environment variable is set, it's used as the target charset.

Otherwise, if you system provides the nl_langinfo(3) function, current locale's native charset is used as the target charset.

When both methods fail, Enca complains and terminates.

If reversibility is crucial for you, you shouldn't use enca as convertor at all (or maybe you can, with very specifically designed recode(1) wrapper). Otherwise you should at least know that there four basic means of handling inconvertible character entities: fail--this is a possibility, too, and incidentally it's exactly what current GNU libc iconv implementation does (recode can be also told to do it) don't touch them--this is what enca internal convertor always does and recode can do; though it is not reversible, a human being is usually able to reconstruct the original (at least in principle) approximate them--this is what cstocs can do, and recode too, though differently; and the best choice if you just want to make the accursed text readable drop them out--this is what both recode and cstocs can do (cstocs can also replace these characters by some fixed character instead of mere ignoring); useful when the to-be-omitted characters contain only noise. Please consult your favourite convertor manual for details of this issue. Generally, if you are not lucky enough to have all convertible characters in you file, manual intervention is needed anyway.

Poor performance of available convertors has been one of main reasons for including built-in convertor in enca. Try to use it whenever possible, i.e. when files in consideration are charset-clean enough or charset-messy enough so that its zero built-in intelligence doesn't matter. It requires no extra disk space nor extra memory and can outperform recode(1) more than 10 times on large files and Perl version (i.e. the faster one) of cstocs(1) more than 400 times on small files (in fact it's almost as fast as mere cp(1)).

Try to avoid external convertors when it's not absolutely necessary since all the forking and moving stuff around is incredibily slow.

Following list of recognised charsets uses Enca's names (-e) and verbal descriptions as reported by Enca (-f):

tab (@); l l. ASCII@7bit ASCII characters ISO-8859-2@ISO 8859-2 standard; ISO Latin 2 ISO-8859-4@ISO 8859-4 standard; Latin 4 ISO-8859-5@ISO 8859-5 standard; ISO Cyrillic ISO-8859-13@ISO 8859-13 standard; ISO Baltic; Latin 7 ISO-8859-16@ISO 8859-16 standard CP1125@MS-Windows code page 1125 CP1250@MS-Windows code page 1250 CP1251@MS-Windows code page 1251 CP1257@MS-Windows code page 1257; WinBaltRim IBM852@IBM/MS code page 852; PC (DOS) Latin 2 IBM855@IBM/MS code page 855 IBM775@IBM/MS code page 775 IBM866@IBM/MS code page 866 baltic@ISO-IR-179; Baltic KEYBCS2@Kamenicky encoding; KEYBCS2 macce@Macintosh Central European maccyr@Macintosh Cyrillic ECMA-113@Ecma Cyrillic; ECMA-113 KOI-8_CS_2@KOI8-CS2 code (`T602') KOI8-R@KOI8-R Cyrillic KOI8-U@KOI8-U Cyrillic KOI8-UNI@KOI8-Unified Cyrillic TeX@(La)TeX control sequences UCS-2@Universal character set 2 bytes; UCS-2; BMP UCS-4@Universal character set 4 bytes; UCS-4; ISO-10646 UTF-7@Universal transformation format 7 bits; UTF-7 UTF-8@Universal transformation format 8 bits; UTF-8 CORK@Cork encoding; T1 GBK@Simplified Chinese National Standard; GB2312 BIG5@Traditional Chinese Industrial Standard; Big5 HZ@HZ encoded GB2312 unknown@Unrecognized encoding

where unknown is not any real encoding, it's reported when Enca is not able to give a reliable answer.

Enca has some experimental support for so-called surfaces (see below). It detects following surfaces (not all can be applied to all charsets):

tab (@); l l. /CR@CR line terminators /LF@LF line terminators /CRLF@CRLF line terminators N.A.@Mixed line terminators N.A.@Surrounded by/intermixed with non-text data /21@Byte order reversed in pairs (1,2 -> 2,1) /4321@Byte order reversed in quadruples (1,2,3,4 -> 4,3,2,1) N.A.@Both little and big endian chunks, concatenated /qp@Quoted-printable encoded

Note some surfaces have N.A. in place of identifier--they cannot be specified on command line, they can only be reported by Enca. This is intentional because they only inform you why the file cannot be considered surface-consistent instead of representing a real surface.

Each charset has its natural surface (called `implied' in recode) which is not reported, e.g., for IBM 852 charset it's `CRLF line terminators'. For UCS encodings, big endian is considered as natural surface; unusual byte orders are constructed from 21 and 4321 permutations: 2143 is reported simply as 21, while 3412 is reported as combination of 4321 and 21.

Doubly-encoded UTF-8 is neither charset nor surface, it's just reported.

Charset is a set of character entities while encoding is its representation in the terms of bytes and bits. In Enca, the word encoding means the same as `representation of text', i.e. the relation between sequence of character entities constituting the text and sequence of bytes (bits) constituting the file.

So, encoding is both character set and so-called surface (line terminators, byte order, combining, Base64 transformation, etc.). Nevertheless, it proves convenient to work with some {charset,surface} pairs as with genuine charsets. So, as in recode(1), all UCS- and UTF- encodings of Universal character set are called charsets. Please see recode documentation for more details of this issue.

The only good thing about surfaces is: when you don't start playing with them, neither Enca won't start and it will try to behave as much as possible as a surface-unaware program, even when talking to recode.