diff --git a/import/upx/bin/upx.exe b/import/upx/bin/upx.exe index 05a8758a3..f1fbc8cb7 100644 Binary files a/import/upx/bin/upx.exe and b/import/upx/bin/upx.exe differ diff --git a/import/upx/doc/BUGS b/import/upx/doc/BUGS new file mode 100644 index 000000000..721df810c --- /dev/null +++ b/import/upx/doc/BUGS @@ -0,0 +1,51 @@ + ooooo ooo ooooooooo. ooooooo ooooo + `888' `8' `888 `Y88. `8888 d8' + 888 8 888 .d88' Y888..8P + 888 8 888ooo88P' `8888' + 888 8 888 .8PY888. + `88. .8' 888 d8' `888b + `YbodP' o888o o888o o88888o + + + The Ultimate Packer for eXecutables + Copyright (c) 1996-2006 Markus Oberhumer, Laszlo Molnar & John Reiser + http://upx.sourceforge.net + + +Limitations and other things which are not (yet) supported: +=========================================================== + +djgpp2/coff +----------- + * all overlays (except Allegro pakfiles) are silently stripped + +dos/exe +------- + * normal dos/exes with new exe headers + * max ~24000 relocation records (...should be enough for everyone ;-) + * exe + sys combined images + +watcom/le +--------- + * 16-bit selector alias fixups + * 16-bit offset relocation for objects larger than 4 kB + * 16:16 fixups + +If you need any of the above (they're very rare), send us an URL of a +test file. + + * 16-bit objects are not loaded into DOS memory + * There is still a problem with the wdosx extender: if you compress a + watcom/le file which does NOT contain the wdosx extender, and after this + you bind the wdosx stub to the compressed file, then it will work. + Otherwise it won't. + * unpacked pmwlite compressed programs might not work when compressed + with UPX (this is a bug in pmwunlite) + +win32/pe +-------- + * writeable shared sections (`--force' *may* work) + * certificates in the image + * compressing files which contain a big BSS requires lots of memory + during compression + diff --git a/import/upx/doc/COPYING b/import/upx/doc/COPYING new file mode 100644 index 000000000..b4951ab75 --- /dev/null +++ b/import/upx/doc/COPYING @@ -0,0 +1,340 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc. + 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +License is intended to guarantee your freedom to share and change free +software--to make sure the software is free for all its users. This +General Public License applies to most of the Free Software +Foundation's software and to any other program whose authors commit to +using it. (Some other Free Software Foundation software is covered by +the GNU Library General Public License instead.) You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +this service if you wish), that you receive source code or can get it +if you want it, that you can change the software or use pieces of it +in new free programs; and that you know you can do these things. + + To protect your rights, we need to make restrictions that forbid +anyone to deny you these rights or to ask you to surrender the rights. +These restrictions translate to certain responsibilities for you if you +distribute copies of the software, or if you modify it. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must give the recipients all the rights that +you have. You must make sure that they, too, receive or can get the +source code. And you must show them these terms so they know their +rights. + + We protect your rights with two steps: (1) copyright the software, and +(2) offer you this license which gives you legal permission to copy, +distribute and/or modify the software. + + Also, for each author's protection and ours, we want to make certain +that everyone understands that there is no warranty for this free +software. If the software is modified by someone else and passed on, we +want its recipients to know that what they have is not the original, so +that any problems introduced by others will not reflect on the original +authors' reputations. + + Finally, any free program is threatened constantly by software +patents. We wish to avoid the danger that redistributors of a free +program will individually obtain patent licenses, in effect making the +program proprietary. To prevent this, we have made it clear that any +patent must be licensed for everyone's free use or not licensed at all. + + The precise terms and conditions for copying, distribution and +modification follow. + + GNU GENERAL PUBLIC LICENSE + TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION + + 0. This License applies to any program or other work which contains +a notice placed by the copyright holder saying it may be distributed +under the terms of this General Public License. The "Program", below, +refers to any such program or work, and a "work based on the Program" +means either the Program or any derivative work under copyright law: +that is to say, a work containing the Program or a portion of it, +either verbatim or with modifications and/or translated into another +language. (Hereinafter, translation is included without limitation in +the term "modification".) Each licensee is addressed as "you". + +Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running the Program is not restricted, and the output from the Program +is covered only if its contents constitute a work based on the +Program (independent of having been made by running the Program). +Whether that is true depends on what the Program does. + + 1. You may copy and distribute verbatim copies of the Program's +source code as you receive it, in any medium, provided that you +conspicuously and appropriately publish on each copy an appropriate +copyright notice and disclaimer of warranty; keep intact all the +notices that refer to this License and to the absence of any warranty; +and give any other recipients of the Program a copy of this License +along with the Program. + +You may charge a fee for the physical act of transferring a copy, and +you may at your option offer warranty protection in exchange for a fee. + + 2. You may modify your copy or copies of the Program or any portion +of it, thus forming a work based on the Program, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + + a) You must cause the modified files to carry prominent notices + stating that you changed the files and the date of any change. + + b) You must cause any work that you distribute or publish, that in + whole or in part contains or is derived from the Program or any + part thereof, to be licensed as a whole at no charge to all third + parties under the terms of this License. + + c) If the modified program normally reads commands interactively + when run, you must cause it, when started running for such + interactive use in the most ordinary way, to print or display an + announcement including an appropriate copyright notice and a + notice that there is no warranty (or else, saying that you provide + a warranty) and that users may redistribute the program under + these conditions, and telling the user how to view a copy of this + License. (Exception: if the Program itself is interactive but + does not normally print such an announcement, your work based on + the Program is not required to print an announcement.) + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Program, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Program, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Program. + +In addition, mere aggregation of another work not based on the Program +with the Program (or with a work based on the Program) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + + 3. You may copy and distribute the Program (or a work based on it, +under Section 2) in object code or executable form under the terms of +Sections 1 and 2 above provided that you also do one of the following: + + a) Accompany it with the complete corresponding machine-readable + source code, which must be distributed under the terms of Sections + 1 and 2 above on a medium customarily used for software interchange; or, + + b) Accompany it with a written offer, valid for at least three + years, to give any third party, for a charge no more than your + cost of physically performing source distribution, a complete + machine-readable copy of the corresponding source code, to be + distributed under the terms of Sections 1 and 2 above on a medium + customarily used for software interchange; or, + + c) Accompany it with the information you received as to the offer + to distribute corresponding source code. (This alternative is + allowed only for noncommercial distribution and only if you + received the program in object code or executable form with such + an offer, in accord with Subsection b above.) + +The source code for a work means the preferred form of the work for +making modifications to it. For an executable work, complete source +code means all the source code for all modules it contains, plus any +associated interface definition files, plus the scripts used to +control compilation and installation of the executable. However, as a +special exception, the source code distributed need not include +anything that is normally distributed (in either source or binary +form) with the major components (compiler, kernel, and so on) of the +operating system on which the executable runs, unless that component +itself accompanies the executable. + +If distribution of executable or object code is made by offering +access to copy from a designated place, then offering equivalent +access to copy the source code from the same place counts as +distribution of the source code, even though third parties are not +compelled to copy the source along with the object code. + + 4. You may not copy, modify, sublicense, or distribute the Program +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense or distribute the Program is +void, and will automatically terminate your rights under this License. +However, parties who have received copies, or rights, from you under +this License will not have their licenses terminated so long as such +parties remain in full compliance. + + 5. You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Program or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Program (or any work based on the +Program), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Program or works based on it. + + 6. Each time you redistribute the Program (or any work based on the +Program), the recipient automatically receives a license from the +original licensor to copy, distribute or modify the Program subject to +these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties to +this License. + + 7. If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Program at all. For example, if a patent +license would not permit royalty-free redistribution of the Program by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Program. + +If any portion of this section is held invalid or unenforceable under +any particular circumstance, the balance of the section is intended to +apply and the section as a whole is intended to apply in other +circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system, which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + + 8. If the distribution and/or use of the Program is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Program under this License +may add an explicit geographical distribution limitation excluding +those countries, so that distribution is permitted only in or among +countries not thus excluded. In such case, this License incorporates +the limitation as if written in the body of this License. + + 9. The Free Software Foundation may publish revised and/or new versions +of the General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies a version number of this License which applies to it and "any +later version", you have the option of following the terms and conditions +either of that version or of any later version published by the Free +Software Foundation. If the Program does not specify a version number of +this License, you may choose any version ever published by the Free Software +Foundation. + + 10. If you wish to incorporate parts of the Program into other free +programs whose distribution conditions are different, write to the author +to ask for permission. For software which is copyrighted by the Free +Software Foundation, write to the Free Software Foundation; we sometimes +make exceptions for this. Our decision will be guided by the two goals +of preserving the free status of all derivatives of our free software and +of promoting the sharing and reuse of software generally. + + NO WARRANTY + + 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY +FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN +OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES +PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED +OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS +TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE +PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, +REPAIR OR CORRECTION. + + 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR +REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING +OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED +TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY +YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER +PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE +POSSIBILITY OF SUCH DAMAGES. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) 19yy + + This program is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; if not, write to the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA + + +Also add information on how to contact you by electronic and paper mail. + +If the program is interactive, make it output a short notice like this +when it starts in an interactive mode: + + Gnomovision version 69, Copyright (C) 19yy name of author + Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, the commands you use may +be called something other than `show w' and `show c'; they could even be +mouse-clicks or menu items--whatever suits your program. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. Here is a sample; alter the names: + + Yoyodyne, Inc., hereby disclaims all copyright interest in the program + `Gnomovision' (which makes passes at compilers) written by James Hacker. + + , 1 April 1989 + Ty Coon, President of Vice + +This General Public License does not permit incorporating your program into +proprietary programs. If your program is a subroutine library, you may +consider it more useful to permit linking proprietary applications with the +library. If this is what you want to do, use the GNU Library General +Public License instead of this License. diff --git a/import/upx/doc/LICENSE b/import/upx/doc/LICENSE new file mode 100644 index 000000000..444ded8d9 --- /dev/null +++ b/import/upx/doc/LICENSE @@ -0,0 +1,138 @@ +-----BEGIN PGP SIGNED MESSAGE----- + + + ooooo ooo ooooooooo. ooooooo ooooo + `888' `8' `888 `Y88. `8888 d8' + 888 8 888 .d88' Y888..8P + 888 8 888ooo88P' `8888' + 888 8 888 .8PY888. + `88. .8' 888 d8' `888b + `YbodP' o888o o888o o88888o + + + The Ultimate Packer for eXecutables + Copyright (c) 1996-2000 Markus Oberhumer & Laszlo Molnar + http://wildsau.idv.uni-linz.ac.at/mfx/upx.html + http://www.nexus.hu/upx + http://upx.tsx.org + + +PLEASE CAREFULLY READ THIS LICENSE AGREEMENT, ESPECIALLY IF YOU PLAN +TO MODIFY THE UPX SOURCE CODE OR USE A MODIFIED UPX VERSION. + + +ABSTRACT +======== + + UPX and UCL are copyrighted software distributed under the terms + of the GNU General Public License (hereinafter the "GPL"). + + The stub which is imbedded in each UPX compressed program is part + of UPX and UCL, and contains code that is under our copyright. The + terms of the GNU General Public License still apply as compressing + a program is a special form of linking with our stub. + + As a special exception we grant the free usage of UPX for all + executables, including commercial programs. + See below for details and restrictions. + + +COPYRIGHT +========= + + UPX and UCL are copyrighted software. All rights remain with the authors. + + UPX is Copyright (C) 1996-2000 Markus Franz Xaver Johannes Oberhumer + UPX is Copyright (C) 1996-2000 Laszlo Molnar + + UCL is Copyright (C) 1996-2000 Markus Franz Xaver Johannes Oberhumer + + +GNU GENERAL PUBLIC LICENSE +========================== + + UPX and the UCL library are free software; you can redistribute them + and/or modify them under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2 of + the License, or (at your option) any later version. + + UPX and UCL are distributed in the hope that they will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program; see the file COPYING. + + +SPECIAL EXCEPTION FOR COMPRESSED EXECUTABLES +============================================ + + The stub which is imbedded in each UPX compressed program is part + of UPX and UCL, and contains code that is under our copyright. The + terms of the GNU General Public License still apply as compressing + a program is a special form of linking with our stub. + + Hereby Markus F.X.J. Oberhumer and Laszlo Molnar grant you special + permission to freely use and distribute all UPX compressed programs + (including commercial ones), subject to the following restrictions: + + 1. You must compress your program with a completely unmodified UPX + version; either with our precompiled version, or (at your option) + with a self compiled version of the unmodified UPX sources as + distributed by us. + 2. This also implies that the UPX stub must be completely unmodfied, i.e. + the stub imbedded in your compressed program must be byte-identical + to the stub that is produced by the official unmodified UPX version. + 3. The decompressor and any other code from the stub must exclusively get + used by the unmodified UPX stub for decompressing your program at + program startup. No portion of the stub may get read, copied, + called or otherwise get used or accessed by your program. + + +ANNOTATIONS +=========== + + - You can use a modified UPX version or modified UPX stub only for + programs that are compatible with the GNU General Public License. + + - We grant you special permission to freely use and distribute all UPX + compressed programs. But any modification of the UPX stub (such as, + but not limited to, removing our copyright string or making your + program non-decompressible) will immediately revoke your right to + use and distribute a UPX compressed program. + + - UPX is not a software protection tool; by requiring that you use + the unmodified UPX version for your proprietary programs we + make sure that any user can decompress your program. This protects + both you and your users as nobody can hide malicious code - + any program that cannot be decompressed is highly suspicious + by definition. + + - You can integrate all or part of UPX and UCL into projects that + are compatible with the GNU GPL, but obviously you cannot grant + any special exceptions beyond the GPL for our code in your project. + + - We want to actively support manufacturers of virus scanners and + similar security software. Please contact us if you would like to + incorporate parts of UPX or UCL into such a product. + + + +Markus F.X.J. Oberhumer Laszlo Molnar +markus.oberhumer@jk.uni-linz.ac.at ml1050@cdata.tvnet.hu + +Linz, Austria, 25 Feb 2000 + + + +-----BEGIN PGP SIGNATURE----- +Version: 2.6.3ia +Charset: noconv + +iQCVAwUBOLaLS210fyLu8beJAQFYVAP/ShzENWKLTvedLCjZbDcwaBEHfUVcrGMI +wE7frMkbWT2zmkdv9hW90WmjMhOBu7yhUplvN8BKOtLiolEnZmLCYu8AGCwr5wBf +dfLoClxnzfTtgQv5axF1awp4RwCUH3hf4cDrOVqmAsWXKPHtm4hx96jF6L4oHhjx +OO03+ojZdO8= +=CS52 +-----END PGP SIGNATURE----- diff --git a/import/upx/doc/NEWS b/import/upx/doc/NEWS new file mode 100644 index 000000000..daa16b4fd --- /dev/null +++ b/import/upx/doc/NEWS @@ -0,0 +1,365 @@ +================================================================== +User visible changes for UPX +================================================================== + +Changes in 2.01 (06 Jun 2006): + * arm/pe: better DLL support + * dos/exe: device driver support added + * linux/386: Fix --force-execve for PaX, grSecurity, and strict SELinux. + /tmp must support execve(); therefore /tmp cannot be mounted 'noexec'. + * win32/pe & arm/pe: added new option '--keep-resource=' for + excluding selected resources from compression + +Changes in 2.00 (27 Apr 2006): + * linux/386: the stub now prints an error message if some strict + SELinux mode does prevent runtime decompression and execution + (for a fully SELinux-compatible but otherwise inferior compression + format you can use the '--force-execve' option) + * linux/386: worked around a problem where certain Linux kernels + clobber the %ebx register during a syscall + * win32/pe: disable filters for files with broken PE headers + +Changes in 1.96 beta (13 Apr 2006): + * arm/pe: added filter support + * win32/pe: removed an unnecessary check so that Delphi 2006 and + Digital Mars C++ programs finally are supported + +Changes in 1.95 beta (09 Apr 2006): + * arm/pe: added DLL support + * arm/pe: added thumb mode stub support + * arm/pe: added unpacking support + * win32/pe: really worked around R6002 runtime errors + +Changes in 1.94 beta (11 Mar 2006): + * new format: added support for arm/pe (ARM executables running on WinCE) + * new format: added support for linux elf/amd64 + * new format: added support for linux elf/ppc32 + * new format: added support for mach/ppc32 (Apple Mac OS X) + * win32/pe: hopefully working "load config" support + * win32/pe: R6002 runtime errors worked around + * win32/pe: the stub now clears the dirty stack + +Changes in 1.93 beta (07 Feb 2005): + * vmlinuz/386: fixes to support more kernels + +Changes in 1.92 beta (20 Jul 2004): + * win32/pe: added option '--strip-loadconf' to strip the SEH load + config section [NOTE: this option is obsolete since UPX 1.94] + * win32/pe: try to detect .NET (win32/net) files [not yet supported by UPX] + * vmlinux/386: new format that directly supports building Linux kernels + * source code: now compiles cleanly under Win64 + +Changes in 1.91 beta (30 Jun 2004): + * djgpp2/coff: added support for recent binutils versions + * linux/elf386, linux/sh386: lots of improvements + * vmlinuz/386: added support for recent kernels + * watcom/le: don't crash on files without relocations + * win32/pe: stricter checks of some PE values + * option '--brute' now implies '--crp-ms=999999'. + * source code: much improved portability using ACC, the + Automatic Compiler Configuration + * source code: compile fixes for strict ISO C++ compilers + * source code: compile fixes for Win64 + * re-synced with upx 1.25 branch + +Changes in 1.90 beta (11 Nov 2002): + * implemented several new options for finer compression control: + '--all-methods', '--all-filters' and '--brute' + * ps1/exe: new format - UPX now supports PlayStation One programs + * linux/386: added the option '--force-execve' + * vmlinuz/386: better kernel detection and sanity checks + * re-synced with upx 1.24 branch + * documentation updates + +Changes in 1.11 beta (20 Dec 2000): + * vmlinuz/386: new format - UPX now supports bootable linux kernels + * linux/elf386: added the new ELF direct-to-memory executable format - no + more temp files are needed for decompression! + * linux/sh386: added the new shell direct-to-memory executable format - no + more temp files are needed for decompression! + * reduced overall memory requirements during packing + * quite a number of internal source code rearrangements + +================================================================== + +Changes in 1.25 (29 Jun 2004) + * INFO: http://upx.sourceforge.net is the permanent UPX home page + * watcom/le: don't crash on files without relocations + * win32/pe: stricter checks of some PE values + * source code: much improved portability using ACC, the + Automatic Compiler Configuration + * source code: compile fixes for strict ISO C++ compilers + * source code: compile fixes for Win64 + +Changes in 1.24 (07 Nov 2002) + * djgpp2/coff: stricter check of the COFF header to work around a + problem with certain binutils versions + +Changes in 1.23 (05 Sep 2002) + * atari/tos: fixed an unpacking problem where a buffer was too + small (introduced in 1.22) + * linux/386: don't give up too early if a single block turns out + to be incompressible + * documentation: added some quick tips how to achieve the best + compression ratio for the final release of your application + * fixed a rare situation where the exit code was not set correctly + +Changes in 1.22 (27 Jun 2002) + * atari/tos: the stub now flushes the CPU cache to avoid + problems on 68030+ machines + * source code: additional compiler support for Borland C++, + Digital Mars C++ and Watcom C++ + +Changes in 1.21 (01 Jun 2002) + * New option '--crp-ms=' for slightly better compression at the cost + of higher memory requirements during compression. + Try 'upx --best --crp-ms=100000'. See the docs for more info. + * source code: portability fixes + * source code: compile fixes for g++ 3.0 and g++ 3.1 + +Changes in 1.20 (23 May 2001) + * slightly faster compression + * work around a gcc problem in the latest djgpp2 distribution + * watcom/le: fixed detection of already compressed files + * win32/pe: do not compress RT_MANIFEST resource types + * win32/pe: improved the error message for empty resource sections + * [NOTE: the jump from 1.08 to 1.20 is to avoid confusion with + our unstable development releases 1.1x and 1.9x] + +Changes in 1.08 (30 Apr 2001) + * new native port to atari/tos + * win32/pe: shortened the identstring + * source code: portability fixes - UPX now builds cleanly under m68k CPUs + +Changes in 1.07 (20 Feb 2001) + * win32/pe: corrected the TLS callback check + * win32/pe: really fixed that rare bug in relocation handling + * win32/pe: experimental support for SizeOfHeaders > 0x1000 + * win32/pe: check for superfluous data between sections + * win32/pe: compressing screensavers (.scr) should finally work + +Changes in 1.06 (27 Jan 2001) + * win32/pe: the check for TLS callbacks introduced in 1.05 + was too strict - disabled for now + * dos/com: decreased the decompressor stack size a little bit + +Changes in 1.05 (24 Jan 2001) + * win32/pe: refuse to compress programs with TLS callbacks + * win32/pe: stub changes to avoid slowdowns with some virus monitors + * win32/pe: reverted the relocation handling changes in 1.04 + * linux/386: dont try to compress Linux kernel images (have a look + at the unstable UPX 1.1x beta versions for that) + +Changes in 1.04 (19 Dec 2000) + * dos/exe: fixed an internal error when using '--no-reloc' + * win32/pe: fixed a rare bug in the relocation handling code + * some tunings for the default compression level + +Changes in 1.03 (30 Nov 2000) + * linked with a new version of the NRV compression library: + - improved compression ratio a little bit + - overall significantly faster compression + - much faster when using high compression levels like '-9' or '--best' + - much faster with large files + * atari/tos: added support for FreeMiNT + * the 32-bit DOS version now uses the new CWSDSTUB extender + +Changes in 1.02 (13 Sep 2000) + * watcom/le: fixed a problem with the Causeway extender + * win32/pe: don't automatically strip relocs if they seem needed + * support multiple backup generations when using '-k' + * updated the console screen driver + +Changes in 1.01 (09 Apr 2000) + * win32/pe: fixed an uncompression problem in DLLs with empty + fixup sections + * win32/pe: fixed another rare uncompression problem - a field in the + PE header was set incorrectly + +Changes in 1.00 (26 Mar 2000) + * documentation updates + * watcom/le: do not duplicate the non-resident name table + * win32/pe: fixed an import handling problem: sometimes too much data + could be deleted from a file -> the uncompressed file would not work + anymore + +Changes in 0.99.3 (07 Mar 2000) + * win32/pe: fixed a rare problem in the stub string handling part + +Changes in 0.99.2 (02 Mar 2000) + * dos/exe: fixed a typo causing an internal error (introduced in 0.99.1) + +Changes in 0.99.1 (29 Feb 2000) + * win32/pe: fixed some object alignments which were causing + problems when loading compressed DLLs under Windows NT/2000 + +Changes in 0.99 (25 Feb 2000) + * FULL SOURCE CODE RELEASED UNDER THE TERMS OF THE GNU GPL + * win32/pe: changed default to '--strip-relocs=1' + * dos/com and dos/sys: fixed a bad decompressor problem + * linux/386: the counter for the progress indicator was off by one + +Changes in 0.94 (06 Dec 1999) + * win32/pe: the stub now calls ExitProcess in case of import errors + * under DOS and Windows, the environment variable UPX now accepts + a '#' as replacement for '=' because of a COMMAND.COM limitation + +Changes in 0.93 (22 Nov 1999) + * win32/pe: fixed --strip-relocs problem with uncompression + * win32/pe: fixed a bug which could produce a broken decompressor stub + * linux/386: yet another FreeBSD compatibility fix + +Changes in 0.92 (14 Nov 1999) + * win32/pe: really fixed that one line (see below) + +Changes in 0.91 (13 Nov 1999) + * win32/pe: an important one-line fix for the newly introduced problems + * dos/com and dos/sys: fixed an internal error + * dos/exe: correctly restore cs when uncompressing + +Changes in 0.90 (10 Nov 1999) + * all formats: '--overlay=copy' now is the default overlay mode + * improved compression ratio for most files + * win32/pe: uncompression is finally supported + * win32/pe: never compress REGISTRY resources + * win32/pe: headersize was not set in PE header + * win32/pe: resource handling is rewritten + * win32/pe: the last :-) TLS problem is fixed + * win32/pe: somewhat less memory is required during compression + * linux/386: fixed compression of scripts which was broken since 0.71 + * linux/386: more FreeBSD compatibility issues + * changed option: '-i' now prints some more details during compression + (not finished yet) + +Changes in 0.84 (04 Oct 1999) + * dos/exe: fixed a rare problem where the decompressor could crash + * some other minor fixes + +Changes in 0.83 (17 Sep 1999) + * dos/exe: fixed minimal memory requirement problem for some files + * win32/pe: fixed a bug which caused a crash in some compressed files + * linux/386: various improvements in the stub; also, for the sake + of FreeBSD users, the stub is now branded as Linux/ELF + +Changes in 0.82 (16 Aug 1999) + * dos/exe: fixed a decompressor bug which could cause crash on some files + * linux/386: section headers are now stripped from the stub so that + 'strip' won't ruin a compressed file any longer + * wc/le: support for stack not in the last object disabled again + * win32/pe: removed some unneeded data + +Changes in 0.81 (04 Aug 1999) + * win32/pe: fixed an important bug in import handling + * dos/com: fixed an internal error that could happen with very small files + +Changes in 0.80 (03 Aug 1999) + * you can set some default options in the environment var 'UPX' + * dos/com: the decompressor stub now checks for enough free memory + * dos/exe: decompressor rewritten, some bugs are fixed + * dos/exe: new option '--no-reloc': no relocation data is put into + the DOS header + * tmt/adam: added support for more stubs, detect already packed files + * tmt/adam: new option '--copy-overlay' + * wc/le: reduced memory requirement during uncompression + * wc/le: support files which do not contain their stack in the last object + * wc/le: fixed a bug which could cause a crash, improved relocation + handling + * wc/le: new option '--copy-overlay' + * win32/pe: '--compress-icons=2' is now the default + * win32/pe: even better TLS support + * win32/pe: versioninfo works on NT + * win32/pe: import by ordinal from kernel32.dll works + * win32/pe: other import improvements: importing a nonexistant DLL + results in a usual Windows message, importing a nonexistant function + results in program exit (instead of crash ;-) + * win32/pe: new option: '--compress-resources=0' + * win32/pe: reduced memory requirement during uncompression, some + files might even require LESS memory when they're compressed + * win32/pe: TYPELIBs should work now + * win32/pe: improved relocation handling, 16-bit relocations should work + * win32/pe: new option '--strip-relocs' (only if you know what you are doing) + * win32/pe: new option '--copy-overlay' + * important internal changes: now the stubs are built at runtime + +Changes in 0.72 (12 May 1999) + * tmt/adam: fixed a serious problem in the decompressor stub; all + compressed tmt files should be recompressed + * win32/pe: fixed the 'shared sections not supported' warning: + read-only shared sections are fine + * win32/pe: never compress TYPELIB resources + * win32/pe: compressed files are hopefully less suspicious to heuristic + virus scanners now + * linux/386: minor decompressor stub updates, nicer progress bar + +Changes in 0.71 (19 Apr 1999) + * dos/exe: added option '--no-overlay' + * linux/386: various improvements in the stub, most notably the + overhead for an extra cleanup process has been removed + * win32/pe: added support for export forwarders + * win32/pe: added support for DLLs without entry point or imports + * win32/pe: yet another .bss fix + * win32/pe: new option '--compress-icons=2': compress all icons + which are not in the first icon directory + * win32/pe: rearranged stub to avoid false alerts from some virus scanners + +Changes in 0.70 (30 Mar 1999) + * added support for linux/386 executables + * improved compression ratio quite a bit + * added new compression level '--best' to squeeze out even some more bytes + * win32/pe: TLS support is much better now + * win32/pe: --compress-icons=0 should now work as well + * the usual minor fixes for win32/pe + +Changes in 0.62 (16 Mar 1999) + * win32/pe: --compress-icons and --compress-exports are on now by default + * win32/pe: --compress-icons should really work now + * win32/pe: fixed a problem with embedded .bss sections + +Changes in 0.61 (08 Mar 1999) + * atari/tos: fixed a problem where the bss segment could become too small + +Changes in 0.60 (06 Mar 1999) + * win32/pe: fixed file corruption when the size of the export data is invalid + * win32/pe: fixed a problem with empty resource data + * win32/pe: compressed file alignment set to minimum value + * win32/pe: made all compressed sections writeable + * fixed some other win32/pe bugs + * fixed an address optimization problem for some not Watcom LE files + * fixed a bug which could make UPX hang when an exe header contained + an illegal value + * added some compression flags for the win32/pe format + * added support for Atari ST/TT executables (atari/tos) + * improved compression ratio + * improved compression speed + +Changes in 0.51 (14 Jan 1999) + * fixed a small bug in the PE header that would prevent some compressed + win32/pe executables from running under Windows NT and WINE + +Changes in 0.50 (03 Jan 1999) + * added support for PE format executables (win32/pe & rtm32/pe) + * added support for TMT executables (tmt/adam) + * fixed a dos/sys bug that affected OpenDOS + +Changes in 0.40 (05 Oct 1998) + * improved compression ratio + * fixed a small but fatal bug in dos/sys introduced in 0.30 + * fixed a rare bug in dos/exe + * worked around a bug in djgpp's strip 2.8 + * djgpp/coff: Allegro packfile support should work now + * added dos/exeh compression method (works on 386+) + +Changes in 0.30 (27 Jul 1998) + * fixed a serious bug in the 32-bit compressors - please don't use + djgpp/coff and watcom/le compressed files from previous versions, + some of them are possibly damaged ! + * the 16-bit uncompressors are a little bit shorter & faster + * fixed progress indicator for VESA and SVGA text modes + +Changes in 0.20 (05 Jul 1998) + * second public beta release + * too many changes to list here + +Changes in 0.05 (26 May 1998) + * first public beta release + diff --git a/import/upx/doc/README b/import/upx/doc/README new file mode 100644 index 000000000..1ba65dd7a --- /dev/null +++ b/import/upx/doc/README @@ -0,0 +1,142 @@ + ooooo ooo ooooooooo. ooooooo ooooo + `888' `8' `888 `Y88. `8888 d8' + 888 8 888 .d88' Y888..8P + 888 8 888ooo88P' `8888' + 888 8 888 .8PY888. + `88. .8' 888 d8' `888b + `YbodP' o888o o888o o88888o + + + The Ultimate Packer for eXecutables + Copyright (c) 1996-2006 Markus Oberhumer, Laszlo Molnar & John Reiser + http://upx.sourceforge.net + + + +WELCOME +======= + +Welcome to UPX ! + +Please don't forget to read the file LICENSE - UPX is distributed +under the GNU General Public License (GPL) with special exceptions +allowing the distribution of all compressed executables, including +commercial programs. + + +INTRODUCTION +============ + +UPX is an advanced executable file compressor. UPX will typically +reduce the file size of programs and DLLs by around 50%-70%, thus +reducing disk space, network load times, download times and +other distribution and storage costs. + +Programs and libraries compressed by UPX are completely self-contained +and run exactly as before, with no runtime or memory penalty for most +of the supported formats. + +UPX supports a number of different executable formats, including +Windows 95/98/ME/NT/2000/XP/CE programs and DLLs, DOS programs, +and Linux executables and kernels. + +UPX is free software distributed under the term of the GNU General +Public License. Full source code is available. + +UPX may be distributed and used freely, even with commercial applications. +See the UPX License Agreement for details. + +UPX is rated number one in the well known Archive Comparison Test. Visit +http://compression.ca/ . + +UPX aims to be Commercial Quality Freeware. + + +SHORT DOCUMENTATION +=================== + +'upx program.exe' will compress a program or DLL. For best compression +results try 'upx --brute program.exe'. + +Please see the file UPX.DOC for the full documentation. The files +NEWS and BUGS also contain various tidbits of information. + + +DISCLAIMER +========== + +UPX comes with ABSOLUTELY NO WARRANTY; for details see the file LICENSE. + +Having said that, we think that UPX is quite stable now. Indeed we +have compressed lots of files without any problems. Also, the +current version has undergone several months of beta testing - +actually it's almost 8 years since our first public beta. + +This is the first production quality release, and we plan that future +releases will be backward compatible with this version. + +Please report all problems or suggestions to the authors. Thanks. + + +THE FUTURE +========== + + - We'd really love to support handheld systems like the PalmPilot because + compression makes a lot of sense here. And - because of the atari/tos + format - we already have a working decompressor in 68000 assembly. + Unfortunately we know next to nothing about the operating system + architecture of such handhelds, so we need some information from + an expert. Please contact us if you think you can help. + + - The Linux approach could probably get ported to a lot of other Unix + variants, at least for other i386 architectures it shouldn't be too + much work. If someone sends me a fresh hard disk and an official + FreeBSD/OpenBSD/NetBSD/Solaris/BeOS... CD I might take a look at it ;-) + + - We will *NOT* add any sort of protection and/or encryption. + This only gives people a false feeling of security because + by definition all protectors/compressors can be broken. + And don't trust any advertisment of authors of other executable + compressors about this topic - just do a websearch on "unpackers"... + + - Fix all remaining bugs - keep your reports coming ;-) + + - See the file PROJECTS in the source code distribution if you want + to contribute. + + +COPYRIGHT +========= + +Copyright (C) 1996-2006 Markus Franz Xaver Johannes Oberhumer +Copyright (C) 1996-2006 Laszlo Molnar +Copyright (C) 2000-2006 John F. Reiser + +This program may be used freely, and you are welcome to +redistribute it under certain conditions. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +UPX License Agreement for more details. + +You should have received a copy of the UPX License Agreement along +with this program; see the file LICENSE. If not, visit the UPX home page. + + +Share and enjoy, +Markus & Laszlo + + + Markus F.X.J. Oberhumer Laszlo Molnar + markus@oberhumer.com ml1050@users.sourceforge.net + + + +[ The term UPX is a shorthand for the Ultimate Packer for eXecutables + and holds no connection with potential owners of registered trademarks + or other rights. ] + +[ Feel free to contact us if you have commercial compression requirements + or interesting job offers. ] + diff --git a/import/upx/doc/README.1ST b/import/upx/doc/README.1ST new file mode 100644 index 000000000..c39d97941 --- /dev/null +++ b/import/upx/doc/README.1ST @@ -0,0 +1,33 @@ + ooooo ooo ooooooooo. ooooooo ooooo + `888' `8' `888 `Y88. `8888 d8' + 888 8 888 .d88' Y888..8P + 888 8 888ooo88P' `8888' + 888 8 888 .8PY888. + `88. .8' 888 d8' `888b + `YbodP' o888o o888o o88888o + + + The Ultimate Packer for eXecutables + Copyright (c) 1996-2006 Markus Oberhumer, Laszlo Molnar & John Reiser + http://upx.sourceforge.net + + + +MAJOR NEWS IN UPX 2 +=================== + +The main news since 1.25 are: + + * new format: added support for arm/pe (ARM executables running on WinCE) + * new format: added support for linux elf/amd64 + * new format: added support for linux elf/ppc32 + * new format: added support for mach/ppc32 (Apple Mac OS X) + * new format: added support for bootable Linux kernels ("vmlinuz/386") + * new format: added support for Playstation exes ("ps1/exe") + + * slightly better compression using the new NRV2E algorithm + * new options for compression tuning (e.g. '--brute') + * improved win32/pe compatibility + * direct ELF-to-memory decompression + * various bug fixes + diff --git a/import/upx/doc/THANKS b/import/upx/doc/THANKS new file mode 100644 index 000000000..df593b8a6 --- /dev/null +++ b/import/upx/doc/THANKS @@ -0,0 +1,59 @@ + ooooo ooo ooooooooo. ooooooo ooooo + `888' `8' `888 `Y88. `8888 d8' + 888 8 888 .d88' Y888..8P + 888 8 888ooo88P' `8888' + 888 8 888 .8PY888. + `88. .8' 888 d8' `888b + `YbodP' o888o o888o o88888o + + + The Ultimate Packer for eXecutables + Copyright (c) 1996-2006 Markus Oberhumer, Laszlo Molnar & John Reiser + http://upx.sourceforge.net + + +.___.. . + | |_ _.._ ;_/ __ + | [ )(_][ )| \_) +-------------------- + +UPX would not be what it is today without the invaluable help of +everybody who was kind enough to spend time testing it, using it +in applications and reporting bugs. + +The following people made especially gracious contributions of their +time and energy in helping to track down bugs, add new features, and +generally assist in the UPX maintainership process: + +Adam Ierymenko + for severals ideas for the Linux version +Andi Kleen and Jamie Lokier + for the /proc/self/fd/X and other Linux suggestions +Andreas Muegge + for the Win32 GUI +Atli Mar Gudmundsson + for several comments on the win32/pe stub +Charles W. Sandmann + for the idea with the stubless decompressor in djgpp2/coff +Ice + for debugging the PE headersize problem down +Joergen Ibsen and d'b + for the relocation & address optimization ideas +John S. Fine + for the new version of the dos/exe decompressor +Lukundoo + for beta testing +Michael Devore + for initial dos/exe device driver support +Oleg V. Volkov + for various FreeBSD specific informations +The Owl & G-RoM + for the --compress-icons fix +Ralph Roth + for reporting several bugs +Salvador Eduardo Tropea + for beta testing +The WINE project (http://www.winehq.com/) + for lots of useful information found in their PE loader sources +Natascha + diff --git a/import/upx/doc/TODO b/import/upx/doc/TODO new file mode 100644 index 000000000..904591013 --- /dev/null +++ b/import/upx/doc/TODO @@ -0,0 +1,120 @@ +UPX TODO list. Last updated 2006-03-11. + + +IMPORTANT PROBLEMS THAT SHOULD BE FIXED SOON: + +- [None] + + +OTHER: + +- docs: convert docs from upx.pod to use AsciiDoc + +- check all to make sure they are not invalid + +- throwNotCompressible() is not a real error, so make the output nicer + (info: bla bla). Also ui.cpp (total_*). + + +----------------------------------------------------------------------- + + +IMPROVED COMPRESSION RATIO +========================== + +- experiment with new filters + +- implement filters for dos/exe + +- filters: could we exploit a f->firstcall info field ? + +- for small programs (e.g. < 64k), try an additional algorithm + to see if it gives better compression + + +ALL FORMATS +=========== + +- more thoroughly test the exe-header in canPack() + and throw exceptions when encountering bad values. + +- implement `--cpu=486' option to use bswap on the 32-bit formats + (if cpu >= 486) + +- consider removing "or ebp,-1" when not needed + + +FORMAT DJGPP2/COFF +================== + +- handle overlays + +- fix default file extension handling when the --coff option is set + + +FORMAT DOS/EXE +============== + +- implement filters + +- add a check so that we don't pack djgpp1 binaries + + +FORMAT LINUX/386 +================ + +- don't mmap() the temporary output file - this seems to improve + file io speed + + +FORMAT TMT/ADAM +=============== + +- the decompressors are already aligned, no need for an + extra alignment + + +FORMAT WATCOM/LE +================ + +- handle files without relocations + +- the decompressors are already aligned, no need for an + extra alignment + +- fix default file extension handling when the --le option is set + +- handle holes in the file + +- implement compressWithFilters() + +- add a call to verifyOverlappingDecompression() + + +FORMAT WIN16/NE +=============== + +- implement readFileHeader() to correctly identify a win16/ne + executable, so that the call for contribution will get thrown + + +FORMAT WIN32/PE +=============== + +- fix the section alignment with the Intel compiler + +- decrease runtime memory overhead + +3 - difficult) don't compress the BSS section and other holes. + +4 - medium - ml) fix when objectalign < 0x1000 + +4 - easy - ml) put the original offset of moved resources somewhere into + the res.dir. (if it's safe to do) + +4 - ??? - ml) fix FIXMEs + +5 - medium - ml) try to put the preprocessed imports & relocs back to their + original section if possible. this could save some virtual memory + address space. + diff --git a/import/upx/doc/upx.1 b/import/upx/doc/upx.1 new file mode 100644 index 000000000..5a572f477 --- /dev/null +++ b/import/upx/doc/upx.1 @@ -0,0 +1,1160 @@ +.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to +.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' +.\" expand to `' in nroff, nothing in troff, for use with C<>. +.tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.hy 0 +.if n .na +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "UPX 1" +.TH UPX 1 "2006-06-06" "upx 2.01" " " +.SH "NAME" +upx \- compress or expand executable files +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBupx\fR [\ \fIcommand\fR\ ] [\ \fIoptions\fR\ ] \fIfilename\fR... +.SH "ABSTRACT" +.IX Header "ABSTRACT" +.Vb 3 +\& The Ultimate Packer for eXecutables +\& Copyright (c) 1996-2006 Markus Oberhumer, Laszlo Molnar & John Reiser +\& http://upx.sourceforge.net +.Ve +.PP +\&\fB\s-1UPX\s0\fR is a portable, extendable, high-performance executable packer for +several different executable formats. It achieves an excellent compression +ratio and offers \fI*very*\fR fast decompression. Your executables suffer +no memory overhead or other drawbacks for most of the formats supported, +because of in-place decompression. +.PP +While you may use \fB\s-1UPX\s0\fR freely for both non-commercial and commercial +executables (for details see the file \s-1LICENSE\s0), we would highly +appreciate if you credit \fB\s-1UPX\s0\fR and ourselves in the documentation, +possibly including a reference to the \fB\s-1UPX\s0\fR home page. Thanks. +.PP +[ Using \fB\s-1UPX\s0\fR in non-OpenSource applications without proper credits +is considered not politically correct ;\-) ] +.SH "DISCLAIMER" +.IX Header "DISCLAIMER" +\&\fB\s-1UPX\s0\fR comes with \s-1ABSOLUTELY\s0 \s-1NO\s0 \s-1WARRANTY\s0; for details see the file \s-1LICENSE\s0. +.PP +This is the first production quality release, and we plan that future 1.xx +releases will be backward compatible with this version. +.PP +Please report all problems or suggestions to the authors. Thanks. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fB\s-1UPX\s0\fR is a versatile executable packer with the following features: +.PP +.Vb 2 +\& - excellent compression ratio: compresses better than zip/gzip, +\& use UPX to decrease the size of your distribution ! +.Ve +.PP +.Vb 2 +\& - very fast decompression: about 10 MB/sec on an ancient Pentium 133, +\& about 200 MB/sec on an Athlon XP 2000+. +.Ve +.PP +.Vb 2 +\& - no memory overhead for your compressed executables for most of the +\& supported formats +.Ve +.PP +.Vb 3 +\& - safe: you can list, test and unpack your executables +\& Also, a checksum of both the compressed and uncompressed file is +\& maintained internally. +.Ve +.PP +.Vb 21 +\& - universal: UPX can pack a number of executable formats: +\& * atari/tos +\& * bvmlinuz/386 [bootable Linux kernel] +\& * djgpp2/coff +\& * dos/com +\& * dos/exe +\& * dos/sys +\& * linux/386 +\& * linux/elf386 +\& * linux/sh386 +\& * ps1/exe +\& * rtm32/pe +\& * tmt/adam +\& * vmlinuz/386 [bootable Linux kernel] +\& * vmlinux/386 +\& * watcom/le (supporting DOS4G, PMODE/W, DOS32a and CauseWay) +\& * win32/pe (exe and dll) +\& * arm/pe (exe and dll) +\& * linux/elfamd64 +\& * linux/elfppc32 +\& * mach/elfppc32 +.Ve +.PP +.Vb 1 +\& - portable: UPX is written in portable endian-neutral C++ +.Ve +.PP +.Vb 2 +\& - extendable: because of the class layout it's very easy to support +\& new executable formats or add new compression algorithms +.Ve +.PP +.Vb 3 +\& - free: UPX can be distributed and used freely. And from version 0.99 +\& the full source code of UPX is released under the GNU General Public +\& License (GPL) ! +.Ve +.PP +You probably understand now why we call \fB\s-1UPX\s0\fR the "\fIultimate\fR" +executable packer. +.SH "COMMANDS" +.IX Header "COMMANDS" +.Sh "Compress" +.IX Subsection "Compress" +This is the default operation, eg. \fBupx yourfile.exe\fR will compress the file +specified on the command line. +.Sh "Decompress" +.IX Subsection "Decompress" +All \fB\s-1UPX\s0\fR supported file formats can be unpacked using the \fB\-d\fR switch, eg. +\&\fBupx \-d yourfile.exe\fR will uncompress the file you've just compressed. +.Sh "Test" +.IX Subsection "Test" +The \fB\-t\fR command tests the integrity of the compressed and uncompressed +data, eg. \fBupx \-t yourfile.exe\fR check whether your file can be safely +decompressed. Note, that this command doesn't check the whole file, only +the part that will be uncompressed during program execution. This means +that you should not use this command instead of a virus checker. +.Sh "List" +.IX Subsection "List" +The \fB\-l\fR command prints out some information about the compressed files +specified on the command line as parameters, eg \fBupx \-l yourfile.exe\fR +shows the compressed / uncompressed size and the compression ratio of +\&\fIyourfile.exe\fR. +.SH "OPTIONS" +.IX Header "OPTIONS" +\&\fB\-q\fR: be quiet, suppress warnings +.PP +\&\fB\-q \-q\fR (or \fB\-qq\fR): be very quiet, suppress errors +.PP +\&\fB\-q \-q \-q\fR (or \fB\-qqq\fR): produce no output at all +.PP +\&\fB\-\-help\fR: prints the help +.PP +\&\fB\-\-version\fR: print the version of \fB\s-1UPX\s0\fR +.PP +[ ...to be written... \- type `\fBupx \-\-help\fR' for now ] +.SH "COMPRESSION LEVELS & TUNING" +.IX Header "COMPRESSION LEVELS & TUNING" +\&\fB\s-1UPX\s0\fR offers ten different compression levels from \fB\-1\fR to \fB\-9\fR, +and \fB\-\-best\fR. The default compression level is \fB\-8\fR for files +smaller than 512 kB, and \fB\-7\fR otherwise. +.IP "\(bu" 4 +Compression levels 1, 2 and 3 are pretty fast. +.IP "\(bu" 4 +Compression levels 4, 5 and 6 achieve a good time/ratio performance. +.IP "\(bu" 4 +Compression levels 7, 8 and 9 favor compression ratio over speed. +.IP "\(bu" 4 +Compression level \fB\-\-best\fR may take a long time. +.PP +Note that compression level \fB\-\-best\fR can be somewhat slow for large +files, but you definitely should use it when releasing a final version +of your program. +.PP +Quick start for achieving the best compression ratio: +.Sp +.RS 4 +Try \fBupx \-\-brute myfile.exe\fR. +.RE +.PP +Details for achieving the best compression ratio: +.IP "\(bu" 4 +Use the compression level \fB\-\-best\fR. +.IP "\(bu" 4 +Try one or both of the options \fB\-\-all\-methods\fR and \fB\-\-all\-filters\fR. +.IP "\(bu" 4 +Try the option \fB\-\-crp\-ms=NUMBER\fR. This uses more memory during compression +to achieve a (slightly) better compression ratio. +.Sp +\&\s-1NUMBER\s0 must be a decimal value from 10000 to 999999, inclusive. +The default value is 10000 (ten thousand). +.IP "\(bu" 4 +Info: the option \fB\-\-brute\fR is an abbrevation for the options +\&\fB\-\-best \-\-all\-methods \-\-all\-filters \-\-crp\-ms=999999\fR. +.IP "\(bu" 4 +Try if \fB\-\-overlay=strip\fR works. +.IP "\(bu" 4 +For win32/pe programs there's \fB\-\-strip\-relocs=0\fR. See notes below. +.SH "OVERLAY HANDLING OPTIONS" +.IX Header "OVERLAY HANDLING OPTIONS" +Info: An \*(L"overlay\*(R" means auxillary data atached after the logical end of +an executable, and it often contains application specific data +(this is a common practice to avoid an extra data file, though +it would be better to use resource sections). +.PP +\&\fB\s-1UPX\s0\fR handles overlays like many other executable packers do: it simply +copies the overlay after the compressed image. This works with some +files, but doesn't work with others, depending on how an application +actually accesses this overlayed data. +.PP +.Vb 1 +\& --overlay=copy Copy any extra data attached to the file. [DEFAULT] +.Ve +.PP +.Vb 3 +\& --overlay=strip Strip any overlay from the program instead of +\& copying it. Be warned, this may make the compressed +\& program crash or otherwise unusable. +.Ve +.PP +.Vb 1 +\& --overlay=skip Refuse to compress any program which has an overlay. +.Ve +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +The environment variable \fB\s-1UPX\s0\fR can hold a set of default +options for \fB\s-1UPX\s0\fR. These options are interpreted first and +can be overwritten by explicit command line parameters. +For example: +.PP +.Vb 3 +\& for DOS/Windows: set UPX=-9 --compress-icons#0 +\& for sh/ksh/zsh: UPX="-9 --compress-icons=0"; export UPX +\& for csh/tcsh: setenv UPX "-9 --compress-icons=0" +.Ve +.PP +Under DOS/Windows you must use '#' instead of '=' when setting the +environment variable because of a \s-1COMMAND\s0.COM limitation. +.PP +Not all of the options are valid in the environment variable \- +\&\fB\s-1UPX\s0\fR will tell you. +.PP +You can explicitly use the \fB\-\-no\-env\fR option to ignore the +environment variable. +.SH "NOTES FOR THE SUPPORTED EXECUTABLE FORMATS" +.IX Header "NOTES FOR THE SUPPORTED EXECUTABLE FORMATS" +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1ATARI/TOS\s0" +.IX Subsection "NOTES FOR ATARI/TOS" +This is the executable format used by the Atari \s-1ST/TT\s0, a Motorola 68000 +based personal computer which was popular in the late '80s. Support +of this format is only because of nostalgic feelings of one of +the authors and serves no practical purpose :\-). +See http://www.freemint.de for more info. +.PP +Packed programs will be byte-identical to the original after uncompression. +All debug information will be stripped, though. +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1BVMLINUZ/I386\s0" +.IX Subsection "NOTES FOR BVMLINUZ/I386" +Same as vmlinuz/i386. +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1DOS/COM\s0" +.IX Subsection "NOTES FOR DOS/COM" +Obviously \fB\s-1UPX\s0\fR won't work with executables that want to read data from +themselves (like some commandline utilities that ship with Win95/98/ME). +.PP +Compressed programs only work on a 286+. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +Maximum uncompressed size: ~65100 bytes. +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& --8086 Create an executable that works on any 8086 CPU. +.Ve +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.PP +.Vb 4 +\& --all-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1DOS/EXE\s0" +.IX Subsection "NOTES FOR DOS/EXE" +dos/exe stands for all \*(L"normal\*(R" 16\-bit \s-1DOS\s0 executables. +.PP +Obviously \fB\s-1UPX\s0\fR won't work with executables that want to read data from +themselves (like some command line utilities that ship with Win95/98/ME). +.PP +Compressed programs only work on a 286+. +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& --8086 Create an executable that works on any 8086 CPU. +.Ve +.PP +.Vb 1 +\& --no-reloc Use no relocation records in the exe header. +.Ve +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1DOS/SYS\s0" +.IX Subsection "NOTES FOR DOS/SYS" +Compressed programs only work on a 286+. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +Maximum uncompressed size: ~65350 bytes. +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& --8086 Create an executable that works on any 8086 CPU. +.Ve +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.PP +.Vb 4 +\& --all-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1DJGPP2/COFF\s0" +.IX Subsection "NOTES FOR DJGPP2/COFF" +First of all, it is recommended to use \fB\s-1UPX\s0\fR *instead* of \fBstrip\fR. strip has +the very bad habit of replacing your stub with its own (outdated) version. +Additionally \fB\s-1UPX\s0\fR corrects a bug/feature in strip v2.8.x: it +will fix the 4 KByte aligment of the stub. +.PP +\&\fB\s-1UPX\s0\fR includes the full functionality of stubify. This means it will +automatically stubify your \s-1COFF\s0 files. Use the option \fB\-\-coff\fR to +disable this functionality (see below). +.PP +\&\fB\s-1UPX\s0\fR automatically handles Allegro packfiles. +.PP +The \s-1DLM\s0 format (a rather exotic shared library extension) is not supported. +.PP +Packed programs will be byte-identical to the original after uncompression. +All debug information and trailing garbage will be stripped, though. +.PP +Extra options available for this executable format: +.PP +.Vb 2 +\& --coff Produce COFF output instead of EXE. By default +\& UPX keeps your current stub. +.Ve +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.PP +.Vb 4 +\& --all-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1LINUX\s0 [general]" +.IX Subsection "NOTES FOR LINUX [general]" +Introduction +.PP +.Vb 4 +\& Linux/386 support in UPX consists of 3 different executable formats, +\& one optimized for ELF excutables ("linux/elf386"), one optimized +\& for shell scripts ("linux/sh386"), and one generic format +\& ("linux/386"). +.Ve +.PP +.Vb 2 +\& We will start with a general discussion first, but please +\& also read the relevant docs for each of the individual formats. +.Ve +.PP +.Vb 2 +\& Also, there is special support for bootable kernels - see the +\& description of the vmlinuz/386 format. +.Ve +.PP +General user's overview +.PP +.Vb 7 +\& Running a compressed executable program trades less space on a +\& ``permanent'' storage medium (such as a hard disk, floppy disk, +\& CD-ROM, flash memory, EPROM, etc.) for more space in one or more +\& ``temporary'' storage media (such as RAM, swap space, /tmp, etc.). +\& Running a compressed executable also requires some additional CPU +\& cycles to generate the compressed executable in the first place, +\& and to decompress it at each invocation. +.Ve +.PP +.Vb 6 +\& How much space is traded? It depends on the executable, but many +\& programs save 30% to 50% of permanent disk space. How much CPU +\& overhead is there? Again, it depends on the executable, but +\& decompression speed generally is at least many megabytes per second, +\& and frequently is limited by the speed of the underlying disk +\& or network I/O. +.Ve +.PP +.Vb 15 +\& Depending on the statistics of usage and access, and the relative +\& speeds of CPU, RAM, swap space, /tmp, and filesystem storage, then +\& invoking and running a compressed executable can be faster than +\& directly running the corresponding uncompressed program. +\& The operating system might perfrom fewer expensive I/O operations +\& to invoke the compressed program. Paging to or from swap space +\& or /tmp might be faster than paging from the general filesystem. +\& ``Medium-sized'' programs which access about 1/3 to 1/2 of their +\& stored program bytes can do particulary well with compression. +\& Small programs tend not to benefit as much because the absolute +\& savings is less. Big programs tend not to benefit proportionally +\& because each invocation may use only a small fraction of the program, +\& yet UPX decompresses the entire program before invoking it. +\& But in environments where disk or flash memory storage is limited, +\& then compression may win anyway. +.Ve +.PP +.Vb 6 +\& Currently, executables compressed by UPX do not share RAM at runtime +\& in the way that executables mapped from a filesystem do. As a +\& result, if the same program is run simultaneously by more than one +\& process, then using the compressed version will require more RAM and/or +\& swap space. So, shell programs (bash, csh, etc.) and ``make'' +\& might not be good candidates for compression. +.Ve +.PP +.Vb 12 +\& UPX recognizes three executable formats for Linux: Linux/elf386, +\& Linux/sh386, and Linux/386. Linux/386 is the most generic format; +\& it accommodates any file that can be executed. At runtime, the UPX +\& decompression stub re-creates in /tmp a copy of the original file, +\& and then the copy is (re-)executed with the same arguments. +\& ELF binary executables prefer the Linux/elf386 format by default, +\& because UPX decompresses them directly into RAM, uses only one +\& exec, does not use space in /tmp, and does not use /proc. +\& Shell scripts where the underlying shell accepts a ``-c'' argument +\& can use the Linux/sh386 format. UPX decompresses the shell script +\& into low memory, then maps the shell and passes the entire text of the +\& script as an argument with a leading ``-c''. +.Ve +.PP +General benefits: +.PP +.Vb 4 +\& - UPX can compress all executables, be it AOUT, ELF, libc4, libc5, +\& libc6, Shell/Perl/Python/... scripts, standalone Java .class +\& binaries, or whatever... +\& All scripts and programs will work just as before. +.Ve +.PP +.Vb 2 +\& - Compressed programs are completely self-contained. No need for +\& any external program. +.Ve +.PP +.Vb 5 +\& - UPX keeps your original program untouched. This means that +\& after decompression you will have a byte-identical version, +\& and you can use UPX as a file compressor just like gzip. +\& [ Note that UPX maintains a checksum of the file internally, +\& so it is indeed a reliable alternative. ] +.Ve +.PP +.Vb 3 +\& - As the stub only uses syscalls and isn't linked against libc it +\& should run under any Linux configuration that can run ELF +\& binaries. +.Ve +.PP +.Vb 3 +\& - For the same reason compressed executables should run under +\& FreeBSD and other systems which can run Linux binaries. +\& [ Please send feedback on this topic ] +.Ve +.PP +General drawbacks: +.PP +.Vb 4 +\& - It is not advisable to compress programs which usually have many +\& instances running (like `sh' or `make') because the common segments of +\& compressed programs won't be shared any longer between different +\& processes. +.Ve +.PP +.Vb 5 +\& - `ldd' and `size' won't show anything useful because all they +\& see is the statically linked stub. Since version 0.82 the section +\& headers are stripped from the UPX stub and `size' doesn't even +\& recognize the file format. The file patches/patch-elfcode.h has a +\& patch to fix this bug in `size' and other programs which use GNU BFD. +.Ve +.PP +General notes: +.PP +.Vb 2 +\& - As UPX leaves your original program untouched it is advantageous +\& to strip it before compression. +.Ve +.PP +.Vb 2 +\& - If you compress a script you will lose platform independence - +\& this could be a problem if you are using NFS mounted disks. +.Ve +.PP +.Vb 2 +\& - Compression of suid, guid and sticky-bit programs is rejected +\& because of possible security implications. +.Ve +.PP +.Vb 2 +\& - For the same reason there is no sense in making any compressed +\& program suid. +.Ve +.PP +.Vb 3 +\& - Obviously UPX won't work with executables that want to read data +\& from themselves. E.g., this might be a problem for Perl scripts +\& which access their __DATA__ lines. +.Ve +.PP +.Vb 4 +\& - In case of internal errors the stub will abort with exitcode 127. +\& Typical reasons for this to happen are that the program has somehow +\& been modified after compression. +\& Running `strace -o strace.log compressed_file' will tell you more. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1LINUX/ELF386\s0" +.IX Subsection "NOTES FOR LINUX/ELF386" +Please read the general Linux description first. +.PP +The linux/elf386 format decompresses directly into \s-1RAM\s0, +uses only one exec, does not use space in /tmp, +and does not use /proc. +.PP +Linux/elf386 is automatically selected for Linux \s-1ELF\s0 exectuables. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +How it works: +.PP +.Vb 9 +\& For ELF executables, UPX decompresses directly to memory, simulating +\& the mapping that the operating system kernel uses during exec(), +\& including the PT_INTERP program interpreter (if any). +\& The brk() is set by a special PT_LOAD segment in the compressed +\& executable itself. UPX then wipes the stack clean except for +\& arguments, environment variables, and Elf_auxv entries (this is +\& required by bugs in the startup code of /lib/ld-linux.so as of +\& May 2000), and transfers control to the program interpreter or +\& the e_entry address of the original executable. +.Ve +.PP +.Vb 2 +\& The UPX stub is about 1700 bytes long, partly written in assembler +\& and only uses kernel syscalls. It is not linked against any libc. +.Ve +.PP +Specific drawbacks: +.PP +.Vb 9 +\& - For linux/elf386 and linux/sh386 formats, you will be relying on +\& RAM and swap space to hold all of the decompressed program during +\& the lifetime of the process. If you already use most of your swap +\& space, then you may run out. A system that is "out of memory" +\& can become fragile. Many programs do not react gracefully when +\& malloc() returns 0. With newer Linux kernels, the kernel +\& may decide to kill some processes to regain memory, and you +\& may not like the kernel's choice of which to kill. Running +\& /usr/bin/top is one way to check on the usage of swap space. +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& (none) +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1LINUX/SH386\s0" +.IX Subsection "NOTES FOR LINUX/SH386" +Please read the general Linux description first. +.PP +Shell scripts where the underling shell accepts a ``\-c'' argument +can use the Linux/sh386 format. \fB\s-1UPX\s0\fR decompresses the shell script +into low memory, then maps the shell and passes the entire text of the +script as an argument with a leading ``\-c''. +It does not use space in /tmp, and does not use /proc. +.PP +Linux/sh386 is automatically selected for shell scripts that +use a known shell. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +How it works: +.PP +.Vb 8 +\& For shell script executables (files beginning with "#!/" or "#! /") +\& where the shell is known to accept "-c ", UPX decompresses +\& the file into low memory, then maps the shell (and its PT_INTERP), +\& and passes control to the shell with the entire decompressed file +\& as the argument after "-c". Known shells are sh, ash, bash, bsh, csh, +\& ksh, tcsh, pdksh. Restriction: UPX cannot use this method +\& for shell scripts which use the one optional string argument after +\& the shell name in the script (example: "#! /bin/sh option3\en".) +.Ve +.PP +.Vb 2 +\& The UPX stub is about 1700 bytes long, partly written in assembler +\& and only uses kernel syscalls. It is not linked against any libc. +.Ve +.PP +Specific drawbacks: +.PP +.Vb 9 +\& - For linux/elf386 and linux/sh386 formats, you will be relying on +\& RAM and swap space to hold all of the decompressed program during +\& the lifetime of the process. If you already use most of your swap +\& space, then you may run out. A system that is "out of memory" +\& can become fragile. Many programs do not react gracefully when +\& malloc() returns 0. With newer Linux kernels, the kernel +\& may decide to kill some processes to regain memory, and you +\& may not like the kernel's choice of which to kill. Running +\& /usr/bin/top is one way to check on the usage of swap space. +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 1 +\& (none) +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1LINUX/386\s0" +.IX Subsection "NOTES FOR LINUX/386" +Please read the general Linux description first. +.PP +The generic linux/386 format decompresses to /tmp and needs +/proc filesystem support. It starts the decompressed program +via the \fIexecve()\fR syscall. +.PP +Linux/386 is only selected if the specialized linux/elf386 +and linux/sh386 won't recognize a file. +.PP +Packed programs will be byte-identical to the original after uncompression. +.PP +How it works: +.PP +.Vb 7 +\& For files which are not ELF and not a script for a known "-c" shell, +\& UPX uses kernel execve(), which first requires decompressing to a +\& temporary file in the filesystem. Interestingly - +\& because of the good memory management of the Linux kernel - this +\& often does not introduce a noticable delay, and in fact there +\& will be no disk access at all if you have enough free memory as +\& the entire process takes places within the filesystem buffers. +.Ve +.PP +.Vb 2 +\& A compressed executable consists of the UPX stub and an overlay +\& which contains the original program in a compressed form. +.Ve +.PP +.Vb 2 +\& The UPX stub is a statically linked ELF executable and does +\& the following at program startup: +.Ve +.PP +.Vb 7 +\& 1) decompress the overlay to a temporary location in /tmp +\& 2) open the temporary file for reading +\& 3) try to delete the temporary file and start (execve) +\& the uncompressed program in /tmp using /proc//fd/X as +\& attained by step 2) +\& 4) if that fails, fork off a subprocess to clean up and +\& start the program in /tmp in the meantime +.Ve +.PP +.Vb 2 +\& The UPX stub is about 1700 bytes long, partly written in assembler +\& and only uses kernel syscalls. It is not linked against any libc. +.Ve +.PP +Specific drawbacks: +.PP +.Vb 4 +\& - You need additional free disk space for the uncompressed program +\& in your /tmp directory. This program is deleted immediately after +\& decompression, but you still need it for the full execution time +\& of the program. +.Ve +.PP +.Vb 4 +\& - You must have /proc filesystem support as the stub wants to open +\& /proc//exe and needs /proc//fd/X. This also means that you +\& cannot compress programs that are used during the boot sequence +\& before /proc is mounted. +.Ve +.PP +.Vb 4 +\& - Utilities like `top' will display numerical values in the process +\& name field. This is because Linux computes the process name from +\& the first argument of the last execve syscall (which is typically +\& something like /proc//fd/3). +.Ve +.PP +.Vb 4 +\& - Because of temporary decompression to disk the decompression speed +\& is not as fast as with the other executable formats. Still, I can see +\& no noticable delay when starting programs like my ~3 MB emacs (which +\& is less than 1 MB when compressed :-). +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 3 +\& --force-execve Force the use of the generic linux/386 "execve" +\& format, i.e. do not try the linux/elf386 and +\& linux/sh386 formats. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1PS1/EXE\s0" +.IX Subsection "NOTES FOR PS1/EXE" +This is the executable format used by the Sony PlayStation (PSone), +a Mips R3000 based gaming console which is popular since the late '90s. +Support of this format is very similar to the Atari one, because of +nostalgic feelings of one of the authors. +.PP +Packed programs will be byte-identical to the original after uncompression, +until further notice. +.PP +Maximum uncompressed size: ~1998848 bytes. +.PP +Notes: +.PP +.Vb 2 +\& - UPX creates as default a 'CD-Rom only' PS1/PS2 compatible executable. +\& For transfer between client/target use options below. +.Ve +.PP +.Vb 6 +\& - Normally the packed files use the same memory areas like the uncompressed +\& versions, so they will not override other memory areas while unpacking. +\& If this isn't possible UPX will abort showing a 'packed data overlap' +\& error. With the "--force" option UPX will set a few 'bytes higher' loading +\& offset for the packed file, but this isn't a real problem if it is a +\& single or boot-only executable. +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.PP +.Vb 4 +\& --boot-only The format will only run from a CD and may slightly +\& improves the compression ratio. The decompression +\& routines are faster than default ones. +\& But it cannot be used for host/client transfer ! +.Ve +.PP +.Vb 4 +\& --no-align This option disables CD mode 2 data sector format +\& alignment. May slightly improves the compression ratio, +\& but the compressed executable will not boot from a CD. +\& Use it for client/target transfer only ! +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1RTM32/PE\s0 and \s-1ARM/PE\s0" +.IX Subsection "NOTES FOR RTM32/PE and ARM/PE" +Same as win32/pe. +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1TMT/ADAM\s0" +.IX Subsection "NOTES FOR TMT/ADAM" +This format is used by the \s-1TMT\s0 Pascal compiler \- see http://www.tmt.com/ . +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.PP +.Vb 4 +\& --all-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1VMLINUZ/386\s0" +.IX Subsection "NOTES FOR VMLINUZ/386" +The vmlinuz/386 and bvmlinuz/386 formats take a gzip-compressed +bootable Linux kernel image (\*(L"vmlinuz\*(R", \*(L"zImage\*(R", \*(L"bzImage\*(R"), +gzip-decompress it and re-compress it with the \fB\s-1UPX\s0\fR compression method. +.PP +vmlinuz/386 is completely unrelated to the other Linux executable +formats, and it does not share any of their drawbacks. +.PP +Notes: +.PP +.Vb 3 +\& - Be sure that "vmlinuz/386" or "bvmlinuz/386" is displayed +\& during compression - otherwise a wrong executable format +\& may have been used, and the kernel won't boot. +.Ve +.PP +Benefits: +.PP +.Vb 4 +\& - Better compression (but note that the kernel was already compressed, +\& so the improvement is not as large as with other formats). +\& Still, the bytes saved may be essential for special needs like +\& bootdisks. +.Ve +.PP +.Vb 4 +\& For example, this is what I get for my 2.2.16 kernel: +\& 1589708 vmlinux +\& 641073 bzImage [original] +\& 560755 bzImage.upx [compressed by "upx -9"] +.Ve +.PP +.Vb 2 +\& - Much faster decompression at kernel boot time (but kernel +\& decompression speed is not really an issue these days). +.Ve +.PP +Drawbacks: +.PP +.Vb 1 +\& (none) +.Ve +.PP +Extra options available for this executable format: +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.PP +.Vb 4 +\& --all-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1WATCOM/LE\s0" +.IX Subsection "NOTES FOR WATCOM/LE" +\&\fB\s-1UPX\s0\fR has been successfully tested with the following extenders: + \s-1DOS4G\s0, \s-1DOS4GW\s0, \s-1PMODE/W\s0, DOS32a, CauseWay. + The \s-1WDOS/X\s0 extender is partly supported (for details + see the file bugs \s-1BUGS\s0). +.PP +DLLs and the \s-1LX\s0 format are not supported. +.PP +Extra options available for this executable format: +.PP +.Vb 2 +\& --le Produce an unbound LE output instead of +\& keeping the current stub. +.Ve +.Sh "\s-1NOTES\s0 \s-1FOR\s0 \s-1WIN32/PE\s0" +.IX Subsection "NOTES FOR WIN32/PE" +The \s-1PE\s0 support in \fB\s-1UPX\s0\fR is quite stable now, but probably there are +still some incompabilities with some files. +.PP +Because of the way \fB\s-1UPX\s0\fR (and other packers for this format) works, you +can see increased memory usage of your compressed files because the whole +program is loaded into memory at startup. +If you start several instances of huge compressed programs you're +wasting memory because the common segements of the program won't +get shared across the instances. +On the other hand if you're compressing only smaller programs, or +running only one instance of larger programs, then this penalty is +smaller, but it's still there. +.PP +If you're running executables from network, then compressed programs +will load faster, and require less bandwidth during execution. +.PP +DLLs are supported. But \s-1UPX\s0 compressed DLLs can not share common data and +code when they got used by multiple applications. So compressing msvcrt.dll +is a waste of memory, but compressing the dll plugins of a particular +application may be a better idea. +.PP +Screensavers are supported, with the restriction that the filename +must end with \*(L".scr\*(R" (as screensavers are handled slightly different +than normal exe files). +.PP +\&\s-1UPX\s0 compressed \s-1PE\s0 files has some minor memory overhead (usually in the +10 \- 30 kbytes range) which can be seen by specifying the \*(L"\-i\*(R" command +line switch during compression. +.PP +Extra options available for this executable format: +.PP +.Vb 9 +\& --compress-exports=0 Don't compress the export section. +\& Use this if you plan to run the compressed +\& program under Wine. +\& --compress-exports=1 Compress the export section. [DEFAULT] +\& Compression of the export section can improve the +\& compression ratio quite a bit but may not work +\& with all programs (like winword.exe). +\& UPX never compresses the export section of a DLL +\& regardless of this option. +.Ve +.PP +.Vb 4 +\& --compress-icons=0 Don't compress any icons. +\& --compress-icons=1 Compress all but the first icon. +\& --compress-icons=2 Compress all icons which are not in the +\& first icon directory. [DEFAULT] +.Ve +.PP +.Vb 1 +\& --compress-resources=0 Don't compress any resources at all. +.Ve +.PP +.Vb 8 +\& --keep-resource=list Don't compress resources specified by the list. +\& The members of the list are separated by commas. +\& A list member has the following format: I. +\& I is the type of the resource. Standard types +\& must be specified as decimal numbers, user types can be +\& specified by decimal IDs or strings. I is the +\& identifier of the resource. It can be a decimal number +\& or a string. For example: +.Ve +.PP +.Vb 1 +\& --keep-resource=2/MYBITMAP,5,6/12345 +.Ve +.PP +.Vb 4 +\& UPX won't compress the named bitmap resource "MYBITMAP", +\& it leaves every dialog (5) resource uncompressed, and +\& it won't touch the string table resource with identifier +\& 12345. +.Ve +.PP +.Vb 3 +\& --force Force compression even when there is an +\& unexpected value in a header field. +\& Use with care. +.Ve +.PP +.Vb 9 +\& --strip-relocs=0 Don't strip relocation records. +\& --strip-relocs=1 Strip relocation records. [DEFAULT] +\& This option only works on executables with base +\& address greater or equal to 0x400000. Usually the +\& compressed files becomes smaller, but some files +\& may become larger. Note that the resulting file will +\& not work under Windows 3.x (Win32s). +\& UPX never strips relocations from a DLL +\& regardless of this option. +.Ve +.PP +.Vb 4 +\& --all-methods Compress the program several times, using all +\& available compression methods. This may improve +\& the compression ratio in some cases, but usually +\& the default method gives the best results anyway. +.Ve +.PP +.Vb 4 +\& --all-filters Compress the program several times, using all +\& available preprocessing filters. This may improve +\& the compression ratio in some cases, but usually +\& the default filter gives the best results anyway. +.Ve +.SH "DIAGNOSTICS" +.IX Header "DIAGNOSTICS" +Exit status is normally 0; if an error occurs, exit status +is 1. If a warning occurs, exit status is 2. +.PP +\&\fB\s-1UPX\s0\fR's diagnostics are intended to be self\-explanatory. +.SH "BUGS" +.IX Header "BUGS" +Please report all bugs immediately to the authors. +.SH "AUTHORS" +.IX Header "AUTHORS" +.Vb 2 +\& Markus F.X.J. Oberhumer +\& http://www.oberhumer.com +.Ve +.PP +.Vb 1 +\& Laszlo Molnar +.Ve +.PP +.Vb 1 +\& John F. Reiser +.Ve +.PP +.Vb 1 +\& Jens Medoch +.Ve +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (C) 1996\-2006 Markus Franz Xaver Johannes Oberhumer +.PP +Copyright (C) 1996\-2006 Laszlo Molnar +.PP +Copyright (C) 2000\-2006 John F. Reiser +.PP +Copyright (C) 2002\-2006 Jens Medoch +.PP +This program may be used freely, and you are welcome to +redistribute it under certain conditions. +.PP +This program is distributed in the hope that it will be useful, +but \s-1WITHOUT\s0 \s-1ANY\s0 \s-1WARRANTY\s0; without even the implied warranty of +\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. See the +\&\fB\s-1UPX\s0 License Agreement\fR for more details. +.PP +You should have received a copy of the \s-1UPX\s0 License Agreement along +with this program; see the file \s-1LICENSE\s0. If not, visit the \s-1UPX\s0 home page. diff --git a/import/upx/doc/upx.doc b/import/upx/doc/upx.doc new file mode 100644 index 000000000..ce5245959 --- /dev/null +++ b/import/upx/doc/upx.doc @@ -0,0 +1,842 @@ +NAME + upx - compress or expand executable files + +SYNOPSIS + upx [ *command* ] [ *options* ] *filename*... + +ABSTRACT + The Ultimate Packer for eXecutables + Copyright (c) 1996-2006 Markus Oberhumer, Laszlo Molnar & John Reiser + http://upx.sourceforge.net + + UPX is a portable, extendable, high-performance executable packer for + several different executable formats. It achieves an excellent + compression ratio and offers **very** fast decompression. Your + executables suffer no memory overhead or other drawbacks for most of the + formats supported, because of in-place decompression. + + While you may use UPX freely for both non-commercial and commercial + executables (for details see the file LICENSE), we would highly + appreciate if you credit UPX and ourselves in the documentation, + possibly including a reference to the UPX home page. Thanks. + + [ Using UPX in non-OpenSource applications without proper credits is + considered not politically correct ;-) ] + +DISCLAIMER + UPX comes with ABSOLUTELY NO WARRANTY; for details see the file LICENSE. + + This is the first production quality release, and we plan that future + 1.xx releases will be backward compatible with this version. + + Please report all problems or suggestions to the authors. Thanks. + +DESCRIPTION + UPX is a versatile executable packer with the following features: + + - excellent compression ratio: compresses better than zip/gzip, + use UPX to decrease the size of your distribution ! + + - very fast decompression: about 10 MB/sec on an ancient Pentium 133, + about 200 MB/sec on an Athlon XP 2000+. + + - no memory overhead for your compressed executables for most of the + supported formats + + - safe: you can list, test and unpack your executables + Also, a checksum of both the compressed and uncompressed file is + maintained internally. + + - universal: UPX can pack a number of executable formats: + * atari/tos + * bvmlinuz/386 [bootable Linux kernel] + * djgpp2/coff + * dos/com + * dos/exe + * dos/sys + * linux/386 + * linux/elf386 + * linux/sh386 + * ps1/exe + * rtm32/pe + * tmt/adam + * vmlinuz/386 [bootable Linux kernel] + * vmlinux/386 + * watcom/le (supporting DOS4G, PMODE/W, DOS32a and CauseWay) + * win32/pe (exe and dll) + * arm/pe (exe and dll) + * linux/elfamd64 + * linux/elfppc32 + * mach/elfppc32 + + - portable: UPX is written in portable endian-neutral C++ + + - extendable: because of the class layout it's very easy to support + new executable formats or add new compression algorithms + + - free: UPX can be distributed and used freely. And from version 0.99 + the full source code of UPX is released under the GNU General Public + License (GPL) ! + + You probably understand now why we call UPX the "*ultimate*" executable + packer. + +COMMANDS + Compress + This is the default operation, eg. upx yourfile.exe will compress the + file specified on the command line. + + Decompress + All UPX supported file formats can be unpacked using the -d switch, eg. + upx -d yourfile.exe will uncompress the file you've just compressed. + + Test + The -t command tests the integrity of the compressed and uncompressed + data, eg. upx -t yourfile.exe check whether your file can be safely + decompressed. Note, that this command doesn't check the whole file, only + the part that will be uncompressed during program execution. This means + that you should not use this command instead of a virus checker. + + List + The -l command prints out some information about the compressed files + specified on the command line as parameters, eg upx -l yourfile.exe + shows the compressed / uncompressed size and the compression ratio of + *yourfile.exe*. + +OPTIONS + -q: be quiet, suppress warnings + + -q -q (or -qq): be very quiet, suppress errors + + -q -q -q (or -qqq): produce no output at all + + --help: prints the help + + --version: print the version of UPX + + [ ...to be written... - type `upx --help' for now ] + +COMPRESSION LEVELS & TUNING + UPX offers ten different compression levels from -1 to -9, and --best. + The default compression level is -8 for files smaller than 512 kB, and + -7 otherwise. + + * Compression levels 1, 2 and 3 are pretty fast. + + * Compression levels 4, 5 and 6 achieve a good time/ratio performance. + + * Compression levels 7, 8 and 9 favor compression ratio over speed. + + * Compression level --best may take a long time. + + Note that compression level --best can be somewhat slow for large files, + but you definitely should use it when releasing a final version of your + program. + + Quick start for achieving the best compression ratio: + + Try upx --brute myfile.exe. + + Details for achieving the best compression ratio: + + * Use the compression level --best. + + * Try one or both of the options --all-methods and --all-filters. + + * Try the option --crp-ms=NUMBER. This uses more memory during + compression to achieve a (slightly) better compression ratio. + + NUMBER must be a decimal value from 10000 to 999999, inclusive. The + default value is 10000 (ten thousand). + + * Info: the option --brute is an abbrevation for the options --best + --all-methods --all-filters --crp-ms=999999. + + * Try if --overlay=strip works. + + * For win32/pe programs there's --strip-relocs=0. See notes below. + +OVERLAY HANDLING OPTIONS + Info: An "overlay" means auxillary data atached after the logical end of + an executable, and it often contains application specific data (this is + a common practice to avoid an extra data file, though it would be better + to use resource sections). + + UPX handles overlays like many other executable packers do: it simply + copies the overlay after the compressed image. This works with some + files, but doesn't work with others, depending on how an application + actually accesses this overlayed data. + + --overlay=copy Copy any extra data attached to the file. [DEFAULT] + + --overlay=strip Strip any overlay from the program instead of + copying it. Be warned, this may make the compressed + program crash or otherwise unusable. + + --overlay=skip Refuse to compress any program which has an overlay. + +ENVIRONMENT + The environment variable UPX can hold a set of default options for UPX. + These options are interpreted first and can be overwritten by explicit + command line parameters. For example: + + for DOS/Windows: set UPX=-9 --compress-icons#0 + for sh/ksh/zsh: UPX="-9 --compress-icons=0"; export UPX + for csh/tcsh: setenv UPX "-9 --compress-icons=0" + + Under DOS/Windows you must use '#' instead of '=' when setting the + environment variable because of a COMMAND.COM limitation. + + Not all of the options are valid in the environment variable - UPX will + tell you. + + You can explicitly use the --no-env option to ignore the environment + variable. + +NOTES FOR THE SUPPORTED EXECUTABLE FORMATS + NOTES FOR ATARI/TOS + This is the executable format used by the Atari ST/TT, a Motorola 68000 + based personal computer which was popular in the late '80s. Support of + this format is only because of nostalgic feelings of one of the authors + and serves no practical purpose :-). See http://www.freemint.de for more + info. + + Packed programs will be byte-identical to the original after + uncompression. All debug information will be stripped, though. + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + NOTES FOR BVMLINUZ/I386 + Same as vmlinuz/i386. + + NOTES FOR DOS/COM + Obviously UPX won't work with executables that want to read data from + themselves (like some commandline utilities that ship with Win95/98/ME). + + Compressed programs only work on a 286+. + + Packed programs will be byte-identical to the original after + uncompression. + + Maximum uncompressed size: ~65100 bytes. + + Extra options available for this executable format: + + --8086 Create an executable that works on any 8086 CPU. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR DOS/EXE + dos/exe stands for all "normal" 16-bit DOS executables. + + Obviously UPX won't work with executables that want to read data from + themselves (like some command line utilities that ship with + Win95/98/ME). + + Compressed programs only work on a 286+. + + Extra options available for this executable format: + + --8086 Create an executable that works on any 8086 CPU. + + --no-reloc Use no relocation records in the exe header. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + NOTES FOR DOS/SYS + Compressed programs only work on a 286+. + + Packed programs will be byte-identical to the original after + uncompression. + + Maximum uncompressed size: ~65350 bytes. + + Extra options available for this executable format: + + --8086 Create an executable that works on any 8086 CPU. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR DJGPP2/COFF + First of all, it is recommended to use UPX *instead* of strip. strip has + the very bad habit of replacing your stub with its own (outdated) + version. Additionally UPX corrects a bug/feature in strip v2.8.x: it + will fix the 4 KByte aligment of the stub. + + UPX includes the full functionality of stubify. This means it will + automatically stubify your COFF files. Use the option --coff to disable + this functionality (see below). + + UPX automatically handles Allegro packfiles. + + The DLM format (a rather exotic shared library extension) is not + supported. + + Packed programs will be byte-identical to the original after + uncompression. All debug information and trailing garbage will be + stripped, though. + + Extra options available for this executable format: + + --coff Produce COFF output instead of EXE. By default + UPX keeps your current stub. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR LINUX [general] + Introduction + + Linux/386 support in UPX consists of 3 different executable formats, + one optimized for ELF excutables ("linux/elf386"), one optimized + for shell scripts ("linux/sh386"), and one generic format + ("linux/386"). + + We will start with a general discussion first, but please + also read the relevant docs for each of the individual formats. + + Also, there is special support for bootable kernels - see the + description of the vmlinuz/386 format. + + General user's overview + + Running a compressed executable program trades less space on a + ``permanent'' storage medium (such as a hard disk, floppy disk, + CD-ROM, flash memory, EPROM, etc.) for more space in one or more + ``temporary'' storage media (such as RAM, swap space, /tmp, etc.). + Running a compressed executable also requires some additional CPU + cycles to generate the compressed executable in the first place, + and to decompress it at each invocation. + + How much space is traded? It depends on the executable, but many + programs save 30% to 50% of permanent disk space. How much CPU + overhead is there? Again, it depends on the executable, but + decompression speed generally is at least many megabytes per second, + and frequently is limited by the speed of the underlying disk + or network I/O. + + Depending on the statistics of usage and access, and the relative + speeds of CPU, RAM, swap space, /tmp, and filesystem storage, then + invoking and running a compressed executable can be faster than + directly running the corresponding uncompressed program. + The operating system might perfrom fewer expensive I/O operations + to invoke the compressed program. Paging to or from swap space + or /tmp might be faster than paging from the general filesystem. + ``Medium-sized'' programs which access about 1/3 to 1/2 of their + stored program bytes can do particulary well with compression. + Small programs tend not to benefit as much because the absolute + savings is less. Big programs tend not to benefit proportionally + because each invocation may use only a small fraction of the program, + yet UPX decompresses the entire program before invoking it. + But in environments where disk or flash memory storage is limited, + then compression may win anyway. + + Currently, executables compressed by UPX do not share RAM at runtime + in the way that executables mapped from a filesystem do. As a + result, if the same program is run simultaneously by more than one + process, then using the compressed version will require more RAM and/or + swap space. So, shell programs (bash, csh, etc.) and ``make'' + might not be good candidates for compression. + + UPX recognizes three executable formats for Linux: Linux/elf386, + Linux/sh386, and Linux/386. Linux/386 is the most generic format; + it accommodates any file that can be executed. At runtime, the UPX + decompression stub re-creates in /tmp a copy of the original file, + and then the copy is (re-)executed with the same arguments. + ELF binary executables prefer the Linux/elf386 format by default, + because UPX decompresses them directly into RAM, uses only one + exec, does not use space in /tmp, and does not use /proc. + Shell scripts where the underlying shell accepts a ``-c'' argument + can use the Linux/sh386 format. UPX decompresses the shell script + into low memory, then maps the shell and passes the entire text of the + script as an argument with a leading ``-c''. + + General benefits: + + - UPX can compress all executables, be it AOUT, ELF, libc4, libc5, + libc6, Shell/Perl/Python/... scripts, standalone Java .class + binaries, or whatever... + All scripts and programs will work just as before. + + - Compressed programs are completely self-contained. No need for + any external program. + + - UPX keeps your original program untouched. This means that + after decompression you will have a byte-identical version, + and you can use UPX as a file compressor just like gzip. + [ Note that UPX maintains a checksum of the file internally, + so it is indeed a reliable alternative. ] + + - As the stub only uses syscalls and isn't linked against libc it + should run under any Linux configuration that can run ELF + binaries. + + - For the same reason compressed executables should run under + FreeBSD and other systems which can run Linux binaries. + [ Please send feedback on this topic ] + + General drawbacks: + + - It is not advisable to compress programs which usually have many + instances running (like `sh' or `make') because the common segments of + compressed programs won't be shared any longer between different + processes. + + - `ldd' and `size' won't show anything useful because all they + see is the statically linked stub. Since version 0.82 the section + headers are stripped from the UPX stub and `size' doesn't even + recognize the file format. The file patches/patch-elfcode.h has a + patch to fix this bug in `size' and other programs which use GNU BFD. + + General notes: + + - As UPX leaves your original program untouched it is advantageous + to strip it before compression. + + - If you compress a script you will lose platform independence - + this could be a problem if you are using NFS mounted disks. + + - Compression of suid, guid and sticky-bit programs is rejected + because of possible security implications. + + - For the same reason there is no sense in making any compressed + program suid. + + - Obviously UPX won't work with executables that want to read data + from themselves. E.g., this might be a problem for Perl scripts + which access their __DATA__ lines. + + - In case of internal errors the stub will abort with exitcode 127. + Typical reasons for this to happen are that the program has somehow + been modified after compression. + Running `strace -o strace.log compressed_file' will tell you more. + + NOTES FOR LINUX/ELF386 + Please read the general Linux description first. + + The linux/elf386 format decompresses directly into RAM, uses only one + exec, does not use space in /tmp, and does not use /proc. + + Linux/elf386 is automatically selected for Linux ELF exectuables. + + Packed programs will be byte-identical to the original after + uncompression. + + How it works: + + For ELF executables, UPX decompresses directly to memory, simulating + the mapping that the operating system kernel uses during exec(), + including the PT_INTERP program interpreter (if any). + The brk() is set by a special PT_LOAD segment in the compressed + executable itself. UPX then wipes the stack clean except for + arguments, environment variables, and Elf_auxv entries (this is + required by bugs in the startup code of /lib/ld-linux.so as of + May 2000), and transfers control to the program interpreter or + the e_entry address of the original executable. + + The UPX stub is about 1700 bytes long, partly written in assembler + and only uses kernel syscalls. It is not linked against any libc. + + Specific drawbacks: + + - For linux/elf386 and linux/sh386 formats, you will be relying on + RAM and swap space to hold all of the decompressed program during + the lifetime of the process. If you already use most of your swap + space, then you may run out. A system that is "out of memory" + can become fragile. Many programs do not react gracefully when + malloc() returns 0. With newer Linux kernels, the kernel + may decide to kill some processes to regain memory, and you + may not like the kernel's choice of which to kill. Running + /usr/bin/top is one way to check on the usage of swap space. + + Extra options available for this executable format: + + (none) + + NOTES FOR LINUX/SH386 + Please read the general Linux description first. + + Shell scripts where the underling shell accepts a ``-c'' argument can + use the Linux/sh386 format. UPX decompresses the shell script into low + memory, then maps the shell and passes the entire text of the script as + an argument with a leading ``-c''. It does not use space in /tmp, and + does not use /proc. + + Linux/sh386 is automatically selected for shell scripts that use a known + shell. + + Packed programs will be byte-identical to the original after + uncompression. + + How it works: + + For shell script executables (files beginning with "#!/" or "#! /") + where the shell is known to accept "-c ", UPX decompresses + the file into low memory, then maps the shell (and its PT_INTERP), + and passes control to the shell with the entire decompressed file + as the argument after "-c". Known shells are sh, ash, bash, bsh, csh, + ksh, tcsh, pdksh. Restriction: UPX cannot use this method + for shell scripts which use the one optional string argument after + the shell name in the script (example: "#! /bin/sh option3\n".) + + The UPX stub is about 1700 bytes long, partly written in assembler + and only uses kernel syscalls. It is not linked against any libc. + + Specific drawbacks: + + - For linux/elf386 and linux/sh386 formats, you will be relying on + RAM and swap space to hold all of the decompressed program during + the lifetime of the process. If you already use most of your swap + space, then you may run out. A system that is "out of memory" + can become fragile. Many programs do not react gracefully when + malloc() returns 0. With newer Linux kernels, the kernel + may decide to kill some processes to regain memory, and you + may not like the kernel's choice of which to kill. Running + /usr/bin/top is one way to check on the usage of swap space. + + Extra options available for this executable format: + + (none) + + NOTES FOR LINUX/386 + Please read the general Linux description first. + + The generic linux/386 format decompresses to /tmp and needs /proc + filesystem support. It starts the decompressed program via the execve() + syscall. + + Linux/386 is only selected if the specialized linux/elf386 and + linux/sh386 won't recognize a file. + + Packed programs will be byte-identical to the original after + uncompression. + + How it works: + + For files which are not ELF and not a script for a known "-c" shell, + UPX uses kernel execve(), which first requires decompressing to a + temporary file in the filesystem. Interestingly - + because of the good memory management of the Linux kernel - this + often does not introduce a noticable delay, and in fact there + will be no disk access at all if you have enough free memory as + the entire process takes places within the filesystem buffers. + + A compressed executable consists of the UPX stub and an overlay + which contains the original program in a compressed form. + + The UPX stub is a statically linked ELF executable and does + the following at program startup: + + 1) decompress the overlay to a temporary location in /tmp + 2) open the temporary file for reading + 3) try to delete the temporary file and start (execve) + the uncompressed program in /tmp using /proc//fd/X as + attained by step 2) + 4) if that fails, fork off a subprocess to clean up and + start the program in /tmp in the meantime + + The UPX stub is about 1700 bytes long, partly written in assembler + and only uses kernel syscalls. It is not linked against any libc. + + Specific drawbacks: + + - You need additional free disk space for the uncompressed program + in your /tmp directory. This program is deleted immediately after + decompression, but you still need it for the full execution time + of the program. + + - You must have /proc filesystem support as the stub wants to open + /proc//exe and needs /proc//fd/X. This also means that you + cannot compress programs that are used during the boot sequence + before /proc is mounted. + + - Utilities like `top' will display numerical values in the process + name field. This is because Linux computes the process name from + the first argument of the last execve syscall (which is typically + something like /proc//fd/3). + + - Because of temporary decompression to disk the decompression speed + is not as fast as with the other executable formats. Still, I can see + no noticable delay when starting programs like my ~3 MB emacs (which + is less than 1 MB when compressed :-). + + Extra options available for this executable format: + + --force-execve Force the use of the generic linux/386 "execve" + format, i.e. do not try the linux/elf386 and + linux/sh386 formats. + + NOTES FOR PS1/EXE + This is the executable format used by the Sony PlayStation (PSone), a + Mips R3000 based gaming console which is popular since the late '90s. + Support of this format is very similar to the Atari one, because of + nostalgic feelings of one of the authors. + + Packed programs will be byte-identical to the original after + uncompression, until further notice. + + Maximum uncompressed size: ~1998848 bytes. + + Notes: + + - UPX creates as default a 'CD-Rom only' PS1/PS2 compatible executable. + For transfer between client/target use options below. + + - Normally the packed files use the same memory areas like the uncompressed + versions, so they will not override other memory areas while unpacking. + If this isn't possible UPX will abort showing a 'packed data overlap' + error. With the "--force" option UPX will set a few 'bytes higher' loading + offset for the packed file, but this isn't a real problem if it is a + single or boot-only executable. + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --boot-only The format will only run from a CD and may slightly + improves the compression ratio. The decompression + routines are faster than default ones. + But it cannot be used for host/client transfer ! + + --no-align This option disables CD mode 2 data sector format + alignment. May slightly improves the compression ratio, + but the compressed executable will not boot from a CD. + Use it for client/target transfer only ! + + NOTES FOR RTM32/PE and ARM/PE + Same as win32/pe. + + NOTES FOR TMT/ADAM + This format is used by the TMT Pascal compiler - see http://www.tmt.com/ + . + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR VMLINUZ/386 + The vmlinuz/386 and bvmlinuz/386 formats take a gzip-compressed bootable + Linux kernel image ("vmlinuz", "zImage", "bzImage"), gzip-decompress it + and re-compress it with the UPX compression method. + + vmlinuz/386 is completely unrelated to the other Linux executable + formats, and it does not share any of their drawbacks. + + Notes: + + - Be sure that "vmlinuz/386" or "bvmlinuz/386" is displayed + during compression - otherwise a wrong executable format + may have been used, and the kernel won't boot. + + Benefits: + + - Better compression (but note that the kernel was already compressed, + so the improvement is not as large as with other formats). + Still, the bytes saved may be essential for special needs like + bootdisks. + + For example, this is what I get for my 2.2.16 kernel: + 1589708 vmlinux + 641073 bzImage [original] + 560755 bzImage.upx [compressed by "upx -9"] + + - Much faster decompression at kernel boot time (but kernel + decompression speed is not really an issue these days). + + Drawbacks: + + (none) + + Extra options available for this executable format: + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + + NOTES FOR WATCOM/LE + UPX has been successfully tested with the following extenders: DOS4G, + DOS4GW, PMODE/W, DOS32a, CauseWay. The WDOS/X extender is partly + supported (for details see the file bugs BUGS). + + DLLs and the LX format are not supported. + + Extra options available for this executable format: + + --le Produce an unbound LE output instead of + keeping the current stub. + + NOTES FOR WIN32/PE + The PE support in UPX is quite stable now, but probably there are still + some incompabilities with some files. + + Because of the way UPX (and other packers for this format) works, you + can see increased memory usage of your compressed files because the + whole program is loaded into memory at startup. If you start several + instances of huge compressed programs you're wasting memory because the + common segements of the program won't get shared across the instances. + On the other hand if you're compressing only smaller programs, or + running only one instance of larger programs, then this penalty is + smaller, but it's still there. + + If you're running executables from network, then compressed programs + will load faster, and require less bandwidth during execution. + + DLLs are supported. But UPX compressed DLLs can not share common data + and code when they got used by multiple applications. So compressing + msvcrt.dll is a waste of memory, but compressing the dll plugins of a + particular application may be a better idea. + + Screensavers are supported, with the restriction that the filename must + end with ".scr" (as screensavers are handled slightly different than + normal exe files). + + UPX compressed PE files has some minor memory overhead (usually in the + 10 - 30 kbytes range) which can be seen by specifying the "-i" command + line switch during compression. + + Extra options available for this executable format: + + --compress-exports=0 Don't compress the export section. + Use this if you plan to run the compressed + program under Wine. + --compress-exports=1 Compress the export section. [DEFAULT] + Compression of the export section can improve the + compression ratio quite a bit but may not work + with all programs (like winword.exe). + UPX never compresses the export section of a DLL + regardless of this option. + + --compress-icons=0 Don't compress any icons. + --compress-icons=1 Compress all but the first icon. + --compress-icons=2 Compress all icons which are not in the + first icon directory. [DEFAULT] + + --compress-resources=0 Don't compress any resources at all. + + --keep-resource=list Don't compress resources specified by the list. + The members of the list are separated by commas. + A list member has the following format: I. + I is the type of the resource. Standard types + must be specified as decimal numbers, user types can be + specified by decimal IDs or strings. I is the + identifier of the resource. It can be a decimal number + or a string. For example: + + --keep-resource=2/MYBITMAP,5,6/12345 + + UPX won't compress the named bitmap resource "MYBITMAP", + it leaves every dialog (5) resource uncompressed, and + it won't touch the string table resource with identifier + 12345. + + --force Force compression even when there is an + unexpected value in a header field. + Use with care. + + --strip-relocs=0 Don't strip relocation records. + --strip-relocs=1 Strip relocation records. [DEFAULT] + This option only works on executables with base + address greater or equal to 0x400000. Usually the + compressed files becomes smaller, but some files + may become larger. Note that the resulting file will + not work under Windows 3.x (Win32s). + UPX never strips relocations from a DLL + regardless of this option. + + --all-methods Compress the program several times, using all + available compression methods. This may improve + the compression ratio in some cases, but usually + the default method gives the best results anyway. + + --all-filters Compress the program several times, using all + available preprocessing filters. This may improve + the compression ratio in some cases, but usually + the default filter gives the best results anyway. + +DIAGNOSTICS + Exit status is normally 0; if an error occurs, exit status is 1. If a + warning occurs, exit status is 2. + + UPX's diagnostics are intended to be self-explanatory. + +BUGS + Please report all bugs immediately to the authors. + +AUTHORS + Markus F.X.J. Oberhumer + http://www.oberhumer.com + + Laszlo Molnar + + John F. Reiser + + Jens Medoch + +COPYRIGHT + Copyright (C) 1996-2006 Markus Franz Xaver Johannes Oberhumer + + Copyright (C) 1996-2006 Laszlo Molnar + + Copyright (C) 2000-2006 John F. Reiser + + Copyright (C) 2002-2006 Jens Medoch + + This program may be used freely, and you are welcome to redistribute it + under certain conditions. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the UPX License + Agreement for more details. + + You should have received a copy of the UPX License Agreement along with + this program; see the file LICENSE. If not, visit the UPX home page. + diff --git a/import/upx/doc/upx.html b/import/upx/doc/upx.html new file mode 100644 index 000000000..a7fb61822 --- /dev/null +++ b/import/upx/doc/upx.html @@ -0,0 +1,888 @@ + + + + +upx - compress or expand executable files + + + + + + +

