# man > Encode

---
type: CommandReference
command: Encode
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference
- `$characters = decode('UTF-8', $octets, Encode::FB_CROAK)` — decode octets to Perl characters, die on malformed data
- `$octets = encode('UTF-8', $characters, Encode::FB_DEFAULT)` — encode characters to octets with substitution of bad chars
- `$enc = find_encoding('shiftjis'); $string = $enc->decode($bytes)` — reuse encoding object for repeated decoding
- `from_to($data, 'iso-8859-1', 'utf-8')` — convert octets between two encodings in-place
- `$octets = encode_utf8($string)` — quick, loose UTF-8 encoding (use `encode("UTF-8", ...)` for strict)
- `$string = decode_utf8($octets, Encode::FB_QUIET)` — loose UTF-8 decoding, returns partial on incomplete bytes
- `open my $fh, '<:encoding(UTF-8)', $file` — enable PerlIO layer for automatic decoding
- `Encode::resolve_alias('latin1')` — get the canonical encoding name (e.g. "iso-8859-1")

## Name
Encode - character encodings in Perl

## Synopsis
perl
use Encode qw(decode encode);
$characters = decode('UTF-8', $octets,     Encode::FB_CROAK);
$octets     = encode('UTF-8', $characters, Encode::FB_CROAK);
## Functions

### Core Functions
- `decode(ENCODING, OCTETS[, CHECK])` — decode a byte sequence from the named encoding into a Perl character string. Input `OCTETS` may be modified in-place unless `CHECK` includes `LEAVE_SRC`. Returns the decoded string or `undef` if the input is `undef`.
- `encode(ENCODING, STRING[, CHECK])` — encode a Perl string into a byte sequence. The result always has the UTF8 flag off. Input `STRING` may be modified in-place (same caveat). Returns `undef` for `undef` input.
- `find_encoding(ENCODING)` — returns the encoding object for the given name or `undef`. The object provides `decode()`, `encode()`, `name()` (canonical name), `mime_name()`, and other methods.
- `find_mime_encoding(MIME_ENCODING)` — like `find_encoding()` but only matches by MIME name (case‑insensitive), e.g. "utf-8". Ignores canonical names and aliases.
- `from_to(OCTETS, FROM_ENC, TO_ENC[, CHECK])` — convert data in-place between two encodings. The input must be octets (not a Perl character string). Returns the new length in octets on success, `undef` on error. The `CHECK` argument applies only during the final `encode` step; for full control use separate `decode`/`encode` calls.
- `encode_utf8(STRING)` — equivalent to `encode("utf8", $string)`. Uses Perl’s loose UTF-8 encoding; never fails because all Perl characters have a loose representation. **Do not use for data exchange**.
- `decode_utf8(OCTETS[, CHECK])` — equivalent to `decode("utf8", $octets, CHECK)`. Loose UTF-8 decoding; can fail for invalid sequences. **Not for data exchange**.
- `encodings([FILTER])` — class method returning a list of canonical names. No argument: already‑loaded encodings. `":all"`: all available. Module name (e.g. `"Encode::JP"`): encodings from that module. If the name lacks `"::"`, `"Encode::"` is prepended.
- `define_alias(NEWNAME, ENCODING)` — registers an alias. `resolve_alias(NAME)` returns the canonical name or false.
- `define_encoding(OBJECT, CANONICAL_NAME, aliases...)` — links an encoding object to a canonical name and optional aliases.
- `perlio_ok(ENCODING)` — returns true if the encoding supports PerlIO layers.

### Check Values (Malformed Data)
Check values control how malformed or unmappable characters are handled. Import constants with `use Encode qw(:fallbacks)`.

- `Encode::FB_DEFAULT` (0) — substitute with the encoding’s substitution character (encode) or U+FFFD (decode). UTF‑8 warnings may be emitted.
- `Encode::FB_CROAK` (1) — die with an error message.
- `Encode::FB_QUIET` — return processed data immediately; the input scalar is truncated to the remaining unprocessed portion. Useful for streaming.
- `Encode::FB_WARN` — like `FB_QUIET` but also issues a warning.
- `Encode::FB_PERLQQ` — fallback to Perl escape sequences: `\xHH` on decode, `\x{HHHH}` on encode.
- `Encode::FB_HTMLCREF` — fallback to decimal HTML entities `&#NNN;`.
- `Encode::FB_XMLCREF` — fallback to hex XML entities `&#xHHHH;`.
- `Encode::LEAVE_SRC` — bitmask to prevent the source string from being overwritten in-place.
- `ENCODE::ONLY_PRAGMA_WARNINGS` — (since 2.99) make warnings respect lexical warning settings; bitwise‑OR with another check value.

A code reference can also be used as `CHECK`:
perl
$ascii = encode("ascii", $utf8, sub{ sprintf "<U+%04X>", shift });
The subroutine receives the ordinal value (encode) or a list of ordinals (decode) and must return the fallback octets (encode) or character string (decode).

## Examples

### PerlIO Layer
perl
open(INPUT,  "< :encoding(shiftjis)", $infile)  or die $!;
open(OUTPUT, "> :encoding(euc-jp)",    $outfile) or die $!;
while (<INPUT>) {
    print OUTPUT;   # auto-decodes, then auto-encodes
}
close(INPUT); close(OUTPUT);
### In‑place Conversion
perl
open(INPUT,  "< :raw", $infile)  or die $!;
open(OUTPUT, "> :raw", $outfile) or die $!;
while (<INPUT>) {
    from_to($_, "shiftjis", "euc-jp", 1);
    print OUTPUT;
}
close(INPUT); close(OUTPUT);
### Streaming with Partial Characters
perl
my($buffer, $string) = ("", "");
while (read($fh, $buffer, 256, length($buffer))) {
    $string .= decode($encoding, $buffer, Encode::FB_QUIET);
    # $buffer now holds the unprocessed partial character
}
### Coderef Fallback for Decoding
perl
$str = decode 'UTF-8', $octets, sub {
    my $tmp = join '', map chr, @_;
    return decode 'ISO-8859-15', $tmp;
};
## See Also
- [Encode::Encoding](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3AEncoding/markdown) – encoding object base class
- [Encode::Supported](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3ASupported/markdown) – list of supported encodings
- [Encode::PerlIO](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3APerlIO/markdown) – PerlIO integration
- [Encode::Alias](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3AAlias/markdown) – alias definitions
- [Encode::CN](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3ACN/markdown), [Encode::JP](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3AJP/markdown), [Encode::KR](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3AKR/markdown), [Encode::TW](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3ATW/markdown) – Asian encodings
- [Encode::Unicode](https://www.chedong.com/phpMan.php/perldoc/Encode%3A%3AUnicode/markdown) – Unicode-specific support
- [utf8](https://www.chedong.com/phpMan.php/perldoc/utf8/markdown) – Perl’s internal UTF-8 flag
- [perlunitut](https://www.chedong.com/phpMan.php/perldoc/perlunitut/markdown), [perlunifaq](https://www.chedong.com/phpMan.php/perldoc/perlunifaq/markdown), [perluniintro](https://www.chedong.com/phpMan.php/perldoc/perluniintro/markdown), [perlunicode](https://www.chedong.com/phpMan.php/perldoc/perlunicode/markdown) – Unicode tutorials and reference
- [perlebcdic](https://www.chedong.com/phpMan.php/perldoc/perlebcdic/markdown) – EBCDIC considerations
- Perl Unicode Mailing List: [http://lists.perl.org/list/perl-unicode.html](http://lists.perl.org/list/perl-unicode.html)