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