+ + + + +

+

+

NAME

+

upx - compress or expand executable files

+

+

+
+

SYNOPSIS

+

upx [ command ] [ options ] filename...

+

+

+
+

ABSTRACT

+
+                    The Ultimate Packer for eXecutables
+   Copyright (c) 1996-2006 Markus Oberhumer, Laszlo Molnar & John Reiser
+                        http://upx.sourceforge.net
+

UPX is a portable, extendable, high-performance executable packer for +several different executable formats. It achieves an excellent compression +ratio and offers *very* fast decompression. Your executables suffer +no memory overhead or other drawbacks for most of the formats supported, +because of in-place decompression.

+

While you may use UPX freely for both non-commercial and commercial +executables (for details see the file LICENSE), we would highly +appreciate if you credit UPX and ourselves in the documentation, +possibly including a reference to the UPX home page. Thanks.

+

[ Using UPX in non-OpenSource applications without proper credits +is considered not politically correct ;-) ]

+

+

+
+

DISCLAIMER

+

UPX comes with ABSOLUTELY NO WARRANTY; for details see the file LICENSE.

+

This is the first production quality release, and we plan that future 1.xx +releases will be backward compatible with this version.

+

Please report all problems or suggestions to the authors. Thanks.

+

+

+
+

DESCRIPTION

