ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/Convert-UUlib/UUlib.pm
(Generate patch)

Comparing Convert-UUlib/UUlib.pm (file contents):
Revision 1.32 by root, Mon Oct 13 12:12:56 2008 UTC vs.
Revision 1.46 by root, Fri Feb 28 06:57:25 2020 UTC

… …
6use Carp; 6use Carp;
7 7
8require Exporter; 8require Exporter;
9require DynaLoader; 9require DynaLoader;
10 10
11our $VERSION = '1.12'; 11our $VERSION = 1.62;
12 12
13our @ISA = qw(Exporter DynaLoader); 13our @ISA = qw(Exporter DynaLoader);
14 14
15our @_consts = qw( 15our @_consts = qw(
16 ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING 16 ACT_COPYING ACT_DECODING ACT_ENCODING ACT_IDLE ACT_SCANNING
… …
22 22
23 OPT_RBUF OPT_WBUF 23 OPT_RBUF OPT_WBUF
24 OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT 24 OPT_BRACKPOL OPT_DEBUG OPT_DESPERATE OPT_DUMBNESS OPT_ENCEXT
25 OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB 25 OPT_ERRNO OPT_FAST OPT_IGNMODE OPT_IGNREPLY OPT_OVERWRITE OPT_PREAMB
26 OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE 26 OPT_PROGRESS OPT_SAVEPATH OPT_TINYB64 OPT_USETEXT OPT_VERBOSE
27 OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT 27 OPT_VERSION OPT_REMOVE OPT_MOREMIME OPT_DOTDOT OPT_AUTOCHECK
28 28
29 RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA 29 RET_CANCEL RET_CONT RET_EXISTS RET_ILLVAL RET_IOERR RET_NODATA
30 RET_NOEND RET_NOMEM RET_OK RET_UNSUP 30 RET_NOEND RET_NOMEM RET_OK RET_UNSUP
31 31
32 B64_ENCODED BH_ENCODED PT_ENCODED QP_ENCODED 32 B64_ENCODED BH_ENCODED PT_ENCODED QP_ENCODED
… …
159 OPT_TINYB64 detect short B64 outside of Mime 159 OPT_TINYB64 detect short B64 outside of Mime
160 OPT_ENCEXT extension for single-part encoded files 160 OPT_ENCEXT extension for single-part encoded files
161 OPT_REMOVE remove input files after decoding (dangerous) 161 OPT_REMOVE remove input files after decoding (dangerous)
162 OPT_MOREMIME strict MIME adherence 162 OPT_MOREMIME strict MIME adherence
163 OPT_DOTDOT ".."-unescaping has not yet been done on input files 163 OPT_DOTDOT ".."-unescaping has not yet been done on input files
164 OPT_RBUF set default read I/O buffer size in bytes *EXPERIMENTAL* 164 OPT_RBUF set default read I/O buffer size in bytes
165 OPT_WBUF set default write I/O buffer size in bytes *EXPERIMENTAL* 165 OPT_WBUF set default write I/O buffer size in bytes
166 OPT_AUTOCHECK automatically check file list after every loadfile
166 167
167=head2 Result/Error codes 168=head2 Result/Error codes
168 169
169 RET_OK everything went fine 170 RET_OK everything went fine
170 RET_IOERR I/O Error - examine errno 171 RET_IOERR I/O Error - examine errno
… …
213again. 214again.
214 215
215On my machine, a fairly complete decode with DBI backend needs about 10MB 216On my machine, a fairly complete decode with DBI backend needs about 10MB
216RSS to decode 20000 files. 217RSS to decode 20000 files.
217 218
218=over 4 219=over
219 220
220=item Initialize 221=item Initialize
221 222
222Not normally necessary, (re-)initializes the library. 223Not normally necessary, (re-)initializes the library.
223 224
… …
228 229
229=back 230=back
230 231
231=head2 Setting and querying options 232=head2 Setting and querying options
232 233
233=over 4 234=over
234 235
235=item $option = GetOption OPT_xxx 236=item $option = GetOption OPT_xxx
236 237
237=item SetOption OPT_xxx, opt-value 238=item SetOption OPT_xxx, opt-value
238 239
… …
240 241
241See the C<OPT_xxx> constants above to see which options exist. 242See the C<OPT_xxx> constants above to see which options exist.
242 243
243=head2 Setting various callbacks 244=head2 Setting various callbacks
244 245
245=over 4 246=over
246 247
247=item SetMsgCallback [callback-function] 248=item SetMsgCallback [callback-function]
248 249
249=item SetBusyCallback [callback-function] 250=item SetBusyCallback [callback-function]
250 251
… …
254 255
255=back 256=back
256 257
257=head2 Call the currently selected FNameFilter 258=head2 Call the currently selected FNameFilter
258 259
259=over 4 260=over
260 261
261=item $file = FNameFilter $file 262=item $file = FNameFilter $file
262 263
263=back 264=back
264 265
265=head2 Loading sourcefiles, optionally fuzzy merge and start decoding 266=head2 Loading sourcefiles, optionally fuzzy merge and start decoding
266 267
267=over 4 268=over
268 269
269=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]] 270=item ($retval, $count) = LoadFile $fname, [$id, [$delflag, [$partno]]]
270 271
271Load the given file and scan it for encoded contents. Optionally tag it 272Load the given file and scan it for encoded contents. Optionally tag it
272with the given id, and if C<$delflag> is true, delete the file after it 273with the given id, and if C<$delflag> is true, delete the file after it
… …
281If you are desperate, try to call C<Smerge> with increasing C<$pass> 282If you are desperate, try to call C<Smerge> with increasing C<$pass>
282values, beginning at C<0>, to try to merge parts that usually would not 283values, beginning at C<0>, to try to merge parts that usually would not
283have been merged. 284have been merged.
284 285
285Most probably this will result in garbled files, so never do this by 286Most probably this will result in garbled files, so never do this by
286default. 287default, except:
288
289If the C<OPT_AUTOCHECK> option has been disabled (by default it is
290enabled) to speed up file loading, then you I<have> to call C<Smerge -1>
291after loading all files as an additional pre-pass (which is normally done
292by C<LoadFile>).
287 293
288=item $item = GetFileListItem $item_number 294=item $item = GetFileListItem $item_number
289 295
290Return the C<$item> structure for the C<$item_number>'th found file, or 296Return the C<$item> structure for the C<$item_number>'th found file, or
291C<undef> of no file with that number exists. 297C<undef> of no file with that number exists.
… …
296 302
297=back 303=back
298 304
299=head2 Decoding files 305=head2 Decoding files
300 306
301=over 4 307=over
302 308
303=item $retval = $item->rename($newname) 309=item $retval = $item->rename ($newname)
304 310
305Change the ondisk filename where the decoded file will be saved. 311Change the ondisk filename where the decoded file will be saved.
306 312
307=item $retval = $item->decode_temp 313=item $retval = $item->decode_temp
308 314
… …
311 317
312=item $retval = $item->remove_temp 318=item $retval = $item->remove_temp
313 319
314Remove the temporarily decoded file again. 320Remove the temporarily decoded file again.
315 321
316=item $retval = $item->decode([$target_path]) 322=item $retval = $item->decode ([$target_path])
317 323
318Decode the file to it's destination, or the given target path. 324Decode the file to its destination, or the given target path.
319 325
320=item $retval = $item->info(callback-function) 326=item $retval = $item->info (callback-function)
321 327
322=back 328=back
323 329
324=head2 Querying (and setting) item attributes 330=head2 Querying (and setting) item attributes
325 331
326=over 4 332=over
327 333
328=item $state = $item->state 334=item $state = $item->state
329 335
330=item $mode = $item->mode([newmode]) 336=item $mode = $item->mode ([newmode])
331 337
332=item $uudet = $item->uudet 338=item $uudet = $item->uudet
333 339
334=item $size = $item->size 340=item $size = $item->size
335 341
336=item $filename = $item->filename([newfilename}) 342=item $filename = $item->filename ([newfilename})
337 343
338=item $subfname = $item->subfname 344=item $subfname = $item->subfname
339 345
340=item $mimeid = $item->mimeid 346=item $mimeid = $item->mimeid
341 347
… …
345 351
346=back 352=back
347 353
348=head2 Information about source parts 354=head2 Information about source parts
349 355
350=over 4 356=over
351 357
352=item $parts = $item->parts 358=item $parts = $item->parts
353 359
354Return information about all parts (source files) used to decode the file 360Return information about all parts (source files) used to decode the file
355as a list of hashrefs with the following structure: 361as a list of hashrefs with the following structure:
… …
369Usually you are interested mostly the C<sfname> and possibly the C<partno> 375Usually you are interested mostly the C<sfname> and possibly the C<partno>
370and C<filename> members. 376and C<filename> members.
371 377
372=back 378=back
373 379
374=head2 Functions below not documented and not very well tested 380=head2 Functions below are not documented and not very well tested - feedback welcome
375 381
376 QuickDecode 382 QuickDecode
377 EncodeMulti 383 EncodeMulti
378 EncodePartial 384 EncodePartial
379 EncodeToStream 385 EncodeToStream
… …
383 389
384=head2 EXTENSION FUNCTIONS 390=head2 EXTENSION FUNCTIONS
385 391
386Functions found in this module but not documented in the uulib documentation: 392Functions found in this module but not documented in the uulib documentation:
387 393
388=over 4 394=over
389 395
390=item $msg = straction ACT_xxx 396=item $msg = straction ACT_xxx
391 397
392Return a human readable string representing the given action code. 398Return a human readable string representing the given action code.
393 399
… …
481 # the following non-trivial FileNameCallback takes care 487 # the following non-trivial FileNameCallback takes care
482 # of some subject lines not detected properly by uulib: 488 # of some subject lines not detected properly by uulib:
483 SetFileNameCallback sub { 489 SetFileNameCallback sub {
484 return unless $_[1]; # skip "Re:"-plies et al. 490 return unless $_[1]; # skip "Re:"-plies et al.
485 local $_ = $_[0]; 491 local $_ = $_[0];
486
487 return $1 if /(\S+\s+IMG_\d+.jpg)/i;
488 492
489 # the following rules are rather effective on some newsgroups, 493 # the following rules are rather effective on some newsgroups,
490 # like alt.binaries.games.anime, where non-mime, uuencoded data 494 # like alt.binaries.games.anime, where non-mime, uuencoded data
491 # is very common 495 # is very common
492 496
… …
554 558
555 print "cleanup...\n"; 559 print "cleanup...\n";
556 560
557 CleanUp; 561 CleanUp;
558 562
563=head1 PERLMULTICORE SUPPORT
564
565This module supports the perlmulticore standard (see
566L<http://perlmulticore.schmorp.de/> for more info) for the following
567functions - generally these are functions accessing the disk and/or using
568considerable CPU time:
569
570 LoadFile
571 $item->decode
572 $item->decode_temp
573 $item->remove_temp
574 $item->info
575
576The perl interpreter will be reacquired/released on every callback
577invocation, so for performance reasons, callbacks should be avoided if
578that is costly.
579
580Future versions might enable multicore support for more functions.
581
582=head1 BUGS AND LIMITATIONS
583
584The original uulib library this module uses was written at a time where
585main memory of measured in megabytes and buffer overflows as a security
586thign didn't exist. While a lot of security fixes have been applied over
587the years (includign some defense in depth mechanism that can shield
588against a lot of as-of-yet undetected bugs), using this library for
589security purposes requires care.
590
591Likewise, file sizes when the uulib library was written were tiny compared
592to today, so do not expect this library to handle files larger than 2GB.
593
559=head1 AUTHOR 594=head1 AUTHOR
560 595
561Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written 596Marc Lehmann <schmorp@schmorp.de>, the original uulib library was written
562by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily 597by Frank Pilhofer <fp@informatik.uni-frankfurt.de>, and later heavily
563bugfixed by Marc Lehmann. 598bugfixed by Marc Lehmann.
564 599
565=head1 SEE ALSO 600=head1 SEE ALSO
566 601
567perl(1), uudeview homepage at http://www.uni-frankfurt.de/~fp/uudeview/. 602perl(1), uudeview homepage at L<http://www.fpx.de/fp/Software/UUDeview/>.
568 603
569=cut 604=cut
605

Diff Legend

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