[ViewVC] Diff of: cvs/Convert-UUlib/UUlib.pm

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.34 by root, Mon Aug 24 04:38:23 2009 UTC vs.
Revision 1.56 by root, Thu Dec 17 01:24:59 2020 UTC

…		…
1	package Convert::UUlib;	1	package Convert::UUlib;
2		2
3	no warnings;	3	use common::sense;
4	use strict;
5		4
6	use Carp;	5	use Carp;
7		6
8	require Exporter;	7	require Exporter;
9	require DynaLoader;	8	require DynaLoader;
10		9
11	our $VERSION = '1.12';	10	our $VERSION = 1.8;
12		11
13	our @ISA = qw(Exporter DynaLoader);	12	our @ISA = qw(Exporter DynaLoader);
14		13
15	our @_consts = qw(	14	our @_consts = qw(
16	ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING	15	ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING
34	);	33	);
35		34
36	our @_funcs = qw(	35	our @_funcs = qw(
37	Initialize CleanUp GetOption SetOption strerror SetMsgCallback	36	Initialize CleanUp GetOption SetOption strerror SetMsgCallback
38	SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback	37	SetBusyCallback SetFileCallback SetFNameFilter SetFileNameCallback
39	FNameFilter LoadFile GetFileListItem RenameFile DecodeToTemp	38	FNameFilter LoadFile GetFileListItem GetFileList RenameFile DecodeToTemp
40	RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti	39	RemoveTemp DecodeFile InfoFile Smerge QuickDecode EncodeMulti
41	EncodePartial EncodeToStream EncodeToFile E_PrepSingle	40	EncodePartial EncodeToStream EncodeToFile E_PrepSingle
42	E_PrepPartial CheckGlobalList	41	E_PrepPartial
43		42
44	straction strencoding strmsglevel	43	straction strencoding strmsglevel
45	);	44	);
46		45
47	our @EXPORT = @_consts;	46	our @EXPORT = @_consts;
48	our @EXPORT_OK = @_funcs;	47	our @EXPORT_OK = @_funcs;
49	our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);	48	our %EXPORT_TAGS = (all => [@_consts,@_funcs], constants => \@_consts);
50		49
51	bootstrap Convert::UUlib $VERSION;	50	bootstrap Convert::UUlib $VERSION;
52		51
53	Initialize();	52	# dummy function for compatiiblity with pre-1.7 versions
54		53	sub Initialize { }
55	# not when < 5.005_6x
56	# END { CleanUp() }
57
58	for (@_consts) {
59	my $constant = constant($_);
60	no strict 'refs';
61	*$_ = sub () { $constant };
62	}
63		54
64	# action code -> string mapping	55	# action code -> string mapping
65	sub straction($) {	56	sub straction($) {
66	return 'copying' if $_[0] == &ACT_COPYING;	57	return 'copying' if $_[0] == &ACT_COPYING;
67	return 'decoding' if $_[0] == &ACT_DECODING;	58	return 'decoding' if $_[0] == &ACT_DECODING;
…		…
96	1;	87	1;
97	__END__	88	__END__
98		89
99	=head1 NAME	90	=head1 NAME
100		91
101	Convert::UUlib - Perl interface to the uulib library (a.k.a. uudeview/uuenview).	92	Convert::UUlib - decode uu/xx/b64/mime/yenc/etc-encoded data from a massive number of files
102		93
103	=head1 SYNOPSIS	94	=head1 SYNOPSIS
104		95
105	use Convert::UUlib ':all';	96	use Convert::UUlib ':all';
106		97
107	# read all the files named on the commandline and decode them	98	# read all the files named on the commandline and decode them
108	# into the CURRENT directory. See below for a longer example.	99	# into the CURRENT directory. See below for a longer example.
109	LoadFile $_ for @ARGV;	100	LoadFile $_ for @ARGV;
110	for (my $i = 0; my $uu = GetFileListItem $i; $i++) {	101
		102	for my $uu (GetFileList) {
111	if ($uu->state & FILE_OK) {	103	if ($uu->state & FILE_OK) {
112	$uu->decode;	104	$uu->decode;
113	print $uu->filename, "\n";	105	print $uu->filename, "\n";
114	}	106	}
115	}	107	}
116		108
117	=head1 DESCRIPTION	109	=head1 DESCRIPTION
		110
		111	This module started as an interface to the uulib/uudeview library by Frank
		112	Pilhofer that can be used to decode all kinds of usenet (and other)
		113	binary messages.
		114
		115	After upstream abondoned the project, th library was continuously bugfixed
		116	and improved in this module, with major focuses on security fixes,
		117	correctness and speed (that does not mean that this library is considered
		118	safe with untrusted data, but it surely is safer than the poriginal
		119	uudeview).
118		120
119	Read the file doc/library.pdf from the distribution for in-depth	121	Read the file doc/library.pdf from the distribution for in-depth
120	information about the C-library used in this interface, and the rest of	122	information about the C-library used in this interface, and the rest of
121	this document and especially the non-trivial decoder program at the end.	123	this document and especially the non-trivial decoder program at the end.
122		124
…		…
159	OPT_TINYB64 detect short B64 outside of Mime	161	OPT_TINYB64 detect short B64 outside of Mime
160	OPT_ENCEXT extension for single-part encoded files	162	OPT_ENCEXT extension for single-part encoded files
161	OPT_REMOVE remove input files after decoding (dangerous)	163	OPT_REMOVE remove input files after decoding (dangerous)
162	OPT_MOREMIME strict MIME adherence	164	OPT_MOREMIME strict MIME adherence
163	OPT_DOTDOT ".."-unescaping has not yet been done on input files	165	OPT_DOTDOT ".."-unescaping has not yet been done on input files
164	OPT_RBUF set default read I/O buffer size in bytes EXPERIMENTAL	166	OPT_RBUF set default read I/O buffer size in bytes
165	OPT_WBUF set default write I/O buffer size in bytes EXPERIMENTAL	167	OPT_WBUF set default write I/O buffer size in bytes
		168	OPT_AUTOCHECK automatically check file list after every loadfile
166		169
167	=head2 Result/Error codes	170	=head2 Result/Error codes
168		171
169	RET_OK everything went fine	172	RET_OK everything went fine
170	RET_IOERR I/O Error - examine errno	173	RET_IOERR I/O Error - examine errno
…		…
213	again.	216	again.
214		217
215	On my machine, a fairly complete decode with DBI backend needs about 10MB	218	On my machine, a fairly complete decode with DBI backend needs about 10MB
216	RSS to decode 20000 files.	219	RSS to decode 20000 files.
217		220
218	=over 4	221	=over
219
220	=item Initialize
221
222	Not normally necessary, (re-)initializes the library.
223		222
224	=item CleanUp	223	=item CleanUp
225		224
226	Not normally necessary, could be called at the end to release memory	225	Release memory, file items and clean up files. Should be called after a
227	before starting a new decoding round.	226	decoidng run, if you want to start a new one.
228		227
229	=back	228	=back
230		229
231	=head2 Setting and querying options	230	=head2 Setting and querying options
232		231
233	=over 4	232	=over
234		233
235	=item $option = GetOption OPT_xxx	234	=item $option = GetOption OPT_xxx
236		235
237	=item SetOption OPT_xxx, opt-value	236	=item SetOption OPT_xxx, opt-value
238		237
…		…
240		239
241	See the C<OPT_xxx> constants above to see which options exist.	240	See the C<OPT_xxx> constants above to see which options exist.
242		241
243	=head2 Setting various callbacks	242	=head2 Setting various callbacks
244		243
245	=over 4	244	=over
246		245
247	=item SetMsgCallback [callback-function]	246	=item SetMsgCallback [callback-function]
248		247
249	=item SetBusyCallback [callback-function]	248	=item SetBusyCallback [callback-function]
250		249
…		…
254		253
255	=back	254	=back
256		255
257	=head2 Call the currently selected FNameFilter	256	=head2 Call the currently selected FNameFilter
258		257
259	=over 4	258	=over
260		259
261	=item $file = FNameFilter $file	260	=item $file = FNameFilter $file
262		261
263	=back	262	=back
264		263
265	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding	264	=head2 Loading sourcefiles, optionally fuzzy merge and start decoding
266		265
267	=over 4	266	=over
268		267
269	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]	268	=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]
270		269
271	Load the given file and scan it for encoded contents. Optionally tag it	270	Load the given file and scan it for encoded contents. Optionally tag it
272	with the given id, and if C<$delflag> is true, delete the file after it	271	with the given id, and if C<$delflag> is true, delete the file after it
…		…
281	If you are desperate, try to call C<Smerge> with increasing C<$pass>	280	If you are desperate, try to call C<Smerge> with increasing C<$pass>
282	values, beginning at C<0>, to try to merge parts that usually would not	281	values, beginning at C<0>, to try to merge parts that usually would not
283	have been merged.	282	have been merged.
284		283
285	Most probably this will result in garbled files, so never do this by	284	Most probably this will result in garbled files, so never do this by
286	default.	285	default, except:
		286
		287	If the C<OPT_AUTOCHECK> option has been disabled (by default it is
		288	enabled) to speed up file loading, then you I<have> to call C<Smerge -1>
		289	after loading all files as an additional pre-pass (which is normally done
		290	by C<LoadFile>).