+

UPX is a versatile executable packer with the following features:

+
+  - excellent compression ratio: compresses better than zip/gzip,
+      use UPX to decrease the size of your distribution !
+
+  - very fast decompression: about 10 MB/sec on an ancient Pentium 133,
+      about 200 MB/sec on an Athlon XP 2000+.
+
+  - no memory overhead for your compressed executables for most of the
+      supported formats
+
+  - safe: you can list, test and unpack your executables
+      Also, a checksum of both the compressed and uncompressed file is
+      maintained internally.
+
+  - universal: UPX can pack a number of executable formats:
+      * atari/tos
+      * bvmlinuz/386    [bootable Linux kernel]
+      * djgpp2/coff
+      * dos/com
+      * dos/exe
+      * dos/sys
+      * linux/386
+      * linux/elf386
+      * linux/sh386
+      * ps1/exe
+      * rtm32/pe
+      * tmt/adam
+      * vmlinuz/386     [bootable Linux kernel]
+      * vmlinux/386
+      * watcom/le (supporting DOS4G, PMODE/W, DOS32a and CauseWay)
+      * win32/pe (exe and dll)
+      * arm/pe (exe and dll)
+      * linux/elfamd64
+      * linux/elfppc32
+      * mach/elfppc32
+
+  - portable: UPX is written in portable endian-neutral C++
+
+  - extendable: because of the class layout it's very easy to support
+      new executable formats or add new compression algorithms
+
+  - free: UPX can be distributed and used freely. And from version 0.99
+      the full source code of UPX is released under the GNU General Public
+      License (GPL) !
+

