Debian Codegraph @

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