Debian Codegraph @

upstream/debian-unstable/man3/Encode::MIME::Header.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Encode::MIME::Header 3perl"
58 .TH Encode::MIME::Header 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Encode::MIME::Header \-\- MIME encoding for an unstructured email header
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use Encode qw(encode decode);
69 \&
70 \& my $mime_str = encode("MIME\-Header", "Sample:Text \eN{U+263A}");
71 \& # $mime_str is "=?UTF\-8?B?U2FtcGxlOlRleHQg4pi6?="
72 \&
73 \& my $mime_q_str = encode("MIME\-Q", "Sample:Text \eN{U+263A}");
74 \& # $mime_q_str is "=?UTF\-8?Q?Sample=3AText_=E2=98=BA?="
75 \&
76 \& my $str = decode("MIME\-Header",
77 \& "=?ISO\-8859\-1?B?SWYgeW91IGNhbiByZWFkIHRoaXMgeW8=?=\er\en " .
78 \& "=?ISO\-8859\-2?B?dSB1bmRlcnN0YW5kIHRoZSBleGFtcGxlLg==?="
79 \& );
80 \& # $str is "If you can read this you understand the example."
81 \&
82 \& use Encode qw(decode :fallbacks);
83 \& use Encode::MIME::Header;
84 \& local $Encode::MIME::Header::STRICT_DECODE = 1;
85 \& my $strict_string = decode("MIME\-Header", $mime_string, FB_CROAK);
86 \& # use strict decoding and croak on errors
87 .Ve
88 .SH ABSTRACT
89 .IX Header "ABSTRACT"
90 This module implements RFC 2047 <https://tools.ietf.org/html/rfc2047> MIME
91 encoding for an unstructured field body of the email header. It can also be
92 used for RFC 822 <https://tools.ietf.org/html/rfc822> 'text' token. However,
93 it cannot be used directly for the whole header with the field name or for the
94 structured header fields like From, To, Cc, Message-Id, etc... There are 3
95 encoding names supported by this module: \f(CW\*(C`MIME\-Header\*(C'\fR, \f(CW\*(C`MIME\-B\*(C'\fR and
96 \&\f(CW\*(C`MIME\-Q\*(C'\fR.
97 .SH DESCRIPTION
98 .IX Header "DESCRIPTION"
99 Decode method takes an unstructured field body of the email header (or
100 RFC 822 <https://tools.ietf.org/html/rfc822> 'text' token) as its input and
101 decodes each MIME encoded-word from input string to a sequence of bytes
102 according to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
103 RFC 2231 <https://tools.ietf.org/html/rfc2231>. Subsequently, each sequence
104 of bytes with the corresponding MIME charset is decoded with
105 the Encode module and finally, one output string is returned. Text
106 parts of the input string which do not contain MIME encoded-word stay
107 unmodified in the output string. Folded newlines between two consecutive MIME
108 encoded-words are discarded, others are preserved in the output string.
109 \&\f(CW\*(C`MIME\-B\*(C'\fR can decode Base64 variant, \f(CW\*(C`MIME\-Q\*(C'\fR can decode Quoted-Printable
110 variant and \f(CW\*(C`MIME\-Header\*(C'\fR can decode both of them. If Encode module
111 does not support particular MIME charset or chosen variant then an action based
112 on CHECK flags is performed (by default, the
113 MIME encoded-word is not decoded).
114 .PP
115 Encode method takes a scalar string as its input and uses
116 strict UTF\-8 encoder for encoding it to UTF\-8
117 bytes. Then a sequence of UTF\-8 bytes is encoded into MIME encoded-words
118 (\f(CW\*(C`MIME\-Header\*(C'\fR and \f(CW\*(C`MIME\-B\*(C'\fR use a Base64 variant while \f(CW\*(C`MIME\-Q\*(C'\fR uses a
119 Quoted-Printable variant) where each MIME encoded-word is limited to 75
120 characters. MIME encoded-words are separated by \f(CW\*(C`CRLF SPACE\*(C'\fR and joined to
121 one output string. Output string is suitable for unstructured field body of
122 the email header.
123 .PP
124 Both encode and decode methods propagate
125 CHECK flags when encoding and decoding the
126 MIME charset.
127 .SH BUGS
128 .IX Header "BUGS"
129 Versions prior to 2.22 (part of Encode 2.83) have a malfunctioning decoder
130 and encoder. The MIME encoder infamously inserted additional spaces or
131 discarded white spaces between consecutive MIME encoded-words, which led to
132 invalid MIME headers produced by this module. The MIME decoder had a tendency
133 to discard white spaces, incorrectly interpret data or attempt to decode Base64
134 MIME encoded-words as Quoted-Printable. These problems were fixed in version
135 2.22. It is highly recommended not to use any version prior 2.22!
136 .PP
137 Versions prior to 2.24 (part of Encode 2.87) ignored
138 CHECK flags. The MIME encoder used
139 not strict utf8 encoder for input Unicode
140 strings which could lead to invalid UTF\-8 sequences. MIME decoder used also
141 not strict utf8 decoder and additionally
142 called the decode method with a \f(CW\*(C`Encode::FB_PERLQQ\*(C'\fR flag (thus user-specified
143 CHECK flags were ignored). Moreover, it
144 automatically croaked when a MIME encoded-word contained unknown encoding.
145 Since version 2.24, this module uses
146 strict UTF\-8 encoder and decoder. And
147 CHECK flags are correctly propagated.
148 .PP
149 Since version 2.22 (part of Encode 2.83), the MIME encoder should be fully
150 compliant to RFC 2047 <https://tools.ietf.org/html/rfc2047> and
151 RFC 2231 <https://tools.ietf.org/html/rfc2231>. Due to the aforementioned
152 bugs in previous versions of the MIME encoder, there is a \fIless strict\fR
153 compatible mode for the MIME decoder which is used by default. It should be
154 able to decode MIME encoded-words encoded by pre 2.22 versions of this module.
155 However, note that this is not correct according to
156 RFC 2047 <https://tools.ietf.org/html/rfc2047>.
157 .PP
158 In default \fInot strict\fR mode the MIME decoder attempts to decode every substring
159 which looks like a MIME encoded-word. Therefore, the MIME encoded-words do not
160 need to be separated by white space. To enforce a correct \fIstrict\fR mode, set
161 variable \f(CW$Encode::MIME::Header::STRICT_DECODE\fR to 1 e.g. by localizing:
162 .PP
163 .Vb 2
164 \& use Encode::MIME::Header;
165 \& local $Encode::MIME::Header::STRICT_DECODE = 1;
166 .Ve
167 .SH AUTHORS
168 .IX Header "AUTHORS"
169 Pali <[email protected]>
170 .SH "SEE ALSO"
171 .IX Header "SEE ALSO"
172 Encode,
173 RFC 822 <https://tools.ietf.org/html/rfc822>,
174 RFC 2047 <https://tools.ietf.org/html/rfc2047>,
175 RFC 2231 <https://tools.ietf.org/html/rfc2231>