You probably understand now why we call UPX the ``ultimate'' +executable packer.

+

+

+
+

COMMANDS

+

+

+

Compress

+

This is the default operation, eg. upx yourfile.exe will compress the file +specified on the command line.

+

+

+

Decompress

+

All UPX supported file formats can be unpacked using the -d switch, eg. +upx -d yourfile.exe will uncompress the file you've just compressed.

+

+

+

Test

+

The -t command tests the integrity of the compressed and uncompressed +data, eg. upx -t yourfile.exe check whether your file can be safely +decompressed. Note, that this command doesn't check the whole file, only +the part that will be uncompressed during program execution. This means +that you should not use this command instead of a virus checker.

+

+

+

List

+

The -l command prints out some information about the compressed files +specified on the command line as parameters, eg upx -l yourfile.exe +shows the compressed / uncompressed size and the compression ratio of +yourfile.exe.

+

+

+
+

OPTIONS

+

-q: be quiet, suppress warnings

+

-q -q (or -qq): be very quiet, suppress errors

+

-q -q -q (or -qqq): produce no output at all

+

--help: prints the help

+

--version: print the version of UPX

+

[ ...to be written... - type `upx --help' for now ]

+

+

+
+

COMPRESSION LEVELS & TUNING

+

UPX offers ten different compression levels from -1 to -9, +and --best. The default compression level is -8 for files +smaller than 512 kB, and -7 otherwise.

+
    +
  • +

    Compression levels 1, 2 and 3 are pretty fast.

    +
    • +
  • +

    Compression levels 4, 5 and 6 achieve a good time/ratio performance.

    +
    • +
  • +

    Compression levels 7, 8 and 9 favor compression ratio over speed.

    +
    • +
  • +

    Compression level --best may take a long time.

    +
    • +
+

Note that compression level --best can be somewhat slow for large +files, but you definitely should use it when releasing a final version +of your program.

+

Quick start for achieving the best compression ratio:

+

Try upx --brute myfile.exe.

+

Details for achieving the best compression ratio:

+
    +
  • +

    Use the compression level --best.

    +
    • +
  • +

    Try one or both of the options --all-methods and --all-filters.

    +
    • +
  • +

    Try the option --crp-ms=NUMBER. This uses more memory during compression +to achieve a (slightly) better compression ratio.

    +

    NUMBER must be a decimal value from 10000 to 999999, inclusive. +The default value is 10000 (ten thousand).

    +
    • +
  • +

    Info: the option --brute is an abbrevation for the options +--best --all-methods --all-filters --crp-ms=999999.

    +
    • +
  • +

    Try if --overlay=strip works.

    +
    • +
  • +

    For win32/pe programs there's --strip-relocs=0. See notes below.

    +
    • +
+

+

+
+

OVERLAY HANDLING OPTIONS

+

Info: An ``overlay'' means auxillary data atached after the logical end of +an executable, and it often contains application specific data +(this is a common practice to avoid an extra data file, though +it would be better to use resource sections).

+

UPX handles overlays like many other executable packers do: it simply +copies the overlay after the compressed image. This works with some +files, but doesn't work with others, depending on how an application +actually accesses this overlayed data.

+
+  --overlay=copy    Copy any extra data attached to the file. [DEFAULT]
+
+  --overlay=strip   Strip any overlay from the program instead of
+                    copying it. Be warned, this may make the compressed
+                    program crash or otherwise unusable.
+
+  --overlay=skip    Refuse to compress any program which has an overlay.
+

+

+
+

ENVIRONMENT

+

The environment variable UPX can hold a set of default +options for UPX. These options are interpreted first and +can be overwritten by explicit command line parameters. +For example:

+
+    for DOS/Windows:   set UPX=-9 --compress-icons#0
+    for sh/ksh/zsh:    UPX="-9 --compress-icons=0"; export UPX
+    for csh/tcsh:      setenv UPX "-9 --compress-icons=0"
+

Under DOS/Windows you must use '#' instead of '=' when setting the +environment variable because of a COMMAND.COM limitation.

+

Not all of the options are valid in the environment variable - +UPX will tell you.

+

You can explicitly use the --no-env option to ignore the +environment variable.

+

+

+
+

NOTES FOR THE SUPPORTED EXECUTABLE FORMATS

+

+

+

NOTES FOR ATARI/TOS

+

This is the executable format used by the Atari ST/TT, a Motorola 68000 +based personal computer which was popular in the late '80s. Support +of this format is only because of nostalgic feelings of one of +the authors and serves no practical purpose :-). +See http://www.freemint.de for more info.

+

Packed programs will be byte-identical to the original after uncompression. +All debug information will be stripped, though.

+

Extra options available for this executable format:

+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+

+

+

NOTES FOR BVMLINUZ/I386

+

Same as vmlinuz/i386.

+

+

+

NOTES FOR DOS/COM

+

Obviously UPX won't work with executables that want to read data from +themselves (like some commandline utilities that ship with Win95/98/ME).

+

Compressed programs only work on a 286+.

+

Packed programs will be byte-identical to the original after uncompression.

+

Maximum uncompressed size: ~65100 bytes.

+

Extra options available for this executable format:

+
+  --8086              Create an executable that works on any 8086 CPU.
+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+
+  --all-filters       Compress the program several times, using all
+                      available preprocessing filters. This may improve
+                      the compression ratio in some cases, but usually
+                      the default filter gives the best results anyway.
+

+

+

NOTES FOR DOS/EXE

+

dos/exe stands for all ``normal'' 16-bit DOS executables.

+

Obviously UPX won't work with executables that want to read data from +themselves (like some command line utilities that ship with Win95/98/ME).

+

Compressed programs only work on a 286+.

+

Extra options available for this executable format:

+
+  --8086              Create an executable that works on any 8086 CPU.
+
+  --no-reloc          Use no relocation records in the exe header.
+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+

+

+

NOTES FOR DOS/SYS

+

Compressed programs only work on a 286+.

+

Packed programs will be byte-identical to the original after uncompression.

+

Maximum uncompressed size: ~65350 bytes.

+

Extra options available for this executable format:

+
+  --8086              Create an executable that works on any 8086 CPU.
+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+
+  --all-filters       Compress the program several times, using all
+                      available preprocessing filters. This may improve
+                      the compression ratio in some cases, but usually
+                      the default filter gives the best results anyway.
+

+

+

NOTES FOR DJGPP2/COFF

+

First of all, it is recommended to use UPX *instead* of strip. strip has +the very bad habit of replacing your stub with its own (outdated) version. +Additionally UPX corrects a bug/feature in strip v2.8.x: it +will fix the 4 KByte aligment of the stub.

+

UPX includes the full functionality of stubify. This means it will +automatically stubify your COFF files. Use the option --coff to +disable this functionality (see below).

+

UPX automatically handles Allegro packfiles.

+

The DLM format (a rather exotic shared library extension) is not supported.

+

Packed programs will be byte-identical to the original after uncompression. +All debug information and trailing garbage will be stripped, though.

+

Extra options available for this executable format:

+
+  --coff              Produce COFF output instead of EXE. By default
+                      UPX keeps your current stub.
+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+
+  --all-filters       Compress the program several times, using all
+                      available preprocessing filters. This may improve
+                      the compression ratio in some cases, but usually
+                      the default filter gives the best results anyway.
+

+

+

NOTES FOR LINUX [general]

+

Introduction

+
+  Linux/386 support in UPX consists of 3 different executable formats,
+  one optimized for ELF excutables ("linux/elf386"), one optimized
+  for shell scripts ("linux/sh386"), and one generic format
+  ("linux/386").
+
+  We will start with a general discussion first, but please
+  also read the relevant docs for each of the individual formats.
+
+  Also, there is special support for bootable kernels - see the
+  description of the vmlinuz/386 format.
+

General user's overview

+
+  Running a compressed executable program trades less space on a
+  ``permanent'' storage medium (such as a hard disk, floppy disk,
+  CD-ROM, flash memory, EPROM, etc.) for more space in one or more
+  ``temporary'' storage media (such as RAM, swap space, /tmp, etc.).
+  Running a compressed executable also requires some additional CPU
+  cycles to generate the compressed executable in the first place,
+  and to decompress it at each invocation.
+
+  How much space is traded?  It depends on the executable, but many
+  programs save 30% to 50% of permanent disk space.  How much CPU
+  overhead is there?  Again, it depends on the executable, but
+  decompression speed generally is at least many megabytes per second,
+  and frequently is limited by the speed of the underlying disk
+  or network I/O.
+
+  Depending on the statistics of usage and access, and the relative
+  speeds of CPU, RAM, swap space, /tmp, and filesystem storage, then
+  invoking and running a compressed executable can be faster than
+  directly running the corresponding uncompressed program.
+  The operating system might perfrom fewer expensive I/O operations
+  to invoke the compressed program.  Paging to or from swap space
+  or /tmp might be faster than paging from the general filesystem.
+  ``Medium-sized'' programs which access about 1/3 to 1/2 of their
+  stored program bytes can do particulary well with compression.
+  Small programs tend not to benefit as much because the absolute
+  savings is less.  Big programs tend not to benefit proportionally
+  because each invocation may use only a small fraction of the program,
+  yet UPX decompresses the entire program before invoking it.
+  But in environments where disk or flash memory storage is limited,
+  then compression may win anyway.
+
+  Currently, executables compressed by UPX do not share RAM at runtime
+  in the way that executables mapped from a filesystem do.  As a
+  result, if the same program is run simultaneously by more than one
+  process, then using the compressed version will require more RAM and/or
+  swap space.  So, shell programs (bash, csh, etc.)  and ``make''
+  might not be good candidates for compression.
+
+  UPX recognizes three executable formats for Linux: Linux/elf386,
+  Linux/sh386, and Linux/386.  Linux/386 is the most generic format;
+  it accommodates any file that can be executed.  At runtime, the UPX
+  decompression stub re-creates in /tmp a copy of the original file,
+  and then the copy is (re-)executed with the same arguments.
+  ELF binary executables prefer the Linux/elf386 format by default,
+  because UPX decompresses them directly into RAM, uses only one
+  exec, does not use space in /tmp, and does not use /proc.
+  Shell scripts where the underlying shell accepts a ``-c'' argument
+  can use the Linux/sh386 format.  UPX decompresses the shell script
+  into low memory, then maps the shell and passes the entire text of the
+  script as an argument with a leading ``-c''.
+

General benefits:

+
+  - UPX can compress all executables, be it AOUT, ELF, libc4, libc5,
+    libc6, Shell/Perl/Python/... scripts, standalone Java .class
+    binaries, or whatever...
+    All scripts and programs will work just as before.
+
+  - Compressed programs are completely self-contained. No need for
+    any external program.
+
+  - UPX keeps your original program untouched. This means that
+    after decompression you will have a byte-identical version,
+    and you can use UPX as a file compressor just like gzip.
+    [ Note that UPX maintains a checksum of the file internally,
+      so it is indeed a reliable alternative. ]
+
+  - As the stub only uses syscalls and isn't linked against libc it
+    should run under any Linux configuration that can run ELF
+    binaries.
+
+  - For the same reason compressed executables should run under
+    FreeBSD and other systems which can run Linux binaries.
+    [ Please send feedback on this topic ]
+

General drawbacks:

+
+  - It is not advisable to compress programs which usually have many
+    instances running (like `sh' or `make') because the common segments of
+    compressed programs won't be shared any longer between different
+    processes.
+
+  - `ldd' and `size' won't show anything useful because all they
+    see is the statically linked stub.  Since version 0.82 the section
+    headers are stripped from the UPX stub and `size' doesn't even
+    recognize the file format.  The file patches/patch-elfcode.h has a
+    patch to fix this bug in `size' and other programs which use GNU BFD.
+