287		291
288	=item $item = GetFileListItem $item_number	292	=item $item = GetFileListItem $item_number
289		293
290	Return the C<$item> structure for the C<$item_number>'th found file, or	294	Return the C<$item> structure for the C<$item_number>'th found file, or
291	C<undef> of no file with that number exists.	295	C<undef> of no file with that number exists.
292		296
293	The first file has number C<0>, and the series has no holes, so you can	297	The first file has number C<0>, and the series has no holes, so you can
294	iterate over all files by starting with zero and incrementing until you	298	iterate over all files by starting with zero and incrementing until you
295	hit C<undef>.	299	hit C<undef>.
296		300
		301	This function has to walk the linear list of fils on each access, so
		302	if you want to iterate over all items, it is usually faster to use
		303	C<GetFileList>.
		304
		305	=item @items = GetFileList
		306
		307	Similar to C<GetFileListItem>, but returns all files in one go, which is
		308	very much faster for large number of items, and has no drawbacks when used
		309	for a small number of items.
		310
297	=back	311	=back
298		312
299	=head2 Decoding files	313	=head2 Decoding files
300		314
301	=over 4	315	=over
302		316
303	=item $retval = $item->rename($newname)	317	=item $retval = $item->rename ($newname)
304		318
305	Change the ondisk filename where the decoded file will be saved.	319	Change the ondisk filename where the decoded file will be saved.
306		320
307	=item $retval = $item->decode_temp	321	=item $retval = $item->decode_temp
308		322
…		…
311		325
312	=item $retval = $item->remove_temp	326	=item $retval = $item->remove_temp
313		327
314	Remove the temporarily decoded file again.	328	Remove the temporarily decoded file again.
315		329
316	=item $retval = $item->decode([$target_path])	330	=item $retval = $item->decode ([$target_path])
317		331
318	Decode the file to it's destination, or the given target path.	332	Decode the file to its destination, or the given target path.
319		333
320	=item $retval = $item->info(callback-function)	334	=item $retval = $item->info (callback-function)
321		335
322	=back	336	=back
323		337
324	=head2 Querying (and setting) item attributes	338	=head2 Querying (and setting) item attributes
325		339
326	=over 4	340	=over
327		341
328	=item $state = $item->state	342	=item $state = $item->state
329		343
330	=item $mode = $item->mode([newmode])	344	=item $mode = $item->mode ([newmode])
331		345
332	=item $uudet = $item->uudet	346	=item $uudet = $item->uudet
333		347
334	=item $size = $item->size	348	=item $size = $item->size
335		349
336	=item $filename = $item->filename([newfilename})	350	=item $filename = $item->filename ([newfilename})
337		351
338	=item $subfname = $item->subfname	352	=item $subfname = $item->subfname
339		353
340	=item $mimeid = $item->mimeid	354	=item $mimeid = $item->mimeid
341		355
…		…
345		359
346	=back	360	=back
347		361
348	=head2 Information about source parts	362	=head2 Information about source parts
349		363
350	=over 4	364	=over
351		365
352	=item $parts = $item->parts	366	=item $parts = $item->parts
353		367
354	Return information about all parts (source files) used to decode the file	368	Return information about all parts (source files) used to decode the file
355	as a list of hashrefs with the following structure:	369	as a list of hashrefs with the following structure:
…		…
369	Usually you are interested mostly the C<sfname> and possibly the C<partno>	383	Usually you are interested mostly the C<sfname> and possibly the C<partno>
370	and C<filename> members.	384	and C<filename> members.
371		385
372	=back	386	=back
373		387
374	=head2 Functions below not documented and not very well tested	388	=head2 Functions below are not documented and not very well tested - feedback welcome
375		389
376	QuickDecode	390	QuickDecode
377	EncodeMulti	391	EncodeMulti
378	EncodePartial	392	EncodePartial
379	EncodeToStream	393	EncodeToStream
…		…
383		397
384	=head2 EXTENSION FUNCTIONS	398	=head2 EXTENSION FUNCTIONS
385		399
386	Functions found in this module but not documented in the uulib documentation:	400	Functions found in this module but not documented in the uulib documentation:
387		401
388	=over 4	402	=over
389		403
390	=item $msg = straction ACT_xxx	404	=item $msg = straction ACT_xxx
391		405
392	Return a human readable string representing the given action code.	406	Return a human readable string representing the given action code.
393		407
…		…
434		448
435	=back	449	=back
436		450
437	=head1 LARGE EXAMPLE DECODER	451	=head1 LARGE EXAMPLE DECODER
438		452
		453	The general workflow for decoding is like this:
		454
		455	=over
		456
		457	=item 1. Configure options with C<SetOption> or C<SetXXXCallback>.
		458
		459	=item 2. Load all source files with C<LoadFile>.
		460
		461	=item 3. Optionally C<Smerge>.
		462
		463	=item 4. Iterate over all C<GetFileList> items (i.e. result files).
		464
		465	=item 5. C<CleanUp> to delete files and free items.
		466
		467	=back
		468
