1=head1 NAME 2 3upx - compress or expand executable files 4 5 6 7=head1 SYNOPSIS 8 9B<upx> S<[ I<command> ]> S<[ I<options> ]> I<filename>... 10 11 12 13=head1 ABSTRACT 14 15 The Ultimate Packer for eXecutables 16 Copyright (c) 1996-2020 Markus Oberhumer, Laszlo Molnar & John Reiser 17 https://upx.github.io 18 19 20B<UPX> is a portable, extendable, high-performance executable packer for 21several different executable formats. It achieves an excellent compression 22ratio and offers I<*very*> fast decompression. Your executables suffer 23no memory overhead or other drawbacks for most of the formats supported, 24because of in-place decompression. 25 26While you may use B<UPX> freely for both non-commercial and commercial 27executables (for details see the file LICENSE), we would highly 28appreciate if you credit B<UPX> and ourselves in the documentation, 29possibly including a reference to the B<UPX> home page. Thanks. 30 31[ Using B<UPX> in non-OpenSource applications without proper credits 32is considered not politically correct ;-) ] 33 34 35 36=head1 DISCLAIMER 37 38B<UPX> comes with ABSOLUTELY NO WARRANTY; for details see the file LICENSE. 39 40This is the first production quality release, and we plan that future 1.xx 41releases will be backward compatible with this version. 42 43Please report all problems or suggestions to the authors. Thanks. 44 45 46 47=head1 DESCRIPTION 48 49B<UPX> is a versatile executable packer with the following features: 50 51 - excellent compression ratio: compresses better than zip/gzip, 52 use UPX to decrease the size of your distribution ! 53 54 - very fast decompression: about 10 MiB/sec on an ancient Pentium 133, 55 about 200 MiB/sec on an Athlon XP 2000+. 56 57 - no memory overhead for your compressed executables for most of the 58 supported formats 59 60 - safe: you can list, test and unpack your executables 61 Also, a checksum of both the compressed and uncompressed file is 62 maintained internally. 63 64 - universal: UPX can pack a number of executable formats: 65 * atari/tos 66 * bvmlinuz/386 [bootable Linux kernel] 67 * djgpp2/coff 68 * dos/com 69 * dos/exe 70 * dos/sys 71 * linux/386 72 * linux/elf386 73 * linux/sh386 74 * ps1/exe 75 * rtm32/pe 76 * tmt/adam 77 * vmlinuz/386 [bootable Linux kernel] 78 * vmlinux/386 79 * watcom/le (supporting DOS4G, PMODE/W, DOS32a and CauseWay) 80 * win32/pe (exe and dll) 81 * win64/pe (exe and dll) 82 * arm/pe (exe and dll) 83 * linux/elfamd64 84 * linux/elfppc32 85 * mach/elfppc32 86 87 - portable: UPX is written in portable endian-neutral C++ 88 89 - extendable: because of the class layout it's very easy to support 90 new executable formats or add new compression algorithms 91 92 - free: UPX can be distributed and used freely. And from version 0.99 93 the full source code of UPX is released under the GNU General Public 94 License (GPL) ! 95 96You probably understand now why we call B<UPX> the "I<ultimate>" 97executable packer. 98 99 100 101=head1 COMMANDS 102 103=head2 Compress 104 105This is the default operation, eg. B<upx yourfile.exe> will compress the file 106specified on the command line. 107 108=head2 Decompress 109 110All B<UPX> supported file formats can be unpacked using the B<-d> switch, eg. 111B<upx -d yourfile.exe> will uncompress the file you've just compressed. 112 113=head2 Test 114 115The B<-t> command tests the integrity of the compressed and uncompressed 116data, eg. B<upx -t yourfile.exe> check whether your file can be safely 117decompressed. Note, that this command doesn't check the whole file, only 118the part that will be uncompressed during program execution. This means 119that you should not use this command instead of a virus checker. 120 121=head2 List 122 123The B<-l> command prints out some information about the compressed files 124specified on the command line as parameters, eg B<upx -l yourfile.exe> 125shows the compressed / uncompressed size and the compression ratio of 126I<yourfile.exe>. 127 128 129 130=head1 OPTIONS 131 132B<-q>: be quiet, suppress warnings 133 134B<-q -q> (or B<-qq>): be very quiet, suppress errors 135 136B<-q -q -q> (or B<-qqq>): produce no output at all 137 138B<--help>: prints the help 139 140B<--version>: print the version of B<UPX> 141 142B<--exact>: when compressing, require to be able to get a byte-identical file 143after decompression with option B<-d>. [NOTE: this is work in progress and is 144not supported for all formats yet. If you do care, as a workaround you can 145compress and then decompress your program a first time - any further 146compress-decompress steps should then yield byte-identical results 147as compared to the first decompressed version.] 148 149[ ...to be written... - type `B<upx --help>' for now ] 150 151 152 153=head1 COMPRESSION LEVELS & TUNING 154 155B<UPX> offers ten different compression levels from B<-1> to B<-9>, 156and B<--best>. The default compression level is B<-8> for files 157smaller than 512 KiB, and B<-7> otherwise. 158 159=over 4 160 161=item * 162 163Compression levels 1, 2 and 3 are pretty fast. 164 165=item * 166 167Compression levels 4, 5 and 6 achieve a good time/ratio performance. 168 169=item * 170 171Compression levels 7, 8 and 9 favor compression ratio over speed. 172 173=item * 174 175Compression level B<--best> may take a long time. 176 177=back 178 179Note that compression level B<--best> can be somewhat slow for large 180files, but you definitely should use it when releasing a final version 181of your program. 182 183Quick info for achieving the best compression ratio: 184 185=over 4 186 187=item * 188 189Try B<upx --brute myfile.exe> or even B<upx --ultra-brute myfile.exe>. 190 191=item * 192 193Try if B<--overlay=strip> works. 194 195=item * 196 197For win32/pe programs there's B<--strip-relocs=0>. See notes below. 198 199=back 200 201 202 203=head1 OVERLAY HANDLING OPTIONS 204 205Info: An "overlay" means auxiliary data attached after the logical end of 206an executable, and it often contains application specific data 207(this is a common practice to avoid an extra data file, though 208it would be better to use resource sections). 209 210B<UPX> handles overlays like many other executable packers do: it simply 211copies the overlay after the compressed image. This works with some 212files, but doesn't work with others, depending on how an application 213actually accesses this overlayed data. 214 215 --overlay=copy Copy any extra data attached to the file. [DEFAULT] 216 217 --overlay=strip Strip any overlay from the program instead of 218 copying it. Be warned, this may make the compressed 219 program crash or otherwise unusable. 220 221 --overlay=skip Refuse to compress any program which has an overlay. 222 223 224 225=head1 ENVIRONMENT 226 227The environment variable B<UPX> can hold a set of default 228options for B<UPX>. These options are interpreted first and 229can be overwritten by explicit command line parameters. 230For example: 231 232 for DOS/Windows: set UPX=-9 --compress-icons#0 233 for sh/ksh/zsh: UPX="-9 --compress-icons=0"; export UPX 234 for csh/tcsh: setenv UPX "-9 --compress-icons=0" 235 236Under DOS/Windows you must use '#' instead of '=' when setting the 237environment variable because of a COMMAND.COM limitation. 238 239Not all of the options are valid in the environment variable - 240B<UPX> will tell you. 241 242You can explicitly use the B<--no-env> option to ignore the 243environment variable. 244 245 246 247=head1 NOTES FOR THE SUPPORTED EXECUTABLE FORMATS 248 249=head2 NOTES FOR ATARI/TOS 250 251This is the executable format used by the Atari ST/TT, a Motorola 68000 252based personal computer which was popular in the late '80s. Support 253of this format is only because of nostalgic feelings of one of 254the authors and serves no practical purpose :-). 255See http://www.freemint.de for more info. 256 257Packed programs will be byte-identical to the original after uncompression. 258All debug information will be stripped, though. 259 260Extra options available for this executable format: 261 262 --all-methods Compress the program several times, using all 263 available compression methods. This may improve 264 the compression ratio in some cases, but usually 265 the default method gives the best results anyway. 266 267 268 269=head2 NOTES FOR BVMLINUZ/I386 270 271Same as vmlinuz/i386. 272 273 274 275=head2 NOTES FOR DOS/COM 276 277Obviously B<UPX> won't work with executables that want to read data from 278themselves (like some commandline utilities that ship with Win95/98/ME). 279 280Compressed programs only work on a 286+. 281 282Packed programs will be byte-identical to the original after uncompression. 283 284Maximum uncompressed size: ~65100 bytes. 285 286Extra options available for this executable format: 287 288 --8086 Create an executable that works on any 8086 CPU. 289 290 --all-methods Compress the program several times, using all 291 available compression methods. This may improve 292 the compression ratio in some cases, but usually 293 the default method gives the best results anyway. 294 295 --all-filters Compress the program several times, using all 296 available preprocessing filters. This may improve 297 the compression ratio in some cases, but usually 298 the default filter gives the best results anyway. 299 300 301 302=head2 NOTES FOR DOS/EXE 303 304dos/exe stands for all "normal" 16-bit DOS executables. 305 306Obviously B<UPX> won't work with executables that want to read data from 307themselves (like some command line utilities that ship with Win95/98/ME). 308 309Compressed programs only work on a 286+. 310 311Extra options available for this executable format: 312 313 --8086 Create an executable that works on any 8086 CPU. 314 315 --no-reloc Use no relocation records in the exe header. 316 317 --all-methods Compress the program several times, using all 318 available compression methods. This may improve 319 the compression ratio in some cases, but usually 320 the default method gives the best results anyway. 321 322 323 324=head2 NOTES FOR DOS/SYS 325 326Compressed programs only work on a 286+. 327 328Packed programs will be byte-identical to the original after uncompression. 329 330Maximum uncompressed size: ~65350 bytes. 331 332Extra options available for this executable format: 333 334 --8086 Create an executable that works on any 8086 CPU. 335 336 --all-methods Compress the program several times, using all 337 available compression methods. This may improve 338 the compression ratio in some cases, but usually 339 the default method gives the best results anyway. 340 341 --all-filters Compress the program several times, using all 342 available preprocessing filters. This may improve 343 the compression ratio in some cases, but usually 344 the default filter gives the best results anyway. 345 346 347 348=head2 NOTES FOR DJGPP2/COFF 349 350First of all, it is recommended to use B<UPX> *instead* of B<strip>. strip has 351the very bad habit of replacing your stub with its own (outdated) version. 352Additionally B<UPX> corrects a bug/feature in strip v2.8.x: it 353will fix the 4 KiB alignment of the stub. 354 355B<UPX> includes the full functionality of stubify. This means it will 356automatically stubify your COFF files. Use the option B<--coff> to 357disable this functionality (see below). 358 359B<UPX> automatically handles Allegro packfiles. 360 361The DLM format (a rather exotic shared library extension) is not supported. 362 363Packed programs will be byte-identical to the original after uncompression. 364All debug information and trailing garbage will be stripped, though. 365 366Extra options available for this executable format: 367 368 --coff Produce COFF output instead of EXE. By default 369 UPX keeps your current stub. 370 371 --all-methods Compress the program several times, using all 372 available compression methods. This may improve 373 the compression ratio in some cases, but usually 374 the default method gives the best results anyway. 375 376 --all-filters Compress the program several times, using all 377 available preprocessing filters. This may improve 378 the compression ratio in some cases, but usually 379 the default filter gives the best results anyway. 380 381 382 383=head2 NOTES FOR LINUX [general] 384 385Introduction 386 387 Linux/386 support in UPX consists of 3 different executable formats, 388 one optimized for ELF executables ("linux/elf386"), one optimized 389 for shell scripts ("linux/sh386"), and one generic format 390 ("linux/386"). 391 392 We will start with a general discussion first, but please 393 also read the relevant docs for each of the individual formats. 394 395 Also, there is special support for bootable kernels - see the 396 description of the vmlinuz/386 format. 397 398General user's overview 399 400 Running a compressed executable program trades less space on a 401 ``permanent'' storage medium (such as a hard disk, floppy disk, 402 CD-ROM, flash memory, EPROM, etc.) for more space in one or more 403 ``temporary'' storage media (such as RAM, swap space, /tmp, etc.). 404 Running a compressed executable also requires some additional CPU 405 cycles to generate the compressed executable in the first place, 406 and to decompress it at each invocation. 407 408 How much space is traded? It depends on the executable, but many 409 programs save 30% to 50% of permanent disk space. How much CPU 410 overhead is there? Again, it depends on the executable, but 411 decompression speed generally is at least many megabytes per second, 412 and frequently is limited by the speed of the underlying disk 413 or network I/O. 414 415 Depending on the statistics of usage and access, and the relative 416 speeds of CPU, RAM, swap space, /tmp, and file system storage, then 417 invoking and running a compressed executable can be faster than 418 directly running the corresponding uncompressed program. 419 The operating system might perform fewer expensive I/O operations 420 to invoke the compressed program. Paging to or from swap space 421 or /tmp might be faster than paging from the general file system. 422 ``Medium-sized'' programs which access about 1/3 to 1/2 of their 423 stored program bytes can do particularly well with compression. 424 Small programs tend not to benefit as much because the absolute 425 savings is less. Big programs tend not to benefit proportionally 426 because each invocation may use only a small fraction of the program, 427 yet UPX decompresses the entire program before invoking it. 428 But in environments where disk or flash memory storage is limited, 429 then compression may win anyway. 430 431 Currently, executables compressed by UPX do not share RAM at runtime 432 in the way that executables mapped from a file system do. As a 433 result, if the same program is run simultaneously by more than one 434 process, then using the compressed version will require more RAM and/or 435 swap space. So, shell programs (bash, csh, etc.) and ``make'' 436 might not be good candidates for compression. 437 438 UPX recognizes three executable formats for Linux: Linux/elf386, 439 Linux/sh386, and Linux/386. Linux/386 is the most generic format; 440 it accommodates any file that can be executed. At runtime, the UPX 441 decompression stub re-creates in /tmp a copy of the original file, 442 and then the copy is (re-)executed with the same arguments. 443 ELF binary executables prefer the Linux/elf386 format by default, 444 because UPX decompresses them directly into RAM, uses only one 445 exec, does not use space in /tmp, and does not use /proc. 446 Shell scripts where the underlying shell accepts a ``-c'' argument 447 can use the Linux/sh386 format. UPX decompresses the shell script 448 into low memory, then maps the shell and passes the entire text of the 449 script as an argument with a leading ``-c''. 450 451General benefits: 452 453 - UPX can compress all executables, be it AOUT, ELF, libc4, libc5, 454 libc6, Shell/Perl/Python/... scripts, standalone Java .class 455 binaries, or whatever... 456 All scripts and programs will work just as before. 457 458 - Compressed programs are completely self-contained. No need for 459 any external program. 460 461 - UPX keeps your original program untouched. This means that 462 after decompression you will have a byte-identical version, 463 and you can use UPX as a file compressor just like gzip. 464 [ Note that UPX maintains a checksum of the file internally, 465 so it is indeed a reliable alternative. ] 466 467 - As the stub only uses syscalls and isn't linked against libc it 468 should run under any Linux configuration that can run ELF 469 binaries. 470 471 - For the same reason compressed executables should run under 472 FreeBSD and other systems which can run Linux binaries. 473 [ Please send feedback on this topic ] 474 475General drawbacks: 476 477 - It is not advisable to compress programs which usually have many 478 instances running (like `sh' or `make') because the common segments of 479 compressed programs won't be shared any longer between different 480 processes. 481 482 - `ldd' and `size' won't show anything useful because all they 483 see is the statically linked stub. Since version 0.82 the section 484 headers are stripped from the UPX stub and `size' doesn't even 485 recognize the file format. The file patches/patch-elfcode.h has a 486 patch to fix this bug in `size' and other programs which use GNU BFD. 487 488General notes: 489 490 - As UPX leaves your original program untouched it is advantageous 491 to strip it before compression. 492 493 - If you compress a script you will lose platform independence - 494 this could be a problem if you are using NFS mounted disks. 495 496 - Compression of suid, guid and sticky-bit programs is rejected 497 because of possible security implications. 498 499 - For the same reason there is no sense in making any compressed 500 program suid. 501 502 - Obviously UPX won't work with executables that want to read data 503 from themselves. E.g., this might be a problem for Perl scripts 504 which access their __DATA__ lines. 505 506 - In case of internal errors the stub will abort with exitcode 127. 507 Typical reasons for this to happen are that the program has somehow 508 been modified after compression. 509 Running `strace -o strace.log compressed_file' will tell you more. 510 511 512 513=head2 NOTES FOR LINUX/ELF386 514 515Please read the general Linux description first. 516 517The linux/elf386 format decompresses directly into RAM, 518uses only one exec, does not use space in /tmp, 519and does not use /proc. 520 521Linux/elf386 is automatically selected for Linux ELF executables. 522 523Packed programs will be byte-identical to the original after uncompression. 524 525How it works: 526 527 For ELF executables, UPX decompresses directly to memory, simulating 528 the mapping that the operating system kernel uses during exec(), 529 including the PT_INTERP program interpreter (if any). 530 The brk() is set by a special PT_LOAD segment in the compressed 531 executable itself. UPX then wipes the stack clean except for 532 arguments, environment variables, and Elf_auxv entries (this is 533 required by bugs in the startup code of /lib/ld-linux.so as of 534 May 2000), and transfers control to the program interpreter or 535 the e_entry address of the original executable. 536 537 The UPX stub is about 1700 bytes long, partly written in assembler 538 and only uses kernel syscalls. It is not linked against any libc. 539 540Specific drawbacks: 541 542 - For linux/elf386 and linux/sh386 formats, you will be relying on 543 RAM and swap space to hold all of the decompressed program during 544 the lifetime of the process. If you already use most of your swap 545 space, then you may run out. A system that is "out of memory" 546 can become fragile. Many programs do not react gracefully when 547 malloc() returns 0. With newer Linux kernels, the kernel 548 may decide to kill some processes to regain memory, and you 549 may not like the kernel's choice of which to kill. Running 550 /usr/bin/top is one way to check on the usage of swap space. 551 552Extra options available for this executable format: 553 554 (none) 555 556 557 558=head2 NOTES FOR LINUX/SH386 559 560Please read the general Linux description first. 561 562Shell scripts where the underling shell accepts a ``-c'' argument 563can use the Linux/sh386 format. B<UPX> decompresses the shell script 564into low memory, then maps the shell and passes the entire text of the 565script as an argument with a leading ``-c''. 566It does not use space in /tmp, and does not use /proc. 567 568Linux/sh386 is automatically selected for shell scripts that 569use a known shell. 570 571Packed programs will be byte-identical to the original after uncompression. 572 573How it works: 574 575 For shell script executables (files beginning with "#!/" or "#! /") 576 where the shell is known to accept "-c <command>", UPX decompresses 577 the file into low memory, then maps the shell (and its PT_INTERP), 578 and passes control to the shell with the entire decompressed file 579 as the argument after "-c". Known shells are sh, ash, bash, bsh, csh, 580 ksh, tcsh, pdksh. Restriction: UPX cannot use this method 581 for shell scripts which use the one optional string argument after 582 the shell name in the script (example: "#! /bin/sh option3\n".) 583 584 The UPX stub is about 1700 bytes long, partly written in assembler 585 and only uses kernel syscalls. It is not linked against any libc. 586 587Specific drawbacks: 588 589 - For linux/elf386 and linux/sh386 formats, you will be relying on 590 RAM and swap space to hold all of the decompressed program during 591 the lifetime of the process. If you already use most of your swap 592 space, then you may run out. A system that is "out of memory" 593 can become fragile. Many programs do not react gracefully when 594 malloc() returns 0. With newer Linux kernels, the kernel 595 may decide to kill some processes to regain memory, and you 596 may not like the kernel's choice of which to kill. Running 597 /usr/bin/top is one way to check on the usage of swap space. 598 599Extra options available for this executable format: 600 601 (none) 602 603 604 605=head2 NOTES FOR LINUX/386 606 607Please read the general Linux description first. 608 609The generic linux/386 format decompresses to /tmp and needs 610/proc file system support. It starts the decompressed program 611via the execve() syscall. 612 613Linux/386 is only selected if the specialized linux/elf386 614and linux/sh386 won't recognize a file. 615 616Packed programs will be byte-identical to the original after uncompression. 617 618How it works: 619 620 For files which are not ELF and not a script for a known "-c" shell, 621 UPX uses kernel execve(), which first requires decompressing to a 622 temporary file in the file system. Interestingly - 623 because of the good memory management of the Linux kernel - this 624 often does not introduce a noticeable delay, and in fact there 625 will be no disk access at all if you have enough free memory as 626 the entire process takes places within the file system buffers. 627 628 A compressed executable consists of the UPX stub and an overlay 629 which contains the original program in a compressed form. 630 631 The UPX stub is a statically linked ELF executable and does 632 the following at program startup: 633 634 1) decompress the overlay to a temporary location in /tmp 635 2) open the temporary file for reading 636 3) try to delete the temporary file and start (execve) 637 the uncompressed program in /tmp using /proc/<pid>/fd/X as 638 attained by step 2) 639 4) if that fails, fork off a subprocess to clean up and 640 start the program in /tmp in the meantime 641 642 The UPX stub is about 1700 bytes long, partly written in assembler 643 and only uses kernel syscalls. It is not linked against any libc. 644 645Specific drawbacks: 646 647 - You need additional free disk space for the uncompressed program 648 in your /tmp directory. This program is deleted immediately after 649 decompression, but you still need it for the full execution time 650 of the program. 651 652 - You must have /proc file system support as the stub wants to open 653 /proc/<pid>/exe and needs /proc/<pid>/fd/X. This also means that you 654 cannot compress programs that are used during the boot sequence 655 before /proc is mounted. 656 657 - Utilities like `top' will display numerical values in the process 658 name field. This is because Linux computes the process name from 659 the first argument of the last execve syscall (which is typically 660 something like /proc/<pid>/fd/3). 661 662 - Because of temporary decompression to disk the decompression speed 663 is not as fast as with the other executable formats. Still, I can see 664 no noticeable delay when starting programs like my ~3 MiB emacs (which 665 is less than 1 MiB when compressed :-). 666 667Extra options available for this executable format: 668 669 --force-execve Force the use of the generic linux/386 "execve" 670 format, i.e. do not try the linux/elf386 and 671 linux/sh386 formats. 672 673 674 675=head2 NOTES FOR PS1/EXE 676 677This is the executable format used by the Sony PlayStation (PSone), 678a Mips R3000 based gaming console which is popular since the late '90s. 679Support of this format is very similar to the Atari one, because of 680nostalgic feelings of one of the authors. 681 682Packed programs will be byte-identical to the original after uncompression, 683until further notice. 684 685Maximum uncompressed size: ~1.89 / ~7.60 MiB. 686 687Notes: 688 689 - UPX creates as default a suitable executable for CD-Mastering 690 and console transfer. For a CD-Master main executable you could also try 691 the special option "--boot-only" as described below. 692 It has been reported that upx packed executables are fully compatible with 693 the Sony PlayStation 2 (PS2, PStwo) and Sony PlayStation Portable (PSP) in 694 Sony PlayStation (PSone) emulation mode. 695 696 - Normally the packed files use the same memory areas like the uncompressed 697 versions, so they will not override other memory areas while unpacking. 698 If this isn't possible UPX will abort showing a 'packed data overlap' 699 error. With the "--force" option UPX will relocate the loading address 700 for the packed file, but this isn't a real problem if it is a single or 701 the main executable. 702 703Extra options available for this executable format: 704 705 --all-methods Compress the program several times, using all 706 available compression methods. This may improve 707 the compression ratio in some cases, but usually 708 the default method gives the best results anyway. 709 710 --8-bit Uses 8 bit size compression [default: 32 bit] 711 712 --8mib-ram PSone has 8 MiB ram available [default: 2 MiB] 713 714 --boot-only This format is for main exes and CD-Mastering only ! 715 It may slightly improve the compression ratio, 716 decompression routines are faster than default ones. 717 But it cannot be used for console transfer ! 718 719 --no-align This option disables CD mode 2 data sector format 720 alignment. May slightly improves the compression ratio, 721 but the compressed executable will not boot from a CD. 722 Use it for console transfer only ! 723 724 725 726=head2 NOTES FOR RTM32/PE and ARM/PE 727 728Same as win32/pe. 729 730 731 732=head2 NOTES FOR TMT/ADAM 733 734This format is used by the TMT Pascal compiler - see http://www.tmt.com/ . 735 736Extra options available for this executable format: 737 738 --all-methods Compress the program several times, using all 739 available compression methods. This may improve 740 the compression ratio in some cases, but usually 741 the default method gives the best results anyway. 742 743 --all-filters Compress the program several times, using all 744 available preprocessing filters. This may improve 745 the compression ratio in some cases, but usually 746 the default filter gives the best results anyway. 747 748 749 750=head2 NOTES FOR VMLINUZ/386 751 752The vmlinuz/386 and bvmlinuz/386 formats take a gzip-compressed 753bootable Linux kernel image ("vmlinuz", "zImage", "bzImage"), 754gzip-decompress it and re-compress it with the B<UPX> compression method. 755 756vmlinuz/386 is completely unrelated to the other Linux executable 757formats, and it does not share any of their drawbacks. 758 759Notes: 760 761 - Be sure that "vmlinuz/386" or "bvmlinuz/386" is displayed 762 during compression - otherwise a wrong executable format 763 may have been used, and the kernel won't boot. 764 765Benefits: 766 767 - Better compression (but note that the kernel was already compressed, 768 so the improvement is not as large as with other formats). 769 Still, the bytes saved may be essential for special needs like 770 boot disks. 771 772 For example, this is what I get for my 2.2.16 kernel: 773 1589708 vmlinux 774 641073 bzImage [original] 775 560755 bzImage.upx [compressed by "upx -9"] 776 777 - Much faster decompression at kernel boot time (but kernel 778 decompression speed is not really an issue these days). 779 780Drawbacks: 781 782 (none) 783 784Extra options available for this executable format: 785 786 --all-methods Compress the program several times, using all 787 available compression methods. This may improve 788 the compression ratio in some cases, but usually 789 the default method gives the best results anyway. 790 791 --all-filters Compress the program several times, using all 792 available preprocessing filters. This may improve 793 the compression ratio in some cases, but usually 794 the default filter gives the best results anyway. 795 796 797 798=head2 NOTES FOR WATCOM/LE 799 800B<UPX> has been successfully tested with the following extenders: 801 DOS4G, DOS4GW, PMODE/W, DOS32a, CauseWay. 802 The WDOS/X extender is partly supported (for details 803 see the file bugs BUGS). 804 805DLLs and the LX format are not supported. 806 807Extra options available for this executable format: 808 809 --le Produce an unbound LE output instead of 810 keeping the current stub. 811 812 813 814=head2 NOTES FOR WIN32/PE 815 816The PE support in B<UPX> is quite stable now, but probably there are 817still some incompatibilities with some files. 818 819Because of the way B<UPX> (and other packers for this format) works, you 820can see increased memory usage of your compressed files because the whole 821program is loaded into memory at startup. 822If you start several instances of huge compressed programs you're 823wasting memory because the common segments of the program won't 824get shared across the instances. 825On the other hand if you're compressing only smaller programs, or 826running only one instance of larger programs, then this penalty is 827smaller, but it's still there. 828 829If you're running executables from network, then compressed programs 830will load faster, and require less bandwidth during execution. 831 832DLLs are supported. But UPX compressed DLLs can not share common data and 833code when they got used by multiple applications. So compressing msvcrt.dll 834is a waste of memory, but compressing the dll plugins of a particular 835application may be a better idea. 836 837Screensavers are supported, with the restriction that the filename 838must end with ".scr" (as screensavers are handled slightly different 839than normal exe files). 840 841UPX compressed PE files have some minor memory overhead (usually in the 84210 - 30 KiB range) which can be seen by specifying the "-i" command 843line switch during compression. 844 845Extra options available for this executable format: 846 847 --compress-exports=0 Don't compress the export section. 848 Use this if you plan to run the compressed 849 program under Wine. 850 --compress-exports=1 Compress the export section. [DEFAULT] 851 Compression of the export section can improve the 852 compression ratio quite a bit but may not work 853 with all programs (like winword.exe). 854 UPX never compresses the export section of a DLL 855 regardless of this option. 856 857 --compress-icons=0 Don't compress any icons. 858 --compress-icons=1 Compress all but the first icon. 859 --compress-icons=2 Compress all icons which are not in the 860 first icon directory. [DEFAULT] 861 --compress-icons=3 Compress all icons. 862 863 --compress-resources=0 Don't compress any resources at all. 864 865 --keep-resource=list Don't compress resources specified by the list. 866 The members of the list are separated by commas. 867 A list member has the following format: I<type[/name]>. 868 I<Type> is the type of the resource. Standard types 869 must be specified as decimal numbers, user types can be 870 specified by decimal IDs or strings. I<Name> is the 871 identifier of the resource. It can be a decimal number 872 or a string. For example: 873 874 --keep-resource=2/MYBITMAP,5,6/12345 875 876 UPX won't compress the named bitmap resource "MYBITMAP", 877 it leaves every dialog (5) resource uncompressed, and 878 it won't touch the string table resource with identifier 879 12345. 880 881 --force Force compression even when there is an 882 unexpected value in a header field. 883 Use with care. 884 885 --strip-relocs=0 Don't strip relocation records. 886 --strip-relocs=1 Strip relocation records. [DEFAULT] 887 This option only works on executables with base 888 address greater or equal to 0x400000. Usually the 889 compressed files becomes smaller, but some files 890 may become larger. Note that the resulting file will 891 not work under Windows 3.x (Win32s). 892 UPX never strips relocations from a DLL 893 regardless of this option. 894 895 --all-methods Compress the program several times, using all 896 available compression methods. This may improve 897 the compression ratio in some cases, but usually 898 the default method gives the best results anyway. 899 900 --all-filters Compress the program several times, using all 901 available preprocessing filters. This may improve 902 the compression ratio in some cases, but usually 903 the default filter gives the best results anyway. 904 905 906 907=head1 DIAGNOSTICS 908 909Exit status is normally 0; if an error occurs, exit status 910is 1. If a warning occurs, exit status is 2. 911 912B<UPX>'s diagnostics are intended to be self-explanatory. 913 914 915 916=head1 BUGS 917 918Please report all bugs immediately to the authors. 919 920 921 922=head1 AUTHORS 923 924 Markus F.X.J. Oberhumer <markus@oberhumer.com> 925 http://www.oberhumer.com 926 927 Laszlo Molnar <ezerotven+github@gmail.com> 928 929 John F. Reiser <jreiser@BitWagon.com> 930 931 Jens Medoch <jssg@users.sourceforge.net> 932 933 934 935=head1 COPYRIGHT 936 937Copyright (C) 1996-2020 Markus Franz Xaver Johannes Oberhumer 938 939Copyright (C) 1996-2020 Laszlo Molnar 940 941Copyright (C) 2000-2020 John F. Reiser 942 943Copyright (C) 2002-2020 Jens Medoch 944 945This program may be used freely, and you are welcome to 946redistribute it under certain conditions. 947 948This program is distributed in the hope that it will be useful, 949but WITHOUT ANY WARRANTY; without even the implied warranty of 950MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 951B<UPX License Agreement> for more details. 952 953You should have received a copy of the UPX License Agreement along 954with this program; see the file LICENSE. If not, visit the UPX home page. 955 956