General notes:

+
+  - As UPX leaves your original program untouched it is advantageous
+    to strip it before compression.
+
+  - If you compress a script you will lose platform independence -
+    this could be a problem if you are using NFS mounted disks.
+
+  - Compression of suid, guid and sticky-bit programs is rejected
+    because of possible security implications.
+
+  - For the same reason there is no sense in making any compressed
+    program suid.
+
+  - Obviously UPX won't work with executables that want to read data
+    from themselves. E.g., this might be a problem for Perl scripts
+    which access their __DATA__ lines.
+
+  - In case of internal errors the stub will abort with exitcode 127.
+    Typical reasons for this to happen are that the program has somehow
+    been modified after compression.
+    Running `strace -o strace.log compressed_file' will tell you more.
+

+

+

NOTES FOR LINUX/ELF386

+

Please read the general Linux description first.

+

The linux/elf386 format decompresses directly into RAM, +uses only one exec, does not use space in /tmp, +and does not use /proc.

+

Linux/elf386 is automatically selected for Linux ELF exectuables.

+

Packed programs will be byte-identical to the original after uncompression.

+

How it works:

+
+  For ELF executables, UPX decompresses directly to memory, simulating
+  the mapping that the operating system kernel uses during exec(),
+  including the PT_INTERP program interpreter (if any).
+  The brk() is set by a special PT_LOAD segment in the compressed
+  executable itself.  UPX then wipes the stack clean except for
+  arguments, environment variables, and Elf_auxv entries (this is
+  required by bugs in the startup code of /lib/ld-linux.so as of
+  May 2000), and transfers control to the program interpreter or
+  the e_entry address of the original executable.
+
+  The UPX stub is about 1700 bytes long, partly written in assembler
+  and only uses kernel syscalls. It is not linked against any libc.
+

Specific drawbacks:

+
+  - For linux/elf386 and linux/sh386 formats, you will be relying on
+    RAM and swap space to hold all of the decompressed program during
+    the lifetime of the process.  If you already use most of your swap
+    space, then you may run out.  A system that is "out of memory"
+    can become fragile.  Many programs do not react gracefully when
+    malloc() returns 0.  With newer Linux kernels, the kernel
+    may decide to kill some processes to regain memory, and you
+    may not like the kernel's choice of which to kill.  Running
+    /usr/bin/top is one way to check on the usage of swap space.
+

Extra options available for this executable format:

+
+  (none)
+

+

+

NOTES FOR LINUX/SH386

+

Please read the general Linux description first.

+

Shell scripts where the underling shell accepts a ``-c'' argument +can use the Linux/sh386 format. UPX decompresses the shell script +into low memory, then maps the shell and passes the entire text of the +script as an argument with a leading ``-c''. +It does not use space in /tmp, and does not use /proc.

+

Linux/sh386 is automatically selected for shell scripts that +use a known shell.

+

Packed programs will be byte-identical to the original after uncompression.

+

How it works:

+
+  For shell script executables (files beginning with "#!/" or "#! /")
+  where the shell is known to accept "-c <command>", UPX decompresses
+  the file into low memory, then maps the shell (and its PT_INTERP),
+  and passes control to the shell with the entire decompressed file
+  as the argument after "-c".  Known shells are sh, ash, bash, bsh, csh,
+  ksh, tcsh, pdksh.  Restriction: UPX cannot use this method
+  for shell scripts which use the one optional string argument after
+  the shell name in the script (example: "#! /bin/sh option3\n".)
+
+  The UPX stub is about 1700 bytes long, partly written in assembler
+  and only uses kernel syscalls. It is not linked against any libc.
+

Specific drawbacks:

+
+  - For linux/elf386 and linux/sh386 formats, you will be relying on
+    RAM and swap space to hold all of the decompressed program during
+    the lifetime of the process.  If you already use most of your swap
+    space, then you may run out.  A system that is "out of memory"
+    can become fragile.  Many programs do not react gracefully when
+    malloc() returns 0.  With newer Linux kernels, the kernel
+    may decide to kill some processes to regain memory, and you
+    may not like the kernel's choice of which to kill.  Running
+    /usr/bin/top is one way to check on the usage of swap space.
+

Extra options available for this executable format:

+
+  (none)
+

+

+

NOTES FOR LINUX/386

+

Please read the general Linux description first.

+

The generic linux/386 format decompresses to /tmp and needs +/proc filesystem support. It starts the decompressed program +via the execve() syscall.

+

Linux/386 is only selected if the specialized linux/elf386 +and linux/sh386 won't recognize a file.

+

Packed programs will be byte-identical to the original after uncompression.

+

How it works:

+
+  For files which are not ELF and not a script for a known "-c" shell,
+  UPX uses kernel execve(), which first requires decompressing to a
+  temporary file in the filesystem.  Interestingly -
+  because of the good memory management of the Linux kernel - this
+  often does not introduce a noticable delay, and in fact there
+  will be no disk access at all if you have enough free memory as
+  the entire process takes places within the filesystem buffers.
+
+  A compressed executable consists of the UPX stub and an overlay
+  which contains the original program in a compressed form.
+
+  The UPX stub is a statically linked ELF executable and does
+  the following at program startup:
+
+    1) decompress the overlay to a temporary location in /tmp
+    2) open the temporary file for reading
+    3) try to delete the temporary file and start (execve)
+       the uncompressed program in /tmp using /proc/<pid>/fd/X as
+       attained by step 2)
+    4) if that fails, fork off a subprocess to clean up and
+       start the program in /tmp in the meantime
+
+  The UPX stub is about 1700 bytes long, partly written in assembler
+  and only uses kernel syscalls. It is not linked against any libc.
+

Specific drawbacks:

+
+  - You need additional free disk space for the uncompressed program
+    in your /tmp directory. This program is deleted immediately after
+    decompression, but you still need it for the full execution time
+    of the program.
+
+  - You must have /proc filesystem support as the stub wants to open
+    /proc/<pid>/exe and needs /proc/<pid>/fd/X. This also means that you
+    cannot compress programs that are used during the boot sequence
+    before /proc is mounted.
+
+  - Utilities like `top' will display numerical values in the process
+    name field. This is because Linux computes the process name from
+    the first argument of the last execve syscall (which is typically
+    something like /proc/<pid>/fd/3).
+
+  - Because of temporary decompression to disk the decompression speed
+    is not as fast as with the other executable formats. Still, I can see
+    no noticable delay when starting programs like my ~3 MB emacs (which
+    is less than 1 MB when compressed :-).
+