439	This is the file C<example-decoder> from the distribution, put here	469	What follows is the file C<example-decoder> from the distribution that
440	instead of more thorough documentation.	470	illustrates the above worklfow in a non-trivial example.
441		471
442	#!/usr/bin/perl	472	#!/usr/bin/perl
443		473
444	# decode all the files in the directory uusrc/ and copy	474	# decode all the files in the directory uusrc/ and copy
445	# the resulting files to uudst/	475	# the resulting files to uudst/
…		…
464	SetOption OPT_RBUF, 128*1024;	494	SetOption OPT_RBUF, 128*1024;
465	SetOption OPT_WBUF, 1024*1024;	495	SetOption OPT_WBUF, 1024*1024;
466	SetOption OPT_IGNMODE, 1;	496	SetOption OPT_IGNMODE, 1;
467	SetOption OPT_IGNMODE, 1;	497	SetOption OPT_IGNMODE, 1;
468	SetOption OPT_VERBOSE, 1;	498	SetOption OPT_VERBOSE, 1;
		499	SetOption OPT_AUTOCHK, 0;
469		500
470	# show the three ways you can set callback functions. I normally	501	# show the three ways you can set callback functions. I normally
471	# prefer the one with the sub inplace.	502	# prefer the one with the sub inplace.
472	SetFNameFilter \&namefilter;	503	SetFNameFilter \&namefilter;
473		504
…		…
507	# otherwise just pass what we have	538	# otherwise just pass what we have
508	()	539	()
509	};	540	};
510		541
511	# now read all files in the directory uusrc/*	542	# now read all files in the directory uusrc/*
512	for(<uusrc/*>) {	543	for (<uusrc/*>) {
513	my ($retval, $count) = LoadFile ($_, $_, 1);	544	my ($retval, $count) = LoadFile ($_, $_, 1);
514	print "file($_), status(", strerror $retval, ") parts($count)\n";	545	print "file($_), status(", strerror $retval, ") parts($count)\n";
515	}	546	}
516		547
		548	Smerge -1;
		549
517	SetOption OPT_SAVEPATH, "uudst/";	550	SetOption OPT_SAVEPATH, "uudst/";
518		551
519	# now wade through all files and their source parts	552	# now wade through all files and their source parts
520	$i = 0;	553	for my $uu (GetFileList) {
521	while ($uu = GetFileListItem $i) {	554	print "file ", $uu->filename, "\n";
522	$i++;
523	print "file nr. $i";
524	print " state ", $uu->state;	555	print " state ", $uu->state, "\n";
525	print " mode ", $uu->mode;	556	print " mode ", $uu->mode, "\n";
526	print " uudet ", strencoding $uu->uudet;	557	print " uudet ", strencoding $uu->uudet, "\n";
527	print " size ", $uu->size;	558	print " size ", $uu->size, "\n";
528	print " filename ", $uu->filename;
529	print " subfname ", $uu->subfname;	559	print " subfname ", $uu->subfname, "\n";
530	print " mimeid ", $uu->mimeid;	560	print " mimeid ", $uu->mimeid, "\n";
531	print " mimetype ", $uu->mimetype;	561	print " mimetype ", $uu->mimetype, "\n";
532	print "\n";
533		562
534	# print additional info about all parts	563	# print additional info about all parts
		564	print " parts";
535	for ($uu->parts) {	565	for ($uu->parts) {
536	while (my ($k, $v) = each %$_) {	566	for my $k (sort keys %$_) {
537	print "$k > $v, ";	567	print " $k=$_->{$k}";
538	}	568	}
539	print "\n";	569	print "\n";
540	}	570	}
541		571
542	print $uu->filename;
543
544	$uu->remove_temp;	572	$uu->remove_temp;
545		573
546	if (my $err = $uu->decode ()) {	574	if (my $err = $uu->decode) {
547	print ", ", strerror $err, "\n";	575	print " ERROR ", strerror $err, "\n";
548	} else {	576	} else {
549	print ", saved as uudst/", $uu->filename, "\n";	577	print " successfully saved as uudst/", $uu->filename, "\n";
550	}	578	}
551	}	579	}
552		580
553	print "cleanup...\n";	581	print "cleanup...\n";
554		582
555	CleanUp;	583	CleanUp;
		584
		585	=head1 PERLMULTICORE SUPPORT
		586
		587	This module supports the perlmulticore standard (see
		588	L<http://perlmulticore.schmorp.de/> for more info) for the following
		589	functions - generally these are functions accessing the disk and/or using
		590	considerable CPU time:
		591
		592	LoadFile
		593	$item->decode
		594	$item->decode_temp
		595	$item->remove_temp
		596	$item->info
		597
		598	The perl interpreter will be reacquired/released on every callback
		599	invocation, so for performance reasons, callbacks should be avoided if
		600	that is costly.
		601
		602	Future versions might enable multicore support for more functions.
		603
		604	=head1 BUGS AND LIMITATIONS
		605
		606	The original uulib library this module uses was written at a time where
		607	main memory of measured in megabytes and buffer overflows as a security
		608	thign didn't exist. While a lot of security fixes have been applied over
		609	the years (includign some defense in depth mechanism that can shield
		610	against a lot of as-of-yet undetected bugs), using this library for
		611	security purposes requires care.
		612
		613	Likewise, file sizes when the uulib library was written were tiny compared
		614	to today, so do not expect this library to handle files larger than 2GB.
		615
		616	Lastly, this module uses a very "C-like" interface, which means it doesn't
		617	protect you from invalid points as you might expect from "more perlish"
		618	modules - for example, accessing a file item object after callinbg
		619	C<CleanUp> will likely result in crashes, memory corruption, or worse.
556		620
557	=head1 AUTHOR	621	=head1 AUTHOR
558		622
559	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written	623	Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
560	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily	624	by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
561	bugfixed by Marc Lehmann.	625	bugfixed by Marc Lehmann.
562		626
563	=head1 SEE ALSO	627	=head1 SEE ALSO
564		628
565	perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/.	629	perl(1), uudeview homepage at L<http://www.fpx.de/fp/Software/UUDeview/>.
566		630
567	=cut	631	=cut
		632

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing Convert-UUlib/UUlib.pm (file contents): Revision 1.34 by root, Mon Aug 24 04:38:23 2009 UTC vs. Revision 1.56 by root, Thu Dec 17 01:24:59 2020 UTC

Diff Legend

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.34 by root, Mon Aug 24 04:38:23 2009 UTC vs.
Revision 1.56 by root, Thu Dec 17 01:24:59 2020 UTC