Debian Codegraph @

upstream/mageia-cauldron/man3pm/MIME::Base64.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "MIME::Base64 3pm"
61 .TH MIME::Base64 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 MIME::Base64 \- Encoding and decoding of base64 strings
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use MIME::Base64;
72 \&
73 \& $encoded = encode_base64(\*(AqAladdin:open sesame\*(Aq);
74 \& $decoded = decode_base64($encoded);
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 This module provides functions to encode and decode strings into and from the
79 base64 encoding specified in RFC 2045 \- \fIMIME (Multipurpose Internet
80 Mail Extensions)\fR. The base64 encoding is designed to represent
81 arbitrary sequences of octets in a form that need not be humanly
82 readable. A 65\-character subset ([A\-Za\-z0\-9+/=]) of US\-ASCII is used,
83 enabling 6 bits to be represented per printable character.
84 .PP
85 The following primary functions are provided:
86 .ie n .IP "encode_base64( $bytes )" 4
87 .el .IP "encode_base64( \f(CW$bytes\fR )" 4
88 .IX Item "encode_base64( $bytes )"
89 .PD 0
90 .ie n .IP "encode_base64( $bytes, $eol );" 4
91 .el .IP "encode_base64( \f(CW$bytes\fR, \f(CW$eol\fR );" 4
92 .IX Item "encode_base64( $bytes, $eol );"
93 .PD
94 Encode data by calling the \fBencode_base64()\fR function. The first
95 argument is the byte string to encode. The second argument is the
96 line\-ending sequence to use. It is optional and defaults to "\en". The
97 returned encoded string is broken into lines of no more than 76
98 characters each and it will end with \f(CW$eol\fR unless it is empty. Pass an
99 empty string as second argument if you do not want the encoded string
100 to be broken into lines.
101 .Sp
102 The function will croak with "Wide character in subroutine entry" if \f(CW$bytes\fR
103 contains characters with code above 255. The base64 encoding is only defined
104 for single\-byte characters. Use the Encode module to select the byte encoding
105 you want.
106 .ie n .IP "decode_base64( $str )" 4
107 .el .IP "decode_base64( \f(CW$str\fR )" 4
108 .IX Item "decode_base64( $str )"
109 Decode a base64 string by calling the \fBdecode_base64()\fR function. This
110 function takes a single argument which is the string to decode and
111 returns the decoded data.
112 .Sp
113 Any character not part of the 65\-character base64 subset is
114 silently ignored. Characters occurring after a \*(Aq=\*(Aq padding character
115 are never decoded.
116 .PP
117 If you prefer not to import these routines into your namespace, you can
118 call them as:
119 .PP
120 .Vb 3
121 \& use MIME::Base64 ();
122 \& $encoded = MIME::Base64::encode($decoded);
123 \& $decoded = MIME::Base64::decode($encoded);
124 .Ve
125 .PP
126 Additional functions not exported by default:
127 .ie n .IP "encode_base64url( $bytes )" 4
128 .el .IP "encode_base64url( \f(CW$bytes\fR )" 4
129 .IX Item "encode_base64url( $bytes )"
130 .PD 0
131 .ie n .IP "decode_base64url( $str )" 4
132 .el .IP "decode_base64url( \f(CW$str\fR )" 4
133 .IX Item "decode_base64url( $str )"
134 .PD
135 Encode and decode according to the base64 scheme for "URL applications" [1].
136 This is a variant of the base64 encoding which does not use padding, does not
137 break the string into multiple lines and use the characters "\-" and "_" instead
138 of "+" and "/" to avoid using reserved URL characters.
139 .ie n .IP "encoded_base64_length( $bytes )" 4
140 .el .IP "encoded_base64_length( \f(CW$bytes\fR )" 4
141 .IX Item "encoded_base64_length( $bytes )"
142 .PD 0
143 .ie n .IP "encoded_base64_length( $bytes, $eol )" 4
144 .el .IP "encoded_base64_length( \f(CW$bytes\fR, \f(CW$eol\fR )" 4
145 .IX Item "encoded_base64_length( $bytes, $eol )"
146 .PD
147 Returns the length that the encoded string would have without actually
148 encoding it. This will return the same value as \f(CW\*(C`length(encode_base64($bytes))\*(C'\fR,
149 but should be more efficient.
150 .ie n .IP "decoded_base64_length( $str )" 4
151 .el .IP "decoded_base64_length( \f(CW$str\fR )" 4
152 .IX Item "decoded_base64_length( $str )"
153 Returns the length that the decoded string would have without actually
154 decoding it. This will return the same value as \f(CW\*(C`length(decode_base64($str))\*(C'\fR,
155 but should be more efficient.
156 .SH EXAMPLES
157 .IX Header "EXAMPLES"
158 If you want to encode a large file, you should encode it in chunks
159 that are a multiple of 57 bytes. This ensures that the base64 lines
160 line up and that you do not end up with padding in the middle. 57
161 bytes of data fills one complete base64 line (76 == 57*4/3):
162 .PP
163 .Vb 1
164 \& use MIME::Base64 qw(encode_base64);
165 \&
166 \& open(FILE, "/var/log/wtmp") or die "$!";
167 \& while (read(FILE, $buf, 60*57)) {
168 \& print encode_base64($buf);
169 \& }
170 .Ve
171 .PP
172 or if you know you have enough memory
173 .PP
174 .Vb 3
175 \& use MIME::Base64 qw(encode_base64);
176 \& local($/) = undef; # slurp
177 \& print encode_base64(<STDIN>);
178 .Ve
179 .PP
180 The same approach as a command line:
181 .PP
182 .Vb 1
183 \& perl \-MMIME::Base64 \-0777 \-ne \*(Aqprint encode_base64($_)\*(Aq <file
184 .Ve
185 .PP
186 Decoding does not need slurp mode if every line contains a multiple
187 of four base64 chars:
188 .PP
189 .Vb 1
190 \& perl \-MMIME::Base64 \-ne \*(Aqprint decode_base64($_)\*(Aq <file
191 .Ve
192 .PP
193 Perl v5.8 and better allow extended Unicode characters in strings.
194 Such strings cannot be encoded directly, as the base64
195 encoding is only defined for single\-byte characters. The solution is
196 to use the Encode module to select the byte encoding you want. For
197 example:
198 .PP
199 .Vb 2
200 \& use MIME::Base64 qw(encode_base64);
201 \& use Encode qw(encode);
202 \&
203 \& $encoded = encode_base64(encode("UTF\-8", "\ex{FFFF}\en"));
204 \& print $encoded;
205 .Ve
206 .SH COPYRIGHT
207 .IX Header "COPYRIGHT"
208 Copyright 1995\-1999, 2001\-2004, 2010 Gisle Aas.
209 .PP
210 This library is free software; you can redistribute it and/or
211 modify it under the same terms as Perl itself.
212 .PP
213 Distantly based on LWP::Base64 written by Martijn Koster
214 <[email protected]> and Joerg Reichelt <[email protected]> and
215 code posted to comp.lang.perl <[email protected]> by Hans
216 Mulder <[email protected]>
217 .PP
218 The XS implementation uses code from metamail. Copyright 1991 Bell
219 Communications Research, Inc. (Bellcore)
220 .SH "SEE ALSO"
221 .IX Header "SEE ALSO"
222 MIME::QuotedPrint
223 .PP
224 [1] <http://en.wikipedia.org/wiki/Base64#URL_applications>