Extra options available for this executable format:

+
+  --force-execve      Force the use of the generic linux/386 "execve"
+                      format, i.e. do not try the linux/elf386 and
+                      linux/sh386 formats.
+

+

+

NOTES FOR PS1/EXE

+

This is the executable format used by the Sony PlayStation (PSone), +a Mips R3000 based gaming console which is popular since the late '90s. +Support of this format is very similar to the Atari one, because of +nostalgic feelings of one of the authors.

+

Packed programs will be byte-identical to the original after uncompression, +until further notice.

+

Maximum uncompressed size: ~1998848 bytes.

+

Notes:

+
+  - UPX creates as default a 'CD-Rom only' PS1/PS2 compatible executable.
+    For transfer between client/target use options below.
+
+  - Normally the packed files use the same memory areas like the uncompressed
+    versions, so they will not override other memory areas while unpacking.
+    If this isn't possible UPX will abort showing a 'packed data overlap'
+    error. With the "--force" option UPX will set a few 'bytes higher' loading
+    offset for the packed file, but this isn't a real problem if it is a
+    single or boot-only executable.
+

Extra options available for this executable format:

+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+
+  --boot-only         The format will only run from a CD and may slightly
+                      improves the compression ratio. The decompression
+                      routines are faster than default ones.
+                      But it cannot be used for host/client transfer !
+
+  --no-align          This option disables CD mode 2 data sector format
+                      alignment. May slightly improves the compression ratio,
+                      but the compressed executable will not boot from a CD.
+                      Use it for client/target transfer only !
+

