This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Version bumps for z/OS fixes.
[perl5.git] / ext / MIME / Base64 / Base64.pm
CommitLineData
6fba102d
JH
1package MIME::Base64;
2
4e2e3d15 3# $Id: Base64.pm,v 3.11 2005/11/29 20:59:55 gisle Exp $
0a362e9d
RGS
4
5use strict;
6use vars qw(@ISA @EXPORT $VERSION);
7
8require Exporter;
e1839706 9@ISA = qw(Exporter);
0a362e9d
RGS
10@EXPORT = qw(encode_base64 decode_base64);
11
4438fa18 12$VERSION = '3.07_01';
0a362e9d 13
e1839706
SP
14require XSLoader;
15XSLoader::load('MIME::Base64', $VERSION);
0a362e9d
RGS
16
17*encode = \&encode_base64;
18*decode = \&decode_base64;
19
201;
21
22__END__
23
6fba102d
JH
24=head1 NAME
25
26MIME::Base64 - Encoding and decoding of base64 strings
27
28=head1 SYNOPSIS
29
30 use MIME::Base64;
31
32 $encoded = encode_base64('Aladdin:open sesame');
33 $decoded = decode_base64($encoded);
34
35=head1 DESCRIPTION
36
691d66bd
RGS
37This module provides functions to encode and decode strings into and from the
38base64 encoding specified in RFC 2045 - I<MIME (Multipurpose Internet
39Mail Extensions)>. The base64 encoding is designed to represent
6fba102d
JH
40arbitrary sequences of octets in a form that need not be humanly
41readable. A 65-character subset ([A-Za-z0-9+/=]) of US-ASCII is used,
42enabling 6 bits to be represented per printable character.
43
44The following functions are provided:
45
46=over 4
47
6a63fb82
AMS
48=item encode_base64($str)
49
50=item encode_base64($str, $eol);
6fba102d
JH
51
52Encode data by calling the encode_base64() function. The first
691d66bd
RGS
53argument is the string to encode. The second argument is the
54line-ending sequence to use. It is optional and defaults to "\n". The
6fba102d
JH
55returned encoded string is broken into lines of no more than 76
56characters each and it will end with $eol unless it is empty. Pass an
57empty string as second argument if you do not want the encoded string
691d66bd 58to be broken into lines.
6fba102d
JH
59
60=item decode_base64($str)
61
62Decode a base64 string by calling the decode_base64() function. This
63function takes a single argument which is the string to decode and
64returns the decoded data.
65
691d66bd
RGS
66Any character not part of the 65-character base64 subset is
67silently ignored. Characters occurring after a '=' padding character
6fba102d
JH
68are never decoded.
69
8be5f608 70If the length of the string to decode, after ignoring
691d66bd 71non-base64 chars, is not a multiple of 4 or if padding occurs too early,
6fba102d
JH
72then a warning is generated if perl is running under C<-w>.
73
74=back
75
691d66bd 76If you prefer not to import these routines into your namespace, you can
6fba102d
JH
77call them as:
78
79 use MIME::Base64 ();
80 $encoded = MIME::Base64::encode($decoded);
81 $decoded = MIME::Base64::decode($encoded);
82
83=head1 DIAGNOSTICS
84
691d66bd 85The following warnings can be generated if perl is invoked with the
6fba102d
JH
86C<-w> switch:
87
88=over 4
89
90=item Premature end of base64 data
91
92The number of characters to decode is not a multiple of 4. Legal
93base64 data should be padded with one or two "=" characters to make
4e2e3d15
SP
94its length a multiple of 4. The decoded result will be the same
95whether the padding is present or not.
6fba102d
JH
96
97=item Premature padding of base64 data
98
99The '=' padding character occurs as the first or second character
100in a base64 quartet.
101
102=back
103
e1839706
SP
104The following exception can be raised:
105
106=over 4
107
108=item Wide character in subroutine entry
109
110The string passed to encode_base64() contains characters with code
111above 255. The base64 encoding is only defined for single-byte
112characters. Use the Encode module to select the byte encoding you
113want.
114
115=back
116
6fba102d
JH
117=head1 EXAMPLES
118
119If you want to encode a large file, you should encode it in chunks
120that are a multiple of 57 bytes. This ensures that the base64 lines
121line up and that you do not end up with padding in the middle. 57
122bytes of data fills one complete base64 line (76 == 57*4/3):
123
124 use MIME::Base64 qw(encode_base64);
125
126 open(FILE, "/var/log/wtmp") or die "$!";
127 while (read(FILE, $buf, 60*57)) {
128 print encode_base64($buf);
129 }
130
131or if you know you have enough memory
132
133 use MIME::Base64 qw(encode_base64);
134 local($/) = undef; # slurp
135 print encode_base64(<STDIN>);
136
137The same approach as a command line:
138
139 perl -MMIME::Base64 -0777 -ne 'print encode_base64($_)' <file
140
691d66bd
RGS
141Decoding does not need slurp mode if every line contains a multiple
142of four base64 chars:
6fba102d
JH
143
144 perl -MMIME::Base64 -ne 'print decode_base64($_)' <file
145
e1839706
SP
146Perl v5.8 and better allow extended Unicode characters in strings.
147Such strings cannot be encoded directly, as the base64
148encoding is only defined for single-byte characters. The solution is
149to use the Encode module to select the byte encoding you want. For
150example:
151
152 use MIME::Base64 qw(encode_base64);
153 use Encode qw(encode);
154
155 $encoded = encode_base64(encode("UTF-8", "\x{FFFF}\n"));
156 print $encoded;
157
6fba102d
JH
158=head1 COPYRIGHT
159
691d66bd 160Copyright 1995-1999, 2001-2004 Gisle Aas.
6fba102d
JH
161
162This library is free software; you can redistribute it and/or
163modify it under the same terms as Perl itself.
164
165Distantly based on LWP::Base64 written by Martijn Koster
166<m.koster@nexor.co.uk> and Joerg Reichelt <j.reichelt@nexor.co.uk> and
167code posted to comp.lang.perl <3pd2lp$6gf@wsinti07.win.tue.nl> by Hans
168Mulder <hansm@wsinti07.win.tue.nl>
169
691d66bd 170The XS implementation uses code from metamail. Copyright 1991 Bell
6fba102d
JH
171Communications Research, Inc. (Bellcore)
172
8be5f608
RGS
173=head1 SEE ALSO
174
175L<MIME::QuotedPrint>
176
6fba102d 177=cut