Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 221 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/MIME::Base64.3perl b/upstream/debian-unstable/man3/MIME::Base64.3perl
new file mode 100644
index 00000000..08b8977d
--- /dev/null
+++ b/upstream/debian-unstable/man3/MIME::Base64.3perl
@@ -0,0 +1,221 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "MIME::Base64 3perl"
+.TH MIME::Base64 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+MIME::Base64 \- Encoding and decoding of base64 strings
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use MIME::Base64;
+\&
+\& $encoded = encode_base64(\*(AqAladdin:open sesame\*(Aq);
+\& $decoded = decode_base64($encoded);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This module provides functions to encode and decode strings into and from the
+base64 encoding specified in RFC 2045 \- \fIMIME (Multipurpose Internet
+Mail Extensions)\fR. The base64 encoding is designed to represent
+arbitrary sequences of octets in a form that need not be humanly
+readable. A 65\-character subset ([A\-Za\-z0\-9+/=]) of US-ASCII is used,
+enabling 6 bits to be represented per printable character.
+.PP
+The following primary functions are provided:
+.ie n .IP "encode_base64( $bytes )" 4
+.el .IP "encode_base64( \f(CW$bytes\fR )" 4
+.IX Item "encode_base64( $bytes )"
+.PD 0
+.ie n .IP "encode_base64( $bytes, $eol );" 4
+.el .IP "encode_base64( \f(CW$bytes\fR, \f(CW$eol\fR );" 4
+.IX Item "encode_base64( $bytes, $eol );"
+.PD
+Encode data by calling the \fBencode_base64()\fR function.  The first
+argument is the byte string to encode.  The second argument is the
+line-ending sequence to use.  It is optional and defaults to "\en".  The
+returned encoded string is broken into lines of no more than 76
+characters each and it will end with \f(CW$eol\fR unless it is empty.  Pass an
+empty string as second argument if you do not want the encoded string
+to be broken into lines.
+.Sp
+The function will croak with "Wide character in subroutine entry" if \f(CW$bytes\fR
+contains characters with code above 255.  The base64 encoding is only defined
+for single-byte characters.  Use the Encode module to select the byte encoding
+you want.
+.ie n .IP "decode_base64( $str )" 4
+.el .IP "decode_base64( \f(CW$str\fR )" 4
+.IX Item "decode_base64( $str )"
+Decode a base64 string by calling the \fBdecode_base64()\fR function.  This
+function takes a single argument which is the string to decode and
+returns the decoded data.
+.Sp
+Any character not part of the 65\-character base64 subset is
+silently ignored.  Characters occurring after a '=' padding character
+are never decoded.
+.PP
+If you prefer not to import these routines into your namespace, you can
+call them as:
+.PP
+.Vb 3
+\&    use MIME::Base64 ();
+\&    $encoded = MIME::Base64::encode($decoded);
+\&    $decoded = MIME::Base64::decode($encoded);
+.Ve
+.PP
+Additional functions not exported by default:
+.ie n .IP "encode_base64url( $bytes )" 4
+.el .IP "encode_base64url( \f(CW$bytes\fR )" 4
+.IX Item "encode_base64url( $bytes )"
+.PD 0
+.ie n .IP "decode_base64url( $str )" 4
+.el .IP "decode_base64url( \f(CW$str\fR )" 4
+.IX Item "decode_base64url( $str )"
+.PD
+Encode and decode according to the base64 scheme for "URL applications" [1].
+This is a variant of the base64 encoding which does not use padding, does not
+break the string into multiple lines and use the characters "\-" and "_" instead
+of "+" and "/" to avoid using reserved URL characters.
+.ie n .IP "encoded_base64_length( $bytes )" 4
+.el .IP "encoded_base64_length( \f(CW$bytes\fR )" 4
+.IX Item "encoded_base64_length( $bytes )"
+.PD 0
+.ie n .IP "encoded_base64_length( $bytes, $eol )" 4
+.el .IP "encoded_base64_length( \f(CW$bytes\fR, \f(CW$eol\fR )" 4
+.IX Item "encoded_base64_length( $bytes, $eol )"
+.PD
+Returns the length that the encoded string would have without actually
+encoding it.  This will return the same value as \f(CW\*(C`length(encode_base64($bytes))\*(C'\fR,
+but should be more efficient.
+.ie n .IP "decoded_base64_length( $str )" 4
+.el .IP "decoded_base64_length( \f(CW$str\fR )" 4
+.IX Item "decoded_base64_length( $str )"
+Returns the length that the decoded string would have without actually
+decoding it.  This will return the same value as \f(CW\*(C`length(decode_base64($str))\*(C'\fR,
+but should be more efficient.
+.SH EXAMPLES
+.IX Header "EXAMPLES"
+If you want to encode a large file, you should encode it in chunks
+that are a multiple of 57 bytes.  This ensures that the base64 lines
+line up and that you do not end up with padding in the middle. 57
+bytes of data fills one complete base64 line (76 == 57*4/3):
+.PP
+.Vb 1
+\&   use MIME::Base64 qw(encode_base64);
+\&
+\&   open(FILE, "/var/log/wtmp") or die "$!";
+\&   while (read(FILE, $buf, 60*57)) {
+\&       print encode_base64($buf);
+\&   }
+.Ve
+.PP
+or if you know you have enough memory
+.PP
+.Vb 3
+\&   use MIME::Base64 qw(encode_base64);
+\&   local($/) = undef;  # slurp
+\&   print encode_base64(<STDIN>);
+.Ve
+.PP
+The same approach as a command line:
+.PP
+.Vb 1
+\&   perl \-MMIME::Base64 \-0777 \-ne \*(Aqprint encode_base64($_)\*(Aq <file
+.Ve
+.PP
+Decoding does not need slurp mode if every line contains a multiple
+of four base64 chars:
+.PP
+.Vb 1
+\&   perl \-MMIME::Base64 \-ne \*(Aqprint decode_base64($_)\*(Aq <file
+.Ve
+.PP
+Perl v5.8 and better allow extended Unicode characters in strings.
+Such strings cannot be encoded directly, as the base64
+encoding is only defined for single-byte characters.  The solution is
+to use the Encode module to select the byte encoding you want.  For
+example:
+.PP
+.Vb 2
+\&    use MIME::Base64 qw(encode_base64);
+\&    use Encode qw(encode);
+\&
+\&    $encoded = encode_base64(encode("UTF\-8", "\ex{FFFF}\en"));
+\&    print $encoded;
+.Ve
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 1995\-1999, 2001\-2004, 2010 Gisle Aas.
+.PP
+This library is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+Distantly based on LWP::Base64 written by Martijn Koster
+<m.koster@nexor.co.uk> and Joerg Reichelt <j.reichelt@nexor.co.uk> and
+code posted to comp.lang.perl <3pd2lp$6gf@wsinti07.win.tue.nl> by Hans
+Mulder <hansm@wsinti07.win.tue.nl>
+.PP
+The XS implementation uses code from metamail.  Copyright 1991 Bell
+Communications Research, Inc. (Bellcore)
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+MIME::QuotedPrint
+.PP
+[1] <http://en.wikipedia.org/wiki/Base64#URL_applications>