+

+

NOTES FOR RTM32/PE and ARM/PE

+

Same as win32/pe.

+

+

+

NOTES FOR TMT/ADAM

+

This format is used by the TMT Pascal compiler - see http://www.tmt.com/ .

+

Extra options available for this executable format:

+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+
+  --all-filters       Compress the program several times, using all
+                      available preprocessing filters. This may improve
+                      the compression ratio in some cases, but usually
+                      the default filter gives the best results anyway.
+

+

+

NOTES FOR VMLINUZ/386

+

The vmlinuz/386 and bvmlinuz/386 formats take a gzip-compressed +bootable Linux kernel image (``vmlinuz'', ``zImage'', ``bzImage''), +gzip-decompress it and re-compress it with the UPX compression method.

+

vmlinuz/386 is completely unrelated to the other Linux executable +formats, and it does not share any of their drawbacks.

+

Notes:

+
+  - Be sure that "vmlinuz/386" or "bvmlinuz/386" is displayed
+  during compression - otherwise a wrong executable format
+  may have been used, and the kernel won't boot.
+

Benefits:

+
+  - Better compression (but note that the kernel was already compressed,
+  so the improvement is not as large as with other formats).
+  Still, the bytes saved may be essential for special needs like
+  bootdisks.
+
+     For example, this is what I get for my 2.2.16 kernel:
+        1589708  vmlinux
+         641073  bzImage        [original]
+         560755  bzImage.upx    [compressed by "upx -9"]
+
+  - Much faster decompression at kernel boot time (but kernel
+    decompression speed is not really an issue these days).
+

Drawbacks:

+
+  (none)
+

Extra options available for this executable format:

+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+
+  --all-filters       Compress the program several times, using all
+                      available preprocessing filters. This may improve
+                      the compression ratio in some cases, but usually
+                      the default filter gives the best results anyway.
+

+

+

NOTES FOR WATCOM/LE

+

UPX has been successfully tested with the following extenders: + DOS4G, DOS4GW, PMODE/W, DOS32a, CauseWay. + The WDOS/X extender is partly supported (for details + see the file bugs BUGS).

+

DLLs and the LX format are not supported.

+

Extra options available for this executable format:

+
+  --le                Produce an unbound LE output instead of
+                      keeping the current stub.
+

+

+

NOTES FOR WIN32/PE

+

The PE support in UPX is quite stable now, but probably there are +still some incompabilities with some files.

+

Because of the way UPX (and other packers for this format) works, you +can see increased memory usage of your compressed files because the whole +program is loaded into memory at startup. +If you start several instances of huge compressed programs you're +wasting memory because the common segements of the program won't +get shared across the instances. +On the other hand if you're compressing only smaller programs, or +running only one instance of larger programs, then this penalty is +smaller, but it's still there.

+

If you're running executables from network, then compressed programs +will load faster, and require less bandwidth during execution.

+

DLLs are supported. But UPX compressed DLLs can not share common data and +code when they got used by multiple applications. So compressing msvcrt.dll +is a waste of memory, but compressing the dll plugins of a particular +application may be a better idea.

+

Screensavers are supported, with the restriction that the filename +must end with ``.scr'' (as screensavers are handled slightly different +than normal exe files).

+

UPX compressed PE files has some minor memory overhead (usually in the +10 - 30 kbytes range) which can be seen by specifying the ``-i'' command +line switch during compression.

+

Extra options available for this executable format:

+
+ --compress-exports=0 Don't compress the export section.
+                      Use this if you plan to run the compressed
+                      program under Wine.
+ --compress-exports=1 Compress the export section. [DEFAULT]
+                      Compression of the export section can improve the
+                      compression ratio quite a bit but may not work
+                      with all programs (like winword.exe).
+                      UPX never compresses the export section of a DLL
+                      regardless of this option.
+
+  --compress-icons=0  Don't compress any icons.
+  --compress-icons=1  Compress all but the first icon.
+  --compress-icons=2  Compress all icons which are not in the
+                      first icon directory. [DEFAULT]
+
+  --compress-resources=0  Don't compress any resources at all.
+
+  --keep-resource=list Don't compress resources specified by the list.
+                      The members of the list are separated by commas.
+                      A list member has the following format: I<type[/name]>.
+                      I<Type> is the type of the resource. Standard types
+                      must be specified as decimal numbers, user types can be
+                      specified by decimal IDs or strings. I<Name> is the
+                      identifier of the resource. It can be a decimal number
+                      or a string. For example:
+
+                      --keep-resource=2/MYBITMAP,5,6/12345
+
+                      UPX won't compress the named bitmap resource "MYBITMAP",
+                      it leaves every dialog (5) resource uncompressed, and
+                      it won't touch the string table resource with identifier
+                      12345.
+
+  --force             Force compression even when there is an
+                      unexpected value in a header field.
+                      Use with care.
+
+  --strip-relocs=0    Don't strip relocation records.
+  --strip-relocs=1    Strip relocation records. [DEFAULT]
+                      This option only works on executables with base
+                      address greater or equal to 0x400000. Usually the
+                      compressed files becomes smaller, but some files
+                      may become larger. Note that the resulting file will
+                      not work under Windows 3.x (Win32s).
+                      UPX never strips relocations from a DLL
+                      regardless of this option.
+
+  --all-methods       Compress the program several times, using all
+                      available compression methods. This may improve
+                      the compression ratio in some cases, but usually
+                      the default method gives the best results anyway.
+
+  --all-filters       Compress the program several times, using all
+                      available preprocessing filters. This may improve
+                      the compression ratio in some cases, but usually
+                      the default filter gives the best results anyway.
+

+

+
+

DIAGNOSTICS

+

Exit status is normally 0; if an error occurs, exit status +is 1. If a warning occurs, exit status is 2.

+

UPX's diagnostics are intended to be self-explanatory.

+

+

+
+

BUGS

+

Please report all bugs immediately to the authors.

+

+

+
+

AUTHORS

+
+ Markus F.X.J. Oberhumer <markus@oberhumer.com>
+ http://www.oberhumer.com
+
+ Laszlo Molnar <ml1050@users.sourceforge.net>
+
+ John F. Reiser <jreiser@BitWagon.com>
+
+ Jens Medoch <jssg@users.sourceforge.net>
+

+

+
+

COPYRIGHT

+

Copyright (C) 1996-2006 Markus Franz Xaver Johannes Oberhumer

+

Copyright (C) 1996-2006 Laszlo Molnar

+

Copyright (C) 2000-2006 John F. Reiser

+

Copyright (C) 2002-2006 Jens Medoch

+

This program may be used freely, and you are welcome to +redistribute it under certain conditions.

+

This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +UPX License Agreement for more details.

+

You should have received a copy of the UPX License Agreement along +with this program; see the file LICENSE. If not, visit the UPX home page.

+ + + +