diff options
Diffstat (limited to 'deps/share')
233 files changed, 13931 insertions, 0 deletions
diff --git a/deps/share/doc/xz/AUTHORS b/deps/share/doc/xz/AUTHORS new file mode 100644 index 0000000..bda8797 --- /dev/null +++ b/deps/share/doc/xz/AUTHORS @@ -0,0 +1,27 @@ + +Authors of XZ Utils +=================== + + XZ Utils is developed and maintained by Lasse Collin + <[email protected]>. + + Major parts of liblzma are based on code written by Igor Pavlov, + specifically the LZMA SDK <http://7-zip.org/sdk.html>. Without + this code, XZ Utils wouldn't exist. + + The SHA-256 implementation in liblzma is based on the code found from + 7-Zip <http://7-zip.org/>, which has a modified version of the SHA-256 + code found from Crypto++ <http://www.cryptopp.com/>. The SHA-256 code + in Crypto++ was written by Kevin Springle and Wei Dai. + + Some scripts have been adapted from gzip. The original versions + were written by Jean-loup Gailly, Charles Levert, and Paul Eggert. + Andrew Dudman helped adapting the scripts and their man pages for + XZ Utils. + + The GNU Autotools-based build system contains files from many authors, + which I'm not trying to list here. + + Several people have contributed fixes or reported bugs. Most of them + are mentioned in the file THANKS. + diff --git a/deps/share/doc/xz/COPYING b/deps/share/doc/xz/COPYING new file mode 100644 index 0000000..20e60d5 --- /dev/null +++ b/deps/share/doc/xz/COPYING @@ -0,0 +1,65 @@ + +XZ Utils Licensing +================== + + Different licenses apply to different files in this package. Here + is a rough summary of which licenses apply to which parts of this + package (but check the individual files to be sure!): + + - liblzma is in the public domain. + + - xz, xzdec, and lzmadec command line tools are in the public + domain unless GNU getopt_long had to be compiled and linked + in from the lib directory. The getopt_long code is under + GNU LGPLv2.1+. + + - The scripts to grep, diff, and view compressed files have been + adapted from gzip. These scripts and their documentation are + under GNU GPLv2+. + + - All the documentation in the doc directory and most of the + XZ Utils specific documentation files in other directories + are in the public domain. + + - Translated messages are in the public domain. + + - The build system contains public domain files, and files that + are under GNU GPLv2+ or GNU GPLv3+. None of these files end up + in the binaries being built. + + - Test files and test code in the tests directory, and debugging + utilities in the debug directory are in the public domain. + + - The extra directory may contain public domain files, and files + that are under various free software licenses. + + You can do whatever you want with the files that have been put into + the public domain. If you find public domain legally problematic, + take the previous sentence as a license grant. If you still find + the lack of copyright legally problematic, you have too many + lawyers. + + As usual, this software is provided "as is", without any warranty. + + If you copy significant amounts of public domain code from XZ Utils + into your project, acknowledging this somewhere in your software is + polite (especially if it is proprietary, non-free software), but + naturally it is not legally required. Here is an example of a good + notice to put into "about box" or into documentation: + + This software includes code from XZ Utils <https://tukaani.org/xz/>. + + The following license texts are included in the following files: + - COPYING.LGPLv2.1: GNU Lesser General Public License version 2.1 + - COPYING.GPLv2: GNU General Public License version 2 + - COPYING.GPLv3: GNU General Public License version 3 + + Note that the toolchain (compiler, linker etc.) may add some code + pieces that are copyrighted. Thus, it is possible that e.g. liblzma + binary wouldn't actually be in the public domain in its entirety + even though it contains no copyrighted code from the XZ Utils source + package. + + If you have questions, don't hesitate to ask the author(s) for more + information. + diff --git a/deps/share/doc/xz/COPYING.GPLv2 b/deps/share/doc/xz/COPYING.GPLv2 new file mode 100644 index 0000000..d159169 --- /dev/null +++ b/deps/share/doc/xz/COPYING.GPLv2 @@ -0,0 +1,339 @@ + GNU GENERAL PUBLIC LICENSE + Version 2, June 1991 + + Copyright (C) 1989, 1991 Free Software Foundation, Inc., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 Lesser 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. + + <one line to give the program's name and a brief idea of what it does.> + Copyright (C) <year> <name of author> + + 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., + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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) year 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. + + <signature of Ty Coon>, 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 Lesser General +Public License instead of this License. diff --git a/deps/share/doc/xz/NEWS b/deps/share/doc/xz/NEWS new file mode 100644 index 0000000..aade494 --- /dev/null +++ b/deps/share/doc/xz/NEWS @@ -0,0 +1,687 @@ + +XZ Utils Release Notes +====================== + +5.3.1alpha (2018-04-29) + + * All fixes from 5.2.4. + + * Add lzma_file_info_decoder() into liblzma and use it in xz to + implement the --list feature. + + * Capsicum sandbox support is enabled by default where available + (FreeBSD >= 10). + + +5.2.5 (2020-03-17) + + * liblzma: + + - Fixed several C99/C11 conformance bugs. Now the code is clean + under gcc/clang -fsanitize=undefined. Some of these changes + might have a negative effect on performance with old GCC + versions or compilers other than GCC and Clang. The configure + option --enable-unsafe-type-punning can be used to (mostly) + restore the old behavior but it shouldn't normally be used. + + - Improved API documentation of lzma_properties_decode(). + + - Added a very minor encoder speed optimization. + + * xz: + + - Fixed a crash in "xz -dcfv not_an_xz_file". All four options + were required to trigger it. The crash occurred in the + progress indicator code when xz was in passthru mode where + xz works like "cat". + + - Fixed an integer overflow with 32-bit off_t. It could happen + when decompressing a file that has a long run of zero bytes + which xz would try to write as a sparse file. Since the build + system enables large file support by default, off_t is + normally 64-bit even on 32-bit systems. + + - Fixes for --flush-timeout: + * Fix semi-busy-waiting. + * Avoid unneeded flushes when no new input has arrived + since the previous flush was completed. + + - Added a special case for 32-bit xz: If --memlimit-compress is + used to specify a limit that exceeds 4020 MiB, the limit will + be set to 4020 MiB. The values "0" and "max" aren't affected + by this and neither is decompression. This hack can be + helpful when a 32-bit xz has access to 4 GiB address space + but the specified memlimit exceeds 4 GiB. This can happen + e.g. with some scripts. + + - Capsicum sandbox is now enabled by default where available + (FreeBSD >= 10). The sandbox debug messages (xz -vv) were + removed since they seemed to be more annoying than useful. + + - DOS build now requires DJGPP 2.05 instead of 2.04beta. + A workaround for a locale problem with DJGPP 2.05 was added. + + * xzgrep and other scripts: + + - Added a configure option --enable-path-for-scripts=PREFIX. + It is disabled by default except on Solaris where the default + is /usr/xpg4/bin. See INSTALL for details. + + - Added a workaround for a POSIX shell detection problem on + Solaris. + + * Build systems: + + - Added preliminary build instructions for z/OS. See INSTALL + section 1.2.9. + + - Experimental CMake support was added. It should work to build + static liblzma on a few operating systems. It may or may not + work to build shared liblzma. On some platforms it can build + xz and xzdec too but those are only for testing. See the + comment in the beginning of CMakeLists.txt for details. + + - Visual Studio project files were updated. + WindowsTargetPlatformVersion was removed from VS2017 files + and set to "10.0" in the added VS2019 files. In the future + the VS project files will be removed when CMake support is + good enough. + + - New #defines in config.h: HAVE___BUILTIN_ASSUME_ALIGNED, + HAVE___BUILTIN_BSWAPXX, and TUKLIB_USE_UNSAFE_TYPE_PUNNING. + + - autogen.sh has a new optional dependency on po4a and a new + option --no-po4a to skip that step. This matters only if one + wants to remake the build files. po4a is used to update the + translated man pages but as long as the man pages haven't + been modified, there's nothing to update and one can use + --no-po4a to avoid the dependency on po4a. + + * Translations: + + - XZ Utils translations are now handled by the Translation + Project: https://translationproject.org/domain/xz.html + + - All man pages are now included in German too. + + - New xz translations: Brazilian Portuguese, Finnish, + Hungarian, Chinese (simplified), Chinese (traditional), + and Danish (partial translation) + + - Updated xz translations: French, German, Italian, and Polish + + - Unfortunately a few new xz translations weren't included due + to technical problems like too long lines in --help output or + misaligned column headings in tables. In the future, many of + these strings will be split and e.g. the table column + alignment will be handled in software. This should make the + strings easier to translate. + + +5.2.4 (2018-04-29) + + * liblzma: + + - Allow 0 as memory usage limit instead of returning + LZMA_PROG_ERROR. Now 0 is treated as if 1 byte was specified, + which effectively is the same as 0. + + - Use "noexcept" keyword instead of "throw()" in the public + headers when a C++11 (or newer standard) compiler is used. + + - Added a portability fix for recent Intel C Compilers. + + - Microsoft Visual Studio build files have been moved under + windows/vs2013 and windows/vs2017. + + * xz: + + - Fix "xz --list --robot missing_or_bad_file.xz" which would + try to print an uninitialized string and thus produce garbage + output. Since the exit status is non-zero, most uses of such + a command won't try to interpret the garbage output. + + - "xz --list foo.xz" could print "Internal error (bug)" in a + corner case where a specific memory usage limit had been set. + + +5.2.3 (2016-12-30) + + * xz: + + - Always close a file before trying to delete it to avoid + problems on some operating system and file system combinations. + + - Fixed copying of file timestamps on Windows. + + - Added experimental (disabled by default) sandbox support using + Capsicum (FreeBSD >= 10). See --enable-sandbox in INSTALL. + + * C99/C11 conformance fixes to liblzma. The issues affected at least + some builds using link-time optimizations. + + * Fixed bugs in the rarely-used function lzma_index_dup(). + + * Use of external SHA-256 code is now disabled by default. + It can still be enabled by passing --enable-external-sha256 + to configure. The reasons to disable it by default (see INSTALL + for more details): + + - Some OS-specific SHA-256 implementations conflict with + OpenSSL and cause problems in programs that link against both + liblzma and libcrypto. At least FreeBSD 10 and MINIX 3.3.0 + are affected. + + - The internal SHA-256 is faster than the SHA-256 code in + some operating systems. + + * Changed CPU core count detection to use sched_getaffinity() on + GNU/Linux and GNU/kFreeBSD. + + * Fixes to the build-system and xz to make xz buildable even when + encoders, decoders, or threading have been disabled from libilzma + using configure options. These fixes added two new #defines to + config.h: HAVE_ENCODERS and HAVE_DECODERS. + + +5.2.2 (2015-09-29) + + * Fixed bugs in QNX-specific code. + + * Omitted the use of pipe2() even if it is available to avoid + portability issues with some old Linux and glibc combinations. + + * Updated German translation. + + * Added project files to build static and shared liblzma (not the + whole XZ Utils) with Visual Studio 2013 update 2 or later. + + * Documented that threaded decompression hasn't been implemented + yet. A 5.2.0 NEWS entry describing multi-threading support had + incorrectly said "decompression" when it should have said + "compression". + + +5.2.1 (2015-02-26) + + * Fixed a compression-ratio regression in fast mode of LZMA1 and + LZMA2. The bug is present in 5.1.4beta and 5.2.0 releases. + + * Fixed a portability problem in xz that affected at least OpenBSD. + + * Fixed xzdiff to be compatible with FreeBSD's mktemp which differs + from most other mktemp implementations. + + * Changed CPU core count detection to use cpuset_getaffinity() on + FreeBSD. + + +5.2.0 (2014-12-21) + + Since 5.1.4beta: + + * All fixes from 5.0.8 + + * liblzma: Fixed lzma_stream_encoder_mt_memusage() when a preset + was used. + + * xzdiff: If mktemp isn't installed, mkdir will be used as + a fallback to create a temporary directory. Installing mktemp + is still recommended. + + * Updated French, German, Italian, Polish, and Vietnamese + translations. + + Summary of fixes and new features added in the 5.1.x development + releases: + + * liblzma: + + - Added support for multi-threaded compression. See the + lzma_mt structure, lzma_stream_encoder_mt(), and + lzma_stream_encoder_mt_memusage() in <lzma/container.h>, + lzma_get_progress() in <lzma/base.h>, and lzma_cputhreads() + in <lzma/hardware.h> for details. + + - Made the uses of lzma_allocator const correct. + + - Added lzma_block_uncomp_encode() to create uncompressed + .xz Blocks using LZMA2 uncompressed chunks. + + - Added support for LZMA_IGNORE_CHECK. + + - A few speed optimizations were made. + + - Added support for symbol versioning. It is enabled by default + on GNU/Linux, other GNU-based systems, and FreeBSD. + + - liblzma (not the whole XZ Utils) should now be buildable + with MSVC 2013 update 2 or later using windows/config.h. + + * xz: + + - Fixed a race condition in the signal handling. It was + possible that e.g. the first SIGINT didn't make xz exit + if reading or writing blocked and one had bad luck. The fix + is non-trivial, so as of writing it is unknown if it will be + backported to the v5.0 branch. + + - Multi-threaded compression can be enabled with the + --threads (-T) option. + [Fixed: This originally said "decompression".] + + - New command line options in xz: --single-stream, + --block-size=SIZE, --block-list=SIZES, + --flush-timeout=TIMEOUT, and --ignore-check. + + - xz -lvv now shows the minimum xz version that is required to + decompress the file. Currently it is 5.0.0 for all supported + .xz files except files with empty LZMA2 streams require 5.0.2. + + * xzdiff and xzgrep now support .lzo files if lzop is installed. + The .tzo suffix is also recognized as a shorthand for .tar.lzo. + + +5.1.4beta (2014-09-14) + + * All fixes from 5.0.6 + + * liblzma: Fixed the use of presets in threaded encoder + initialization. + + * xz --block-list and --block-size can now be used together + in single-threaded mode. Previously the combination only + worked in multi-threaded mode. + + * Added support for LZMA_IGNORE_CHECK to liblzma and made it + available in xz as --ignore-check. + + * liblzma speed optimizations: + + - Initialization of a new LZMA1 or LZMA2 encoder has been + optimized. (The speed of reinitializing an already-allocated + encoder isn't affected.) This helps when compressing many + small buffers with lzma_stream_buffer_encode() and other + similar situations where an already-allocated encoder state + isn't reused. This speed-up is visible in xz too if one + compresses many small files one at a time instead running xz + once and giving all files as command-line arguments. + + - Buffer comparisons are now much faster when unaligned access + is allowed (configured with --enable-unaligned-access). This + speeds up encoding significantly. There is arch-specific code + for 32-bit and 64-bit x86 (32-bit needs SSE2 for the best + results and there's no run-time CPU detection for now). + For other archs there is only generic code which probably + isn't as optimal as arch-specific solutions could be. + + - A few speed optimizations were made to the SHA-256 code. + (Note that the builtin SHA-256 code isn't used on all + operating systems.) + + * liblzma can now be built with MSVC 2013 update 2 or later + using windows/config.h. + + * Vietnamese translation was added. + + +5.1.3alpha (2013-10-26) + + * All fixes from 5.0.5 + + * liblzma: + + - Fixed a deadlock in the threaded encoder. + + - Made the uses of lzma_allocator const correct. + + - Added lzma_block_uncomp_encode() to create uncompressed + .xz Blocks using LZMA2 uncompressed chunks. + + - Added support for native threads on Windows and the ability + to detect the number of CPU cores. + + * xz: + + - Fixed a race condition in the signal handling. It was + possible that e.g. the first SIGINT didn't make xz exit + if reading or writing blocked and one had bad luck. The fix + is non-trivial, so as of writing it is unknown if it will be + backported to the v5.0 branch. + + - Made the progress indicator work correctly in threaded mode. + + - Threaded encoder now works together with --block-list=SIZES. + + - Added preliminary support for --flush-timeout=TIMEOUT. + It can be useful for (somewhat) real-time streaming. For + now the decompression side has to be done with something + else than the xz tool due to how xz does buffering, but this + should be fixed. + + +5.1.2alpha (2012-07-04) + + * All fixes from 5.0.3 and 5.0.4 + + * liblzma: + + - Fixed a deadlock and an invalid free() in the threaded encoder. + + - Added support for symbol versioning. It is enabled by default + on GNU/Linux, other GNU-based systems, and FreeBSD. + + - Use SHA-256 implementation from the operating system if one is + available in libc, libmd, or libutil. liblzma won't use e.g. + OpenSSL or libgcrypt to avoid introducing new dependencies. + + - Fixed liblzma.pc for static linking. + + - Fixed a few portability bugs. + + * xz --decompress --single-stream now fixes the input position after + successful decompression. Now the following works: + + echo foo | xz > foo.xz + echo bar | xz >> foo.xz + ( xz -dc --single-stream ; xz -dc --single-stream ) < foo.xz + + Note that it doesn't work if the input is not seekable + or if there is Stream Padding between the concatenated + .xz Streams. + + * xz -lvv now shows the minimum xz version that is required to + decompress the file. Currently it is 5.0.0 for all supported .xz + files except files with empty LZMA2 streams require 5.0.2. + + * Added an *incomplete* implementation of --block-list=SIZES to xz. + It only works correctly in single-threaded mode and when + --block-size isn't used at the same time. --block-list allows + specifying the sizes of Blocks which can be useful e.g. when + creating files for random-access reading. + + +5.1.1alpha (2011-04-12) + + * All fixes from 5.0.2 + + * liblzma fixes that will also be included in 5.0.3: + + - A memory leak was fixed. + + - lzma_stream_buffer_encode() no longer creates an empty .xz + Block if encoding an empty buffer. Such an empty Block with + LZMA2 data would trigger a bug in 5.0.1 and older (see the + first bullet point in 5.0.2 notes). When releasing 5.0.2, + I thought that no encoder creates this kind of files but + I was wrong. + + - Validate function arguments better in a few functions. Most + importantly, specifying an unsupported integrity check to + lzma_stream_buffer_encode() no longer creates a corrupt .xz + file. Probably no application tries to do that, so this + shouldn't be a big problem in practice. + + - Document that lzma_block_buffer_encode(), + lzma_easy_buffer_encode(), lzma_stream_encoder(), and + lzma_stream_buffer_encode() may return LZMA_UNSUPPORTED_CHECK. + + - The return values of the _memusage() functions are now + documented better. + + * Support for multithreaded compression was added using the simplest + method, which splits the input data into blocks and compresses + them independently. Other methods will be added in the future. + The current method has room for improvement, e.g. it is possible + to reduce the memory usage. + + * Added the options --single-stream and --block-size=SIZE to xz. + + * xzdiff and xzgrep now support .lzo files if lzop is installed. + The .tzo suffix is also recognized as a shorthand for .tar.lzo. + + * Support for short 8.3 filenames under DOS was added to xz. It is + experimental and may change before it gets into a stable release. + + +5.0.8 (2014-12-21) + + * Fixed an old bug in xzgrep that affected OpenBSD and probably + a few other operating systems too. + + * Updated French and German translations. + + * Added support for detecting the amount of RAM on AmigaOS/AROS. + + * Minor build system updates. + + +5.0.7 (2014-09-20) + + * Fix regressions introduced in 5.0.6: + + - Fix building with non-GNU make. + + - Fix invalid Libs.private value in liblzma.pc which broke + static linking against liblzma if the linker flags were + taken from pkg-config. + + +5.0.6 (2014-09-14) + + * xzgrep now exits with status 0 if at least one file matched. + + * A few minor portability and build system fixes + + +5.0.5 (2013-06-30) + + * lzmadec and liblzma's lzma_alone_decoder(): Support decompressing + .lzma files that have less common settings in the headers + (dictionary size other than 2^n or 2^n + 2^(n-1), or uncompressed + size greater than 256 GiB). The limitations existed to avoid false + positives when detecting .lzma files. The lc + lp <= 4 limitation + still remains since liblzma's LZMA decoder has that limitation. + + NOTE: xz's .lzma support or liblzma's lzma_auto_decoder() are NOT + affected by this change. They still consider uncommon .lzma headers + as not being in the .lzma format. Changing this would give way too + many false positives. + + * xz: + + - Interaction of preset and custom filter chain options was + made less illogical. This affects only certain less typical + uses cases so few people are expected to notice this change. + + Now when a custom filter chain option (e.g. --lzma2) is + specified, all preset options (-0 ... -9, -e) earlier are on + the command line are completely forgotten. Similarly, when + a preset option is specified, all custom filter chain options + earlier on the command line are completely forgotten. + + Example 1: "xz -9 --lzma2=preset=5 -e" is equivalent to "xz -e" + which is equivalent to "xz -6e". Earlier -e didn't put xz back + into preset mode and thus the example command was equivalent + to "xz --lzma2=preset=5". + + Example 2: "xz -9e --lzma2=preset=5 -7" is equivalent to + "xz -7". Earlier a custom filter chain option didn't make + xz forget the -e option so the example was equivalent to + "xz -7e". + + - Fixes and improvements to error handling. + + - Various fixes to the man page. + + * xzless: Fixed to work with "less" versions 448 and later. + + * xzgrep: Made -h an alias for --no-filename. + + * Include the previously missing debug/translation.bash which can + be useful for translators. + + * Include a build script for Mac OS X. This has been in the Git + repository since 2010 but due to a mistake in Makefile.am the + script hasn't been included in a release tarball before. + + +5.0.4 (2012-06-22) + + * liblzma: + + - Fix lzma_index_init(). It could crash if memory allocation + failed. + + - Fix the possibility of an incorrect LZMA_BUF_ERROR when a BCJ + filter is used and the application only provides exactly as + much output space as is the uncompressed size of the file. + + - Fix a bug in doc/examples_old/xz_pipe_decompress.c. It didn't + check if the last call to lzma_code() really returned + LZMA_STREAM_END, which made the program think that truncated + files are valid. + + - New example programs in doc/examples (old programs are now in + doc/examples_old). These have more comments and more detailed + error handling. + + * Fix "xz -lvv foo.xz". It could crash on some corrupted files. + + * Fix output of "xz --robot -lv" and "xz --robot -lvv" which + incorrectly printed the filename also in the "foo (x/x)" format. + + * Fix exit status of "xzdiff foo.xz bar.xz". + + * Fix exit status of "xzgrep foo binary_file". + + * Fix portability to EBCDIC systems. + + * Fix a configure issue on AIX with the XL C compiler. See INSTALL + for details. + + * Update French, German, Italian, and Polish translations. + + +5.0.3 (2011-05-21) + + * liblzma fixes: + + - A memory leak was fixed. + + - lzma_stream_buffer_encode() no longer creates an empty .xz + Block if encoding an empty buffer. Such an empty Block with + LZMA2 data would trigger a bug in 5.0.1 and older (see the + first bullet point in 5.0.2 notes). When releasing 5.0.2, + I thought that no encoder creates this kind of files but + I was wrong. + + - Validate function arguments better in a few functions. Most + importantly, specifying an unsupported integrity check to + lzma_stream_buffer_encode() no longer creates a corrupt .xz + file. Probably no application tries to do that, so this + shouldn't be a big problem in practice. + + - Document that lzma_block_buffer_encode(), + lzma_easy_buffer_encode(), lzma_stream_encoder(), and + lzma_stream_buffer_encode() may return LZMA_UNSUPPORTED_CHECK. + + - The return values of the _memusage() functions are now + documented better. + + * Fix command name detection in xzgrep. xzegrep and xzfgrep now + correctly use egrep and fgrep instead of grep. + + * French translation was added. + + +5.0.2 (2011-04-01) + + * LZMA2 decompressor now correctly accepts LZMA2 streams with no + uncompressed data. Previously it considered them corrupt. The + bug can affect applications that use raw LZMA2 streams. It is + very unlikely to affect .xz files because no compressor creates + .xz files with empty LZMA2 streams. (Empty .xz files are a + different thing than empty LZMA2 streams.) + + * "xz --suffix=.foo filename.foo" now refuses to compress the + file due to it already having the suffix .foo. It was already + documented on the man page, but the code lacked the test. + + * "xzgrep -l foo bar.xz" works now. + + * Polish translation was added. + + +5.0.1 (2011-01-29) + + * xz --force now (de)compresses files that have setuid, setgid, + or sticky bit set and files that have multiple hard links. + The man page had it documented this way already, but the code + had a bug. + + * gzip and bzip2 support in xzdiff was fixed. + + * Portability fixes + + * Minor fix to Czech translation + + +5.0.0 (2010-10-23) + + Only the most important changes compared to 4.999.9beta are listed + here. One change is especially important: + + * The memory usage limit is now disabled by default. Some scripts + written before this change may have used --memory=max on xz command + line or in XZ_OPT. THESE USES OF --memory=max SHOULD BE REMOVED + NOW, because they interfere with user's ability to set the memory + usage limit himself. If user-specified limit causes problems to + your script, blame the user. + + Other significant changes: + + * Added support for XZ_DEFAULTS environment variable. This variable + allows users to set default options for xz, e.g. default memory + usage limit or default compression level. Scripts that use xz + must never set or unset XZ_DEFAULTS. Scripts should use XZ_OPT + instead if they need a way to pass options to xz via an + environment variable. + + * The compression settings associated with the preset levels + -0 ... -9 have been changed. --extreme was changed a little too. + It is now less likely to make compression worse, but with some + files the new --extreme may compress slightly worse than the old + --extreme. + + * If a preset level (-0 ... -9) is specified after a custom filter + chain options have been used (e.g. --lzma2), the custom filter + chain will be forgotten. Earlier the preset options were + completely ignored after custom filter chain options had been + seen. + + * xz will create sparse files when decompressing if the uncompressed + data contains long sequences of binary zeros. This is done even + when writing to standard output that is connected to a regular + file and certain additional conditions are met to make it safe. + + * Support for "xz --list" was added. Combine with --verbose or + --verbose --verbose (-vv) for detailed output. + + * I had hoped that liblzma API would have been stable after + 4.999.9beta, but there have been a couple of changes in the + advanced features, which don't affect most applications: + + - Index handling code was revised. If you were using the old + API, you will get a compiler error (so it's easy to notice). + + - A subtle but important change was made to the Block handling + API. lzma_block.version has to be initialized even for + lzma_block_header_decode(). Code that doesn't do it will work + for now, but might break in the future, which makes this API + change easy to miss. + + * The major soname has been bumped to 5.0.0. liblzma API and ABI + are now stable, so the need to recompile programs linking against + liblzma shouldn't arise soon. + diff --git a/deps/share/doc/xz/README b/deps/share/doc/xz/README new file mode 100644 index 0000000..8cd07ba --- /dev/null +++ b/deps/share/doc/xz/README @@ -0,0 +1,304 @@ + +XZ Utils +======== + + 0. Overview + 1. Documentation + 1.1. Overall documentation + 1.2. Documentation for command-line tools + 1.3. Documentation for liblzma + 2. Version numbering + 3. Reporting bugs + 4. Translations + 5. Other implementations of the .xz format + 6. Contact information + + +0. Overview +----------- + + XZ Utils provide a general-purpose data-compression library plus + command-line tools. The native file format is the .xz format, but + also the legacy .lzma format is supported. The .xz format supports + multiple compression algorithms, which are called "filters" in the + context of XZ Utils. The primary filter is currently LZMA2. With + typical files, XZ Utils create about 30 % smaller files than gzip. + + To ease adapting support for the .xz format into existing applications + and scripts, the API of liblzma is somewhat similar to the API of the + popular zlib library. For the same reason, the command-line tool xz + has a command-line syntax similar to that of gzip. + + When aiming for the highest compression ratio, the LZMA2 encoder uses + a lot of CPU time and may use, depending on the settings, even + hundreds of megabytes of RAM. However, in fast modes, the LZMA2 encoder + competes with bzip2 in compression speed, RAM usage, and compression + ratio. + + LZMA2 is reasonably fast to decompress. It is a little slower than + gzip, but a lot faster than bzip2. Being fast to decompress means + that the .xz format is especially nice when the same file will be + decompressed very many times (usually on different computers), which + is the case e.g. when distributing software packages. In such + situations, it's not too bad if the compression takes some time, + since that needs to be done only once to benefit many people. + + With some file types, combining (or "chaining") LZMA2 with an + additional filter can improve the compression ratio. A filter chain may + contain up to four filters, although usually only one or two are used. + For example, putting a BCJ (Branch/Call/Jump) filter before LZMA2 + in the filter chain can improve compression ratio of executable files. + + Since the .xz format allows adding new filter IDs, it is possible that + some day there will be a filter that is, for example, much faster to + compress than LZMA2 (but probably with worse compression ratio). + Similarly, it is possible that some day there is a filter that will + compress better than LZMA2. + + XZ Utils supports multithreaded compression. XZ Utils doesn't support + multithreaded decompression yet. It has been planned though and taken + into account when designing the .xz file format. In the future, files + that were created in threaded mode can be decompressed in threaded + mode too. + + +1. Documentation +---------------- + +1.1. Overall documentation + + README This file + + INSTALL.generic Generic install instructions for those not familiar + with packages using GNU Autotools + INSTALL Installation instructions specific to XZ Utils + PACKAGERS Information to packagers of XZ Utils + + COPYING XZ Utils copyright and license information + COPYING.GPLv2 GNU General Public License version 2 + COPYING.GPLv3 GNU General Public License version 3 + COPYING.LGPLv2.1 GNU Lesser General Public License version 2.1 + + AUTHORS The main authors of XZ Utils + THANKS Incomplete list of people who have helped making + this software + NEWS User-visible changes between XZ Utils releases + ChangeLog Detailed list of changes (commit log) + TODO Known bugs and some sort of to-do list + + Note that only some of the above files are included in binary + packages. + + +1.2. Documentation for command-line tools + + The command-line tools are documented as man pages. In source code + releases (and possibly also in some binary packages), the man pages + are also provided in plain text (ASCII only) and PDF formats in the + directory "doc/man" to make the man pages more accessible to those + whose operating system doesn't provide an easy way to view man pages. + + +1.3. Documentation for liblzma + + The liblzma API headers include short docs about each function + and data type as Doxygen tags. These docs should be quite OK as + a quick reference. + + There are a few example/tutorial programs that should help in + getting started with liblzma. In the source package the examples + are in "doc/examples" and in binary packages they may be under + "examples" in the same directory as this README. + + Since the liblzma API has similarities to the zlib API, some people + may find it useful to read the zlib docs and tutorial too: + + http://zlib.net/manual.html + http://zlib.net/zlib_how.html + + +2. Version numbering +-------------------- + + The version number format of XZ Utils is X.Y.ZS: + + - X is the major version. When this is incremented, the library + API and ABI break. + + - Y is the minor version. It is incremented when new features + are added without breaking the existing API or ABI. An even Y + indicates a stable release and an odd Y indicates unstable + (alpha or beta version). + + - Z is the revision. This has a different meaning for stable and + unstable releases: + + * Stable: Z is incremented when bugs get fixed without adding + any new features. This is intended to be convenient for + downstream distributors that want bug fixes but don't want + any new features to minimize the risk of introducing new bugs. + + * Unstable: Z is just a counter. API or ABI of features added + in earlier unstable releases having the same X.Y may break. + + - S indicates stability of the release. It is missing from the + stable releases, where Y is an even number. When Y is odd, S + is either "alpha" or "beta" to make it very clear that such + versions are not stable releases. The same X.Y.Z combination is + not used for more than one stability level, i.e. after X.Y.Zalpha, + the next version can be X.Y.(Z+1)beta but not X.Y.Zbeta. + + +3. Reporting bugs +----------------- + + Naturally it is easiest for me if you already know what causes the + unexpected behavior. Even better if you have a patch to propose. + However, quite often the reason for unexpected behavior is unknown, + so here are a few things to do before sending a bug report: + + 1. Try to create a small example how to reproduce the issue. + + 2. Compile XZ Utils with debugging code using configure switches + --enable-debug and, if possible, --disable-shared. If you are + using GCC, use CFLAGS='-O0 -ggdb3'. Don't strip the resulting + binaries. + + 3. Turn on core dumps. The exact command depends on your shell; + for example in GNU bash it is done with "ulimit -c unlimited", + and in tcsh with "limit coredumpsize unlimited". + + 4. Try to reproduce the suspected bug. If you get "assertion failed" + message, be sure to include the complete message in your bug + report. If the application leaves a coredump, get a backtrace + using gdb: + $ gdb /path/to/app-binary # Load the app to the debugger. + (gdb) core core # Open the coredump. + (gdb) bt # Print the backtrace. Copy & paste to bug report. + (gdb) quit # Quit gdb. + + Report your bug via email or IRC (see Contact information below). + Don't send core dump files or any executables. If you have a small + example file(s) (total size less than 256 KiB), please include + it/them as an attachment. If you have bigger test files, put them + online somewhere and include a URL to the file(s) in the bug report. + + Always include the exact version number of XZ Utils in the bug report. + If you are using a snapshot from the git repository, use "git describe" + to get the exact snapshot version. If you are using XZ Utils shipped + in an operating system distribution, mention the distribution name, + distribution version, and exact xz package version; if you cannot + repeat the bug with the code compiled from unpatched source code, + you probably need to report a bug to your distribution's bug tracking + system. + + +4. Translations +--------------- + + The xz command line tool and all man pages can be translated. + The translations are handled via the Translation Project. If you + wish to help translating xz, please join the Translation Project: + + https://translationproject.org/html/translators.html + + Below are notes and testing instructions specific to xz + translations. + + Testing can be done by installing xz into a temporary directory: + + ./configure --disable-shared --prefix=/tmp/xz-test + # <Edit the .po file in the po directory.> + make -C po update-po + make install + bash debug/translation.bash | less + bash debug/translation.bash | less -S # For --list outputs + + Repeat the above as needed (no need to re-run configure though). + + Note especially the following: + + - The output of --help and --long-help must look nice on + an 80-column terminal. It's OK to add extra lines if needed. + + - In contrast, don't add extra lines to error messages and such. + They are often preceded with e.g. a filename on the same line, + so you have no way to predict where to put a \n. Let the terminal + do the wrapping even if it looks ugly. Adding new lines will be + even uglier in the generic case even if it looks nice in a few + limited examples. + + - Be careful with column alignment in tables and table-like output + (--list, --list --verbose --verbose, --info-memory, --help, and + --long-help): + + * All descriptions of options in --help should start in the + same column (but it doesn't need to be the same column as + in the English messages; just be consistent if you change it). + Check that both --help and --long-help look OK, since they + share several strings. + + * --list --verbose and --info-memory print lines that have + the format "Description: %s". If you need a longer + description, you can put extra space between the colon + and %s. Then you may need to add extra space to other + strings too so that the result as a whole looks good (all + values start at the same column). + + * The columns of the actual tables in --list --verbose --verbose + should be aligned properly. Abbreviate if necessary. It might + be good to keep at least 2 or 3 spaces between column headings + and avoid spaces in the headings so that the columns stand out + better, but this is a matter of opinion. Do what you think + looks best. + + - Be careful to put a period at the end of a sentence when the + original version has it, and don't put it when the original + doesn't have it. Similarly, be careful with \n characters + at the beginning and end of the strings. + + - Read the TRANSLATORS comments that have been extracted from the + source code and included in xz.pot. Some comments suggest + testing with a specific command which needs an .xz file. You + may use e.g. any tests/files/good-*.xz. However, these test + commands are included in translations.bash output, so reading + translations.bash output carefully can be enough. + + - If you find language problems in the original English strings, + feel free to suggest improvements. Ask if something is unclear. + + - The translated messages should be understandable (sometimes this + may be a problem with the original English messages too). Don't + make a direct word-by-word translation from English especially if + the result doesn't sound good in your language. + + Thanks for your help! + + +5. Other implementations of the .xz format +------------------------------------------ + + 7-Zip and the p7zip port of 7-Zip support the .xz format starting + from the version 9.00alpha. + + http://7-zip.org/ + http://p7zip.sourceforge.net/ + + XZ Embedded is a limited implementation written for use in the Linux + kernel, but it is also suitable for other embedded use. + + https://tukaani.org/xz/embedded.html + + +6. Contact information +---------------------- + + If you have questions, bug reports, patches etc. related to XZ Utils, + contact Lasse Collin <[email protected]> (in Finnish or English). + I'm sometimes slow at replying. If you haven't got a reply within two + weeks, assume that your email has got lost and resend it or use IRC. + + You can find me also from #tukaani on Freenode; my nick is Larhzu. + The channel tends to be pretty quiet, so just ask your question and + someone may wake up. + diff --git a/deps/share/doc/xz/THANKS b/deps/share/doc/xz/THANKS new file mode 100644 index 0000000..4301f20 --- /dev/null +++ b/deps/share/doc/xz/THANKS @@ -0,0 +1,134 @@ + +Thanks +====== + +Some people have helped more, some less, but nevertheless everyone's help +has been important. :-) In alphabetical order: + - Mark Adler + - H. Peter Anvin + - Jeff Bastian + - Nelson H. F. Beebe + - Karl Berry + - Anders F. Björklund + - Emmanuel Blot + - Melanie Blower + - Martin Blumenstingl + - Ben Boeckel + - Jakub Bogusz + - Maarten Bosmans + - Trent W. Buck + - James Buren + - David Burklund + - Daniel Mealha Cabrita + - Milo Casagrande + - Marek Černocký + - Tomer Chachamu + - Antoine Cœur + - Gabi Davar + - Chris Donawa + - Andrew Dudman + - Markus Duft + - İsmail Dönmez + - Robert Elz + - Gilles Espinasse + - Denis Excoffier + - Michael Felt + - Michael Fox + - Mike Frysinger + - Daniel Richard G. + - Bill Glessner + - Jason Gorski + - Juan Manuel Guerrero + - Diederik de Haas + - Joachim Henke + - Christian Hesse + - Vincenzo Innocente + - Peter Ivanov + - Jouk Jansen + - Jun I Jin + - Kiyoshi Kanazawa + - Per Øyvind Karlsen + - Thomas Klausner + - Richard Koch + - Ville Koskinen + - Jan Kratochvil + - Christian Kujau + - Stephan Kulow + - Peter Lawler + - James M Leddy + - Hin-Tak Leung + - Andraž 'ruskie' Levstik + - Cary Lewis + - Wim Lewis + - Xin Li + - Eric Lindblad + - Lorenzo De Liso + - Bela Lubkin + - Gregory Margo + - Julien Marrec + - Martin Matuška + - Jim Meyering + - Arkadiusz Miskiewicz + - Conley Moorhous + - Rafał Mużyło + - Adrien Nader + - Evan Nemerson + - Hongbo Ni + - Jonathan Nieder + - Andre Noll + - Peter O'Gorman + - Filip Palian + - Peter Pallinger + - Rui Paulo + - Igor Pavlov + - Diego Elio Pettenò + - Elbert Pol + - Mikko Pouru + - Rich Prohaska + - Trần Ngọc Quân + - Pavel Raiskup + - Ole André Vadla Ravnås + - Robert Readman + - Bernhard Reutner-Fischer + - Eric S. Raymond + - Cristian Rodríguez + - Christian von Roques + - Torsten Rupp + - Jukka Salmi + - Alexandre Sauvé + - Benno Schulenberg + - Andreas Schwab + - Bhargava Shastry + - Dan Shechter + - Stuart Shelton + - Sebastian Andrzej Siewior + - Brad Smith + - Bruce Stark + - Pippijn van Steenhoven + - Jonathan Stott + - Dan Stromberg + - Vincent Torri + - Paul Townsend + - Mohammed Adnène Trojette + - Alexey Tourbin + - Loganaden Velvindron + - Patrick J. Volkerding + - Martin Väth + - Adam Walling + - Jeffrey Walton + - Christian Weisgerber + - Bert Wesarg + - Fredrik Wikstrom + - Jim Wilcoxson + - Ralf Wildenhues + - Charles Wilson + - Lars Wirzenius + - Pilorz Wojciech + - Ryan Young + - Andreas Zieringer + +Also thanks to all the people who have participated in the Tukaani project. + +I have probably forgot to add some names to the above list. Sorry about +that and thanks for your help. + diff --git a/deps/share/doc/xz/TODO b/deps/share/doc/xz/TODO new file mode 100644 index 0000000..45ba433 --- /dev/null +++ b/deps/share/doc/xz/TODO @@ -0,0 +1,111 @@ + +XZ Utils To-Do List +=================== + +Known bugs +---------- + + The test suite is too incomplete. + + If the memory usage limit is less than about 13 MiB, xz is unable to + automatically scale down the compression settings enough even though + it would be possible by switching from BT2/BT3/BT4 match finder to + HC3/HC4. + + XZ Utils compress some files significantly worse than LZMA Utils. + This is due to faster compression presets used by XZ Utils, and + can often be worked around by using "xz --extreme". With some files + --extreme isn't enough though: it's most likely with files that + compress extremely well, so going from compression ratio of 0.003 + to 0.004 means big relative increase in the compressed file size. + + xz doesn't quote unprintable characters when it displays file names + given on the command line. + + tuklib_exit() doesn't block signals => EINTR is possible. + + SIGTSTP is not handled. If xz is stopped, the estimated remaining + time and calculated (de)compression speed won't make sense in the + progress indicator (xz --verbose). + + If liblzma has created threads and fork() gets called, liblzma + code will break in the child process unless it calls exec() and + doesn't touch liblzma. + + +Missing features +---------------- + + Add support for storing metadata in .xz files. A preliminary + idea is to create a new Stream type for metadata. When both + metadata and data are wanted in the same .xz file, two or more + Streams would be concatenated. + + The state stored in lzma_stream should be cloneable, which would + be mostly useful when using a preset dictionary in LZMA2, but + it may have other uses too. Compare to deflateCopy() in zlib. + + Support LZMA_FINISH in raw decoder to indicate end of LZMA1 and + other streams that don't have an end of payload marker. + + Adjust dictionary size when the input file size is known. + Maybe do this only if an option is given. + + xz doesn't support copying extended attributes, access control + lists etc. from source to target file. + + Multithreaded compression: + - Reduce memory usage of the current method. + - Implement threaded match finders. + - Implement pigz-style threading in LZMA2. + + Multithreaded decompression + + Buffer-to-buffer coding could use less RAM (especially when + decompressing LZMA1 or LZMA2). + + I/O library is not implemented (similar to gzopen() in zlib). + It will be a separate library that supports uncompressed, .gz, + .bz2, .lzma, and .xz files. + + Support changing lzma_options_lzma.mode with lzma_filters_update(). + + Support LZMA_FULL_FLUSH for lzma_stream_decoder() to stop at + Block and Stream boundaries. + + lzma_strerror() to convert lzma_ret to human readable form? + This is tricky, because the same error codes are used with + slightly different meanings, and this cannot be fixed anymore. + + Make it possible to adjust LZMA2 options in the middle of a Block + so that the encoding speed vs. compression ratio can be optimized + when the compressed data is streamed over network. + + Improved BCJ filters. The current filters are small but they aren't + so great when compressing binary packages that contain various file + types. Specifically, they make things worse if there are static + libraries or Linux kernel modules. The filtering could also be + more effective (without getting overly complex), for example, + streamable variant BCJ2 from 7-Zip could be implemented. + + Filter that autodetects specific data types in the input stream + and applies appropriate filters for the corrects parts of the input. + Perhaps combine this with the BCJ filter improvement point above. + + Long-range LZ77 method as a separate filter or as a new LZMA2 + match finder. + + +Documentation +------------- + + More tutorial programs are needed for liblzma. + + Document the LZMA1 and LZMA2 algorithms. + + +Miscellaneous +------------ + + Try to get the media type for .xz registered at IANA. + diff --git a/deps/share/doc/xz/examples/00_README.txt b/deps/share/doc/xz/examples/00_README.txt new file mode 100644 index 0000000..120e1eb --- /dev/null +++ b/deps/share/doc/xz/examples/00_README.txt @@ -0,0 +1,31 @@ + +liblzma example programs +======================== + +Introduction + + The examples are written so that the same comments aren't + repeated (much) in later files. + + On POSIX systems, the examples should build by just typing "make". + + The examples that use stdin or stdout don't set stdin and stdout + to binary mode. On systems where it matters (e.g. Windows) it is + possible that the examples won't work without modification. + + +List of examples + + 01_compress_easy.c Multi-call compression using + a compression preset + + 02_decompress.c Multi-call decompression + + 03_compress_custom.c Like 01_compress_easy.c but using + a custom filter chain + (x86 BCJ + LZMA2) + + 04_compress_easy_mt.c Multi-threaded multi-call + compression using a compression + preset + diff --git a/deps/share/doc/xz/examples/01_compress_easy.c b/deps/share/doc/xz/examples/01_compress_easy.c new file mode 100644 index 0000000..e6dd2b0 --- /dev/null +++ b/deps/share/doc/xz/examples/01_compress_easy.c @@ -0,0 +1,297 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 01_compress_easy.c +/// \brief Compress from stdin to stdout in multi-call mode +/// +/// Usage: ./01_compress_easy PRESET < INFILE > OUTFILE +/// +/// Example: ./01_compress_easy 6 < foo > foo.xz +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include <stdbool.h> +#include <stdlib.h> +#include <stdio.h> +#include <string.h> +#include <errno.h> +#include <lzma.h> + + +static void +show_usage_and_exit(const char *argv0) +{ + fprintf(stderr, "Usage: %s PRESET < INFILE > OUTFILE\n" + "PRESET is a number 0-9 and can optionally be " + "followed by `e' to indicate extreme preset\n", + argv0); + exit(EXIT_FAILURE); +} + + +static uint32_t +get_preset(int argc, char **argv) +{ + // One argument whose first char must be 0-9. + if (argc != 2 || argv[1][0] < '0' || argv[1][0] > '9') + show_usage_and_exit(argv[0]); + + // Calculate the preste level 0-9. + uint32_t preset = argv[1][0] - '0'; + + // If there is a second char, it must be 'e'. It will set + // the LZMA_PRESET_EXTREME flag. + if (argv[1][1] != '\0') { + if (argv[1][1] != 'e' || argv[1][2] != '\0') + show_usage_and_exit(argv[0]); + + preset |= LZMA_PRESET_EXTREME; + } + + return preset; +} + + +static bool +init_encoder(lzma_stream *strm, uint32_t preset) +{ + // Initialize the encoder using a preset. Set the integrity to check + // to CRC64, which is the default in the xz command line tool. If + // the .xz file needs to be decompressed with XZ Embedded, use + // LZMA_CHECK_CRC32 instead. + lzma_ret ret = lzma_easy_encoder(strm, preset, LZMA_CHECK_CRC64); + + // Return successfully if the initialization went fine. + if (ret == LZMA_OK) + return true; + + // Something went wrong. The possible errors are documented in + // lzma/container.h (src/liblzma/api/lzma/container.h in the source + // package or e.g. /usr/include/lzma/container.h depending on the + // install prefix). + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + msg = "Specified preset is not supported"; + break; + + case LZMA_UNSUPPORTED_CHECK: + msg = "Specified integrity check is not supported"; + break; + + default: + // This is most likely LZMA_PROG_ERROR indicating a bug in + // this program or in liblzma. It is inconvenient to have a + // separate error message for errors that should be impossible + // to occur, but knowing the error code is important for + // debugging. That's why it is good to print the error code + // at least when there is no good error message to show. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the encoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +static bool +compress(lzma_stream *strm, FILE *infile, FILE *outfile) +{ + // This will be LZMA_RUN until the end of the input file is reached. + // This tells lzma_code() when there will be no more input. + lzma_action action = LZMA_RUN; + + // Buffers to temporarily hold uncompressed input + // and compressed output. + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + // Initialize the input and output pointers. Initializing next_in + // and avail_in isn't really necessary when we are going to encode + // just one file since LZMA_STREAM_INIT takes care of initializing + // those already. But it doesn't hurt much and it will be needed + // if encoding more than one file like we will in 02_decompress.c. + // + // While we don't care about strm->total_in or strm->total_out in this + // example, it is worth noting that initializing the encoder will + // always reset total_in and total_out to zero. But the encoder + // initialization doesn't touch next_in, avail_in, next_out, or + // avail_out. + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + // Loop until the file has been successfully compressed or until + // an error occurs. + while (true) { + // Fill the input buffer if it is empty. + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "Read error: %s\n", + strerror(errno)); + return false; + } + + // Once the end of the input file has been reached, + // we need to tell lzma_code() that no more input + // will be coming and that it should finish the + // encoding. + if (feof(infile)) + action = LZMA_FINISH; + } + + // Tell liblzma do the actual encoding. + // + // This reads up to strm->avail_in bytes of input starting + // from strm->next_in. avail_in will be decremented and + // next_in incremented by an equal amount to match the + // number of input bytes consumed. + // + // Up to strm->avail_out bytes of compressed output will be + // written starting from strm->next_out. avail_out and next_out + // will be incremented by an equal amount to match the number + // of output bytes written. + // + // The encoder has to do internal buffering, which means that + // it may take quite a bit of input before the same data is + // available in compressed form in the output buffer. + lzma_ret ret = lzma_code(strm, action); + + // If the output buffer is full or if the compression finished + // successfully, write the data from the output bufffer to + // the output file. + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + // When lzma_code() has returned LZMA_STREAM_END, + // the output buffer is likely to be only partially + // full. Calculate how much new data there is to + // be written to the output file. + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + // Reset next_out and avail_out. + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + // Normally the return value of lzma_code() will be LZMA_OK + // until everything has been encoded. + if (ret != LZMA_OK) { + // Once everything has been encoded successfully, the + // return value of lzma_code() will be LZMA_STREAM_END. + // + // It is important to check for LZMA_STREAM_END. Do not + // assume that getting ret != LZMA_OK would mean that + // everything has gone well. + if (ret == LZMA_STREAM_END) + return true; + + // It's not LZMA_OK nor LZMA_STREAM_END, + // so it must be an error code. See lzma/base.h + // (src/liblzma/api/lzma/base.h in the source package + // or e.g. /usr/include/lzma/base.h depending on the + // install prefix) for the list and documentation of + // possible values. Most values listen in lzma_ret + // enumeration aren't possible in this example. + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_DATA_ERROR: + // This error is returned if the compressed + // or uncompressed size get near 8 EiB + // (2^63 bytes) because that's where the .xz + // file format size limits currently are. + // That is, the possibility of this error + // is mostly theoretical unless you are doing + // something very unusual. + // + // Note that strm->total_in and strm->total_out + // have nothing to do with this error. Changing + // those variables won't increase or decrease + // the chance of getting this error. + msg = "File size limits exceeded"; + break; + + default: + // This is most likely LZMA_PROG_ERROR, but + // if this program is buggy (or liblzma has + // a bug), it may be e.g. LZMA_BUF_ERROR or + // LZMA_OPTIONS_ERROR too. + // + // It is inconvenient to have a separate + // error message for errors that should be + // impossible to occur, but knowing the error + // code is important for debugging. That's why + // it is good to print the error code at least + // when there is no good error message to show. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Encoder error: %s (error code %u)\n", + msg, ret); + return false; + } + } +} + + +extern int +main(int argc, char **argv) +{ + // Get the preset number from the command line. + uint32_t preset = get_preset(argc, argv); + + // Initialize a lzma_stream structure. When it is allocated on stack, + // it is simplest to use LZMA_STREAM_INIT macro like below. When it + // is allocated on heap, using memset(strmptr, 0, sizeof(*strmptr)) + // works (as long as NULL pointers are represented with zero bits + // as they are on practically all computers today). + lzma_stream strm = LZMA_STREAM_INIT; + + // Initialize the encoder. If it succeeds, compress from + // stdin to stdout. + bool success = init_encoder(&strm, preset); + if (success) + success = compress(&strm, stdin, stdout); + + // Free the memory allocated for the encoder. If we were encoding + // multiple files, this would only need to be done after the last + // file. See 02_decompress.c for handling of multiple files. + // + // It is OK to call lzma_end() multiple times or when it hasn't been + // actually used except initialized with LZMA_STREAM_INIT. + lzma_end(&strm); + + // Close stdout to catch possible write errors that can occur + // when pending data is flushed from the stdio buffers. + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/deps/share/doc/xz/examples/02_decompress.c b/deps/share/doc/xz/examples/02_decompress.c new file mode 100644 index 0000000..98339be --- /dev/null +++ b/deps/share/doc/xz/examples/02_decompress.c @@ -0,0 +1,287 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 02_decompress.c +/// \brief Decompress .xz files to stdout +/// +/// Usage: ./02_decompress INPUT_FILES... > OUTFILE +/// +/// Example: ./02_decompress foo.xz bar.xz > foobar +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include <stdbool.h> +#include <stdlib.h> +#include <stdio.h> +#include <string.h> +#include <errno.h> +#include <lzma.h> + + +static bool +init_decoder(lzma_stream *strm) +{ + // Initialize a .xz decoder. The decoder supports a memory usage limit + // and a set of flags. + // + // The memory usage of the decompressor depends on the settings used + // to compress a .xz file. It can vary from less than a megabyte to + // a few gigabytes, but in practice (at least for now) it rarely + // exceeds 65 MiB because that's how much memory is required to + // decompress files created with "xz -9". Settings requiring more + // memory take extra effort to use and don't (at least for now) + // provide significantly better compression in most cases. + // + // Memory usage limit is useful if it is important that the + // decompressor won't consume gigabytes of memory. The need + // for limiting depends on the application. In this example, + // no memory usage limiting is used. This is done by setting + // the limit to UINT64_MAX. + // + // The .xz format allows concatenating compressed files as is: + // + // echo foo | xz > foobar.xz + // echo bar | xz >> foobar.xz + // + // When decompressing normal standalone .xz files, LZMA_CONCATENATED + // should always be used to support decompression of concatenated + // .xz files. If LZMA_CONCATENATED isn't used, the decoder will stop + // after the first .xz stream. This can be useful when .xz data has + // been embedded inside another file format. + // + // Flags other than LZMA_CONCATENATED are supported too, and can + // be combined with bitwise-or. See lzma/container.h + // (src/liblzma/api/lzma/container.h in the source package or e.g. + // /usr/include/lzma/container.h depending on the install prefix) + // for details. + lzma_ret ret = lzma_stream_decoder( + strm, UINT64_MAX, LZMA_CONCATENATED); + + // Return successfully if the initialization went fine. + if (ret == LZMA_OK) + return true; + + // Something went wrong. The possible errors are documented in + // lzma/container.h (src/liblzma/api/lzma/container.h in the source + // package or e.g. /usr/include/lzma/container.h depending on the + // install prefix). + // + // Note that LZMA_MEMLIMIT_ERROR is never possible here. If you + // specify a very tiny limit, the error will be delayed until + // the first headers have been parsed by a call to lzma_code(). + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + msg = "Unsupported decompressor flags"; + break; + + default: + // This is most likely LZMA_PROG_ERROR indicating a bug in + // this program or in liblzma. It is inconvenient to have a + // separate error message for errors that should be impossible + // to occur, but knowing the error code is important for + // debugging. That's why it is good to print the error code + // at least when there is no good error message to show. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the decoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +static bool +decompress(lzma_stream *strm, const char *inname, FILE *infile, FILE *outfile) +{ + // When LZMA_CONCATENATED flag was used when initializing the decoder, + // we need to tell lzma_code() when there will be no more input. + // This is done by setting action to LZMA_FINISH instead of LZMA_RUN + // in the same way as it is done when encoding. + // + // When LZMA_CONCATENATED isn't used, there is no need to use + // LZMA_FINISH to tell when all the input has been read, but it + // is still OK to use it if you want. When LZMA_CONCATENATED isn't + // used, the decoder will stop after the first .xz stream. In that + // case some unused data may be left in strm->next_in. + lzma_action action = LZMA_RUN; + + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + while (true) { + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "%s: Read error: %s\n", + inname, strerror(errno)); + return false; + } + + // Once the end of the input file has been reached, + // we need to tell lzma_code() that no more input + // will be coming. As said before, this isn't required + // if the LZMA_CONCATENATED flag isn't used when + // initializing the decoder. + if (feof(infile)) + action = LZMA_FINISH; + } + + lzma_ret ret = lzma_code(strm, action); + + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + if (ret != LZMA_OK) { + // Once everything has been decoded successfully, the + // return value of lzma_code() will be LZMA_STREAM_END. + // + // It is important to check for LZMA_STREAM_END. Do not + // assume that getting ret != LZMA_OK would mean that + // everything has gone well or that when you aren't + // getting more output it must have successfully + // decoded everything. + if (ret == LZMA_STREAM_END) + return true; + + // It's not LZMA_OK nor LZMA_STREAM_END, + // so it must be an error code. See lzma/base.h + // (src/liblzma/api/lzma/base.h in the source package + // or e.g. /usr/include/lzma/base.h depending on the + // install prefix) for the list and documentation of + // possible values. Many values listen in lzma_ret + // enumeration aren't possible in this example, but + // can be made possible by enabling memory usage limit + // or adding flags to the decoder initialization. + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_FORMAT_ERROR: + // .xz magic bytes weren't found. + msg = "The input is not in the .xz format"; + break; + + case LZMA_OPTIONS_ERROR: + // For example, the headers specify a filter + // that isn't supported by this liblzma + // version (or it hasn't been enabled when + // building liblzma, but no-one sane does + // that unless building liblzma for an + // embedded system). Upgrading to a newer + // liblzma might help. + // + // Note that it is unlikely that the file has + // accidentally became corrupt if you get this + // error. The integrity of the .xz headers is + // always verified with a CRC32, so + // unintentionally corrupt files can be + // distinguished from unsupported files. + msg = "Unsupported compression options"; + break; + + case LZMA_DATA_ERROR: + msg = "Compressed file is corrupt"; + break; + + case LZMA_BUF_ERROR: + // Typically this error means that a valid + // file has got truncated, but it might also + // be a damaged part in the file that makes + // the decoder think the file is truncated. + // If you prefer, you can use the same error + // message for this as for LZMA_DATA_ERROR. + msg = "Compressed file is truncated or " + "otherwise corrupt"; + break; + + default: + // This is most likely LZMA_PROG_ERROR. + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "%s: Decoder error: " + "%s (error code %u)\n", + inname, msg, ret); + return false; + } + } +} + + +extern int +main(int argc, char **argv) +{ + if (argc <= 1) { + fprintf(stderr, "Usage: %s FILES...\n", argv[0]); + return EXIT_FAILURE; + } + + lzma_stream strm = LZMA_STREAM_INIT; + + bool success = true; + + // Try to decompress all files. + for (int i = 1; i < argc; ++i) { + if (!init_decoder(&strm)) { + // Decoder initialization failed. There's no point + // to retry it so we need to exit. + success = false; + break; + } + + FILE *infile = fopen(argv[i], "rb"); + + if (infile == NULL) { + fprintf(stderr, "%s: Error opening the " + "input file: %s\n", + argv[i], strerror(errno)); + success = false; + } else { + success &= decompress(&strm, argv[i], infile, stdout); + fclose(infile); + } + } + + // Free the memory allocated for the decoder. This only needs to be + // done after the last file. + lzma_end(&strm); + + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/deps/share/doc/xz/examples/03_compress_custom.c b/deps/share/doc/xz/examples/03_compress_custom.c new file mode 100644 index 0000000..40c85e3 --- /dev/null +++ b/deps/share/doc/xz/examples/03_compress_custom.c @@ -0,0 +1,193 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 03_compress_custom.c +/// \brief Compress in multi-call mode using x86 BCJ and LZMA2 +/// +/// Usage: ./03_compress_custom < INFILE > OUTFILE +/// +/// Example: ./03_compress_custom < foo > foo.xz +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include <stdbool.h> +#include <stdlib.h> +#include <stdio.h> +#include <string.h> +#include <errno.h> +#include <lzma.h> + + +static bool +init_encoder(lzma_stream *strm) +{ + // Use the default preset (6) for LZMA2. + // + // The lzma_options_lzma structure and the lzma_lzma_preset() function + // are declared in lzma/lzma12.h (src/liblzma/api/lzma/lzma12.h in the + // source package or e.g. /usr/include/lzma/lzma12.h depending on + // the install prefix). + lzma_options_lzma opt_lzma2; + if (lzma_lzma_preset(&opt_lzma2, LZMA_PRESET_DEFAULT)) { + // It should never fail because the default preset + // (and presets 0-9 optionally with LZMA_PRESET_EXTREME) + // are supported by all stable liblzma versions. + // + // (The encoder initialization later in this function may + // still fail due to unsupported preset *if* the features + // required by the preset have been disabled at build time, + // but no-one does such things except on embedded systems.) + fprintf(stderr, "Unsupported preset, possibly a bug\n"); + return false; + } + + // Now we could customize the LZMA2 options if we wanted. For example, + // we could set the the dictionary size (opt_lzma2.dict_size) to + // something else than the default (8 MiB) of the default preset. + // See lzma/lzma12.h for details of all LZMA2 options. + // + // The x86 BCJ filter will try to modify the x86 instruction stream so + // that LZMA2 can compress it better. The x86 BCJ filter doesn't need + // any options so it will be set to NULL below. + // + // Construct the filter chain. The uncompressed data goes first to + // the first filter in the array, in this case the x86 BCJ filter. + // The array is always terminated by setting .id = LZMA_VLI_UNKNOWN. + // + // See lzma/filter.h for more information about the lzma_filter + // structure. + lzma_filter filters[] = { + { .id = LZMA_FILTER_X86, .options = NULL }, + { .id = LZMA_FILTER_LZMA2, .options = &opt_lzma2 }, + { .id = LZMA_VLI_UNKNOWN, .options = NULL }, + }; + + // Initialize the encoder using the custom filter chain. + lzma_ret ret = lzma_stream_encoder(strm, filters, LZMA_CHECK_CRC64); + + if (ret == LZMA_OK) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + // We are no longer using a plain preset so this error + // message has been edited accordingly compared to + // 01_compress_easy.c. + msg = "Specified filter chain is not supported"; + break; + + case LZMA_UNSUPPORTED_CHECK: + msg = "Specified integrity check is not supported"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the encoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +// This function is identical to the one in 01_compress_easy.c. +static bool +compress(lzma_stream *strm, FILE *infile, FILE *outfile) +{ + lzma_action action = LZMA_RUN; + + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + while (true) { + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "Read error: %s\n", + strerror(errno)); + return false; + } + + if (feof(infile)) + action = LZMA_FINISH; + } + + lzma_ret ret = lzma_code(strm, action); + + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + if (ret != LZMA_OK) { + if (ret == LZMA_STREAM_END) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_DATA_ERROR: + msg = "File size limits exceeded"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Encoder error: %s (error code %u)\n", + msg, ret); + return false; + } + } +} + + +extern int +main(void) +{ + lzma_stream strm = LZMA_STREAM_INIT; + + bool success = init_encoder(&strm); + if (success) + success = compress(&strm, stdin, stdout); + + lzma_end(&strm); + + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/deps/share/doc/xz/examples/04_compress_easy_mt.c b/deps/share/doc/xz/examples/04_compress_easy_mt.c new file mode 100644 index 0000000..efe5697 --- /dev/null +++ b/deps/share/doc/xz/examples/04_compress_easy_mt.c @@ -0,0 +1,206 @@ +/////////////////////////////////////////////////////////////////////////////// +// +/// \file 04_compress_easy_mt.c +/// \brief Compress in multi-call mode using LZMA2 in multi-threaded mode +/// +/// Usage: ./04_compress_easy_mt < INFILE > OUTFILE +/// +/// Example: ./04_compress_easy_mt < foo > foo.xz +// +// Author: Lasse Collin +// +// This file has been put into the public domain. +// You can do whatever you want with this file. +// +/////////////////////////////////////////////////////////////////////////////// + +#include <stdbool.h> +#include <stdlib.h> +#include <stdio.h> +#include <string.h> +#include <errno.h> +#include <lzma.h> + + +static bool +init_encoder(lzma_stream *strm) +{ + // The threaded encoder takes the options as pointer to + // a lzma_mt structure. + lzma_mt mt = { + // No flags are needed. + .flags = 0, + + // Let liblzma determine a sane block size. + .block_size = 0, + + // Use no timeout for lzma_code() calls by setting timeout + // to zero. That is, sometimes lzma_code() might block for + // a long time (from several seconds to even minutes). + // If this is not OK, for example due to progress indicator + // needing updates, specify a timeout in milliseconds here. + // See the documentation of lzma_mt in lzma/container.h for + // information how to choose a reasonable timeout. + .timeout = 0, + + // Use the default preset (6) for LZMA2. + // To use a preset, filters must be set to NULL. + .preset = LZMA_PRESET_DEFAULT, + .filters = NULL, + + // Use CRC64 for integrity checking. See also + // 01_compress_easy.c about choosing the integrity check. + .check = LZMA_CHECK_CRC64, + }; + + // Detect how many threads the CPU supports. + mt.threads = lzma_cputhreads(); + + // If the number of CPU cores/threads cannot be detected, + // use one thread. Note that this isn't the same as the normal + // single-threaded mode as this will still split the data into + // blocks and use more RAM than the normal single-threaded mode. + // You may want to consider using lzma_easy_encoder() or + // lzma_stream_encoder() instead of lzma_stream_encoder_mt() if + // lzma_cputhreads() returns 0 or 1. + if (mt.threads == 0) + mt.threads = 1; + + // If the number of CPU cores/threads exceeds threads_max, + // limit the number of threads to keep memory usage lower. + // The number 8 is arbitrarily chosen and may be too low or + // high depending on the compression preset and the computer + // being used. + // + // FIXME: A better way could be to check the amount of RAM + // (or available RAM) and use lzma_stream_encoder_mt_memusage() + // to determine if the number of threads should be reduced. + const uint32_t threads_max = 8; + if (mt.threads > threads_max) + mt.threads = threads_max; + + // Initialize the threaded encoder. + lzma_ret ret = lzma_stream_encoder_mt(strm, &mt); + + if (ret == LZMA_OK) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_OPTIONS_ERROR: + // We are no longer using a plain preset so this error + // message has been edited accordingly compared to + // 01_compress_easy.c. + msg = "Specified filter chain is not supported"; + break; + + case LZMA_UNSUPPORTED_CHECK: + msg = "Specified integrity check is not supported"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Error initializing the encoder: %s (error code %u)\n", + msg, ret); + return false; +} + + +// This function is identical to the one in 01_compress_easy.c. +static bool +compress(lzma_stream *strm, FILE *infile, FILE *outfile) +{ + lzma_action action = LZMA_RUN; + + uint8_t inbuf[BUFSIZ]; + uint8_t outbuf[BUFSIZ]; + + strm->next_in = NULL; + strm->avail_in = 0; + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + + while (true) { + if (strm->avail_in == 0 && !feof(infile)) { + strm->next_in = inbuf; + strm->avail_in = fread(inbuf, 1, sizeof(inbuf), + infile); + + if (ferror(infile)) { + fprintf(stderr, "Read error: %s\n", + strerror(errno)); + return false; + } + + if (feof(infile)) + action = LZMA_FINISH; + } + + lzma_ret ret = lzma_code(strm, action); + + if (strm->avail_out == 0 || ret == LZMA_STREAM_END) { + size_t write_size = sizeof(outbuf) - strm->avail_out; + + if (fwrite(outbuf, 1, write_size, outfile) + != write_size) { + fprintf(stderr, "Write error: %s\n", + strerror(errno)); + return false; + } + + strm->next_out = outbuf; + strm->avail_out = sizeof(outbuf); + } + + if (ret != LZMA_OK) { + if (ret == LZMA_STREAM_END) + return true; + + const char *msg; + switch (ret) { + case LZMA_MEM_ERROR: + msg = "Memory allocation failed"; + break; + + case LZMA_DATA_ERROR: + msg = "File size limits exceeded"; + break; + + default: + msg = "Unknown error, possibly a bug"; + break; + } + + fprintf(stderr, "Encoder error: %s (error code %u)\n", + msg, ret); + return false; + } + } +} + + +extern int +main(void) +{ + lzma_stream strm = LZMA_STREAM_INIT; + + bool success = init_encoder(&strm); + if (success) + success = compress(&strm, stdin, stdout); + + lzma_end(&strm); + + if (fclose(stdout)) { + fprintf(stderr, "Write error: %s\n", strerror(errno)); + success = false; + } + + return success ? EXIT_SUCCESS : EXIT_FAILURE; +} diff --git a/deps/share/doc/xz/examples/Makefile b/deps/share/doc/xz/examples/Makefile new file mode 100644 index 0000000..e8839d8 --- /dev/null +++ b/deps/share/doc/xz/examples/Makefile @@ -0,0 +1,25 @@ +# +# Author: Lasse Collin +# +# This file has been put into the public domain. +# You can do whatever you want with this file. +# + +CC = c99 +CFLAGS = -g +LDFLAGS = -llzma + +PROGS = \ + 01_compress_easy \ + 02_decompress \ + 03_compress_custom \ + 04_compress_easy_mt \ + 11_file_info + +all: $(PROGS) + +.c: + $(CC) $(CFLAGS) -o $@ $< $(LDFLAGS) + +clean: + -rm -f $(PROGS) diff --git a/deps/share/doc/xz/examples_old/xz_pipe_comp.c b/deps/share/doc/xz/examples_old/xz_pipe_comp.c new file mode 100644 index 0000000..9f9224b --- /dev/null +++ b/deps/share/doc/xz/examples_old/xz_pipe_comp.c @@ -0,0 +1,127 @@ +/* + * xz_pipe_comp.c + * A simple example of pipe-only xz compressor implementation. + * version: 2010-07-12 - by Daniel Mealha Cabrita + * Not copyrighted -- provided to the public domain. + * + * Compiling: + * Link with liblzma. GCC example: + * $ gcc -llzma xz_pipe_comp.c -o xz_pipe_comp + * + * Usage example: + * $ cat some_file | ./xz_pipe_comp > some_file.xz + */ + +#include <stdio.h> +#include <stdint.h> +#include <inttypes.h> +#include <stdbool.h> +#include <lzma.h> + + +/* COMPRESSION SETTINGS */ + +/* analogous to xz CLI options: -0 to -9 */ +#define COMPRESSION_LEVEL 6 + +/* boolean setting, analogous to xz CLI option: -e */ +#define COMPRESSION_EXTREME true + +/* see: /usr/include/lzma/check.h LZMA_CHECK_* */ +#define INTEGRITY_CHECK LZMA_CHECK_CRC64 + + +/* read/write buffer sizes */ +#define IN_BUF_MAX 4096 +#define OUT_BUF_MAX 4096 + +/* error codes */ +#define RET_OK 0 +#define RET_ERROR_INIT 1 +#define RET_ERROR_INPUT 2 +#define RET_ERROR_OUTPUT 3 +#define RET_ERROR_COMPRESSION 4 + + +/* note: in_file and out_file must be open already */ +int xz_compress (FILE *in_file, FILE *out_file) +{ + uint32_t preset = COMPRESSION_LEVEL | (COMPRESSION_EXTREME ? LZMA_PRESET_EXTREME : 0); + lzma_check check = INTEGRITY_CHECK; + lzma_stream strm = LZMA_STREAM_INIT; /* alloc and init lzma_stream struct */ + uint8_t in_buf [IN_BUF_MAX]; + uint8_t out_buf [OUT_BUF_MAX]; + size_t in_len; /* length of useful data in in_buf */ + size_t out_len; /* length of useful data in out_buf */ + bool in_finished = false; + bool out_finished = false; + lzma_action action; + lzma_ret ret_xz; + int ret; + + ret = RET_OK; + + /* initialize xz encoder */ + ret_xz = lzma_easy_encoder (&strm, preset, check); + if (ret_xz != LZMA_OK) { + fprintf (stderr, "lzma_easy_encoder error: %d\n", (int) ret_xz); + return RET_ERROR_INIT; + } + + while ((! in_finished) && (! out_finished)) { + /* read incoming data */ + in_len = fread (in_buf, 1, IN_BUF_MAX, in_file); + + if (feof (in_file)) { + in_finished = true; + } + if (ferror (in_file)) { + in_finished = true; + ret = RET_ERROR_INPUT; + } + + strm.next_in = in_buf; + strm.avail_in = in_len; + + /* if no more data from in_buf, flushes the + internal xz buffers and closes the xz data + with LZMA_FINISH */ + action = in_finished ? LZMA_FINISH : LZMA_RUN; + + /* loop until there's no pending compressed output */ + do { + /* out_buf is clean at this point */ + strm.next_out = out_buf; + strm.avail_out = OUT_BUF_MAX; + + /* compress data */ + ret_xz = lzma_code (&strm, action); + + if ((ret_xz != LZMA_OK) && (ret_xz != LZMA_STREAM_END)) { + fprintf (stderr, "lzma_code error: %d\n", (int) ret_xz); + out_finished = true; + ret = RET_ERROR_COMPRESSION; + } else { + /* write compressed data */ + out_len = OUT_BUF_MAX - strm.avail_out; + fwrite (out_buf, 1, out_len, out_file); + if (ferror (out_file)) { + out_finished = true; + ret = RET_ERROR_OUTPUT; + } + } + } while (strm.avail_out == 0); + } + + lzma_end (&strm); + return ret; +} + +int main () +{ + int ret; + + ret = xz_compress (stdin, stdout); + return ret; +} + diff --git a/deps/share/doc/xz/examples_old/xz_pipe_decomp.c b/deps/share/doc/xz/examples_old/xz_pipe_decomp.c new file mode 100644 index 0000000..fb5ad89 --- /dev/null +++ b/deps/share/doc/xz/examples_old/xz_pipe_decomp.c @@ -0,0 +1,123 @@ +/* + * xz_pipe_decomp.c + * A simple example of pipe-only xz decompressor implementation. + * version: 2012-06-14 - by Daniel Mealha Cabrita + * Not copyrighted -- provided to the public domain. + * + * Compiling: + * Link with liblzma. GCC example: + * $ gcc -llzma xz_pipe_decomp.c -o xz_pipe_decomp + * + * Usage example: + * $ cat some_file.xz | ./xz_pipe_decomp > some_file + */ + +#include <stdio.h> +#include <stdint.h> +#include <inttypes.h> +#include <stdbool.h> +#include <lzma.h> + + +/* read/write buffer sizes */ +#define IN_BUF_MAX 4096 +#define OUT_BUF_MAX 4096 + +/* error codes */ +#define RET_OK 0 +#define RET_ERROR_INIT 1 +#define RET_ERROR_INPUT 2 +#define RET_ERROR_OUTPUT 3 +#define RET_ERROR_DECOMPRESSION 4 + + +/* note: in_file and out_file must be open already */ +int xz_decompress (FILE *in_file, FILE *out_file) +{ + lzma_stream strm = LZMA_STREAM_INIT; /* alloc and init lzma_stream struct */ + const uint32_t flags = LZMA_TELL_UNSUPPORTED_CHECK | LZMA_CONCATENATED; + const uint64_t memory_limit = UINT64_MAX; /* no memory limit */ + uint8_t in_buf [IN_BUF_MAX]; + uint8_t out_buf [OUT_BUF_MAX]; + size_t in_len; /* length of useful data in in_buf */ + size_t out_len; /* length of useful data in out_buf */ + bool in_finished = false; + bool out_finished = false; + lzma_action action; + lzma_ret ret_xz; + int ret; + + ret = RET_OK; + + /* initialize xz decoder */ + ret_xz = lzma_stream_decoder (&strm, memory_limit, flags); + if (ret_xz != LZMA_OK) { + fprintf (stderr, "lzma_stream_decoder error: %d\n", (int) ret_xz); + return RET_ERROR_INIT; + } + + while ((! in_finished) && (! out_finished)) { + /* read incoming data */ + in_len = fread (in_buf, 1, IN_BUF_MAX, in_file); + + if (feof (in_file)) { + in_finished = true; + } + if (ferror (in_file)) { + in_finished = true; + ret = RET_ERROR_INPUT; + } + + strm.next_in = in_buf; + strm.avail_in = in_len; + + /* if no more data from in_buf, flushes the + internal xz buffers and closes the decompressed data + with LZMA_FINISH */ + action = in_finished ? LZMA_FINISH : LZMA_RUN; + + /* loop until there's no pending decompressed output */ + do { + /* out_buf is clean at this point */ + strm.next_out = out_buf; + strm.avail_out = OUT_BUF_MAX; + + /* decompress data */ + ret_xz = lzma_code (&strm, action); + + if ((ret_xz != LZMA_OK) && (ret_xz != LZMA_STREAM_END)) { + fprintf (stderr, "lzma_code error: %d\n", (int) ret_xz); + out_finished = true; + ret = RET_ERROR_DECOMPRESSION; + } else { + /* write decompressed data */ + out_len = OUT_BUF_MAX - strm.avail_out; + fwrite (out_buf, 1, out_len, out_file); + if (ferror (out_file)) { + out_finished = true; + ret = RET_ERROR_OUTPUT; + } + } + } while (strm.avail_out == 0); + } + + /* Bug fix (2012-06-14): If no errors were detected, check + that the last lzma_code() call returned LZMA_STREAM_END. + If not, the file is probably truncated. */ + if ((ret == RET_OK) && (ret_xz != LZMA_STREAM_END)) { + fprintf (stderr, "Input truncated or corrupt\n"); + ret = RET_ERROR_DECOMPRESSION; + } + + lzma_end (&strm); + return ret; +} + +int main () +{ + int ret; + + ret = xz_decompress (stdin, stdout); + return ret; +} + diff --git a/deps/share/doc/xz/faq.txt b/deps/share/doc/xz/faq.txt new file mode 100644 index 0000000..dee7824 --- /dev/null +++ b/deps/share/doc/xz/faq.txt @@ -0,0 +1,224 @@ + +XZ Utils FAQ +============ + +Q: What do the letters XZ mean? + +A: Nothing. They are just two letters, which come from the file format + suffix .xz. The .xz suffix was selected, because it seemed to be + pretty much unused. It has no deeper meaning. + + +Q: What are LZMA and LZMA2? + +A: LZMA stands for Lempel-Ziv-Markov chain-Algorithm. It is the name + of the compression algorithm designed by Igor Pavlov for 7-Zip. + LZMA is based on LZ77 and range encoding. + + LZMA2 is an updated version of the original LZMA to fix a couple of + practical issues. In context of XZ Utils, LZMA is called LZMA1 to + emphasize that LZMA is not the same thing as LZMA2. LZMA2 is the + primary compression algorithm in the .xz file format. + + +Q: There are many LZMA related projects. How does XZ Utils relate to them? + +A: 7-Zip and LZMA SDK are the original projects. LZMA SDK is roughly + a subset of the 7-Zip source tree. + + p7zip is 7-Zip's command-line tools ported to POSIX-like systems. + + LZMA Utils provide a gzip-like lzma tool for POSIX-like systems. + LZMA Utils are based on LZMA SDK. XZ Utils are the successor to + LZMA Utils. + + There are several other projects using LZMA. Most are more or less + based on LZMA SDK. See <http://7-zip.org/links.html>. + + +Q: Why is liblzma named liblzma if its primary file format is .xz? + Shouldn't it be e.g. libxz? + +A: When the designing of the .xz format began, the idea was to replace + the .lzma format and use the same .lzma suffix. It would have been + quite OK to reuse the suffix when there were very few .lzma files + around. However, the old .lzma format became popular before the + new format was finished. The new format was renamed to .xz but the + name of liblzma wasn't changed. + + +Q: Do XZ Utils support the .7z format? + +A: No. Use 7-Zip (Windows) or p7zip (POSIX-like systems) to handle .7z + files. + + +Q: I have many .tar.7z files. Can I convert them to .tar.xz without + spending hours recompressing the data? + +A: In the "extra" directory, there is a script named 7z2lzma.bash which + is able to convert some .7z files to the .lzma format (not .xz). It + needs the 7za (or 7z) command from p7zip. The script may silently + produce corrupt output if certain assumptions are not met, so + decompress the resulting .lzma file and compare it against the + original before deleting the original file! + + +Q: I have many .lzma files. Can I quickly convert them to the .xz format? + +A: For now, no. Since XZ Utils supports the .lzma format, it's usually + not too bad to keep the old files in the old format. If you want to + do the conversion anyway, you need to decompress the .lzma files and + then recompress to the .xz format. + + Technically, there is a way to make the conversion relatively fast + (roughly twice the time that normal decompression takes). Writing + such a tool would take quite a bit of time though, and would probably + be useful to only a few people. If you really want such a conversion + tool, contact Lasse Collin and offer some money. + + +Q: I have installed xz, but my tar doesn't recognize .tar.xz files. + How can I extract .tar.xz files? + +A: xz -dc foo.tar.xz | tar xf - + + +Q: Can I recover parts of a broken .xz file (e.g. a corrupted CD-R)? + +A: It may be possible if the file consists of multiple blocks, which + typically is not the case if the file was created in single-threaded + mode. There is no recovery program yet. + + +Q: Is (some part of) XZ Utils patented? + +A: Lasse Collin is not aware of any patents that could affect XZ Utils. + However, due to the nature of software patents, it's not possible to + guarantee that XZ Utils isn't affected by any third party patent(s). + + +Q: Where can I find documentation about the file format and algorithms? + +A: The .xz format is documented in xz-file-format.txt. It is a container + format only, and doesn't include descriptions of any non-trivial + filters. + + Documenting LZMA and LZMA2 is planned, but for now, there is no other + documentation than the source code. Before you begin, you should know + the basics of LZ77 and range-coding algorithms. LZMA is based on LZ77, + but LZMA is a lot more complex. Range coding is used to compress + the final bitstream like Huffman coding is used in Deflate. + + +Q: I cannot find BCJ and BCJ2 filters. Don't they exist in liblzma? + +A: BCJ filter is called "x86" in liblzma. BCJ2 is not included, + because it requires using more than one encoded output stream. + A streamable version of BCJ2-style filtering is planned. + + +Q: I need to use a script that runs "xz -9". On a system with 256 MiB + of RAM, xz says that it cannot allocate memory. Can I make the + script work without modifying it? + +A: Set a default memory usage limit for compression. You can do it e.g. + in a shell initialization script such as ~/.bashrc or /etc/profile: + + XZ_DEFAULTS=--memlimit-compress=150MiB + export XZ_DEFAULTS + + xz will then scale the compression settings down so that the given + memory usage limit is not reached. This way xz shouldn't run out + of memory. + + Check also that memory-related resource limits are high enough. + On most systems, "ulimit -a" will show the current resource limits. + + +Q: How do I create files that can be decompressed with XZ Embedded? + +A: See the documentation in XZ Embedded. In short, something like + this is a good start: + + xz --check=crc32 --lzma2=preset=6e,dict=64KiB + + Or if a BCJ filter is needed too, e.g. if compressing + a kernel image for PowerPC: + + xz --check=crc32 --powerpc --lzma2=preset=6e,dict=64KiB + + Adjust the dictionary size to get a good compromise between + compression ratio and decompressor memory usage. Note that + in single-call decompression mode of XZ Embedded, a big + dictionary doesn't increase memory usage. + + +Q: Will xz support threaded compression? + +A: It is planned and has been taken into account when designing + the .xz file format. Eventually there will probably be three types + of threading, each method having its own advantages and disadvantages. + + The simplest method is splitting the uncompressed data into blocks + and compressing them in parallel independent from each other. + Since the blocks are compressed independently, they can also be + decompressed independently. Together with the index feature in .xz, + this allows using threads to create .xz files for random-access + reading. This also makes threaded decompression possible, although + it is not clear if threaded decompression will ever be implemented. + + The independent blocks method has a couple of disadvantages too. It + will compress worse than a single-block method. Often the difference + is not too big (maybe 1-2 %) but sometimes it can be too big. Also, + the memory usage of the compressor increases linearly when adding + threads. + + Match finder parallelization is another threading method. It has + been in 7-Zip for ages. It doesn't affect compression ratio or + memory usage significantly. Among the three threading methods, only + this is useful when compressing small files (files that are not + significantly bigger than the dictionary). Unfortunately this method + scales only to about two CPU cores. + + The third method is pigz-style threading (I use that name, because + pigz <http://www.zlib.net/pigz/> uses that method). It doesn't + affect compression ratio significantly and scales to many cores. + The memory usage scales linearly when threads are added. This isn't + significant with pigz, because Deflate uses only a 32 KiB dictionary, + but with LZMA2 the memory usage will increase dramatically just like + with the independent-blocks method. There is also a constant + computational overhead, which may make pigz-method a bit dull on + dual-core compared to the parallel match finder method, but with more + cores the overhead is not a big deal anymore. + + Combining the threading methods will be possible and also useful. + E.g. combining match finder parallelization with pigz-style threading + can cut the memory usage by 50 %. + + It is possible that the single-threaded method will be modified to + create files identical to the pigz-style method. We'll see once + pigz-style threading has been implemented in liblzma. + + +Q: How do I build a program that needs liblzmadec (lzmadec.h)? + +A: liblzmadec is part of LZMA Utils. XZ Utils has liblzma, but no + liblzmadec. The code using liblzmadec should be ported to use + liblzma instead. If you cannot or don't want to do that, download + LZMA Utils from <https://tukaani.org/lzma/>. + + +Q: The default build of liblzma is too big. How can I make it smaller? + +A: Give --enable-small to the configure script. Use also appropriate + --enable or --disable options to include only those filter encoders + and decoders and integrity checks that you actually need. Use + CFLAGS=-Os (with GCC) or equivalent to tell your compiler to optimize + for size. See INSTALL for information about configure options. + + If the result is still too big, take a look at XZ Embedded. It is + a separate project, which provides a limited but significantly + smaller XZ decoder implementation than XZ Utils. You can find it + at <https://tukaani.org/xz/embedded.html>. + diff --git a/deps/share/doc/xz/history.txt b/deps/share/doc/xz/history.txt new file mode 100644 index 0000000..8545e23 --- /dev/null +++ b/deps/share/doc/xz/history.txt @@ -0,0 +1,150 @@ + +History of LZMA Utils and XZ Utils +================================== + +Tukaani distribution + + In 2005, there was a small group working on the Tukaani distribution, + which was a Slackware fork. One of the project's goals was to fit the + distro on a single 700 MiB ISO-9660 image. Using LZMA instead of gzip + helped a lot. Roughly speaking, one could fit data that took 1000 MiB + in gzipped form into 700 MiB with LZMA. Naturally, the compression + ratio varied across packages, but this was what we got on average. + + Slackware packages have traditionally had .tgz as the filename suffix, + which is an abbreviation of .tar.gz. A logical naming for LZMA + compressed packages was .tlz, being an abbreviation of .tar.lzma. + + At the end of the year 2007, there was no distribution under the + Tukaani project anymore, but development of LZMA Utils was kept going. + Still, there were .tlz packages around, because at least Vector Linux + (a Slackware based distribution) used LZMA for its packages. + + First versions of the modified pkgtools used the LZMA_Alone tool from + Igor Pavlov's LZMA SDK as is. It was fine, because users wouldn't need + to interact with LZMA_Alone directly. But people soon wanted to use + LZMA for other files too, and the interface of LZMA_Alone wasn't + comfortable for those used to gzip and bzip2. + + +First steps of LZMA Utils + + The first version of LZMA Utils (4.22.0) included a shell script called + lzmash. It was a wrapper that had a gzip-like command-line interface. It + used the LZMA_Alone tool from LZMA SDK to do all the real work. zgrep, + zdiff, and related scripts from gzip were adapted to work with LZMA and + were part of the first LZMA Utils release too. + + LZMA Utils 4.22.0 included also lzmadec, which was a small (less than + 10 KiB) decoder-only command-line tool. It was written on top of the + decoder-only C code found from the LZMA SDK. lzmadec was convenient in + situations where LZMA_Alone (a few hundred KiB) would be too big. + + lzmash and lzmadec were written by Lasse Collin. + + +Second generation + + The lzmash script was an ugly and not very secure hack. The last + version of LZMA Utils to use lzmash was 4.27.1. + + LZMA Utils 4.32.0beta1 introduced a new lzma command-line tool written + by Ville Koskinen. It was written in C++, and used the encoder and + decoder from C++ LZMA SDK with some little modifications. This tool + replaced both the lzmash script and the LZMA_Alone command-line tool + in LZMA Utils. + + Introducing this new tool caused some temporary incompatibilities, + because the LZMA_Alone executable was simply named lzma like the new + command-line tool, but they had a completely different command-line + interface. The file format was still the same. + + Lasse wrote liblzmadec, which was a small decoder-only library based + on the C code found from LZMA SDK. liblzmadec had an API similar to + zlib, although there were some significant differences, which made it + non-trivial to use it in some applications designed for zlib and + libbzip2. + + The lzmadec command-line tool was converted to use liblzmadec. + + Alexandre Sauvé helped converting the build system to use GNU + Autotools. This made it easier to test for certain less portable + features needed by the new command-line tool. + + Since the new command-line tool never got completely finished (for + example, it didn't support the LZMA_OPT environment variable), the + intent was to not call 4.32.x stable. Similarly, liblzmadec wasn't + polished, but appeared to work well enough, so some people started + using it too. + + Because the development of the third generation of LZMA Utils was + delayed considerably (3-4 years), the 4.32.x branch had to be kept + maintained. It got some bug fixes now and then, and finally it was + decided to call it stable, although most of the missing features were + never added. + + +File format problems + + The file format used by LZMA_Alone was primitive. It was designed with + embedded systems in mind, and thus provided only a minimal set of + features. The two biggest problems for non-embedded use were the lack + of magic bytes and an integrity check. + + Igor and Lasse started developing a new file format with some help + from Ville Koskinen. Also Mark Adler, Mikko Pouru, H. Peter Anvin, + and Lars Wirzenius helped with some minor things at some point of the + development. Designing the new format took quite a long time (actually, + too long a time would be a more appropriate expression). It was mostly + because Lasse was quite slow at getting things done due to personal + reasons. + + Originally the new format was supposed to use the same .lzma suffix + that was already used by the old file format. Switching to the new + format wouldn't have caused much trouble when the old format wasn't + used by many people. But since the development of the new format took + such a long time, the old format got quite popular, and it was decided + that the new file format must use a different suffix. + + It was decided to use .xz as the suffix of the new file format. The + first stable .xz file format specification was finally released in + December 2008. In addition to fixing the most obvious problems of + the old .lzma format, the .xz format added some new features like + support for multiple filters (compression algorithms), filter chaining + (like piping on the command line), and limited random-access reading. + + Currently the primary compression algorithm used in .xz is LZMA2. + It is an extension on top of the original LZMA to fix some practical + problems: LZMA2 adds support for flushing the encoder, uncompressed + chunks, eases stateful decoder implementations, and improves support + for multithreading. Since LZMA2 is better than the original LZMA, the + original LZMA is not supported in .xz. + + +Transition to XZ Utils + + The early versions of XZ Utils were called LZMA Utils. The first + releases were 4.42.0alphas. They dropped the rest of the C++ LZMA SDK. + The code was still directly based on LZMA SDK but ported to C and + converted from a callback API to a stateful API. Later, Igor Pavlov + made a C version of the LZMA encoder too; these ports from C++ to C + were independent in LZMA SDK and LZMA Utils. + + The core of the new LZMA Utils was liblzma, a compression library with + a zlib-like API. liblzma supported both the old and new file format. + The gzip-like lzma command-line tool was rewritten to use liblzma. + + The new LZMA Utils code base was renamed to XZ Utils when the name + of the new file format had been decided. The liblzma compression + library retained its name though, because changing it would have + caused unnecessary breakage in applications already using the early + liblzma snapshots. + + The xz command-line tool can emulate the gzip-like lzma tool by + creating appropriate symlinks (e.g. lzma -> xz). Thus, practically + all scripts using the lzma tool from LZMA Utils will work as is with + XZ Utils (and will keep using the old .lzma format). Still, the .lzma + format is more or less deprecated. XZ Utils will keep supporting it, + but new applications should use the .xz format, and migrating old + applications to .xz is often a good idea too. + diff --git a/deps/share/doc/xz/lzma-file-format.txt b/deps/share/doc/xz/lzma-file-format.txt new file mode 100644 index 0000000..015b0fa --- /dev/null +++ b/deps/share/doc/xz/lzma-file-format.txt @@ -0,0 +1,166 @@ + +The .lzma File Format +===================== + + 0. Preface + 0.1. Notices and Acknowledgements + 0.2. Changes + 1. File Format + 1.1. Header + 1.1.1. Properties + 1.1.2. Dictionary Size + 1.1.3. Uncompressed Size + 1.2. LZMA Compressed Data + 2. References + + +0. Preface + + This document describes the .lzma file format, which is + sometimes also called LZMA_Alone format. It is a legacy file + format, which is being or has been replaced by the .xz format. + The MIME type of the .lzma format is `application/x-lzma'. + + The most commonly used software to handle .lzma files are + LZMA SDK, LZMA Utils, 7-Zip, and XZ Utils. This document + describes some of the differences between these implementations + and gives hints what subset of the .lzma format is the most + portable. + + +0.1. Notices and Acknowledgements + + This file format was designed by Igor Pavlov for use in + LZMA SDK. This document was written by Lasse Collin + <[email protected]> using the documentation found + from the LZMA SDK. + + This document has been put into the public domain. + + +0.2. Changes + + Last modified: 2011-04-12 11:55+0300 + + +1. File Format + + +-+-+-+-+-+-+-+-+-+-+-+-+-+==========================+ + | Header | LZMA Compressed Data | + +-+-+-+-+-+-+-+-+-+-+-+-+-+==========================+ + + The .lzma format file consist of 13-byte Header followed by + the LZMA Compressed Data. + + Unlike the .gz, .bz2, and .xz formats, it is not possible to + concatenate multiple .lzma files as is and expect the + decompression tool to decode the resulting file as if it were + a single .lzma file. + + For example, the command line tools from LZMA Utils and + LZMA SDK silently ignore all the data after the first .lzma + stream. In contrast, the command line tool from XZ Utils + considers the .lzma file to be corrupt if there is data after + the first .lzma stream. + + +1.1. Header + + +------------+----+----+----+----+--+--+--+--+--+--+--+--+ + | Properties | Dictionary Size | Uncompressed Size | + +------------+----+----+----+----+--+--+--+--+--+--+--+--+ + + +1.1.1. Properties + + The Properties field contains three properties. An abbreviation + is given in parentheses, followed by the value range of the + property. The field consists of + + 1) the number of literal context bits (lc, [0, 8]); + 2) the number of literal position bits (lp, [0, 4]); and + 3) the number of position bits (pb, [0, 4]). + + The properties are encoded using the following formula: + + Properties = (pb * 5 + lp) * 9 + lc + + The following C code illustrates a straightforward way to + decode the Properties field: + + uint8_t lc, lp, pb; + uint8_t prop = get_lzma_properties(); + if (prop > (4 * 5 + 4) * 9 + 8) + return LZMA_PROPERTIES_ERROR; + + pb = prop / (9 * 5); + prop -= pb * 9 * 5; + lp = prop / 9; + lc = prop - lp * 9; + + XZ Utils has an additional requirement: lc + lp <= 4. Files + which don't follow this requirement cannot be decompressed + with XZ Utils. Usually this isn't a problem since the most + common lc/lp/pb values are 3/0/2. It is the only lc/lp/pb + combination that the files created by LZMA Utils can have, + but LZMA Utils can decompress files with any lc/lp/pb. + + +1.1.2. Dictionary Size + + Dictionary Size is stored as an unsigned 32-bit little endian + integer. Any 32-bit value is possible, but for maximum + portability, only sizes of 2^n and 2^n + 2^(n-1) should be + used. + + LZMA Utils creates only files with dictionary size 2^n, + 16 <= n <= 25. LZMA Utils can decompress files with any + dictionary size. + + XZ Utils creates and decompresses .lzma files only with + dictionary sizes 2^n and 2^n + 2^(n-1). If some other + dictionary size is specified when compressing, the value + stored in the Dictionary Size field is a rounded up, but the + specified value is still used in the actual compression code. + + +1.1.3. Uncompressed Size + + Uncompressed Size is stored as unsigned 64-bit little endian + integer. A special value of 0xFFFF_FFFF_FFFF_FFFF indicates + that Uncompressed Size is unknown. End of Payload Marker (*) + is used if and only if Uncompressed Size is unknown. + + XZ Utils rejects files whose Uncompressed Size field specifies + a known size that is 256 GiB or more. This is to reject false + positives when trying to guess if the input file is in the + .lzma format. When Uncompressed Size is unknown, there is no + limit for the uncompressed size of the file. + + (*) Some tools use the term End of Stream (EOS) marker + instead of End of Payload Marker. + + +1.2. LZMA Compressed Data + + Detailed description of the format of this field is out of + scope of this document. + + +2. References + + LZMA SDK - The original LZMA implementation + http://7-zip.org/sdk.html + + 7-Zip + http://7-zip.org/ + + LZMA Utils - LZMA adapted to POSIX-like systems + http://tukaani.org/lzma/ + + XZ Utils - The next generation of LZMA Utils + http://tukaani.org/xz/ + + The .xz file format - The successor of the .lzma format + http://tukaani.org/xz/xz-file-format.txt + diff --git a/deps/share/doc/xz/xz-file-format.txt b/deps/share/doc/xz/xz-file-format.txt new file mode 100644 index 0000000..4ed6650 --- /dev/null +++ b/deps/share/doc/xz/xz-file-format.txt @@ -0,0 +1,1150 @@ + +The .xz File Format +=================== + +Version 1.0.4 (2009-08-27) + + + 0. Preface + 0.1. Notices and Acknowledgements + 0.2. Getting the Latest Version + 0.3. Version History + 1. Conventions + 1.1. Byte and Its Representation + 1.2. Multibyte Integers + 2. Overall Structure of .xz File + 2.1. Stream + 2.1.1. Stream Header + 2.1.1.1. Header Magic Bytes + 2.1.1.2. Stream Flags + 2.1.1.3. CRC32 + 2.1.2. Stream Footer + 2.1.2.1. CRC32 + 2.1.2.2. Backward Size + 2.1.2.3. Stream Flags + 2.1.2.4. Footer Magic Bytes + 2.2. Stream Padding + 3. Block + 3.1. Block Header + 3.1.1. Block Header Size + 3.1.2. Block Flags + 3.1.3. Compressed Size + 3.1.4. Uncompressed Size + 3.1.5. List of Filter Flags + 3.1.6. Header Padding + 3.1.7. CRC32 + 3.2. Compressed Data + 3.3. Block Padding + 3.4. Check + 4. Index + 4.1. Index Indicator + 4.2. Number of Records + 4.3. List of Records + 4.3.1. Unpadded Size + 4.3.2. Uncompressed Size + 4.4. Index Padding + 4.5. CRC32 + 5. Filter Chains + 5.1. Alignment + 5.2. Security + 5.3. Filters + 5.3.1. LZMA2 + 5.3.2. Branch/Call/Jump Filters for Executables + 5.3.3. Delta + 5.3.3.1. Format of the Encoded Output + 5.4. Custom Filter IDs + 5.4.1. Reserved Custom Filter ID Ranges + 6. Cyclic Redundancy Checks + 7. References + + +0. Preface + + This document describes the .xz file format (filename suffix + ".xz", MIME type "application/x-xz"). It is intended that this + this format replace the old .lzma format used by LZMA SDK and + LZMA Utils. + + +0.1. Notices and Acknowledgements + + This file format was designed by Lasse Collin + <[email protected]> and Igor Pavlov. + + Special thanks for helping with this document goes to + Ville Koskinen. Thanks for helping with this document goes to + Mark Adler, H. Peter Anvin, Mikko Pouru, and Lars Wirzenius. + + This document has been put into the public domain. + + +0.2. Getting the Latest Version + + The latest official version of this document can be downloaded + from <http://tukaani.org/xz/xz-file-format.txt>. + + Specific versions of this document have a filename + xz-file-format-X.Y.Z.txt where X.Y.Z is the version number. + For example, the version 1.0.0 of this document is available + at <http://tukaani.org/xz/xz-file-format-1.0.0.txt>. + + +0.3. Version History + + Version Date Description + + 1.0.4 2009-08-27 Language improvements in Sections 1.2, + 2.1.1.2, 3.1.1, 3.1.2, and 5.3.1 + + 1.0.3 2009-06-05 Spelling fixes in Sections 5.1 and 5.4 + + 1.0.2 2009-06-04 Typo fixes in Sections 4 and 5.3.1 + + 1.0.1 2009-06-01 Typo fix in Section 0.3 and minor + clarifications to Sections 2, 2.2, + 3.3, 4.4, and 5.3.2 + + 1.0.0 2009-01-14 The first official version + + +1. Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", + "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC-2119]. + + Indicating a warning means displaying a message, returning + appropriate exit status, or doing something else to let the + user know that something worth warning occurred. The operation + SHOULD still finish if a warning is indicated. + + Indicating an error means displaying a message, returning + appropriate exit status, or doing something else to let the + user know that something prevented successfully finishing the + operation. The operation MUST be aborted once an error has + been indicated. + + +1.1. Byte and Its Representation + + In this document, byte is always 8 bits. + + A "null byte" has all bits unset. That is, the value of a null + byte is 0x00. + + To represent byte blocks, this document uses notation that + is similar to the notation used in [RFC-1952]: + + +-------+ + | Foo | One byte. + +-------+ + + +---+---+ + | Foo | Two bytes; that is, some of the vertical bars + +---+---+ can be missing. + + +=======+ + | Foo | Zero or more bytes. + +=======+ + + In this document, a boxed byte or a byte sequence declared + using this notation is called "a field". The example field + above would be called "the Foo field" or plain "Foo". + + If there are many fields, they may be split to multiple lines. + This is indicated with an arrow ("--->"): + + +=====+ + | Foo | + +=====+ + + +=====+ + ---> | Bar | + +=====+ + + The above is equivalent to this: + + +=====+=====+ + | Foo | Bar | + +=====+=====+ + + +1.2. Multibyte Integers + + Multibyte integers of static length, such as CRC values, + are stored in little endian byte order (least significant + byte first). + + When smaller values are more likely than bigger values (for + example file sizes), multibyte integers are encoded in a + variable-length representation: + - Numbers in the range [0, 127] are copied as is, and take + one byte of space. + - Bigger numbers will occupy two or more bytes. All but the + last byte of the multibyte representation have the highest + (eighth) bit set. + + For now, the value of the variable-length integers is limited + to 63 bits, which limits the encoded size of the integer to + nine bytes. These limits may be increased in the future if + needed. + + The following C code illustrates encoding and decoding of + variable-length integers. The functions return the number of + bytes occupied by the integer (1-9), or zero on error. + + #include <stddef.h> + #include <inttypes.h> + + size_t + encode(uint8_t buf[static 9], uint64_t num) + { + if (num > UINT64_MAX / 2) + return 0; + + size_t i = 0; + + while (num >= 0x80) { + buf[i++] = (uint8_t)(num) | 0x80; + num >>= 7; + } + + buf[i++] = (uint8_t)(num); + + return i; + } + + size_t + decode(const uint8_t buf[], size_t size_max, uint64_t *num) + { + if (size_max == 0) + return 0; + + if (size_max > 9) + size_max = 9; + + *num = buf[0] & 0x7F; + size_t i = 0; + + while (buf[i++] & 0x80) { + if (i >= size_max || buf[i] == 0x00) + return 0; + + *num |= (uint64_t)(buf[i] & 0x7F) << (i * 7); + } + + return i; + } + + +2. Overall Structure of .xz File + + A standalone .xz files consist of one or more Streams which may + have Stream Padding between or after them: + + +========+================+========+================+ + | Stream | Stream Padding | Stream | Stream Padding | ... + +========+================+========+================+ + + The sizes of Stream and Stream Padding are always multiples + of four bytes, thus the size of every valid .xz file MUST be + a multiple of four bytes. + + While a typical file contains only one Stream and no Stream + Padding, a decoder handling standalone .xz files SHOULD support + files that have more than one Stream or Stream Padding. + + In contrast to standalone .xz files, when the .xz file format + is used as an internal part of some other file format or + communication protocol, it usually is expected that the decoder + stops after the first Stream, and doesn't look for Stream + Padding or possibly other Streams. + + +2.1. Stream + + +-+-+-+-+-+-+-+-+-+-+-+-+=======+=======+ +=======+ + | Stream Header | Block | Block | ... | Block | + +-+-+-+-+-+-+-+-+-+-+-+-+=======+=======+ +=======+ + + +=======+-+-+-+-+-+-+-+-+-+-+-+-+ + ---> | Index | Stream Footer | + +=======+-+-+-+-+-+-+-+-+-+-+-+-+ + + All the above fields have a size that is a multiple of four. If + Stream is used as an internal part of another file format, it + is RECOMMENDED to make the Stream start at an offset that is + a multiple of four bytes. + + Stream Header, Index, and Stream Footer are always present in + a Stream. The maximum size of the Index field is 16 GiB (2^34). + + There are zero or more Blocks. The maximum number of Blocks is + limited only by the maximum size of the Index field. + + Total size of a Stream MUST be less than 8 EiB (2^63 bytes). + The same limit applies to the total amount of uncompressed + data stored in a Stream. + + If an implementation supports handling .xz files with multiple + concatenated Streams, it MAY apply the above limits to the file + as a whole instead of limiting per Stream basis. + + +2.1.1. Stream Header + + +---+---+---+---+---+---+-------+------+--+--+--+--+ + | Header Magic Bytes | Stream Flags | CRC32 | + +---+---+---+---+---+---+-------+------+--+--+--+--+ + + +2.1.1.1. Header Magic Bytes + + The first six (6) bytes of the Stream are so called Header + Magic Bytes. They can be used to identify the file type. + + Using a C array and ASCII: + const uint8_t HEADER_MAGIC[6] + = { 0xFD, '7', 'z', 'X', 'Z', 0x00 }; + + In plain hexadecimal: + FD 37 7A 58 5A 00 + + Notes: + - The first byte (0xFD) was chosen so that the files cannot + be erroneously detected as being in .lzma format, in which + the first byte is in the range [0x00, 0xE0]. + - The sixth byte (0x00) was chosen to prevent applications + from misdetecting the file as a text file. + + If the Header Magic Bytes don't match, the decoder MUST + indicate an error. + + +2.1.1.2. Stream Flags + + The first byte of Stream Flags is always a null byte. In the + future, this byte may be used to indicate a new Stream version + or other Stream properties. + + The second byte of Stream Flags is a bit field: + + Bit(s) Mask Description + 0-3 0x0F Type of Check (see Section 3.4): + ID Size Check name + 0x00 0 bytes None + 0x01 4 bytes CRC32 + 0x02 4 bytes (Reserved) + 0x03 4 bytes (Reserved) + 0x04 8 bytes CRC64 + 0x05 8 bytes (Reserved) + 0x06 8 bytes (Reserved) + 0x07 16 bytes (Reserved) + 0x08 16 bytes (Reserved) + 0x09 16 bytes (Reserved) + 0x0A 32 bytes SHA-256 + 0x0B 32 bytes (Reserved) + 0x0C 32 bytes (Reserved) + 0x0D 64 bytes (Reserved) + 0x0E 64 bytes (Reserved) + 0x0F 64 bytes (Reserved) + 4-7 0xF0 Reserved for future use; MUST be zero for now. + + Implementations SHOULD support at least the Check IDs 0x00 + (None) and 0x01 (CRC32). Supporting other Check IDs is + OPTIONAL. If an unsupported Check is used, the decoder SHOULD + indicate a warning or error. + + If any reserved bit is set, the decoder MUST indicate an error. + It is possible that there is a new field present which the + decoder is not aware of, and can thus parse the Stream Header + incorrectly. + + +2.1.1.3. CRC32 + + The CRC32 is calculated from the Stream Flags field. It is + stored as an unsigned 32-bit little endian integer. If the + calculated value does not match the stored one, the decoder + MUST indicate an error. + + The idea is that Stream Flags would always be two bytes, even + if new features are needed. This way old decoders will be able + to verify the CRC32 calculated from Stream Flags, and thus + distinguish between corrupt files (CRC32 doesn't match) and + files that the decoder doesn't support (CRC32 matches but + Stream Flags has reserved bits set). + + +2.1.2. Stream Footer + + +-+-+-+-+---+---+---+---+-------+------+----------+---------+ + | CRC32 | Backward Size | Stream Flags | Footer Magic Bytes | + +-+-+-+-+---+---+---+---+-------+------+----------+---------+ + + +2.1.2.1. CRC32 + + The CRC32 is calculated from the Backward Size and Stream Flags + fields. It is stored as an unsigned 32-bit little endian + integer. If the calculated value does not match the stored one, + the decoder MUST indicate an error. + + The reason to have the CRC32 field before the Backward Size and + Stream Flags fields is to keep the four-byte fields aligned to + a multiple of four bytes. + + +2.1.2.2. Backward Size + + Backward Size is stored as a 32-bit little endian integer, + which indicates the size of the Index field as multiple of + four bytes, minimum value being four bytes: + + real_backward_size = (stored_backward_size + 1) * 4; + + If the stored value does not match the real size of the Index + field, the decoder MUST indicate an error. + + Using a fixed-size integer to store Backward Size makes + it slightly simpler to parse the Stream Footer when the + application needs to parse the Stream backwards. + + +2.1.2.3. Stream Flags + + This is a copy of the Stream Flags field from the Stream + Header. The information stored to Stream Flags is needed + when parsing the Stream backwards. The decoder MUST compare + the Stream Flags fields in both Stream Header and Stream + Footer, and indicate an error if they are not identical. + + +2.1.2.4. Footer Magic Bytes + + As the last step of the decoding process, the decoder MUST + verify the existence of Footer Magic Bytes. If they don't + match, an error MUST be indicated. + + Using a C array and ASCII: + const uint8_t FOOTER_MAGIC[2] = { 'Y', 'Z' }; + + In hexadecimal: + 59 5A + + The primary reason to have Footer Magic Bytes is to make + it easier to detect incomplete files quickly, without + uncompressing. If the file does not end with Footer Magic Bytes + (excluding Stream Padding described in Section 2.2), it cannot + be undamaged, unless someone has intentionally appended garbage + after the end of the Stream. + + +2.2. Stream Padding + + Only the decoders that support decoding of concatenated Streams + MUST support Stream Padding. + + Stream Padding MUST contain only null bytes. To preserve the + four-byte alignment of consecutive Streams, the size of Stream + Padding MUST be a multiple of four bytes. Empty Stream Padding + is allowed. If these requirements are not met, the decoder MUST + indicate an error. + + Note that non-empty Stream Padding is allowed at the end of the + file; there doesn't need to be a new Stream after non-empty + Stream Padding. This can be convenient in certain situations + [GNU-tar]. + + The possibility of Stream Padding MUST be taken into account + when designing an application that parses Streams backwards, + and the application supports concatenated Streams. + + +3. Block + + +==============+=================+===============+=======+ + | Block Header | Compressed Data | Block Padding | Check | + +==============+=================+===============+=======+ + + +3.1. Block Header + + +-------------------+-------------+=================+ + | Block Header Size | Block Flags | Compressed Size | + +-------------------+-------------+=================+ + + +===================+======================+ + ---> | Uncompressed Size | List of Filter Flags | + +===================+======================+ + + +================+--+--+--+--+ + ---> | Header Padding | CRC32 | + +================+--+--+--+--+ + + +3.1.1. Block Header Size + + This field overlaps with the Index Indicator field (see + Section 4.1). + + This field contains the size of the Block Header field, + including the Block Header Size field itself. Valid values are + in the range [0x01, 0xFF], which indicate the size of the Block + Header as multiples of four bytes, minimum size being eight + bytes: + + real_header_size = (encoded_header_size + 1) * 4; + + If a Block Header bigger than 1024 bytes is needed in the + future, a new field can be added between the Block Header and + Compressed Data fields. The presence of this new field would + be indicated in the Block Header field. + + +3.1.2. Block Flags + + The Block Flags field is a bit field: + + Bit(s) Mask Description + 0-1 0x03 Number of filters (1-4) + 2-5 0x3C Reserved for future use; MUST be zero for now. + 6 0x40 The Compressed Size field is present. + 7 0x80 The Uncompressed Size field is present. + + If any reserved bit is set, the decoder MUST indicate an error. + It is possible that there is a new field present which the + decoder is not aware of, and can thus parse the Block Header + incorrectly. + + +3.1.3. Compressed Size + + This field is present only if the appropriate bit is set in + the Block Flags field (see Section 3.1.2). + + The Compressed Size field contains the size of the Compressed + Data field, which MUST be non-zero. Compressed Size is stored + using the encoding described in Section 1.2. If the Compressed + Size doesn't match the size of the Compressed Data field, the + decoder MUST indicate an error. + + +3.1.4. Uncompressed Size + + This field is present only if the appropriate bit is set in + the Block Flags field (see Section 3.1.2). + + The Uncompressed Size field contains the size of the Block + after uncompressing. Uncompressed Size is stored using the + encoding described in Section 1.2. If the Uncompressed Size + does not match the real uncompressed size, the decoder MUST + indicate an error. + + Storing the Compressed Size and Uncompressed Size fields serves + several purposes: + - The decoder knows how much memory it needs to allocate + for a temporary buffer in multithreaded mode. + - Simple error detection: wrong size indicates a broken file. + - Seeking forwards to a specific location in streamed mode. + + It should be noted that the only reliable way to determine + the real uncompressed size is to uncompress the Block, + because the Block Header and Index fields may contain + (intentionally or unintentionally) invalid information. + + +3.1.5. List of Filter Flags + + +================+================+ +================+ + | Filter 0 Flags | Filter 1 Flags | ... | Filter n Flags | + +================+================+ +================+ + + The number of Filter Flags fields is stored in the Block Flags + field (see Section 3.1.2). + + The format of each Filter Flags field is as follows: + + +===========+====================+===================+ + | Filter ID | Size of Properties | Filter Properties | + +===========+====================+===================+ + + Both Filter ID and Size of Properties are stored using the + encoding described in Section 1.2. Size of Properties indicates + the size of the Filter Properties field as bytes. The list of + officially defined Filter IDs and the formats of their Filter + Properties are described in Section 5.3. + + Filter IDs greater than or equal to 0x4000_0000_0000_0000 + (2^62) are reserved for implementation-specific internal use. + These Filter IDs MUST never be used in List of Filter Flags. + + +3.1.6. Header Padding + + This field contains as many null byte as it is needed to make + the Block Header have the size specified in Block Header Size. + If any of the bytes are not null bytes, the decoder MUST + indicate an error. It is possible that there is a new field + present which the decoder is not aware of, and can thus parse + the Block Header incorrectly. + + +3.1.7. CRC32 + + The CRC32 is calculated over everything in the Block Header + field except the CRC32 field itself. It is stored as an + unsigned 32-bit little endian integer. If the calculated + value does not match the stored one, the decoder MUST indicate + an error. + + By verifying the CRC32 of the Block Header before parsing the + actual contents allows the decoder to distinguish between + corrupt and unsupported files. + + +3.2. Compressed Data + + The format of Compressed Data depends on Block Flags and List + of Filter Flags. Excluding the descriptions of the simplest + filters in Section 5.3, the format of the filter-specific + encoded data is out of scope of this document. + + +3.3. Block Padding + + Block Padding MUST contain 0-3 null bytes to make the size of + the Block a multiple of four bytes. This can be needed when + the size of Compressed Data is not a multiple of four. If any + of the bytes in Block Padding are not null bytes, the decoder + MUST indicate an error. + + +3.4. Check + + The type and size of the Check field depends on which bits + are set in the Stream Flags field (see Section 2.1.1.2). + + The Check, when used, is calculated from the original + uncompressed data. If the calculated Check does not match the + stored one, the decoder MUST indicate an error. If the selected + type of Check is not supported by the decoder, it SHOULD + indicate a warning or error. + + +4. Index + + +-----------------+===================+ + | Index Indicator | Number of Records | + +-----------------+===================+ + + +=================+===============+-+-+-+-+ + ---> | List of Records | Index Padding | CRC32 | + +=================+===============+-+-+-+-+ + + Index serves several purposes. Using it, one can + - verify that all Blocks in a Stream have been processed; + - find out the uncompressed size of a Stream; and + - quickly access the beginning of any Block (random access). + + +4.1. Index Indicator + + This field overlaps with the Block Header Size field (see + Section 3.1.1). The value of Index Indicator is always 0x00. + + +4.2. Number of Records + + This field indicates how many Records there are in the List + of Records field, and thus how many Blocks there are in the + Stream. The value is stored using the encoding described in + Section 1.2. If the decoder has decoded all the Blocks of the + Stream, and then notices that the Number of Records doesn't + match the real number of Blocks, the decoder MUST indicate an + error. + + +4.3. List of Records + + List of Records consists of as many Records as indicated by the + Number of Records field: + + +========+========+ + | Record | Record | ... + +========+========+ + + Each Record contains information about one Block: + + +===============+===================+ + | Unpadded Size | Uncompressed Size | + +===============+===================+ + + If the decoder has decoded all the Blocks of the Stream, it + MUST verify that the contents of the Records match the real + Unpadded Size and Uncompressed Size of the respective Blocks. + + Implementation hint: It is possible to verify the Index with + constant memory usage by calculating for example SHA-256 of + both the real size values and the List of Records, then + comparing the hash values. Implementing this using + non-cryptographic hash like CRC32 SHOULD be avoided unless + small code size is important. + + If the decoder supports random-access reading, it MUST verify + that Unpadded Size and Uncompressed Size of every completely + decoded Block match the sizes stored in the Index. If only + partial Block is decoded, the decoder MUST verify that the + processed sizes don't exceed the sizes stored in the Index. + + +4.3.1. Unpadded Size + + This field indicates the size of the Block excluding the Block + Padding field. That is, Unpadded Size is the size of the Block + Header, Compressed Data, and Check fields. Unpadded Size is + stored using the encoding described in Section 1.2. The value + MUST never be zero; with the current structure of Blocks, the + actual minimum value for Unpadded Size is five. + + Implementation note: Because the size of the Block Padding + field is not included in Unpadded Size, calculating the total + size of a Stream or doing random-access reading requires + calculating the actual size of the Blocks by rounding Unpadded + Sizes up to the next multiple of four. + + The reason to exclude Block Padding from Unpadded Size is to + ease making a raw copy of Compressed Data without Block + Padding. This can be useful, for example, if someone wants + to convert Streams to some other file format quickly. + + +4.3.2. Uncompressed Size + + This field indicates the Uncompressed Size of the respective + Block as bytes. The value is stored using the encoding + described in Section 1.2. + + +4.4. Index Padding + + This field MUST contain 0-3 null bytes to pad the Index to + a multiple of four bytes. If any of the bytes are not null + bytes, the decoder MUST indicate an error. + + +4.5. CRC32 + + The CRC32 is calculated over everything in the Index field + except the CRC32 field itself. The CRC32 is stored as an + unsigned 32-bit little endian integer. If the calculated + value does not match the stored one, the decoder MUST indicate + an error. + + +5. Filter Chains + + The Block Flags field defines how many filters are used. When + more than one filter is used, the filters are chained; that is, + the output of one filter is the input of another filter. The + following figure illustrates the direction of data flow. + + v Uncompressed Data ^ + | Filter 0 | + Encoder | Filter 1 | Decoder + | Filter n | + v Compressed Data ^ + + +5.1. Alignment + + Alignment of uncompressed input data is usually the job of + the application producing the data. For example, to get the + best results, an archiver tool should make sure that all + PowerPC executable files in the archive stream start at + offsets that are multiples of four bytes. + + Some filters, for example LZMA2, can be configured to take + advantage of specified alignment of input data. Note that + taking advantage of aligned input can be beneficial also when + a filter is not the first filter in the chain. For example, + if you compress PowerPC executables, you may want to use the + PowerPC filter and chain that with the LZMA2 filter. Because + not only the input but also the output alignment of the PowerPC + filter is four bytes, it is now beneficial to set LZMA2 + settings so that the LZMA2 encoder can take advantage of its + four-byte-aligned input data. + + The output of the last filter in the chain is stored to the + Compressed Data field, which is is guaranteed to be aligned + to a multiple of four bytes relative to the beginning of the + Stream. This can increase + - speed, if the filtered data is handled multiple bytes at + a time by the filter-specific encoder and decoder, + because accessing aligned data in computer memory is + usually faster; and + - compression ratio, if the output data is later compressed + with an external compression tool. + + +5.2. Security + + If filters would be allowed to be chained freely, it would be + possible to create malicious files, that would be very slow to + decode. Such files could be used to create denial of service + attacks. + + Slow files could occur when multiple filters are chained: + + v Compressed input data + | Filter 1 decoder (last filter) + | Filter 0 decoder (non-last filter) + v Uncompressed output data + + The decoder of the last filter in the chain produces a lot of + output from little input. Another filter in the chain takes the + output of the last filter, and produces very little output + while consuming a lot of input. As a result, a lot of data is + moved inside the filter chain, but the filter chain as a whole + gets very little work done. + + To prevent this kind of slow files, there are restrictions on + how the filters can be chained. These restrictions MUST be + taken into account when designing new filters. + + The maximum number of filters in the chain has been limited to + four, thus there can be at maximum of three non-last filters. + Of these three non-last filters, only two are allowed to change + the size of the data. + + The non-last filters, that change the size of the data, MUST + have a limit how much the decoder can compress the data: the + decoder SHOULD produce at least n bytes of output when the + filter is given 2n bytes of input. This limit is not + absolute, but significant deviations MUST be avoided. + + The above limitations guarantee that if the last filter in the + chain produces 4n bytes of output, the chain as a whole will + produce at least n bytes of output. + + +5.3. Filters + +5.3.1. LZMA2 + + LZMA (Lempel-Ziv-Markov chain-Algorithm) is a general-purpose + compression algorithm with high compression ratio and fast + decompression. LZMA is based on LZ77 and range coding + algorithms. + + LZMA2 is an extension on top of the original LZMA. LZMA2 uses + LZMA internally, but adds support for flushing the encoder, + uncompressed chunks, eases stateful decoder implementations, + and improves support for multithreading. Thus, the plain LZMA + will not be supported in this file format. + + Filter ID: 0x21 + Size of Filter Properties: 1 byte + Changes size of data: Yes + Allow as a non-last filter: No + Allow as the last filter: Yes + + Preferred alignment: + Input data: Adjustable to 1/2/4/8/16 byte(s) + Output data: 1 byte + + The format of the one-byte Filter Properties field is as + follows: + + Bits Mask Description + 0-5 0x3F Dictionary Size + 6-7 0xC0 Reserved for future use; MUST be zero for now. + + Dictionary Size is encoded with one-bit mantissa and five-bit + exponent. The smallest dictionary size is 4 KiB and the biggest + is 4 GiB. + + Raw value Mantissa Exponent Dictionary size + 0 2 11 4 KiB + 1 3 11 6 KiB + 2 2 12 8 KiB + 3 3 12 12 KiB + 4 2 13 16 KiB + 5 3 13 24 KiB + 6 2 14 32 KiB + ... ... ... ... + 35 3 27 768 MiB + 36 2 28 1024 MiB + 37 3 29 1536 MiB + 38 2 30 2048 MiB + 39 3 30 3072 MiB + 40 2 31 4096 MiB - 1 B + + Instead of having a table in the decoder, the dictionary size + can be decoded using the following C code: + + const uint8_t bits = get_dictionary_flags() & 0x3F; + if (bits > 40) + return DICTIONARY_TOO_BIG; // Bigger than 4 GiB + + uint32_t dictionary_size; + if (bits == 40) { + dictionary_size = UINT32_MAX; + } else { + dictionary_size = 2 | (bits & 1); + dictionary_size <<= bits / 2 + 11; + } + + +5.3.2. Branch/Call/Jump Filters for Executables + + These filters convert relative branch, call, and jump + instructions to their absolute counterparts in executable + files. This conversion increases redundancy and thus + compression ratio. + + Size of Filter Properties: 0 or 4 bytes + Changes size of data: No + Allow as a non-last filter: Yes + Allow as the last filter: No + + Below is the list of filters in this category. The alignment + is the same for both input and output data. + + Filter ID Alignment Description + 0x04 1 byte x86 filter (BCJ) + 0x05 4 bytes PowerPC (big endian) filter + 0x06 16 bytes IA64 filter + 0x07 4 bytes ARM (little endian) filter + 0x08 2 bytes ARM Thumb (little endian) filter + 0x09 4 bytes SPARC filter + + If the size of Filter Properties is four bytes, the Filter + Properties field contains the start offset used for address + conversions. It is stored as an unsigned 32-bit little endian + integer. The start offset MUST be a multiple of the alignment + of the filter as listed in the table above; if it isn't, the + decoder MUST indicate an error. If the size of Filter + Properties is zero, the start offset is zero. + + Setting the start offset may be useful if an executable has + multiple sections, and there are many cross-section calls. + Taking advantage of this feature usually requires usage of + the Subblock filter, whose design is not complete yet. + + +5.3.3. Delta + + The Delta filter may increase compression ratio when the value + of the next byte correlates with the value of an earlier byte + at specified distance. + + Filter ID: 0x03 + Size of Filter Properties: 1 byte + Changes size of data: No + Allow as a non-last filter: Yes + Allow as the last filter: No + + Preferred alignment: + Input data: 1 byte + Output data: Same as the original input data + + The Properties byte indicates the delta distance, which can be + 1-256 bytes backwards from the current byte: 0x00 indicates + distance of 1 byte and 0xFF distance of 256 bytes. + + +5.3.3.1. Format of the Encoded Output + + The code below illustrates both encoding and decoding with + the Delta filter. + + // Distance is in the range [1, 256]. + const unsigned int distance = get_properties_byte() + 1; + uint8_t pos = 0; + uint8_t delta[256]; + + memset(delta, 0, sizeof(delta)); + + while (1) { + const int byte = read_byte(); + if (byte == EOF) + break; + + uint8_t tmp = delta[(uint8_t)(distance + pos)]; + if (is_encoder) { + tmp = (uint8_t)(byte) - tmp; + delta[pos] = (uint8_t)(byte); + } else { + tmp = (uint8_t)(byte) + tmp; + delta[pos] = tmp; + } + + write_byte(tmp); + --pos; + } + + +5.4. Custom Filter IDs + + If a developer wants to use custom Filter IDs, he has two + choices. The first choice is to contact Lasse Collin and ask + him to allocate a range of IDs for the developer. + + The second choice is to generate a 40-bit random integer, + which the developer can use as his personal Developer ID. + To minimize the risk of collisions, Developer ID has to be + a randomly generated integer, not manually selected "hex word". + The following command, which works on many free operating + systems, can be used to generate Developer ID: + + dd if=/dev/urandom bs=5 count=1 | hexdump + + The developer can then use his Developer ID to create unique + (well, hopefully unique) Filter IDs. + + Bits Mask Description + 0-15 0x0000_0000_0000_FFFF Filter ID + 16-55 0x00FF_FFFF_FFFF_0000 Developer ID + 56-62 0x3F00_0000_0000_0000 Static prefix: 0x3F + + The resulting 63-bit integer will use 9 bytes of space when + stored using the encoding described in Section 1.2. To get + a shorter ID, see the beginning of this Section how to + request a custom ID range. + + +5.4.1. Reserved Custom Filter ID Ranges + + Range Description + 0x0000_0300 - 0x0000_04FF Reserved to ease .7z compatibility + 0x0002_0000 - 0x0007_FFFF Reserved to ease .7z compatibility + 0x0200_0000 - 0x07FF_FFFF Reserved to ease .7z compatibility + + +6. Cyclic Redundancy Checks + + There are several incompatible variations to calculate CRC32 + and CRC64. For simplicity and clarity, complete examples are + provided to calculate the checks as they are used in this file + format. Implementations MAY use different code as long as it + gives identical results. + + The program below reads data from standard input, calculates + the CRC32 and CRC64 values, and prints the calculated values + as big endian hexadecimal strings to standard output. + + #include <stddef.h> + #include <inttypes.h> + #include <stdio.h> + + uint32_t crc32_table[256]; + uint64_t crc64_table[256]; + + void + init(void) + { + static const uint32_t poly32 = UINT32_C(0xEDB88320); + static const uint64_t poly64 + = UINT64_C(0xC96C5795D7870F42); + + for (size_t i = 0; i < 256; ++i) { + uint32_t crc32 = i; + uint64_t crc64 = i; + + for (size_t j = 0; j < 8; ++j) { + if (crc32 & 1) + crc32 = (crc32 >> 1) ^ poly32; + else + crc32 >>= 1; + + if (crc64 & 1) + crc64 = (crc64 >> 1) ^ poly64; + else + crc64 >>= 1; + } + + crc32_table[i] = crc32; + crc64_table[i] = crc64; + } + } + + uint32_t + crc32(const uint8_t *buf, size_t size, uint32_t crc) + { + crc = ~crc; + for (size_t i = 0; i < size; ++i) + crc = crc32_table[buf[i] ^ (crc & 0xFF)] + ^ (crc >> 8); + return ~crc; + } + + uint64_t + crc64(const uint8_t *buf, size_t size, uint64_t crc) + { + crc = ~crc; + for (size_t i = 0; i < size; ++i) + crc = crc64_table[buf[i] ^ (crc & 0xFF)] + ^ (crc >> 8); + return ~crc; + } + + int + main() + { + init(); + + uint32_t value32 = 0; + uint64_t value64 = 0; + uint64_t total_size = 0; + uint8_t buf[8192]; + + while (1) { + const size_t buf_size + = fread(buf, 1, sizeof(buf), stdin); + if (buf_size == 0) + break; + + total_size += buf_size; + value32 = crc32(buf, buf_size, value32); + value64 = crc64(buf, buf_size, value64); + } + + printf("Bytes: %" PRIu64 "\n", total_size); + printf("CRC-32: 0x%08" PRIX32 "\n", value32); + printf("CRC-64: 0x%016" PRIX64 "\n", value64); + + return 0; + } + + +7. References + + LZMA SDK - The original LZMA implementation + http://7-zip.org/sdk.html + + LZMA Utils - LZMA adapted to POSIX-like systems + http://tukaani.org/lzma/ + + XZ Utils - The next generation of LZMA Utils + http://tukaani.org/xz/ + + [RFC-1952] + GZIP file format specification version 4.3 + http://www.ietf.org/rfc/rfc1952.txt + - Notation of byte boxes in section "2.1. Overall conventions" + + [RFC-2119] + Key words for use in RFCs to Indicate Requirement Levels + http://www.ietf.org/rfc/rfc2119.txt + + [GNU-tar] + GNU tar 1.21 manual + http://www.gnu.org/software/tar/manual/html_node/Blocking-Factor.html + - Node 9.4.2 "Blocking Factor", paragraph that begins + "gzip will complain about trailing garbage" + - Note that this URL points to the latest version of the + manual, and may some day not contain the note which is in + 1.21. For the exact version of the manual, download GNU + tar 1.21: ftp://ftp.gnu.org/pub/gnu/tar/tar-1.21.tar.gz + diff --git a/deps/share/locale/cs/LC_MESSAGES/xz.mo b/deps/share/locale/cs/LC_MESSAGES/xz.mo Binary files differnew file mode 100644 index 0000000..81fdbdf --- /dev/null +++ b/deps/share/locale/cs/LC_MESSAGES/xz.mo diff --git a/deps/share/locale/de/LC_MESSAGES/elfutils.mo b/deps/share/locale/de/LC_MESSAGES/elfutils.mo Binary files differnew file mode 100644 index 0000000..d94cb6a --- /dev/null +++ b/deps/share/locale/de/LC_MESSAGES/elfutils.mo diff --git a/deps/share/locale/de/LC_MESSAGES/xz.mo b/deps/share/locale/de/LC_MESSAGES/xz.mo Binary files differnew file mode 100644 index 0000000..934400c --- /dev/null +++ b/deps/share/locale/de/LC_MESSAGES/xz.mo diff --git a/deps/share/locale/en@boldquot/LC_MESSAGES/elfutils.mo b/deps/share/locale/en@boldquot/LC_MESSAGES/elfutils.mo Binary files differnew file mode 100644 index 0000000..8ee79cf --- /dev/null +++ b/deps/share/locale/en@boldquot/LC_MESSAGES/elfutils.mo diff --git a/deps/share/locale/en@quot/LC_MESSAGES/elfutils.mo b/deps/share/locale/en@quot/LC_MESSAGES/elfutils.mo Binary files differnew file mode 100644 index 0000000..599ae45 --- /dev/null +++ b/deps/share/locale/en@quot/LC_MESSAGES/elfutils.mo diff --git a/deps/share/locale/es/LC_MESSAGES/elfutils.mo b/deps/share/locale/es/LC_MESSAGES/elfutils.mo Binary files differnew file mode 100644 index 0000000..61e8da7 --- /dev/null +++ b/deps/share/locale/es/LC_MESSAGES/elfutils.mo diff --git a/deps/share/locale/fr/LC_MESSAGES/xz.mo b/deps/share/locale/fr/LC_MESSAGES/xz.mo Binary files differnew file mode 100644 index 0000000..70a282f --- /dev/null +++ b/deps/share/locale/fr/LC_MESSAGES/xz.mo diff --git a/deps/share/locale/it/LC_MESSAGES/xz.mo b/deps/share/locale/it/LC_MESSAGES/xz.mo Binary files differnew file mode 100644 index 0000000..0e83538 --- /dev/null +++ b/deps/share/locale/it/LC_MESSAGES/xz.mo diff --git a/deps/share/locale/ja/LC_MESSAGES/elfutils.mo b/deps/share/locale/ja/LC_MESSAGES/elfutils.mo Binary files differnew file mode 100644 index 0000000..8e68e98 --- /dev/null +++ b/deps/share/locale/ja/LC_MESSAGES/elfutils.mo diff --git a/deps/share/locale/pl/LC_MESSAGES/elfutils.mo b/deps/share/locale/pl/LC_MESSAGES/elfutils.mo Binary files differnew file mode 100644 index 0000000..28f505c --- /dev/null +++ b/deps/share/locale/pl/LC_MESSAGES/elfutils.mo diff --git a/deps/share/locale/pl/LC_MESSAGES/xz.mo b/deps/share/locale/pl/LC_MESSAGES/xz.mo Binary files differnew file mode 100644 index 0000000..6e311fc --- /dev/null +++ b/deps/share/locale/pl/LC_MESSAGES/xz.mo diff --git a/deps/share/locale/uk/LC_MESSAGES/elfutils.mo b/deps/share/locale/uk/LC_MESSAGES/elfutils.mo Binary files differnew file mode 100644 index 0000000..f4427c8 --- /dev/null +++ b/deps/share/locale/uk/LC_MESSAGES/elfutils.mo diff --git a/deps/share/locale/vi/LC_MESSAGES/xz.mo b/deps/share/locale/vi/LC_MESSAGES/xz.mo Binary files differnew file mode 100644 index 0000000..f85214f --- /dev/null +++ b/deps/share/locale/vi/LC_MESSAGES/xz.mo diff --git a/deps/share/man/man1/eu-elfclassify.1 b/deps/share/man/man1/eu-elfclassify.1 new file mode 100644 index 0000000..cbfdae4 --- /dev/null +++ b/deps/share/man/man1/eu-elfclassify.1 @@ -0,0 +1,197 @@ +.\" Copyright 2019 Red Hat Inc. +.\" Tue 2019-Aug 20 Ben Woodard <[email protected]> +.\" Florian Wiemer <[email protected]> +.\" Mark Wielaard <[email protected]> +.\" Contact [email protected] to correct errors or typos. +.TH EU-ELFCLASSIFY 1 "2019-Aug-20" "elfutils" +.SH "NAME" +eu-elfclassify \- Determine the type of an ELF file. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +eu-elfclassify [\fB\-\-core\fR] + [\fB\-\-debug-only\fR] + [\fB\-\-elf\fR] + [\fB\-\-elf\-archive\fR] + [\fB\-\-elf\-file\fR] + [\fB\-\-executable\fR] + [\fB\-\-library\fR] + [\fB\-\-linux\-kernel\-module\fR] + [\fB\-\-loadable\fR] + [\fB\-\-program\fR] + [\fB\-\-shared\fR] + [\fB\-\-unstripped\fR] + [\fB\-f\fR|\fB \-\-file\fR] + [\fB\-\-no\-stdin\fR] + [\fB\-\-stdin\fR] + [\fB\-\-stdin0\fR] + [\fB\-z\fR|\fB \-\-compressed\fR] + [\fB\-\-matching\fR] + [\fB\-\-no\-print\fR] + [\fB\-\-not\-matching\fR] + [\fB\-\-print\fR] + [\fB\-\-print0\fR] + [\fB\-q\fR|\fB \-\-quiet\fR] + [\fB\-v\fR|\fB \-\-verbose\fR] + [\fB\-?\fR|\fB \-\-help\fR] + [\fB\-\-usage\fR] + [\fB\-V\fR|\fB \-\-version\fR] + \fIelffile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBeu-elfclassify\fR identifies the primary purpose of a particular kind of + \s-1ELF\s0 file or files +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. All of the classification options must apply at the same time to a +particular file. Classification options can be negated using a +\fB\-\-not\-\fR prefix. +.SS "Classification Options" +.IX Subsection "Classification Options" +.IP "\fB\-\-core\fR" 4 +.IX Item "--core" +.PD +File is an ELF core dump file. +.IP "\FB\-\-debug\-only\fR" 4 +.IX Item "--debug-only" +.PD +File is a debug only ELF file (separate .debug, .dwo or dwz multi-file). +.IP "\fB\-\-elf\fR" 4 +.IX Item "--elf" +.PD +File looks like an ELF object or archive/static library (default). +.IP "\fB\-\-elf\-archive\fR" 4 +.IX Item "--elf-archive" +.PD +File is an ELF archive or static library. +.IP "\fB\-\-elf\-file\fR" 4 +.IX Item "--elf-file" +.PD +File is an regular ELF object (not an archive/static library). +.IP "\fB\-\-executable\fR" 4 +.IX Item "--executable" +.PD +File is (primarily) an ELF program executable (not primarily a DS.O) +.IP "\fB\-\-library\fR" 4 +.IX Item "--library" +.PD +File is an ELF shared object (DSO) (might also be an executable). +.IP "\fB\-\-linux\-kernel\-module\fR" 4 +.IX Item "--linux-kernel-module" +.PD +File is a linux kernel module. +.IP "\fB\-\-loadable\fR" 4 +.IX Item "--loadable" +.PD +File is a loadable ELF object (program or shared object). +.IP "\fB\--program\fR" 4 +.IX Item "--program" +.PD +File is an ELF program executable (might also be a DSO). +.IP "\fB\-\-shared\fR" 4 +.IX Item "--shared" +.PD +File is (primarily) an ELF shared object (DSO) (not primarily an executable). +.IP "\fB\-\-unstripped\fR" 4 +.IX Item "--unstripped" +.PD +File is an ELF file with symbol table or .debug_* sections and can be stripped +further. +.SS "Input flags" +.IX Subsection "Input flags" +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD 0 +.IP "\fB\-\-file\fR" 4 +.IX Item "--file" +.PD +Only classify regular (not symlink nor special device) files. +.IP "\fB\-\-no\-stdin\fR" 4 +.IX Item "--no-stdin" +.PD +Do not read files from standard input (default). +.IP "\fB\-\-stdin\fR" 4 +.IX Item "--stdin" +.PD +Also read file names to process from standard input, separated by newlines. +.IP "\fB\-\-stdin0\fR" 4 +.IX Item "--stdin0" +.PD +Also read file names to process from standard input, separated by ASCII NUL +bytes. +.IP "\fB\-z\fR" 4 +.IX Item "-z" +.PD 0 +.IP "\fB\-\-compressed\fR" 4 +.IX Item "--compressed" +.PD +Try to open compressed files or embedded (kernel) ELF images. +.SS "Output flags" +.IX Subsection "Output flags" +.IP "\fB\-\-matching\fR" 4 +.IX Item "--matching" +.PD +If printing file names, print matching files (default). +.IP "\fB\-\-no\-print\fR" 4 +.IX Item "--no-print" +.PD +Do not output file names. +.IP "\fB\-\-not\-matching\fR" 4 +.IX Item "--not-matching" +.PD +If printing file names, print files that do not match. +.IP "\fB\-\-print\fR" 4 +.IX Item "--print" +.PD +Output names of files, separated by newline. +.IP "\fB\-\-print0\fR" 4 +.IX Item "--print0" +.PD +Output names of files, separated by ASCII NUL. +.SS " Additional flags" +.IX Subsection " Additional flags" +.IP "\fB\-q\fR" 4 +.IX Item "-q," +.PD +.IP "\fB\-\-quiet\fR" 4 +.IX Item "--quiet" +.PD +Suppress some error output (counterpart to --verbose). +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD +.IP "\fB\-\-verbose\fR" 4 +.IX Item "--verbose" +.PD +Output additional information (can be specified multiple times). +.IP "\fB\-?\fR" 4 +.IX Item "-?" +.PD +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD +Give this help list. +.IP "\fB\-\-usage\fR" 4 +.IX Item "--usage" +.PD +Give a short usage message. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Print program version. + +.SH "AUTHOR" +.IX Header "AUTHOR" +Written by Florian Wiemer. +.SH "REPORTING BUGS" +.IX Header "REPORTING BUGS" +Please reports bugs at https://sourceware.org/bugzilla/ +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright © 2019 Red Hat Inc. License GPLv3+: GNU GPL version 3 or +later <https://gnu.org/licenses/gpl.html>. This is free software: you +are free to change and redistribute it. There is NO WARRANTY, to the +extent permitted by law. diff --git a/deps/share/man/man1/eu-readelf.1 b/deps/share/man/man1/eu-readelf.1 new file mode 100644 index 0000000..3326381 --- /dev/null +++ b/deps/share/man/man1/eu-readelf.1 @@ -0,0 +1,511 @@ +.\" Modified from readelf.1 man page +.\" Tue 2019-Aug 20 by Ben Woodard <[email protected]> +.\" Contact [email protected] to correct errors or typos. +.\" +.\" Standard preamble: +.\" ======================================================================== +.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 \\$1q +.. +.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. \*(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- +.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" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.if !\nF .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +.\} +.\" +.\" 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 "EU-READELF 1" +.TH EU-READELF 1 "2019-Aug-20" "elfutils" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +eu-readelf \- Displays information about ELF files. +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +eu-readelf [\fB\-a\fR|\fB\-\-all\fR] + [\fB\-h\fR|\fB\-\-file\-header\fR] + [\fB\-l\fR|\fB\-\-program\-headers\fR|\fB\-\-segments\fR] + [\fB\-S\fR|\fB\-\-section\-headers\fR|\fB\-\-sections\fR] + [\fB\-g\fR|\fB\-\-section\-groups\fR] + [\fB\-e\fR|\fB\-\-exception\fR] + [\fB\-s\fR|\fB\-\-symbols\fR] [section name] ] + [\fB\-\-dyn-syms\fR] + [\fB\-n\fR|\fB\-\-notes\fR [section name] ] + [\fB\-r\fR|\fB\-\-relocs\fR] + [\fB\-d\fR|\fB\-\-dynamic\fR] + [\fB\-V\fR|\fB\-\-version\-info\fR] + [\fB\-A\fR|\fB\-\-arch\-specific\fR] + [\fB\-x\fR <number or name>|\fB\-\-hex\-dump=\fR<number or name>] + [\fB\-p\fR <number or name>|\fB\-\-string\-dump=\fR<number or name>] + [\fB\-z\fR|\fB\-\-decompress\fR] + [\fB\-c\fR|\fB\-\-archive\-index\fR] + [\fB\-\-dwarf\-skeleton\fR <file> ] + [\fB\-\-elf\-section\fR [section] ] + [\fB\-w\fR| + \fB\-\-debug\-dump\fR[=line,=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]] + [\fB\-I\fR|\fB\-\-histogram\fR] + [\fB\-v\fR|\fB\-\-version\fR] + [\fB\-W\fR|\fB\-\-wide\fR] + [\fB\-H\fR|\fB\-\-help\fR] + \fIelffile\fR... +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBeu-readelf\fR displays information about one or more \s-1ELF\s0 format object +files. The options control what particular information to display. +.PP +\&\fIelffile\fR... are the object files to be examined. 32\-bit and +64\-bit \s-1ELF\s0 files are supported, as are archives containing \s-1ELF\s0 files. +.PP +This program performs a similar function to \fBobjdump\fR but it +goes into more detail and it exists independently of the \s-1BFD\s0 +library, so if there is a bug in \s-1BFD\s0 then readelf will not be +affected. +.SH "OPTIONS" +.IX Header "OPTIONS" +The long and short forms of options, shown here as alternatives, are +equivalent. At least one option in addition to \fB\-v\fR or \fB\-H\fR must be +given. +.SS "ELF Input Selection" +.IX Subsection "ELF Input Selection" +.IP "\fB\-\-dwarf\-skeleton <file>\fR" 4 +.IX Item "--dwarf-skeleton <file>" +.PD +Used with -w to find the skeleton Compile Units in FILE associated +with the Split Compile units in a .dwo input file. +.IP "\fB\-\-elf\-section [section]\fR" 4 +.IX Item "--elf-section [section]" +.PD +Use the named SECTION (default .gnu_debugdata) as (compressed) ELF input data +.SS "ELF Output Selection" +.IX Subsection "ELF Output Selection" +.IP "\fB\-a\fR" 4 +.IX Item "-a" +.PD 0 +.IP "\fB\-\-all\fR" 4 +.IX Item "--all" +.PD +Equivalent to specifying \fB\-\-file\-header\fR, +\&\fB\-\-program\-headers\fR, \fB\-\-sections\fR, \fB\-\-symbols\fR, +\&\fB\-\-relocs\fR, \fB\-\-dynamic\fR, \fB\-\-notes\fR, +\&\fB\-\-version\-info\fR, \fB\-\-arch\-specific\fR, +\&\fB\-\-section\-groups\fR and \fB\-\-histogram\fR. +.Sp +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD 0 +.IP "\fB\-\-file\-header\fR" 4 +.IX Item "--file-header" +.PD +Displays the information contained in the \s-1ELF\s0 header at the start of the +file. +.IP "\fB\-l\fR" 4 +.IX Item "-l" +.PD 0 +.IP "\fB\-\-program\-headers\fR" 4 +.IX Item "--program-headers" +.IP "\fB\-\-segments\fR" 4 +.IX Item "--segments" +.PD +Displays the information contained in the file's segment headers, if it +has any. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +.PD 0 +.IP "\fB\-\-sections\fR" 4 +.IX Item "--sections" +.IP "\fB\-\-section\-headers\fR" 4 +.IX Item "--section-headers" +.PD +Displays the information contained in the file's section headers, if it +has any. +.IP "\fB\-g\fR" 4 +.IX Item "-g" +.PD 0 +.IP "\fB\-\-section\-groups\fR" 4 +.IX Item "--section-groups" +.PD +Displays the information contained in the file's section groups, if it +has any. +.IP "\fB\-I\fR" 4 +.IX Item "-I" +.PD 0 +.IP "\fB\-\-histogram\fR" 4 +.IX Item "--histogram" +.PD +Display a histogram of bucket list lengths when displaying the contents +of the symbol tables. +.IP "\fB\-s\fR" 4 +.IX Item "-s" +.PD 0 +.IP "\fB\-\-symbols\fR [section name]" 4 +.IX Item "--symbols" +.PD +Displays the entries in symbol table section of the file, if it has one. +If a symbol has version information associated with it then this is +displayed as well. The version string is displayed as a suffix to the +symbol name, preceeded by an @ character. For example +\&\fBfoo@VER_1\fR. If the version is the default version to be used +when resolving unversioned references to the symbol then it is +displayed as a suffix preceeded by two @ characters. For example +\&\fBfoo@@VER_2\fR. +.IP "\fB\-\-dyn-syms\fR" 4 +.IX Item "--dyn-syms" +.PD +Display (only) the dynamic symbol table. +.IP "\fB\-e\fR" 4 +.IX Item "-e" +.PD 0 +.IP "\fB\-\-exception\fR" 4 +.IX Item "--exception" +.PD +Display sections for exception handling. +.IP "\fB\-n\fR" 4 +.IX Item "-n [section name]" +.PD 0 +.IP "\fB\-\-notes [section name]\fR" 4 +.IX Item "--notes" +.PD +Displays the contents of the \s-1NOTE\s0 segments and/or sections, if any. +.IP "\fB\-r\fR" 4 +.IX Item "-r" +.PD 0 +.IP "\fB\-\-relocs\fR" 4 +.IX Item "--relocs" +.PD +Displays the contents of the file's relocation section, if it has one. +.IP "\fB\-d\fR" 4 +.IX Item "-d" +.PD 0 +.IP "\fB\-\-dynamic\fR" 4 +.IX Item "--dynamic" +.PD +Displays the contents of the file's dynamic section, if it has one. +.IP "\fB\-V\fR" 4 +.IX Item "-V" +.PD 0 +.IP "\fB\-\-version\-info\fR" 4 +.IX Item "--version-info" +.PD +Displays the contents of the version sections in the file, it they +exist. +.IP "\fB\-A\fR" 4 +.IX Item "-A" +.PD 0 +.IP "\fB\-\-arch\-specific\fR" 4 +.IX Item "--arch-specific" +.PD +Displays architecture-specific information in the file, if there +is any. +.SS "Additional output selection" +.IX Subsection "Additional output selection" +.IP "\fB\-x <name>\fR" 4 +.IX Item "-x <name>" +.PD 0 +.IP "\fB\-\-hex\-dump=<name>\fR" 4 +.IX Item "--hex-dump=<name>" +.PD +Displays the contents of the indicated section name as a hexadecimal bytes. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +.PD 0 +.IP "\fB\-\-debug\-dump[=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]\fR" 4 +.IX Item "--debug-dump[=line,=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]" +.PD +Displays the contents of the \s-1DWARF\s0 debug sections in the file, if any +are present. Compressed debug sections are automatically decompressed +(temporarily) before they are displayed. If one or more of the +optional letters or words follows the switch then only those type(s) +of data will be dumped. The letters and words refer to the following +information: +.RS 4 +.PD 0 +.ie n .IP """=abbrev""" 4 +.el .IP "\f(CW=abbrev\fR" 4 +.IX Item "=abbrev" +.PD +Displays the contents of the \fB.debug_abbrev\fR section. +.PD 0 +.ie n .IP """=addr""" 4 +.el .IP "\f(CW=addr\fR" 4 +.IX Item "=addr" +.PD +Displays the contents of the \fB.debug_addr\fR section. +.PD 0 +.ie n .IP """=frames""" 4 +.el .IP "\f(CW=frames\fR" 4 +.IX Item "=frames" +.PD +Display the raw contents of a \fB.debug_frame\fR section. +.PD 0 +.ie n .IP """=gdb_index""" 4 +.el .IP "\f(CW=gdb_index\fR" 4 +.IX Item "=gdb_index" +.PD +Displays the contents of the \fB.gdb_index\fR and/or +\&\fB.debug_names\fR sections. +.PD 0 +.ie n .IP """=info""" 4 +.el .IP "\f(CW=info\fR" 4 +.IX Item "=info" +.PD +Displays the contents of the \fB.debug_info\fR section. +.PD 0 +.ie n .IP """=info+""" 4 +.el .IP "\f(CW=info+\fR" 4 +.IX Item "=info+" +.PD +Displays the contents of the \fB.debug_info\fR section, plus any skeleton +unit will be immediately followed by the corresponding split compile unit +(from the .dwo file). To show the difference between "regular" CUs and +split CUs print offsets and references between { and } instead of [ and ]. +.PD 0 +.ie n .IP """=decodedline""" 4 +.el .IP "\f(CW=decodedline\fR" 4 +.IX Item "=decodedline" +.PD +Displays the interpreted contents of the \fB.debug_line\fR section. +.PD 0 +.ie n .IP """=macro""" 4 +.el .IP "\f(CW=macro\fR" 4 +.IX Item "=macro" +.PD +Displays the contents of the \fB.debug_macro\fR and/or +\&\fB.debug_macinfo\fR sections. +.PD 0 +.ie n .IP """=loc""" 4 +.el .IP "\f(CW=loc\fR" 4 +.IX Item "=loc" +.PD +Displays the contents of the \fB.debug_loc\fR and/or +\&\fB.debug_loclists\fR sections. +.PD 0 +.ie n .IP """=pubnames""" 4 +.el .IP "\f(CW=pubnames\fR" 4 +.IX Item "=pubnames" +.PD +Displays the contents of the \fB.debug_pubnames\fR and/or +\&\fB.debug_gnu_pubnames\fR sections. +.PD 0 +.ie n .IP """=aranges""" 4 +.el .IP "\f(CW=aranges\fR" 4 +.IX Item "=aranges" +.PD +Displays the contents of the \fB.debug_aranges\fR section. +.PD 0 +.ie n .IP """=ranges""" 4 +.el .IP "\f(CW=ranges\fR" 4 +.IX Item "=ranges" +.PD +Displays the contents of the \fB.debug_ranges\fR and/or +\&\fB.debug_rnglists\fR sections. +.PD 0 +.ie n .IP """=str""" 4 +.el .IP "\f(CW=str\fR" 4 +.IX Item "=str" +.PD +Displays the contents of the \fB.debug_str\fR, \fB.debug_line_str\fR +and/or \fB.debug_str_offsets\fR sections. +.PD 0 +.RS 4 +.Sp +Note: displaying the contents of \fB.debug_static_funcs\fR, +\&\fB.debug_static_vars\fR and \fBdebug_weaknames\fR sections is not +currently supported. +.RE +.IP "\fB\-p <number or name>\fR" 4 +.IX Item "-p <number or name>" +.PD 0 +.IP "\fB\-\-string\-dump=<number or name>\fR" 4 +.IX Item "--string-dump=<number or name>" +.PD +Displays the contents of the indicated section as printable strings. +A number identifies a particular section by index in the section table; +any other string identifies all sections with that name in the object file. +.IP "\fB\-c\fR" 4 +.IX Item "-c" +.PD 0 +.IP "\fB\-\-archive\-index\fR" 4 +.IX Item "--archive-index" +.PD +Displays the file symbol index information contained in the header part +of binary archives. Performs the same function as the \fBt\fR +command to \fBar\fR, but without using the \s-1BFD\s0 library. +.SS "Output control" +.IX Subsection "Output control" +.IP "\fB\-z\fR" 4 +.IX Item "-z" +.PD 0 +.IP "\fB\-\-decompress\fR" 4 +.IX Item "--decompress" +.PD +Requests that the section(s) being dumped by \fBx\fR, \fBR\fR or +\&\fBp\fR options are decompressed before being displayed. If the +section(s) are not compressed then they are displayed as is. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Display the version number of eu-readelf. +.IP "\fB\-W\fR" 4 +.IX Item "-W" +.PD 0 +.IP "\fB\-\-wide\fR" 4 +.IX Item "--wide" +.PD +Ignored for compatibility (lines always wide). +.IP "\fB\-H\fR" 4 +.IX Item "-H" +.PD 0 +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD +Display the command line options understood by \fBeu-readelf\fR. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and the Info entries for +\fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1991\-2018 Free Software Foundation, Inc. + +Copyright (c) 2019 Red Hat Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R". diff --git a/deps/share/man/man1/lzcat.1 b/deps/share/man/man1/lzcat.1 new file mode 120000 index 0000000..01b6808 --- /dev/null +++ b/deps/share/man/man1/lzcat.1 @@ -0,0 +1 @@ +xz.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzcmp.1 b/deps/share/man/man1/lzcmp.1 new file mode 120000 index 0000000..e65fb97 --- /dev/null +++ b/deps/share/man/man1/lzcmp.1 @@ -0,0 +1 @@ +xzdiff.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzdiff.1 b/deps/share/man/man1/lzdiff.1 new file mode 120000 index 0000000..e65fb97 --- /dev/null +++ b/deps/share/man/man1/lzdiff.1 @@ -0,0 +1 @@ +xzdiff.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzegrep.1 b/deps/share/man/man1/lzegrep.1 new file mode 120000 index 0000000..bebd8a4 --- /dev/null +++ b/deps/share/man/man1/lzegrep.1 @@ -0,0 +1 @@ +xzgrep.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzfgrep.1 b/deps/share/man/man1/lzfgrep.1 new file mode 120000 index 0000000..bebd8a4 --- /dev/null +++ b/deps/share/man/man1/lzfgrep.1 @@ -0,0 +1 @@ +xzgrep.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzgrep.1 b/deps/share/man/man1/lzgrep.1 new file mode 120000 index 0000000..bebd8a4 --- /dev/null +++ b/deps/share/man/man1/lzgrep.1 @@ -0,0 +1 @@ +xzgrep.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzless.1 b/deps/share/man/man1/lzless.1 new file mode 120000 index 0000000..1b00a0a --- /dev/null +++ b/deps/share/man/man1/lzless.1 @@ -0,0 +1 @@ +xzless.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzma.1 b/deps/share/man/man1/lzma.1 new file mode 120000 index 0000000..01b6808 --- /dev/null +++ b/deps/share/man/man1/lzma.1 @@ -0,0 +1 @@ +xz.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzmadec.1 b/deps/share/man/man1/lzmadec.1 new file mode 120000 index 0000000..cd2223d --- /dev/null +++ b/deps/share/man/man1/lzmadec.1 @@ -0,0 +1 @@ +xzdec.1
\ No newline at end of file diff --git a/deps/share/man/man1/lzmainfo.1 b/deps/share/man/man1/lzmainfo.1 new file mode 100644 index 0000000..ce38eee --- /dev/null +++ b/deps/share/man/man1/lzmainfo.1 @@ -0,0 +1,60 @@ +.\" +.\" Author: Lasse Collin +.\" +.\" This file has been put into the public domain. +.\" You can do whatever you want with this file. +.\" +.TH LZMAINFO 1 "2013-06-30" "Tukaani" "XZ Utils" +.SH NAME +lzmainfo \- show information stored in the .lzma file header +.SH SYNOPSIS +.B lzmainfo +.RB [ \-\-help ] +.RB [ \-\-version ] +.RI [ file... ] +.SH DESCRIPTION +.B lzmainfo +shows information stored in the +.B .lzma +file header. +It reads the first 13 bytes from the specified +.IR file , +decodes the header, and prints it to standard output in human +readable format. +If no +.I files +are given or +.I file +is +.BR \- , +standard input is read. +.PP +Usually the most interesting information is +the uncompressed size and the dictionary size. +Uncompressed size can be shown only if +the file is in the non-streamed +.B .lzma +format variant. +The amount of memory required to decompress the file is +a few dozen kilobytes plus the dictionary size. +.PP +.B lzmainfo +is included in XZ Utils primarily for +backward compatibility with LZMA Utils. +.SH "EXIT STATUS" +.TP +.B 0 +All is good. +.TP +.B 1 +An error occurred. +.SH BUGS +.B lzmainfo +uses +.B MB +while the correct suffix would be +.B MiB +(2^20 bytes). +This is to keep the output compatible with LZMA Utils. +.SH "SEE ALSO" +.BR xz (1) diff --git a/deps/share/man/man1/lzmore.1 b/deps/share/man/man1/lzmore.1 new file mode 120000 index 0000000..341082b --- /dev/null +++ b/deps/share/man/man1/lzmore.1 @@ -0,0 +1 @@ +xzmore.1
\ No newline at end of file diff --git a/deps/share/man/man1/unlzma.1 b/deps/share/man/man1/unlzma.1 new file mode 120000 index 0000000..01b6808 --- /dev/null +++ b/deps/share/man/man1/unlzma.1 @@ -0,0 +1 @@ +xz.1
\ No newline at end of file diff --git a/deps/share/man/man1/unxz.1 b/deps/share/man/man1/unxz.1 new file mode 120000 index 0000000..01b6808 --- /dev/null +++ b/deps/share/man/man1/unxz.1 @@ -0,0 +1 @@ +xz.1
\ No newline at end of file diff --git a/deps/share/man/man1/xz.1 b/deps/share/man/man1/xz.1 new file mode 100644 index 0000000..540d136 --- /dev/null +++ b/deps/share/man/man1/xz.1 @@ -0,0 +1,2805 @@ +'\" t +.\" +.\" Author: Lasse Collin +.\" +.\" This file has been put into the public domain. +.\" You can do whatever you want with this file. +.\" +.TH XZ 1 "2020-02-01" "Tukaani" "XZ Utils" +. +.SH NAME +xz, unxz, xzcat, lzma, unlzma, lzcat \- Compress or decompress .xz and .lzma files +. +.SH SYNOPSIS +.B xz +.RI [ option... ] +.RI [ file... ] +. +.SH COMMAND ALIASES +.B unxz +is equivalent to +.BR "xz \-\-decompress" . +.br +.B xzcat +is equivalent to +.BR "xz \-\-decompress \-\-stdout" . +.br +.B lzma +is equivalent to +.BR "xz \-\-format=lzma" . +.br +.B unlzma +is equivalent to +.BR "xz \-\-format=lzma \-\-decompress" . +.br +.B lzcat +is equivalent to +.BR "xz \-\-format=lzma \-\-decompress \-\-stdout" . +.PP +When writing scripts that need to decompress files, +it is recommended to always use the name +.B xz +with appropriate arguments +.RB ( "xz \-d" +or +.BR "xz \-dc" ) +instead of the names +.B unxz +and +.BR xzcat . +. +.SH DESCRIPTION +.B xz +is a general-purpose data compression tool with +command line syntax similar to +.BR gzip (1) +and +.BR bzip2 (1). +The native file format is the +.B .xz +format, but the legacy +.B .lzma +format used by LZMA Utils and +raw compressed streams with no container format headers +are also supported. +.PP +.B xz +compresses or decompresses each +.I file +according to the selected operation mode. +If no +.I files +are given or +.I file +is +.BR \- , +.B xz +reads from standard input and writes the processed data +to standard output. +.B xz +will refuse (display an error and skip the +.IR file ) +to write compressed data to standard output if it is a terminal. +Similarly, +.B xz +will refuse to read compressed data +from standard input if it is a terminal. +.PP +Unless +.B \-\-stdout +is specified, +.I files +other than +.B \- +are written to a new file whose name is derived from the source +.I file +name: +.IP \(bu 3 +When compressing, the suffix of the target file format +.RB ( .xz +or +.BR .lzma ) +is appended to the source filename to get the target filename. +.IP \(bu 3 +When decompressing, the +.B .xz +or +.B .lzma +suffix is removed from the filename to get the target filename. +.B xz +also recognizes the suffixes +.B .txz +and +.BR .tlz , +and replaces them with the +.B .tar +suffix. +.PP +If the target file already exists, an error is displayed and the +.I file +is skipped. +.PP +Unless writing to standard output, +.B xz +will display a warning and skip the +.I file +if any of the following applies: +.IP \(bu 3 +.I File +is not a regular file. +Symbolic links are not followed, +and thus they are not considered to be regular files. +.IP \(bu 3 +.I File +has more than one hard link. +.IP \(bu 3 +.I File +has setuid, setgid, or sticky bit set. +.IP \(bu 3 +The operation mode is set to compress and the +.I file +already has a suffix of the target file format +.RB ( .xz +or +.B .txz +when compressing to the +.B .xz +format, and +.B .lzma +or +.B .tlz +when compressing to the +.B .lzma +format). +.IP \(bu 3 +The operation mode is set to decompress and the +.I file +doesn't have a suffix of any of the supported file formats +.RB ( .xz , +.BR .txz , +.BR .lzma , +or +.BR .tlz ). +.PP +After successfully compressing or decompressing the +.IR file , +.B xz +copies the owner, group, permissions, access time, +and modification time from the source +.I file +to the target file. +If copying the group fails, the permissions are modified +so that the target file doesn't become accessible to users +who didn't have permission to access the source +.IR file . +.B xz +doesn't support copying other metadata like access control lists +or extended attributes yet. +.PP +Once the target file has been successfully closed, the source +.I file +is removed unless +.B \-\-keep +was specified. +The source +.I file +is never removed if the output is written to standard output. +.PP +Sending +.B SIGINFO +or +.B SIGUSR1 +to the +.B xz +process makes it print progress information to standard error. +This has only limited use since when standard error +is a terminal, using +.B \-\-verbose +will display an automatically updating progress indicator. +. +.SS "Memory usage" +The memory usage of +.B xz +varies from a few hundred kilobytes to several gigabytes +depending on the compression settings. +The settings used when compressing a file determine +the memory requirements of the decompressor. +Typically the decompressor needs 5\ % to 20\ % of +the amount of memory that the compressor needed when +creating the file. +For example, decompressing a file created with +.B xz \-9 +currently requires 65\ MiB of memory. +Still, it is possible to have +.B .xz +files that require several gigabytes of memory to decompress. +.PP +Especially users of older systems may find +the possibility of very large memory usage annoying. +To prevent uncomfortable surprises, +.B xz +has a built-in memory usage limiter, which is disabled by default. +While some operating systems provide ways to limit +the memory usage of processes, relying on it +wasn't deemed to be flexible enough (e.g. using +.BR ulimit (1) +to limit virtual memory tends to cripple +.BR mmap (2)). +.PP +The memory usage limiter can be enabled with +the command line option \fB\-\-memlimit=\fIlimit\fR. +Often it is more convenient to enable the limiter +by default by setting the environment variable +.BR XZ_DEFAULTS , +e.g.\& +.BR XZ_DEFAULTS=\-\-memlimit=150MiB . +It is possible to set the limits separately +for compression and decompression +by using \fB\-\-memlimit\-compress=\fIlimit\fR and +\fB\-\-memlimit\-decompress=\fIlimit\fR. +Using these two options outside +.B XZ_DEFAULTS +is rarely useful because a single run of +.B xz +cannot do both compression and decompression and +.BI \-\-memlimit= limit +(or \fB\-M\fR \fIlimit\fR) +is shorter to type on the command line. +.PP +If the specified memory usage limit is exceeded when decompressing, +.B xz +will display an error and decompressing the file will fail. +If the limit is exceeded when compressing, +.B xz +will try to scale the settings down so that the limit +is no longer exceeded (except when using \fB\-\-format=raw\fR +or \fB\-\-no\-adjust\fR). +This way the operation won't fail unless the limit is very small. +The scaling of the settings is done in steps that don't +match the compression level presets, e.g. if the limit is +only slightly less than the amount required for +.BR "xz \-9" , +the settings will be scaled down only a little, +not all the way down to +.BR "xz \-8" . +. +.SS "Concatenation and padding with .xz files" +It is possible to concatenate +.B .xz +files as is. +.B xz +will decompress such files as if they were a single +.B .xz +file. +.PP +It is possible to insert padding between the concatenated parts +or after the last part. +The padding must consist of null bytes and the size +of the padding must be a multiple of four bytes. +This can be useful e.g. if the +.B .xz +file is stored on a medium that measures file sizes +in 512-byte blocks. +.PP +Concatenation and padding are not allowed with +.B .lzma +files or raw streams. +. +.SH OPTIONS +. +.SS "Integer suffixes and special values" +In most places where an integer argument is expected, +an optional suffix is supported to easily indicate large integers. +There must be no space between the integer and the suffix. +.TP +.B KiB +Multiply the integer by 1,024 (2^10). +.BR Ki , +.BR k , +.BR kB , +.BR K , +and +.B KB +are accepted as synonyms for +.BR KiB . +.TP +.B MiB +Multiply the integer by 1,048,576 (2^20). +.BR Mi , +.BR m , +.BR M , +and +.B MB +are accepted as synonyms for +.BR MiB . +.TP +.B GiB +Multiply the integer by 1,073,741,824 (2^30). +.BR Gi , +.BR g , +.BR G , +and +.B GB +are accepted as synonyms for +.BR GiB . +.PP +The special value +.B max +can be used to indicate the maximum integer value +supported by the option. +. +.SS "Operation mode" +If multiple operation mode options are given, +the last one takes effect. +.TP +.BR \-z ", " \-\-compress +Compress. +This is the default operation mode when no operation mode option +is specified and no other operation mode is implied from +the command name (for example, +.B unxz +implies +.BR \-\-decompress ). +.TP +.BR \-d ", " \-\-decompress ", " \-\-uncompress +Decompress. +.TP +.BR \-t ", " \-\-test +Test the integrity of compressed +.IR files . +This option is equivalent to +.B "\-\-decompress \-\-stdout" +except that the decompressed data is discarded instead of being +written to standard output. +No files are created or removed. +.TP +.BR \-l ", " \-\-list +Print information about compressed +.IR files . +No uncompressed output is produced, +and no files are created or removed. +In list mode, the program cannot read +the compressed data from standard +input or from other unseekable sources. +.IP "" +The default listing shows basic information about +.IR files , +one file per line. +To get more detailed information, use also the +.B \-\-verbose +option. +For even more information, use +.B \-\-verbose +twice, but note that this may be slow, because getting all the extra +information requires many seeks. +The width of verbose output exceeds +80 characters, so piping the output to e.g.\& +.B "less\ \-S" +may be convenient if the terminal isn't wide enough. +.IP "" +The exact output may vary between +.B xz +versions and different locales. +For machine-readable output, +.B \-\-robot \-\-list +should be used. +. +.SS "Operation modifiers" +.TP +.BR \-k ", " \-\-keep +Don't delete the input files. +.TP +.BR \-f ", " \-\-force +This option has several effects: +.RS +.IP \(bu 3 +If the target file already exists, +delete it before compressing or decompressing. +.IP \(bu 3 +Compress or decompress even if the input is +a symbolic link to a regular file, +has more than one hard link, +or has the setuid, setgid, or sticky bit set. +The setuid, setgid, and sticky bits are not copied +to the target file. +.IP \(bu 3 +When used with +.B \-\-decompress +.BR \-\-stdout +and +.B xz +cannot recognize the type of the source file, +copy the source file as is to standard output. +This allows +.B xzcat +.B \-\-force +to be used like +.BR cat (1) +for files that have not been compressed with +.BR xz . +Note that in future, +.B xz +might support new compressed file formats, which may make +.B xz +decompress more types of files instead of copying them as is to +standard output. +.BI \-\-format= format +can be used to restrict +.B xz +to decompress only a single file format. +.RE +.TP +.BR \-c ", " \-\-stdout ", " \-\-to\-stdout +Write the compressed or decompressed data to +standard output instead of a file. +This implies +.BR \-\-keep . +.TP +.B \-\-single\-stream +Decompress only the first +.B .xz +stream, and +silently ignore possible remaining input data following the stream. +Normally such trailing garbage makes +.B xz +display an error. +.IP "" +.B xz +never decompresses more than one stream from +.B .lzma +files or raw streams, but this option still makes +.B xz +ignore the possible trailing data after the +.B .lzma +file or raw stream. +.IP "" +This option has no effect if the operation mode is not +.B \-\-decompress +or +.BR \-\-test . +.TP +.B \-\-no\-sparse +Disable creation of sparse files. +By default, if decompressing into a regular file, +.B xz +tries to make the file sparse if the decompressed data contains +long sequences of binary zeros. +It also works when writing to standard output +as long as standard output is connected to a regular file +and certain additional conditions are met to make it safe. +Creating sparse files may save disk space and speed up +the decompression by reducing the amount of disk I/O. +.TP +\fB\-S\fR \fI.suf\fR, \fB\-\-suffix=\fI.suf +When compressing, use +.I .suf +as the suffix for the target file instead of +.B .xz +or +.BR .lzma . +If not writing to standard output and +the source file already has the suffix +.IR .suf , +a warning is displayed and the file is skipped. +.IP "" +When decompressing, recognize files with the suffix +.I .suf +in addition to files with the +.BR .xz , +.BR .txz , +.BR .lzma , +or +.B .tlz +suffix. +If the source file has the suffix +.IR .suf , +the suffix is removed to get the target filename. +.IP "" +When compressing or decompressing raw streams +.RB ( \-\-format=raw ), +the suffix must always be specified unless +writing to standard output, +because there is no default suffix for raw streams. +.TP +\fB\-\-files\fR[\fB=\fIfile\fR] +Read the filenames to process from +.IR file ; +if +.I file +is omitted, filenames are read from standard input. +Filenames must be terminated with the newline character. +A dash +.RB ( \- ) +is taken as a regular filename; it doesn't mean standard input. +If filenames are given also as command line arguments, they are +processed before the filenames read from +.IR file . +.TP +\fB\-\-files0\fR[\fB=\fIfile\fR] +This is identical to \fB\-\-files\fR[\fB=\fIfile\fR] except +that each filename must be terminated with the null character. +. +.SS "Basic file format and compression options" +.TP +\fB\-F\fR \fIformat\fR, \fB\-\-format=\fIformat +Specify the file +.I format +to compress or decompress: +.RS +.TP +.B auto +This is the default. +When compressing, +.B auto +is equivalent to +.BR xz . +When decompressing, +the format of the input file is automatically detected. +Note that raw streams (created with +.BR \-\-format=raw ) +cannot be auto-detected. +.TP +.B xz +Compress to the +.B .xz +file format, or accept only +.B .xz +files when decompressing. +.TP +.BR lzma ", " alone +Compress to the legacy +.B .lzma +file format, or accept only +.B .lzma +files when decompressing. +The alternative name +.B alone +is provided for backwards compatibility with LZMA Utils. +.TP +.B raw +Compress or uncompress a raw stream (no headers). +This is meant for advanced users only. +To decode raw streams, you need use +.B \-\-format=raw +and explicitly specify the filter chain, +which normally would have been stored in the container headers. +.RE +.TP +\fB\-C\fR \fIcheck\fR, \fB\-\-check=\fIcheck +Specify the type of the integrity check. +The check is calculated from the uncompressed data and +stored in the +.B .xz +file. +This option has an effect only when compressing into the +.B .xz +format; the +.B .lzma +format doesn't support integrity checks. +The integrity check (if any) is verified when the +.B .xz +file is decompressed. +.IP "" +Supported +.I check +types: +.RS +.TP +.B none +Don't calculate an integrity check at all. +This is usually a bad idea. +This can be useful when integrity of the data is verified +by other means anyway. +.TP +.B crc32 +Calculate CRC32 using the polynomial from IEEE-802.3 (Ethernet). +.TP +.B crc64 +Calculate CRC64 using the polynomial from ECMA-182. +This is the default, since it is slightly better than CRC32 +at detecting damaged files and the speed difference is negligible. +.TP +.B sha256 +Calculate SHA-256. +This is somewhat slower than CRC32 and CRC64. +.RE +.IP "" +Integrity of the +.B .xz +headers is always verified with CRC32. +It is not possible to change or disable it. +.TP +.B \-\-ignore\-check +Don't verify the integrity check of the compressed data when decompressing. +The CRC32 values in the +.B .xz +headers will still be verified normally. +.IP "" +.B "Do not use this option unless you know what you are doing." +Possible reasons to use this option: +.RS +.IP \(bu 3 +Trying to recover data from a corrupt .xz file. +.IP \(bu 3 +Speeding up decompression. +This matters mostly with SHA-256 or +with files that have compressed extremely well. +It's recommended to not use this option for this purpose +unless the file integrity is verified externally in some other way. +.RE +.TP +.BR \-0 " ... " \-9 +Select a compression preset level. +The default is +.BR \-6 . +If multiple preset levels are specified, +the last one takes effect. +If a custom filter chain was already specified, setting +a compression preset level clears the custom filter chain. +.IP "" +The differences between the presets are more significant than with +.BR gzip (1) +and +.BR bzip2 (1). +The selected compression settings determine +the memory requirements of the decompressor, +thus using a too high preset level might make it painful +to decompress the file on an old system with little RAM. +Specifically, +.B "it's not a good idea to blindly use \-9 for everything" +like it often is with +.BR gzip (1) +and +.BR bzip2 (1). +.RS +.TP +.BR "\-0" " ... " "\-3" +These are somewhat fast presets. +.B \-0 +is sometimes faster than +.B "gzip \-9" +while compressing much better. +The higher ones often have speed comparable to +.BR bzip2 (1) +with comparable or better compression ratio, +although the results +depend a lot on the type of data being compressed. +.TP +.BR "\-4" " ... " "\-6" +Good to very good compression while keeping +decompressor memory usage reasonable even for old systems. +.B \-6 +is the default, which is usually a good choice +e.g. for distributing files that need to be decompressible +even on systems with only 16\ MiB RAM. +.RB ( \-5e +or +.B \-6e +may be worth considering too. +See +.BR \-\-extreme .) +.TP +.B "\-7 ... \-9" +These are like +.B \-6 +but with higher compressor and decompressor memory requirements. +These are useful only when compressing files bigger than +8\ MiB, 16\ MiB, and 32\ MiB, respectively. +.RE +.IP "" +On the same hardware, the decompression speed is approximately +a constant number of bytes of compressed data per second. +In other words, the better the compression, +the faster the decompression will usually be. +This also means that the amount of uncompressed output +produced per second can vary a lot. +.IP "" +The following table summarises the features of the presets: +.RS +.RS +.PP +.TS +tab(;); +c c c c c +n n n n n. +Preset;DictSize;CompCPU;CompMem;DecMem +\-0;256 KiB;0;3 MiB;1 MiB +\-1;1 MiB;1;9 MiB;2 MiB +\-2;2 MiB;2;17 MiB;3 MiB +\-3;4 MiB;3;32 MiB;5 MiB +\-4;4 MiB;4;48 MiB;5 MiB +\-5;8 MiB;5;94 MiB;9 MiB +\-6;8 MiB;6;94 MiB;9 MiB +\-7;16 MiB;6;186 MiB;17 MiB +\-8;32 MiB;6;370 MiB;33 MiB +\-9;64 MiB;6;674 MiB;65 MiB +.TE +.RE +.RE +.IP "" +Column descriptions: +.RS +.IP \(bu 3 +DictSize is the LZMA2 dictionary size. +It is waste of memory to use a dictionary bigger than +the size of the uncompressed file. +This is why it is good to avoid using the presets +.BR \-7 " ... " \-9 +when there's no real need for them. +At +.B \-6 +and lower, the amount of memory wasted is +usually low enough to not matter. +.IP \(bu 3 +CompCPU is a simplified representation of the LZMA2 settings +that affect compression speed. +The dictionary size affects speed too, +so while CompCPU is the same for levels +.BR \-6 " ... " \-9 , +higher levels still tend to be a little slower. +To get even slower and thus possibly better compression, see +.BR \-\-extreme . +.IP \(bu 3 +CompMem contains the compressor memory requirements +in the single-threaded mode. +It may vary slightly between +.B xz +versions. +Memory requirements of some of the future multithreaded modes may +be dramatically higher than that of the single-threaded mode. +.IP \(bu 3 +DecMem contains the decompressor memory requirements. +That is, the compression settings determine +the memory requirements of the decompressor. +The exact decompressor memory usage is slightly more than +the LZMA2 dictionary size, but the values in the table +have been rounded up to the next full MiB. +.RE +.TP +.BR \-e ", " \-\-extreme +Use a slower variant of the selected compression preset level +.RB ( \-0 " ... " \-9 ) +to hopefully get a little bit better compression ratio, +but with bad luck this can also make it worse. +Decompressor memory usage is not affected, +but compressor memory usage increases a little at preset levels +.BR \-0 " ... " \-3 . +.IP "" +Since there are two presets with dictionary sizes +4\ MiB and 8\ MiB, the presets +.B \-3e +and +.B \-5e +use slightly faster settings (lower CompCPU) than +.B \-4e +and +.BR \-6e , +respectively. +That way no two presets are identical. +.RS +.RS +.PP +.TS +tab(;); +c c c c c +n n n n n. +Preset;DictSize;CompCPU;CompMem;DecMem +\-0e;256 KiB;8;4 MiB;1 MiB +\-1e;1 MiB;8;13 MiB;2 MiB +\-2e;2 MiB;8;25 MiB;3 MiB +\-3e;4 MiB;7;48 MiB;5 MiB +\-4e;4 MiB;8;48 MiB;5 MiB +\-5e;8 MiB;7;94 MiB;9 MiB +\-6e;8 MiB;8;94 MiB;9 MiB +\-7e;16 MiB;8;186 MiB;17 MiB +\-8e;32 MiB;8;370 MiB;33 MiB +\-9e;64 MiB;8;674 MiB;65 MiB +.TE +.RE +.RE +.IP "" +For example, there are a total of four presets that use +8\ MiB dictionary, whose order from the fastest to the slowest is +.BR \-5 , +.BR \-6 , +.BR \-5e , +and +.BR \-6e . +.TP +.B \-\-fast +.PD 0 +.TP +.B \-\-best +.PD +These are somewhat misleading aliases for +.B \-0 +and +.BR \-9 , +respectively. +These are provided only for backwards compatibility +with LZMA Utils. +Avoid using these options. +.TP +.BI \-\-block\-size= size +When compressing to the +.B .xz +format, split the input data into blocks of +.I size +bytes. +The blocks are compressed independently from each other, +which helps with multi-threading and +makes limited random-access decompression possible. +This option is typically used to override the default +block size in multi-threaded mode, +but this option can be used in single-threaded mode too. +.IP "" +In multi-threaded mode about three times +.I size +bytes will be allocated in each thread for buffering input and output. +The default +.I size +is three times the LZMA2 dictionary size or 1 MiB, +whichever is more. +Typically a good value is 2\-4 times +the size of the LZMA2 dictionary or at least 1 MiB. +Using +.I size +less than the LZMA2 dictionary size is waste of RAM +because then the LZMA2 dictionary buffer will never get fully used. +The sizes of the blocks are stored in the block headers, +which a future version of +.B xz +will use for multi-threaded decompression. +.IP "" +In single-threaded mode no block splitting is done by default. +Setting this option doesn't affect memory usage. +No size information is stored in block headers, +thus files created in single-threaded mode +won't be identical to files created in multi-threaded mode. +The lack of size information also means that a future version of +.B xz +won't be able decompress the files in multi-threaded mode. +.TP +.BI \-\-block\-list= sizes +When compressing to the +.B .xz +format, start a new block after +the given intervals of uncompressed data. +.IP "" +The uncompressed +.I sizes +of the blocks are specified as a comma-separated list. +Omitting a size (two or more consecutive commas) is a shorthand +to use the size of the previous block. +.IP "" +If the input file is bigger than the sum of +.IR sizes , +the last value in +.I sizes +is repeated until the end of the file. +A special value of +.B 0 +may be used as the last value to indicate that +the rest of the file should be encoded as a single block. +.IP "" +If one specifies +.I sizes +that exceed the encoder's block size +(either the default value in threaded mode or +the value specified with \fB\-\-block\-size=\fIsize\fR), +the encoder will create additional blocks while +keeping the boundaries specified in +.IR sizes . +For example, if one specifies +.B \-\-block\-size=10MiB +.B \-\-block\-list=5MiB,10MiB,8MiB,12MiB,24MiB +and the input file is 80 MiB, +one will get 11 blocks: +5, 10, 8, 10, 2, 10, 10, 4, 10, 10, and 1 MiB. +.IP "" +In multi-threaded mode the sizes of the blocks +are stored in the block headers. +This isn't done in single-threaded mode, +so the encoded output won't be +identical to that of the multi-threaded mode. +.TP +.BI \-\-flush\-timeout= timeout +When compressing, if more than +.I timeout +milliseconds (a positive integer) has passed since the previous flush and +reading more input would block, +all the pending input data is flushed from the encoder and +made available in the output stream. +This can be useful if +.B xz +is used to compress data that is streamed over a network. +Small +.I timeout +values make the data available at the receiving end +with a small delay, but large +.I timeout +values give better compression ratio. +.IP "" +This feature is disabled by default. +If this option is specified more than once, the last one takes effect. +The special +.I timeout +value of +.B 0 +can be used to explicitly disable this feature. +.IP "" +This feature is not available on non-POSIX systems. +.IP "" +.\" FIXME +.B "This feature is still experimental." +Currently +.B xz +is unsuitable for decompressing the stream in real time due to how +.B xz +does buffering. +.TP +.BI \-\-memlimit\-compress= limit +Set a memory usage limit for compression. +If this option is specified multiple times, +the last one takes effect. +.IP "" +If the compression settings exceed the +.IR limit , +.B xz +will adjust the settings downwards so that +the limit is no longer exceeded and display a notice that +automatic adjustment was done. +Such adjustments are not made when compressing with +.B \-\-format=raw +or if +.B \-\-no\-adjust +has been specified. +In those cases, an error is displayed and +.B xz +will exit with exit status 1. +.IP "" +The +.I limit +can be specified in multiple ways: +.RS +.IP \(bu 3 +The +.I limit +can be an absolute value in bytes. +Using an integer suffix like +.B MiB +can be useful. +Example: +.B "\-\-memlimit\-compress=80MiB" +.IP \(bu 3 +The +.I limit +can be specified as a percentage of total physical memory (RAM). +This can be useful especially when setting the +.B XZ_DEFAULTS +environment variable in a shell initialization script +that is shared between different computers. +That way the limit is automatically bigger +on systems with more memory. +Example: +.B "\-\-memlimit\-compress=70%" +.IP \(bu 3 +The +.I limit +can be reset back to its default value by setting it to +.BR 0 . +This is currently equivalent to setting the +.I limit +to +.B max +(no memory usage limit). +Once multithreading support has been implemented, +there may be a difference between +.B 0 +and +.B max +for the multithreaded case, so it is recommended to use +.B 0 +instead of +.B max +until the details have been decided. +.RE +.IP "" +For 32-bit +.BR xz +there is a special case: if the +.I limit +would be over +.BR "4020\ MiB" , +the +.I limit +is set to +.BR "4020\ MiB" . +(The values +.B 0 +and +.B max +aren't affected by this. +A similar feature doesn't exist for decompression.) +This can be helpful when a 32-bit executable has access +to 4\ GiB address space while hopefully doing no harm in other situations. +.IP "" +See also the section +.BR "Memory usage" . +.TP +.BI \-\-memlimit\-decompress= limit +Set a memory usage limit for decompression. +This also affects the +.B \-\-list +mode. +If the operation is not possible without exceeding the +.IR limit , +.B xz +will display an error and decompressing the file will fail. +See +.BI \-\-memlimit\-compress= limit +for possible ways to specify the +.IR limit . +.TP +\fB\-M\fR \fIlimit\fR, \fB\-\-memlimit=\fIlimit\fR, \fB\-\-memory=\fIlimit +This is equivalent to specifying \fB\-\-memlimit\-compress=\fIlimit +\fB\-\-memlimit\-decompress=\fIlimit\fR. +.TP +.B \-\-no\-adjust +Display an error and exit if the compression settings exceed +the memory usage limit. +The default is to adjust the settings downwards so +that the memory usage limit is not exceeded. +Automatic adjusting is always disabled when creating raw streams +.RB ( \-\-format=raw ). +.TP +\fB\-T\fR \fIthreads\fR, \fB\-\-threads=\fIthreads +Specify the number of worker threads to use. +Setting +.I threads +to a special value +.B 0 +makes +.B xz +use as many threads as there are CPU cores on the system. +The actual number of threads can be less than +.I threads +if the input file is not big enough +for threading with the given settings or +if using more threads would exceed the memory usage limit. +.IP "" +Currently the only threading method is to split the input into +blocks and compress them independently from each other. +The default block size depends on the compression level and +can be overridden with the +.BI \-\-block\-size= size +option. +.IP "" +Threaded decompression hasn't been implemented yet. +It will only work on files that contain multiple blocks +with size information in block headers. +All files compressed in multi-threaded mode meet this condition, +but files compressed in single-threaded mode don't even if +.BI \-\-block\-size= size +is used. +. +.SS "Custom compressor filter chains" +A custom filter chain allows specifying +the compression settings in detail instead of relying on +the settings associated to the presets. +When a custom filter chain is specified, +preset options (\fB\-0\fR ... \fB\-9\fR and \fB\-\-extreme\fR) +earlier on the command line are forgotten. +If a preset option is specified +after one or more custom filter chain options, +the new preset takes effect and +the custom filter chain options specified earlier are forgotten. +.PP +A filter chain is comparable to piping on the command line. +When compressing, the uncompressed input goes to the first filter, +whose output goes to the next filter (if any). +The output of the last filter gets written to the compressed file. +The maximum number of filters in the chain is four, +but typically a filter chain has only one or two filters. +.PP +Many filters have limitations on where they can be +in the filter chain: +some filters can work only as the last filter in the chain, +some only as a non-last filter, and some work in any position +in the chain. +Depending on the filter, this limitation is either inherent to +the filter design or exists to prevent security issues. +.PP +A custom filter chain is specified by using one or more +filter options in the order they are wanted in the filter chain. +That is, the order of filter options is significant! +When decoding raw streams +.RB ( \-\-format=raw ), +the filter chain is specified in the same order as +it was specified when compressing. +.PP +Filters take filter-specific +.I options +as a comma-separated list. +Extra commas in +.I options +are ignored. +Every option has a default value, so you need to +specify only those you want to change. +.PP +To see the whole filter chain and +.IR options , +use +.B "xz \-vv" +(that is, use +.B \-\-verbose +twice). +This works also for viewing the filter chain options used by presets. +.TP +\fB\-\-lzma1\fR[\fB=\fIoptions\fR] +.PD 0 +.TP +\fB\-\-lzma2\fR[\fB=\fIoptions\fR] +.PD +Add LZMA1 or LZMA2 filter to the filter chain. +These filters can be used only as the last filter in the chain. +.IP "" +LZMA1 is a legacy filter, +which is supported almost solely due to the legacy +.B .lzma +file format, which supports only LZMA1. +LZMA2 is an updated +version of LZMA1 to fix some practical issues of LZMA1. +The +.B .xz +format uses LZMA2 and doesn't support LZMA1 at all. +Compression speed and ratios of LZMA1 and LZMA2 +are practically the same. +.IP "" +LZMA1 and LZMA2 share the same set of +.IR options : +.RS +.TP +.BI preset= preset +Reset all LZMA1 or LZMA2 +.I options +to +.IR preset . +.I Preset +consist of an integer, which may be followed by single-letter +preset modifiers. +The integer can be from +.B 0 +to +.BR 9 , +matching the command line options \fB\-0\fR ... \fB\-9\fR. +The only supported modifier is currently +.BR e , +which matches +.BR \-\-extreme . +If no +.B preset +is specified, the default values of LZMA1 or LZMA2 +.I options +are taken from the preset +.BR 6 . +.TP +.BI dict= size +Dictionary (history buffer) +.I size +indicates how many bytes of the recently processed +uncompressed data is kept in memory. +The algorithm tries to find repeating byte sequences (matches) in +the uncompressed data, and replace them with references +to the data currently in the dictionary. +The bigger the dictionary, the higher is the chance +to find a match. +Thus, increasing dictionary +.I size +usually improves compression ratio, but +a dictionary bigger than the uncompressed file is waste of memory. +.IP "" +Typical dictionary +.I size +is from 64\ KiB to 64\ MiB. +The minimum is 4\ KiB. +The maximum for compression is currently 1.5\ GiB (1536\ MiB). +The decompressor already supports dictionaries up to +one byte less than 4\ GiB, which is the maximum for +the LZMA1 and LZMA2 stream formats. +.IP "" +Dictionary +.I size +and match finder +.RI ( mf ) +together determine the memory usage of the LZMA1 or LZMA2 encoder. +The same (or bigger) dictionary +.I size +is required for decompressing that was used when compressing, +thus the memory usage of the decoder is determined +by the dictionary size used when compressing. +The +.B .xz +headers store the dictionary +.I size +either as +.RI "2^" n +or +.RI "2^" n " + 2^(" n "\-1)," +so these +.I sizes +are somewhat preferred for compression. +Other +.I sizes +will get rounded up when stored in the +.B .xz +headers. +.TP +.BI lc= lc +Specify the number of literal context bits. +The minimum is 0 and the maximum is 4; the default is 3. +In addition, the sum of +.I lc +and +.I lp +must not exceed 4. +.IP "" +All bytes that cannot be encoded as matches +are encoded as literals. +That is, literals are simply 8-bit bytes +that are encoded one at a time. +.IP "" +The literal coding makes an assumption that the highest +.I lc +bits of the previous uncompressed byte correlate +with the next byte. +E.g. in typical English text, an upper-case letter is +often followed by a lower-case letter, and a lower-case +letter is usually followed by another lower-case letter. +In the US-ASCII character set, the highest three bits are 010 +for upper-case letters and 011 for lower-case letters. +When +.I lc +is at least 3, the literal coding can take advantage of +this property in the uncompressed data. +.IP "" +The default value (3) is usually good. +If you want maximum compression, test +.BR lc=4 . +Sometimes it helps a little, and +sometimes it makes compression worse. +If it makes it worse, test e.g.\& +.B lc=2 +too. +.TP +.BI lp= lp +Specify the number of literal position bits. +The minimum is 0 and the maximum is 4; the default is 0. +.IP "" +.I Lp +affects what kind of alignment in the uncompressed data is +assumed when encoding literals. +See +.I pb +below for more information about alignment. +.TP +.BI pb= pb +Specify the number of position bits. +The minimum is 0 and the maximum is 4; the default is 2. +.IP "" +.I Pb +affects what kind of alignment in the uncompressed data is +assumed in general. +The default means four-byte alignment +.RI (2^ pb =2^2=4), +which is often a good choice when there's no better guess. +.IP "" +When the aligment is known, setting +.I pb +accordingly may reduce the file size a little. +E.g. with text files having one-byte +alignment (US-ASCII, ISO-8859-*, UTF-8), setting +.B pb=0 +can improve compression slightly. +For UTF-16 text, +.B pb=1 +is a good choice. +If the alignment is an odd number like 3 bytes, +.B pb=0 +might be the best choice. +.IP "" +Even though the assumed alignment can be adjusted with +.I pb +and +.IR lp , +LZMA1 and LZMA2 still slightly favor 16-byte alignment. +It might be worth taking into account when designing file formats +that are likely to be often compressed with LZMA1 or LZMA2. +.TP +.BI mf= mf +Match finder has a major effect on encoder speed, +memory usage, and compression ratio. +Usually Hash Chain match finders are faster than Binary Tree +match finders. +The default depends on the +.IR preset : +0 uses +.BR hc3 , +1\-3 +use +.BR hc4 , +and the rest use +.BR bt4 . +.IP "" +The following match finders are supported. +The memory usage formulas below are rough approximations, +which are closest to the reality when +.I dict +is a power of two. +.RS +.TP +.B hc3 +Hash Chain with 2- and 3-byte hashing +.br +Minimum value for +.IR nice : +3 +.br +Memory usage: +.br +.I dict +* 7.5 (if +.I dict +<= 16 MiB); +.br +.I dict +* 5.5 + 64 MiB (if +.I dict +> 16 MiB) +.TP +.B hc4 +Hash Chain with 2-, 3-, and 4-byte hashing +.br +Minimum value for +.IR nice : +4 +.br +Memory usage: +.br +.I dict +* 7.5 (if +.I dict +<= 32 MiB); +.br +.I dict +* 6.5 (if +.I dict +> 32 MiB) +.TP +.B bt2 +Binary Tree with 2-byte hashing +.br +Minimum value for +.IR nice : +2 +.br +Memory usage: +.I dict +* 9.5 +.TP +.B bt3 +Binary Tree with 2- and 3-byte hashing +.br +Minimum value for +.IR nice : +3 +.br +Memory usage: +.br +.I dict +* 11.5 (if +.I dict +<= 16 MiB); +.br +.I dict +* 9.5 + 64 MiB (if +.I dict +> 16 MiB) +.TP +.B bt4 +Binary Tree with 2-, 3-, and 4-byte hashing +.br +Minimum value for +.IR nice : +4 +.br +Memory usage: +.br +.I dict +* 11.5 (if +.I dict +<= 32 MiB); +.br +.I dict +* 10.5 (if +.I dict +> 32 MiB) +.RE +.TP +.BI mode= mode +Compression +.I mode +specifies the method to analyze +the data produced by the match finder. +Supported +.I modes +are +.B fast +and +.BR normal . +The default is +.B fast +for +.I presets +0\-3 and +.B normal +for +.I presets +4\-9. +.IP "" +Usually +.B fast +is used with Hash Chain match finders and +.B normal +with Binary Tree match finders. +This is also what the +.I presets +do. +.TP +.BI nice= nice +Specify what is considered to be a nice length for a match. +Once a match of at least +.I nice +bytes is found, the algorithm stops +looking for possibly better matches. +.IP "" +.I Nice +can be 2\-273 bytes. +Higher values tend to give better compression ratio +at the expense of speed. +The default depends on the +.IR preset . +.TP +.BI depth= depth +Specify the maximum search depth in the match finder. +The default is the special value of 0, +which makes the compressor determine a reasonable +.I depth +from +.I mf +and +.IR nice . +.IP "" +Reasonable +.I depth +for Hash Chains is 4\-100 and 16\-1000 for Binary Trees. +Using very high values for +.I depth +can make the encoder extremely slow with some files. +Avoid setting the +.I depth +over 1000 unless you are prepared to interrupt +the compression in case it is taking far too long. +.RE +.IP "" +When decoding raw streams +.RB ( \-\-format=raw ), +LZMA2 needs only the dictionary +.IR size . +LZMA1 needs also +.IR lc , +.IR lp , +and +.IR pb . +.TP +\fB\-\-x86\fR[\fB=\fIoptions\fR] +.PD 0 +.TP +\fB\-\-powerpc\fR[\fB=\fIoptions\fR] +.TP +\fB\-\-ia64\fR[\fB=\fIoptions\fR] +.TP +\fB\-\-arm\fR[\fB=\fIoptions\fR] +.TP +\fB\-\-armthumb\fR[\fB=\fIoptions\fR] +.TP +\fB\-\-sparc\fR[\fB=\fIoptions\fR] +.PD +Add a branch/call/jump (BCJ) filter to the filter chain. +These filters can be used only as a non-last filter +in the filter chain. +.IP "" +A BCJ filter converts relative addresses in +the machine code to their absolute counterparts. +This doesn't change the size of the data, +but it increases redundancy, +which can help LZMA2 to produce 0\-15\ % smaller +.B .xz +file. +The BCJ filters are always reversible, +so using a BCJ filter for wrong type of data +doesn't cause any data loss, although it may make +the compression ratio slightly worse. +.IP "" +It is fine to apply a BCJ filter on a whole executable; +there's no need to apply it only on the executable section. +Applying a BCJ filter on an archive that contains both executable +and non-executable files may or may not give good results, +so it generally isn't good to blindly apply a BCJ filter when +compressing binary packages for distribution. +.IP "" +These BCJ filters are very fast and +use insignificant amount of memory. +If a BCJ filter improves compression ratio of a file, +it can improve decompression speed at the same time. +This is because, on the same hardware, +the decompression speed of LZMA2 is roughly +a fixed number of bytes of compressed data per second. +.IP "" +These BCJ filters have known problems related to +the compression ratio: +.RS +.IP \(bu 3 +Some types of files containing executable code +(e.g. object files, static libraries, and Linux kernel modules) +have the addresses in the instructions filled with filler values. +These BCJ filters will still do the address conversion, +which will make the compression worse with these files. +.IP \(bu 3 +Applying a BCJ filter on an archive containing multiple similar +executables can make the compression ratio worse than not using +a BCJ filter. +This is because the BCJ filter doesn't detect the boundaries +of the executable files, and doesn't reset +the address conversion counter for each executable. +.RE +.IP "" +Both of the above problems will be fixed +in the future in a new filter. +The old BCJ filters will still be useful in embedded systems, +because the decoder of the new filter will be bigger +and use more memory. +.IP "" +Different instruction sets have different alignment: +.RS +.RS +.PP +.TS +tab(;); +l n l +l n l. +Filter;Alignment;Notes +x86;1;32-bit or 64-bit x86 +PowerPC;4;Big endian only +ARM;4;Little endian only +ARM-Thumb;2;Little endian only +IA-64;16;Big or little endian +SPARC;4;Big or little endian +.TE +.RE +.RE +.IP "" +Since the BCJ-filtered data is usually compressed with LZMA2, +the compression ratio may be improved slightly if +the LZMA2 options are set to match the +alignment of the selected BCJ filter. +For example, with the IA-64 filter, it's good to set +.B pb=4 +with LZMA2 (2^4=16). +The x86 filter is an exception; +it's usually good to stick to LZMA2's default +four-byte alignment when compressing x86 executables. +.IP "" +All BCJ filters support the same +.IR options : +.RS +.TP +.BI start= offset +Specify the start +.I offset +that is used when converting between relative +and absolute addresses. +The +.I offset +must be a multiple of the alignment of the filter +(see the table above). +The default is zero. +In practice, the default is good; specifying a custom +.I offset +is almost never useful. +.RE +.TP +\fB\-\-delta\fR[\fB=\fIoptions\fR] +Add the Delta filter to the filter chain. +The Delta filter can be only used as a non-last filter +in the filter chain. +.IP "" +Currently only simple byte-wise delta calculation is supported. +It can be useful when compressing e.g. uncompressed bitmap images +or uncompressed PCM audio. +However, special purpose algorithms may give significantly better +results than Delta + LZMA2. +This is true especially with audio, +which compresses faster and better e.g. with +.BR flac (1). +.IP "" +Supported +.IR options : +.RS +.TP +.BI dist= distance +Specify the +.I distance +of the delta calculation in bytes. +.I distance +must be 1\-256. +The default is 1. +.IP "" +For example, with +.B dist=2 +and eight-byte input A1 B1 A2 B3 A3 B5 A4 B7, the output will be +A1 B1 01 02 01 02 01 02. +.RE +. +.SS "Other options" +.TP +.BR \-q ", " \-\-quiet +Suppress warnings and notices. +Specify this twice to suppress errors too. +This option has no effect on the exit status. +That is, even if a warning was suppressed, +the exit status to indicate a warning is still used. +.TP +.BR \-v ", " \-\-verbose +Be verbose. +If standard error is connected to a terminal, +.B xz +will display a progress indicator. +Specifying +.B \-\-verbose +twice will give even more verbose output. +.IP "" +The progress indicator shows the following information: +.RS +.IP \(bu 3 +Completion percentage is shown +if the size of the input file is known. +That is, the percentage cannot be shown in pipes. +.IP \(bu 3 +Amount of compressed data produced (compressing) +or consumed (decompressing). +.IP \(bu 3 +Amount of uncompressed data consumed (compressing) +or produced (decompressing). +.IP \(bu 3 +Compression ratio, which is calculated by dividing +the amount of compressed data processed so far by +the amount of uncompressed data processed so far. +.IP \(bu 3 +Compression or decompression speed. +This is measured as the amount of uncompressed data consumed +(compression) or produced (decompression) per second. +It is shown after a few seconds have passed since +.B xz +started processing the file. +.IP \(bu 3 +Elapsed time in the format M:SS or H:MM:SS. +.IP \(bu 3 +Estimated remaining time is shown +only when the size of the input file is +known and a couple of seconds have already passed since +.B xz +started processing the file. +The time is shown in a less precise format which +never has any colons, e.g. 2 min 30 s. +.RE +.IP "" +When standard error is not a terminal, +.B \-\-verbose +will make +.B xz +print the filename, compressed size, uncompressed size, +compression ratio, and possibly also the speed and elapsed time +on a single line to standard error after compressing or +decompressing the file. +The speed and elapsed time are included only when +the operation took at least a few seconds. +If the operation didn't finish, e.g. due to user interruption, +also the completion percentage is printed +if the size of the input file is known. +.TP +.BR \-Q ", " \-\-no\-warn +Don't set the exit status to 2 +even if a condition worth a warning was detected. +This option doesn't affect the verbosity level, thus both +.B \-\-quiet +and +.B \-\-no\-warn +have to be used to not display warnings and +to not alter the exit status. +.TP +.B \-\-robot +Print messages in a machine-parsable format. +This is intended to ease writing frontends that want to use +.B xz +instead of liblzma, which may be the case with various scripts. +The output with this option enabled is meant to be stable across +.B xz +releases. +See the section +.B "ROBOT MODE" +for details. +.TP +.BR \-\-info\-memory +Display, in human-readable format, how much physical memory (RAM) +.B xz +thinks the system has and the memory usage limits for compression +and decompression, and exit successfully. +.TP +.BR \-h ", " \-\-help +Display a help message describing the most commonly used options, +and exit successfully. +.TP +.BR \-H ", " \-\-long\-help +Display a help message describing all features of +.BR xz , +and exit successfully +.TP +.BR \-V ", " \-\-version +Display the version number of +.B xz +and liblzma in human readable format. +To get machine-parsable output, specify +.B \-\-robot +before +.BR \-\-version . +. +.SH "ROBOT MODE" +The robot mode is activated with the +.B \-\-robot +option. +It makes the output of +.B xz +easier to parse by other programs. +Currently +.B \-\-robot +is supported only together with +.BR \-\-version , +.BR \-\-info\-memory , +and +.BR \-\-list . +It will be supported for compression and +decompression in the future. +. +.SS Version +.B "xz \-\-robot \-\-version" +will print the version number of +.B xz +and liblzma in the following format: +.PP +.BI XZ_VERSION= XYYYZZZS +.br +.BI LIBLZMA_VERSION= XYYYZZZS +.TP +.I X +Major version. +.TP +.I YYY +Minor version. +Even numbers are stable. +Odd numbers are alpha or beta versions. +.TP +.I ZZZ +Patch level for stable releases or +just a counter for development releases. +.TP +.I S +Stability. +0 is alpha, 1 is beta, and 2 is stable. +.I S +should be always 2 when +.I YYY +is even. +.PP +.I XYYYZZZS +are the same on both lines if +.B xz +and liblzma are from the same XZ Utils release. +.PP +Examples: 4.999.9beta is +.B 49990091 +and +5.0.0 is +.BR 50000002 . +. +.SS "Memory limit information" +.B "xz \-\-robot \-\-info\-memory" +prints a single line with three tab-separated columns: +.IP 1. 4 +Total amount of physical memory (RAM) in bytes +.IP 2. 4 +Memory usage limit for compression in bytes. +A special value of zero indicates the default setting, +which for single-threaded mode is the same as no limit. +.IP 3. 4 +Memory usage limit for decompression in bytes. +A special value of zero indicates the default setting, +which for single-threaded mode is the same as no limit. +.PP +In the future, the output of +.B "xz \-\-robot \-\-info\-memory" +may have more columns, but never more than a single line. +. +.SS "List mode" +.B "xz \-\-robot \-\-list" +uses tab-separated output. +The first column of every line has a string +that indicates the type of the information found on that line: +.TP +.B name +This is always the first line when starting to list a file. +The second column on the line is the filename. +.TP +.B file +This line contains overall information about the +.B .xz +file. +This line is always printed after the +.B name +line. +.TP +.B stream +This line type is used only when +.B \-\-verbose +was specified. +There are as many +.B stream +lines as there are streams in the +.B .xz +file. +.TP +.B block +This line type is used only when +.B \-\-verbose +was specified. +There are as many +.B block +lines as there are blocks in the +.B .xz +file. +The +.B block +lines are shown after all the +.B stream +lines; different line types are not interleaved. +.TP +.B summary +This line type is used only when +.B \-\-verbose +was specified twice. +This line is printed after all +.B block +lines. +Like the +.B file +line, the +.B summary +line contains overall information about the +.B .xz +file. +.TP +.B totals +This line is always the very last line of the list output. +It shows the total counts and sizes. +.PP +The columns of the +.B file +lines: +.PD 0 +.RS +.IP 2. 4 +Number of streams in the file +.IP 3. 4 +Total number of blocks in the stream(s) +.IP 4. 4 +Compressed size of the file +.IP 5. 4 +Uncompressed size of the file +.IP 6. 4 +Compression ratio, for example +.BR 0.123. +If ratio is over 9.999, three dashes +.RB ( \-\-\- ) +are displayed instead of the ratio. +.IP 7. 4 +Comma-separated list of integrity check names. +The following strings are used for the known check types: +.BR None , +.BR CRC32 , +.BR CRC64 , +and +.BR SHA\-256 . +For unknown check types, +.BI Unknown\- N +is used, where +.I N +is the Check ID as a decimal number (one or two digits). +.IP 8. 4 +Total size of stream padding in the file +.RE +.PD +.PP +The columns of the +.B stream +lines: +.PD 0 +.RS +.IP 2. 4 +Stream number (the first stream is 1) +.IP 3. 4 +Number of blocks in the stream +.IP 4. 4 +Compressed start offset +.IP 5. 4 +Uncompressed start offset +.IP 6. 4 +Compressed size (does not include stream padding) +.IP 7. 4 +Uncompressed size +.IP 8. 4 +Compression ratio +.IP 9. 4 +Name of the integrity check +.IP 10. 4 +Size of stream padding +.RE +.PD +.PP +The columns of the +.B block +lines: +.PD 0 +.RS +.IP 2. 4 +Number of the stream containing this block +.IP 3. 4 +Block number relative to the beginning of the stream +(the first block is 1) +.IP 4. 4 +Block number relative to the beginning of the file +.IP 5. 4 +Compressed start offset relative to the beginning of the file +.IP 6. 4 +Uncompressed start offset relative to the beginning of the file +.IP 7. 4 +Total compressed size of the block (includes headers) +.IP 8. 4 +Uncompressed size +.IP 9. 4 +Compression ratio +.IP 10. 4 +Name of the integrity check +.RE +.PD +.PP +If +.B \-\-verbose +was specified twice, additional columns are included on the +.B block +lines. +These are not displayed with a single +.BR \-\-verbose , +because getting this information requires many seeks +and can thus be slow: +.PD 0 +.RS +.IP 11. 4 +Value of the integrity check in hexadecimal +.IP 12. 4 +Block header size +.IP 13. 4 +Block flags: +.B c +indicates that compressed size is present, and +.B u +indicates that uncompressed size is present. +If the flag is not set, a dash +.RB ( \- ) +is shown instead to keep the string length fixed. +New flags may be added to the end of the string in the future. +.IP 14. 4 +Size of the actual compressed data in the block (this excludes +the block header, block padding, and check fields) +.IP 15. 4 +Amount of memory (in bytes) required to decompress +this block with this +.B xz +version +.IP 16. 4 +Filter chain. +Note that most of the options used at compression time +cannot be known, because only the options +that are needed for decompression are stored in the +.B .xz +headers. +.RE +.PD +.PP +The columns of the +.B summary +lines: +.PD 0 +.RS +.IP 2. 4 +Amount of memory (in bytes) required to decompress +this file with this +.B xz +version +.IP 3. 4 +.B yes +or +.B no +indicating if all block headers have both compressed size and +uncompressed size stored in them +.PP +.I Since +.B xz +.I 5.1.2alpha: +.IP 4. 4 +Minimum +.B xz +version required to decompress the file +.RE +.PD +.PP +The columns of the +.B totals +line: +.PD 0 +.RS +.IP 2. 4 +Number of streams +.IP 3. 4 +Number of blocks +.IP 4. 4 +Compressed size +.IP 5. 4 +Uncompressed size +.IP 6. 4 +Average compression ratio +.IP 7. 4 +Comma-separated list of integrity check names +that were present in the files +.IP 8. 4 +Stream padding size +.IP 9. 4 +Number of files. +This is here to +keep the order of the earlier columns the same as on +.B file +lines. +.PD +.RE +.PP +If +.B \-\-verbose +was specified twice, additional columns are included on the +.B totals +line: +.PD 0 +.RS +.IP 10. 4 +Maximum amount of memory (in bytes) required to decompress +the files with this +.B xz +version +.IP 11. 4 +.B yes +or +.B no +indicating if all block headers have both compressed size and +uncompressed size stored in them +.PP +.I Since +.B xz +.I 5.1.2alpha: +.IP 12. 4 +Minimum +.B xz +version required to decompress the file +.RE +.PD +.PP +Future versions may add new line types and +new columns can be added to the existing line types, +but the existing columns won't be changed. +. +.SH "EXIT STATUS" +.TP +.B 0 +All is good. +.TP +.B 1 +An error occurred. +.TP +.B 2 +Something worth a warning occurred, +but no actual errors occurred. +.PP +Notices (not warnings or errors) printed on standard error +don't affect the exit status. +. +.SH ENVIRONMENT +.B xz +parses space-separated lists of options +from the environment variables +.B XZ_DEFAULTS +and +.BR XZ_OPT , +in this order, before parsing the options from the command line. +Note that only options are parsed from the environment variables; +all non-options are silently ignored. +Parsing is done with +.BR getopt_long (3) +which is used also for the command line arguments. +.TP +.B XZ_DEFAULTS +User-specific or system-wide default options. +Typically this is set in a shell initialization script to enable +.BR xz 's +memory usage limiter by default. +Excluding shell initialization scripts +and similar special cases, scripts must never set or unset +.BR XZ_DEFAULTS . +.TP +.B XZ_OPT +This is for passing options to +.B xz +when it is not possible to set the options directly on the +.B xz +command line. +This is the case e.g. when +.B xz +is run by a script or tool, e.g. GNU +.BR tar (1): +.RS +.RS +.PP +.nf +.ft CW +XZ_OPT=\-2v tar caf foo.tar.xz foo +.ft R +.fi +.RE +.RE +.IP "" +Scripts may use +.B XZ_OPT +e.g. to set script-specific default compression options. +It is still recommended to allow users to override +.B XZ_OPT +if that is reasonable, e.g. in +.BR sh (1) +scripts one may use something like this: +.RS +.RS +.PP +.nf +.ft CW +XZ_OPT=${XZ_OPT\-"\-7e"} +export XZ_OPT +.ft R +.fi +.RE +.RE +. +.SH "LZMA UTILS COMPATIBILITY" +The command line syntax of +.B xz +is practically a superset of +.BR lzma , +.BR unlzma , +and +.BR lzcat +as found from LZMA Utils 4.32.x. +In most cases, it is possible to replace +LZMA Utils with XZ Utils without breaking existing scripts. +There are some incompatibilities though, +which may sometimes cause problems. +. +.SS "Compression preset levels" +The numbering of the compression level presets is not identical in +.B xz +and LZMA Utils. +The most important difference is how dictionary sizes +are mapped to different presets. +Dictionary size is roughly equal to the decompressor memory usage. +.RS +.PP +.TS +tab(;); +c c c +c n n. +Level;xz;LZMA Utils +\-0;256 KiB;N/A +\-1;1 MiB;64 KiB +\-2;2 MiB;1 MiB +\-3;4 MiB;512 KiB +\-4;4 MiB;1 MiB +\-5;8 MiB;2 MiB +\-6;8 MiB;4 MiB +\-7;16 MiB;8 MiB +\-8;32 MiB;16 MiB +\-9;64 MiB;32 MiB +.TE +.RE +.PP +The dictionary size differences affect +the compressor memory usage too, +but there are some other differences between +LZMA Utils and XZ Utils, which +make the difference even bigger: +.RS +.PP +.TS +tab(;); +c c c +c n n. +Level;xz;LZMA Utils 4.32.x +\-0;3 MiB;N/A +\-1;9 MiB;2 MiB +\-2;17 MiB;12 MiB +\-3;32 MiB;12 MiB +\-4;48 MiB;16 MiB +\-5;94 MiB;26 MiB +\-6;94 MiB;45 MiB +\-7;186 MiB;83 MiB +\-8;370 MiB;159 MiB +\-9;674 MiB;311 MiB +.TE +.RE +.PP +The default preset level in LZMA Utils is +.B \-7 +while in XZ Utils it is +.BR \-6 , +so both use an 8 MiB dictionary by default. +. +.SS "Streamed vs. non-streamed .lzma files" +The uncompressed size of the file can be stored in the +.B .lzma +header. +LZMA Utils does that when compressing regular files. +The alternative is to mark that uncompressed size is unknown +and use end-of-payload marker to indicate +where the decompressor should stop. +LZMA Utils uses this method when uncompressed size isn't known, +which is the case for example in pipes. +.PP +.B xz +supports decompressing +.B .lzma +files with or without end-of-payload marker, but all +.B .lzma +files created by +.B xz +will use end-of-payload marker and have uncompressed size +marked as unknown in the +.B .lzma +header. +This may be a problem in some uncommon situations. +For example, a +.B .lzma +decompressor in an embedded device might work +only with files that have known uncompressed size. +If you hit this problem, you need to use LZMA Utils +or LZMA SDK to create +.B .lzma +files with known uncompressed size. +. +.SS "Unsupported .lzma files" +The +.B .lzma +format allows +.I lc +values up to 8, and +.I lp +values up to 4. +LZMA Utils can decompress files with any +.I lc +and +.IR lp , +but always creates files with +.B lc=3 +and +.BR lp=0 . +Creating files with other +.I lc +and +.I lp +is possible with +.B xz +and with LZMA SDK. +.PP +The implementation of the LZMA1 filter in liblzma +requires that the sum of +.I lc +and +.I lp +must not exceed 4. +Thus, +.B .lzma +files, which exceed this limitation, cannot be decompressed with +.BR xz . +.PP +LZMA Utils creates only +.B .lzma +files which have a dictionary size of +.RI "2^" n +(a power of 2) but accepts files with any dictionary size. +liblzma accepts only +.B .lzma +files which have a dictionary size of +.RI "2^" n +or +.RI "2^" n " + 2^(" n "\-1)." +This is to decrease false positives when detecting +.B .lzma +files. +.PP +These limitations shouldn't be a problem in practice, +since practically all +.B .lzma +files have been compressed with settings that liblzma will accept. +. +.SS "Trailing garbage" +When decompressing, +LZMA Utils silently ignore everything after the first +.B .lzma +stream. +In most situations, this is a bug. +This also means that LZMA Utils +don't support decompressing concatenated +.B .lzma +files. +.PP +If there is data left after the first +.B .lzma +stream, +.B xz +considers the file to be corrupt unless +.B \-\-single\-stream +was used. +This may break obscure scripts which have +assumed that trailing garbage is ignored. +. +.SH NOTES +. +.SS "Compressed output may vary" +The exact compressed output produced from +the same uncompressed input file +may vary between XZ Utils versions even if +compression options are identical. +This is because the encoder can be improved +(faster or better compression) +without affecting the file format. +The output can vary even between different +builds of the same XZ Utils version, +if different build options are used. +.PP +The above means that once +.B \-\-rsyncable +has been implemented, +the resulting files won't necessarily be rsyncable +unless both old and new files have been compressed +with the same xz version. +This problem can be fixed if a part of the encoder +implementation is frozen to keep rsyncable output +stable across xz versions. +. +.SS "Embedded .xz decompressors" +Embedded +.B .xz +decompressor implementations like XZ Embedded don't necessarily +support files created with integrity +.I check +types other than +.B none +and +.BR crc32 . +Since the default is +.BR \-\-check=crc64 , +you must use +.B \-\-check=none +or +.B \-\-check=crc32 +when creating files for embedded systems. +.PP +Outside embedded systems, all +.B .xz +format decompressors support all the +.I check +types, or at least are able to decompress +the file without verifying the +integrity check if the particular +.I check +is not supported. +.PP +XZ Embedded supports BCJ filters, +but only with the default start offset. +. +.SH EXAMPLES +. +.SS Basics +Compress the file +.I foo +into +.I foo.xz +using the default compression level +.RB ( \-6 ), +and remove +.I foo +if compression is successful: +.RS +.PP +.nf +.ft CW +xz foo +.ft R +.fi +.RE +.PP +Decompress +.I bar.xz +into +.I bar +and don't remove +.I bar.xz +even if decompression is successful: +.RS +.PP +.nf +.ft CW +xz \-dk bar.xz +.ft R +.fi +.RE +.PP +Create +.I baz.tar.xz +with the preset +.B \-4e +.RB ( "\-4 \-\-extreme" ), +which is slower than e.g. the default +.BR \-6 , +but needs less memory for compression and decompression (48\ MiB +and 5\ MiB, respectively): +.RS +.PP +.nf +.ft CW +tar cf \- baz | xz \-4e > baz.tar.xz +.ft R +.fi +.RE +.PP +A mix of compressed and uncompressed files can be decompressed +to standard output with a single command: +.RS +.PP +.nf +.ft CW +xz \-dcf a.txt b.txt.xz c.txt d.txt.lzma > abcd.txt +.ft R +.fi +.RE +. +.SS "Parallel compression of many files" +On GNU and *BSD, +.BR find (1) +and +.BR xargs (1) +can be used to parallelize compression of many files: +.RS +.PP +.nf +.ft CW +find . \-type f \e! \-name '*.xz' \-print0 \e + | xargs \-0r \-P4 \-n16 xz \-T1 +.ft R +.fi +.RE +.PP +The +.B \-P +option to +.BR xargs (1) +sets the number of parallel +.B xz +processes. +The best value for the +.B \-n +option depends on how many files there are to be compressed. +If there are only a couple of files, +the value should probably be 1; +with tens of thousands of files, +100 or even more may be appropriate to reduce the number of +.B xz +processes that +.BR xargs (1) +will eventually create. +.PP +The option +.B \-T1 +for +.B xz +is there to force it to single-threaded mode, because +.BR xargs (1) +is used to control the amount of parallelization. +. +.SS "Robot mode" +Calculate how many bytes have been saved in total +after compressing multiple files: +.RS +.PP +.nf +.ft CW +xz \-\-robot \-\-list *.xz | awk '/^totals/{print $5\-$4}' +.ft R +.fi +.RE +.PP +A script may want to know that it is using new enough +.BR xz . +The following +.BR sh (1) +script checks that the version number of the +.B xz +tool is at least 5.0.0. +This method is compatible with old beta versions, +which didn't support the +.B \-\-robot +option: +.RS +.PP +.nf +.ft CW +if ! eval "$(xz \-\-robot \-\-version 2> /dev/null)" || + [ "$XZ_VERSION" \-lt 50000002 ]; then + echo "Your xz is too old." +fi +unset XZ_VERSION LIBLZMA_VERSION +.ft R +.fi +.RE +.PP +Set a memory usage limit for decompression using +.BR XZ_OPT , +but if a limit has already been set, don't increase it: +.RS +.PP +.nf +.ft CW +NEWLIM=$((123 << 20)) # 123 MiB +OLDLIM=$(xz \-\-robot \-\-info\-memory | cut \-f3) +if [ $OLDLIM \-eq 0 \-o $OLDLIM \-gt $NEWLIM ]; then + XZ_OPT="$XZ_OPT \-\-memlimit\-decompress=$NEWLIM" + export XZ_OPT +fi +.ft R +.fi +.RE +. +.SS "Custom compressor filter chains" +The simplest use for custom filter chains is +customizing a LZMA2 preset. +This can be useful, +because the presets cover only a subset of the +potentially useful combinations of compression settings. +.PP +The CompCPU columns of the tables +from the descriptions of the options +.BR "\-0" " ... " "\-9" +and +.B \-\-extreme +are useful when customizing LZMA2 presets. +Here are the relevant parts collected from those two tables: +.RS +.PP +.TS +tab(;); +c c +n n. +Preset;CompCPU +\-0;0 +\-1;1 +\-2;2 +\-3;3 +\-4;4 +\-5;5 +\-6;6 +\-5e;7 +\-6e;8 +.TE +.RE +.PP +If you know that a file requires +somewhat big dictionary (e.g. 32 MiB) to compress well, +but you want to compress it quicker than +.B "xz \-8" +would do, a preset with a low CompCPU value (e.g. 1) +can be modified to use a bigger dictionary: +.RS +.PP +.nf +.ft CW +xz \-\-lzma2=preset=1,dict=32MiB foo.tar +.ft R +.fi +.RE +.PP +With certain files, the above command may be faster than +.B "xz \-6" +while compressing significantly better. +However, it must be emphasized that only some files benefit from +a big dictionary while keeping the CompCPU value low. +The most obvious situation, +where a big dictionary can help a lot, +is an archive containing very similar files +of at least a few megabytes each. +The dictionary size has to be significantly bigger +than any individual file to allow LZMA2 to take +full advantage of the similarities between consecutive files. +.PP +If very high compressor and decompressor memory usage is fine, +and the file being compressed is +at least several hundred megabytes, it may be useful +to use an even bigger dictionary than the 64 MiB that +.B "xz \-9" +would use: +.RS +.PP +.nf +.ft CW +xz \-vv \-\-lzma2=dict=192MiB big_foo.tar +.ft R +.fi +.RE +.PP +Using +.B \-vv +.RB ( "\-\-verbose \-\-verbose" ) +like in the above example can be useful +to see the memory requirements +of the compressor and decompressor. +Remember that using a dictionary bigger than +the size of the uncompressed file is waste of memory, +so the above command isn't useful for small files. +.PP +Sometimes the compression time doesn't matter, +but the decompressor memory usage has to be kept low +e.g. to make it possible to decompress the file on +an embedded system. +The following command uses +.B \-6e +.RB ( "\-6 \-\-extreme" ) +as a base and sets the dictionary to only 64\ KiB. +The resulting file can be decompressed with XZ Embedded +(that's why there is +.BR \-\-check=crc32 ) +using about 100\ KiB of memory. +.RS +.PP +.nf +.ft CW +xz \-\-check=crc32 \-\-lzma2=preset=6e,dict=64KiB foo +.ft R +.fi +.RE +.PP +If you want to squeeze out as many bytes as possible, +adjusting the number of literal context bits +.RI ( lc ) +and number of position bits +.RI ( pb ) +can sometimes help. +Adjusting the number of literal position bits +.RI ( lp ) +might help too, but usually +.I lc +and +.I pb +are more important. +E.g. a source code archive contains mostly US-ASCII text, +so something like the following might give +slightly (like 0.1\ %) smaller file than +.B "xz \-6e" +(try also without +.BR lc=4 ): +.RS +.PP +.nf +.ft CW +xz \-\-lzma2=preset=6e,pb=0,lc=4 source_code.tar +.ft R +.fi +.RE +.PP +Using another filter together with LZMA2 can improve +compression with certain file types. +E.g. to compress a x86-32 or x86-64 shared library +using the x86 BCJ filter: +.RS +.PP +.nf +.ft CW +xz \-\-x86 \-\-lzma2 libfoo.so +.ft R +.fi +.RE +.PP +Note that the order of the filter options is significant. +If +.B \-\-x86 +is specified after +.BR \-\-lzma2 , +.B xz +will give an error, +because there cannot be any filter after LZMA2, +and also because the x86 BCJ filter cannot be used +as the last filter in the chain. +.PP +The Delta filter together with LZMA2 +can give good results with bitmap images. +It should usually beat PNG, +which has a few more advanced filters than simple +delta but uses Deflate for the actual compression. +.PP +The image has to be saved in uncompressed format, +e.g. as uncompressed TIFF. +The distance parameter of the Delta filter is set +to match the number of bytes per pixel in the image. +E.g. 24-bit RGB bitmap needs +.BR dist=3 , +and it is also good to pass +.B pb=0 +to LZMA2 to accommodate the three-byte alignment: +.RS +.PP +.nf +.ft CW +xz \-\-delta=dist=3 \-\-lzma2=pb=0 foo.tiff +.ft R +.fi +.RE +.PP +If multiple images have been put into a single archive (e.g.\& +.BR .tar ), +the Delta filter will work on that too as long as all images +have the same number of bytes per pixel. +. +.SH "SEE ALSO" +.BR xzdec (1), +.BR xzdiff (1), +.BR xzgrep (1), +.BR xzless (1), +.BR xzmore (1), +.BR gzip (1), +.BR bzip2 (1), +.BR 7z (1) +.PP +XZ Utils: <https://tukaani.org/xz/> +.br +XZ Embedded: <https://tukaani.org/xz/embedded.html> +.br +LZMA SDK: <http://7-zip.org/sdk.html> diff --git a/deps/share/man/man1/xzcat.1 b/deps/share/man/man1/xzcat.1 new file mode 120000 index 0000000..01b6808 --- /dev/null +++ b/deps/share/man/man1/xzcat.1 @@ -0,0 +1 @@ +xz.1
\ No newline at end of file diff --git a/deps/share/man/man1/xzcmp.1 b/deps/share/man/man1/xzcmp.1 new file mode 120000 index 0000000..e65fb97 --- /dev/null +++ b/deps/share/man/man1/xzcmp.1 @@ -0,0 +1 @@ +xzdiff.1
\ No newline at end of file diff --git a/deps/share/man/man1/xzdec.1 b/deps/share/man/man1/xzdec.1 new file mode 100644 index 0000000..78bc9b4 --- /dev/null +++ b/deps/share/man/man1/xzdec.1 @@ -0,0 +1,146 @@ +.\" +.\" Author: Lasse Collin +.\" +.\" This file has been put into the public domain. +.\" You can do whatever you want with this file. +.\" +.TH XZDEC 1 "2017-04-19" "Tukaani" "XZ Utils" +.SH NAME +xzdec, lzmadec \- Small .xz and .lzma decompressors +.SH SYNOPSIS +.B xzdec +.RI [ option... ] +.RI [ file... ] +.br +.B lzmadec +.RI [ option... ] +.RI [ file... ] +.SH DESCRIPTION +.B xzdec +is a liblzma-based decompression-only tool for +.B .xz +(and only +.BR .xz ) +files. +.B xzdec +is intended to work as a drop-in replacement for +.BR xz (1) +in the most common situations where a script +has been written to use +.B "xz \-\-decompress \-\-stdout" +(and possibly a few other commonly used options) to decompress +.B .xz +files. +.B lzmadec +is identical to +.B xzdec +except that +.B lzmadec +supports +.B .lzma +files instead of +.B .xz +files. +.PP +To reduce the size of the executable, +.B xzdec +doesn't support multithreading or localization, +and doesn't read options from +.B XZ_DEFAULTS +and +.B XZ_OPT +environment variables. +.B xzdec +doesn't support displaying intermediate progress information: sending +.B SIGINFO +to +.B xzdec +does nothing, but sending +.B SIGUSR1 +terminates the process instead of displaying progress information. +.SH OPTIONS +.TP +.BR \-d ", " \-\-decompress ", " \-\-uncompress +Ignored for +.BR xz (1) +compatibility. +.B xzdec +supports only decompression. +.TP +.BR \-k ", " \-\-keep +Ignored for +.BR xz (1) +compatibility. +.B xzdec +never creates or removes any files. +.TP +.BR \-c ", " \-\-stdout ", " \-\-to-stdout +Ignored for +.BR xz (1) +compatibility. +.B xzdec +always writes the decompressed data to standard output. +.TP +.BR \-q ", " \-\-quiet +Specifying this once does nothing since +.B xzdec +never displays any warnings or notices. +Specify this twice to suppress errors. +.TP +.BR \-Q ", " \-\-no-warn +Ignored for +.BR xz (1) +compatibility. +.B xzdec +never uses the exit status 2. +.TP +.BR \-h ", " \-\-help +Display a help message and exit successfully. +.TP +.BR \-V ", " \-\-version +Display the version number of +.B xzdec +and liblzma. +.SH "EXIT STATUS" +.TP +.B 0 +All was good. +.TP +.B 1 +An error occurred. +.PP +.B xzdec +doesn't have any warning messages like +.BR xz (1) +has, thus the exit status 2 is not used by +.BR xzdec . +.SH NOTES +Use +.BR xz (1) +instead of +.B xzdec +or +.B lzmadec +for normal everyday use. +.B xzdec +or +.B lzmadec +are meant only for situations where it is important to have +a smaller decompressor than the full-featured +.BR xz (1). +.PP +.B xzdec +and +.B lzmadec +are not really that small. +The size can be reduced further by dropping +features from liblzma at compile time, +but that shouldn't usually be done for executables distributed +in typical non-embedded operating system distributions. +If you need a truly small +.B .xz +decompressor, consider using XZ Embedded. +.SH "SEE ALSO" +.BR xz (1) +.PP +XZ Embedded: <https://tukaani.org/xz/embedded.html> diff --git a/deps/share/man/man1/xzdiff.1 b/deps/share/man/man1/xzdiff.1 new file mode 100644 index 0000000..b33670c --- /dev/null +++ b/deps/share/man/man1/xzdiff.1 @@ -0,0 +1,77 @@ +.\" +.\" Original zdiff.1 for gzip: Jean-loup Gailly +.\" +.\" Modifications for XZ Utils: Lasse Collin +.\" Andrew Dudman +.\" +.\" License: GNU GPLv2+ +.\" +.TH XZDIFF 1 "2011-03-19" "Tukaani" "XZ Utils" +.SH NAME +xzcmp, xzdiff, lzcmp, lzdiff \- compare compressed files +.SH SYNOPSIS +.B xzcmp +.RI [ cmp_options "] " file1 " [" file2 ] +.br +.B xzdiff +.RI [ diff_options "] " file1 " [" file2 ] +.br +.B lzcmp +.RI [ cmp_options "] " file1 " [" file2 ] +.br +.B lzdiff +.RI [ diff_options "] " file1 " [" file2 ] +.SH DESCRIPTION +.B xzcmp +and +.B xzdiff +invoke +.BR cmp (1) +or +.BR diff (1) +on files compressed with +.BR xz (1), +.BR lzma (1), +.BR gzip (1), +.BR bzip2 (1), +or +.BR lzop (1). +All options specified are passed directly to +.BR cmp (1) +or +.BR diff (1). +If only one file is specified, then the files compared are +.I file1 +(which must have a suffix of a supported compression format) and +.I file1 +from which the compression format suffix has been stripped. +If two files are specified, +then they are uncompressed if necessary and fed to +.BR cmp (1) +or +.BR diff (1). +The exit status from +.BR cmp (1) +or +.BR diff (1) +is preserved. +.PP +The names +.B lzcmp +and +.B lzdiff +are provided for backward compatibility with LZMA Utils. +.SH "SEE ALSO" +.BR cmp (1), +.BR diff (1), +.BR xz (1), +.BR gzip (1), +.BR bzip2 (1), +.BR lzop (1), +.BR zdiff (1) +.SH BUGS +Messages from the +.BR cmp (1) +or +.BR diff (1) +programs refer to temporary filenames instead of those specified. diff --git a/deps/share/man/man1/xzegrep.1 b/deps/share/man/man1/xzegrep.1 new file mode 120000 index 0000000..bebd8a4 --- /dev/null +++ b/deps/share/man/man1/xzegrep.1 @@ -0,0 +1 @@ +xzgrep.1
\ No newline at end of file diff --git a/deps/share/man/man1/xzfgrep.1 b/deps/share/man/man1/xzfgrep.1 new file mode 120000 index 0000000..bebd8a4 --- /dev/null +++ b/deps/share/man/man1/xzfgrep.1 @@ -0,0 +1 @@ +xzgrep.1
\ No newline at end of file diff --git a/deps/share/man/man1/xzgrep.1 b/deps/share/man/man1/xzgrep.1 new file mode 100644 index 0000000..4bddbe2 --- /dev/null +++ b/deps/share/man/man1/xzgrep.1 @@ -0,0 +1,98 @@ +.\" +.\" Original zgrep.1 for gzip: Jean-loup Gailly +.\" Charles Levert <[email protected]> +.\" +.\" Modifications for XZ Utils: Lasse Collin +.\" +.\" License: GNU GPLv2+ +.\" +.TH XZGREP 1 "2011-03-19" "Tukaani" "XZ Utils" +.SH NAME +xzgrep \- search compressed files for a regular expression +.SH SYNOPSIS +.B xzgrep +.RI [ grep_options ] +.RB [ \-e ] +.I pattern +.IR file "..." +.br +.B xzegrep +.RB ... +.br +.B xzfgrep +.RB ... +.br +.B lzgrep +.RB ... +.br +.B lzegrep +.RB ... +.br +.B lzfgrep +.RB ... +.SH DESCRIPTION +.B xzgrep +invokes +.BR grep (1) +on +.I files +which may be either uncompressed or compressed with +.BR xz (1), +.BR lzma (1), +.BR gzip (1), +.BR bzip2 (1), +or +.BR lzop (1). +All options specified are passed directly to +.BR grep (1). +.PP +If no +.I file +is specified, then standard input is decompressed if necessary +and fed to +.BR grep (1). +When reading from standard input, +.BR gzip (1), +.BR bzip2 (1), +and +.BR lzop (1) +compressed files are not supported. +.PP +If +.B xzgrep +is invoked as +.B xzegrep +or +.B xzfgrep +then +.BR egrep (1) +or +.BR fgrep (1) +is used instead of +.BR grep (1). +The same applies to names +.BR lzgrep , +.BR lzegrep , +and +.BR lzfgrep , +which are provided for backward compatibility with LZMA Utils. +.PP +.SH ENVIRONMENT +.TP +.B GREP +If the +.B GREP +environment variable is set, +.B xzgrep +uses it instead of +.BR grep (1), +.BR egrep (1), +or +.BR fgrep (1). +.SH "SEE ALSO" +.BR grep (1), +.BR xz (1), +.BR gzip (1), +.BR bzip2 (1), +.BR lzop (1), +.BR zgrep (1) diff --git a/deps/share/man/man1/xzless.1 b/deps/share/man/man1/xzless.1 new file mode 100644 index 0000000..2d05459 --- /dev/null +++ b/deps/share/man/man1/xzless.1 @@ -0,0 +1,69 @@ +.\" +.\" Authors: Andrew Dudman +.\" Lasse Collin +.\" +.\" This file has been put into the public domain. +.\" You can do whatever you want with this file. +.\" +.\" (Note that this file is not based on gzip's zless.1.) +.\" +.TH XZLESS 1 "2010-09-27" "Tukaani" "XZ Utils" +.SH NAME +xzless, lzless \- view xz or lzma compressed (text) files +.SH SYNOPSIS +.B xzless +.RI [ file ...] +.br +.B lzless +.RI [ file ...] +.SH DESCRIPTION +.B xzless +is a filter that displays text from compressed files to a terminal. +It works on files compressed with +.BR xz (1) +or +.BR lzma (1). +If no +.I files +are given, +.B xzless +reads from standard input. +.PP +.B xzless +uses +.BR less (1) +to present its output. +Unlike +.BR xzmore , +its choice of pager cannot be altered by +setting an environment variable. +Commands are based on both +.BR more (1) +and +.BR vi (1) +and allow back and forth movement and searching. +See the +.BR less (1) +manual for more information. +.PP +The command named +.B lzless +is provided for backward compatibility with LZMA Utils. +.SH ENVIRONMENT +.TP +.B LESSMETACHARS +A list of characters special to the shell. +Set by +.B xzless +unless it is already set in the environment. +.TP +.B LESSOPEN +Set to a command line to invoke the +.BR xz (1) +decompressor for preprocessing the input files to +.BR less (1). +.SH "SEE ALSO" +.BR less (1), +.BR xz (1), +.BR xzmore (1), +.BR zless (1) diff --git a/deps/share/man/man1/xzmore.1 b/deps/share/man/man1/xzmore.1 new file mode 100644 index 0000000..9613974 --- /dev/null +++ b/deps/share/man/man1/xzmore.1 @@ -0,0 +1,55 @@ +.\" +.\" Original zdiff.1 for gzip: Jean-loup Gailly +.\" Modifications for XZ Utils: Lasse Collin +.\" +.\" License: GNU GPLv2+ +.\" +.TH XZMORE 1 "2013-06-30" "Tukaani" "XZ Utils" +.SH NAME +xzmore, lzmore \- view xz or lzma compressed (text) files +.SH SYNOPSIS +.B xzmore +.RI [ file... ] +.br +.B lzmore +.RI [ file... ] +.SH DESCRIPTION +.B xzmore +is a filter which allows examination of +.BR xz (1) +or +.BR lzma (1) +compressed text files one screenful at a time +on a soft-copy terminal. +.PP +To use a pager other than the default +.B more, +set environment variable +.B PAGER +to the name of the desired program. +The name +.B lzmore +is provided for backward compatibility with LZMA Utils. +.TP +.BR e " or " q +When the prompt \-\-More\-\-(Next file: +.IR file ) +is printed, this command causes +.B xzmore +to exit. +.TP +.B s +When the prompt \-\-More\-\-(Next file: +.IR file ) +is printed, this command causes +.B xzmore +to skip the next file and continue. +.PP +For list of keyboard commands supported while actually viewing the +content of a file, refer to manual of the pager you use, usually +.BR more (1). +.SH "SEE ALSO" +.BR more (1), +.BR xz (1), +.BR xzless (1), +.BR zmore (1) diff --git a/deps/share/man/man3/elf_begin.3 b/deps/share/man/man3/elf_begin.3 new file mode 100644 index 0000000..6a1d0c2 --- /dev/null +++ b/deps/share/man/man3/elf_begin.3 @@ -0,0 +1,37 @@ +.\" Modified Thu Sep 5 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_BEGIN 3 2017-09-05 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_begin \- Return descriptor for ELF file. +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "Elf *elf_begin (int " filedes ", Elf_Cmd " cmd ", Elf *" ref ");" +.BI "Elf *elf_clone (int " filedes ", Elf_Cmd " cmd ");" +.BI "int elf_end (Elf *" elf ");" +.fi +.SH DESCRIPTION +The +.BR elf_begin () +.SH RETURN VALUE +.SH ERRORS +elf_begin ELF_E_NO_VERSION ELF_E_INVALID_FILE ELF_E_INVALID_CMD ELF_E_NOMEM +elf_clone ELF_E_NOMEM +elf_end +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbw29 lb lb +l l l. +Interface Attribute Value +T{ +.BR elf_begin (), +.BR elf_clone (), +.BR elf_end () +T} Thread safety MT-Safe +.TE + +.SH SEE ALSO diff --git a/deps/share/man/man3/elf_clone.3 b/deps/share/man/man3/elf_clone.3 new file mode 100644 index 0000000..38ec921 --- /dev/null +++ b/deps/share/man/man3/elf_clone.3 @@ -0,0 +1,14 @@ +.\" Modified Thu Sep 5 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_CLONE 3 2017-09-05 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_clone \- Create a clone of an existing ELF descriptor. +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "Elf *elf_clone (int " filedes ", Elf_Cmd " cmd ");" +.fi +.SH DESCRIPTION +The +.BR elf_clone () diff --git a/deps/share/man/man3/elf_getdata.3 b/deps/share/man/man3/elf_getdata.3 new file mode 100644 index 0000000..44d9304 --- /dev/null +++ b/deps/share/man/man3/elf_getdata.3 @@ -0,0 +1,28 @@ +.\" Modified Thu Aug 17 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_GETDATA 3 2017-08-17 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_getdata \- Get washed data of section +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "Elf_Data * elf_getdata (Elf_Scn *" scn ", Elf_Data *" data ");" +.fi +.SH DESCRIPTION +The +.BR elf_getdata () +function allows the user to retrieve the data buffers of the section +.I scn + . There can be more than one buffer if the user explicitly added them. +When a file is read the libelf library creates exactly one data buffer. + +The first buffer in the list can be obtained by passing a null pointer in the +parameter data. To get the next data buffer the previously returned value must +be passed in the data parameter. If there are no more buffer left in the list a +null pointer is returned. + +If the data parameter is not a null pointer it must be a descriptor for a +buffer associated with the section scn . If this is not the case a null pointer +is returned. To facilitate error handling elf_getdata also returns a null +pointer if the scn parameter is a null pointer. diff --git a/deps/share/man/man3/elf_update.3 b/deps/share/man/man3/elf_update.3 new file mode 100644 index 0000000..d0a7ab1 --- /dev/null +++ b/deps/share/man/man3/elf_update.3 @@ -0,0 +1,14 @@ +.\" Modified Thu Sep 5 2017 by Ben Woodard <[email protected]> +.\" +.TH ELF_UPDATE 3 2017-09-05 "Libelf" "Libelf Programmer's Manual" +.SH NAME +elf_update \- update an ELF descriptor +.nf +.SH SYNOPSIS +.B #include <libelf.h> +.sp +.BI "off_t elf_update (Elf *" elf ", Elf_Cmd " cmd ");" +.fi +.SH DESCRIPTION +The +.BR elf_update () diff --git a/deps/share/man/man3/libssh2_agent_connect.3 b/deps/share/man/man3/libssh2_agent_connect.3 new file mode 100644 index 0000000..1c6ff6d --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_connect.3 @@ -0,0 +1,23 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_connect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_connect - connect to an ssh-agent +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_agent_connect(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Connect to an ssh-agent running on the system. + +Call \fBlibssh2_agent_disconnect(3)\fP to close the connection after +you're doing using it. +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_disconnect(3) + diff --git a/deps/share/man/man3/libssh2_agent_disconnect.3 b/deps/share/man/man3/libssh2_agent_disconnect.3 new file mode 100644 index 0000000..f9f9ef0 --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_disconnect.3 @@ -0,0 +1,20 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_disconnect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_disconnect - close a connection to an ssh-agent +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_agent_disconnect(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Close a connection to an ssh-agent. + +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_connect(3) +.BR libssh2_agent_free(3) diff --git a/deps/share/man/man3/libssh2_agent_free.3 b/deps/share/man/man3/libssh2_agent_free.3 new file mode 100644 index 0000000..197f87e --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_free.3 @@ -0,0 +1,20 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_free 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_free - free an ssh-agent handle +.SH SYNOPSIS +#include <libssh2.h> + +void libssh2_agent_free(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Free an ssh-agent handle. This function also frees the internal +collection of public keys. +.SH RETURN VALUE +None. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_disconnect(3) diff --git a/deps/share/man/man3/libssh2_agent_get_identity.3 b/deps/share/man/man3/libssh2_agent_get_identity.3 new file mode 100644 index 0000000..a944165 --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_get_identity.3 @@ -0,0 +1,34 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_get_identity 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_get_identity - get a public key off the collection of public keys managed by ssh-agent +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_agent_get_identity(LIBSSH2_AGENT *agent, + struct libssh2_agent_publickey **store, + struct libssh2_agent_publickey *prev); +.SH DESCRIPTION +\fIlibssh2_agent_get_identity(3)\fP allows an application to iterate +over all public keys in the collection managed by ssh-agent. + +\fIstore\fP should point to a pointer that gets filled in to point to the +public key data. + +\fIprev\fP is a pointer to a previous 'struct libssh2_agent_publickey' +as returned by a previous invoke of this function, or NULL to get the +first entry in the internal collection. +.SH RETURN VALUE +Returns 0 if everything is fine and information about a host was stored in +the \fIstore\fP struct. + +Returns 1 if it reached the end of public keys. + +Returns negative values for error +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_list_identities(3) +.BR libssh2_agent_userauth(3) diff --git a/deps/share/man/man3/libssh2_agent_get_identity_path.3 b/deps/share/man/man3/libssh2_agent_get_identity_path.3 new file mode 100644 index 0000000..58d6dd5 --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_get_identity_path.3 @@ -0,0 +1,22 @@ +.\" +.\" Copyright (c) 2019 by Will Cosgrove +.\" +.TH libssh2_agent_get_identity_path 3 "6 Mar 2019" "libssh2 1.9" "libssh2 manual" +.SH NAME +libssh2_agent_get_identity_path - gets the custom ssh-agent socket path +.SH SYNOPSIS +#include <libssh2.h> + +const char * +libssh2_agent_get_identity_path(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Returns the custom agent identity socket path if set using libssh2_agent_set_identity_path() + +.SH RETURN VALUE +Returns the socket path on disk. +.SH AVAILABILITY +Added in libssh2 1.9 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_set_identity_path(3) + diff --git a/deps/share/man/man3/libssh2_agent_init.3 b/deps/share/man/man3/libssh2_agent_init.3 new file mode 100644 index 0000000..26e891e --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_init.3 @@ -0,0 +1,26 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_init 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_init - init an ssh-agent handle +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_AGENT *libssh2_agent_init(LIBSSH2_SESSION *session); +.SH DESCRIPTION +Init an ssh-agent handle. Returns the handle to an internal +representation of an ssh-agent connection. After the successful +initialization, an application can call \fBlibssh2_agent_connect(3)\fP +to connect to a running ssh-agent. + +Call \fBlibssh2_agent_free(3)\fP to free the handle again after you're +doing using it. +.SH RETURN VALUE +Returns a handle pointer or NULL if something went wrong. The returned handle +is used as input to all other ssh-agent related functions libssh2 provides. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_connect(3) +.BR libssh2_agent_free(3) diff --git a/deps/share/man/man3/libssh2_agent_list_identities.3 b/deps/share/man/man3/libssh2_agent_list_identities.3 new file mode 100644 index 0000000..e1e4b54 --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_list_identities.3 @@ -0,0 +1,24 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_list_identities 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_list_identities - request an ssh-agent to list of public keys. +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_agent_list_identities(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Request an ssh-agent to list of public keys, and stores them in the +internal collection of the handle. Call +\fIlibssh2_agent_get_identity(3)\fP to get a public key off the +collection. + +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_connect(3) +.BR libssh2_agent_get_identity(3) + diff --git a/deps/share/man/man3/libssh2_agent_set_identity_path.3 b/deps/share/man/man3/libssh2_agent_set_identity_path.3 new file mode 100644 index 0000000..73e1266 --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_set_identity_path.3 @@ -0,0 +1,22 @@ +.\" +.\" Copyright (c) 2019 by Will Cosgrove +.\" +.TH libssh2_agent_set_identity_path 3 "6 Mar 2019" "libssh2 1.9" "libssh2 manual" +.SH NAME +libssh2_agent_set_identity_path - set an ssh-agent socket path on disk +.SH SYNOPSIS +#include <libssh2.h> + +void +libssh2_agent_set_identity_path(LIBSSH2_AGENT *agent, const char *path); +.SH DESCRIPTION +Allows a custom agent identity socket path instead of the default SSH_AUTH_SOCK env value + +.SH RETURN VALUE +Returns void +.SH AVAILABILITY +Added in libssh2 1.9 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_get_identity_path(3) + diff --git a/deps/share/man/man3/libssh2_agent_userauth.3 b/deps/share/man/man3/libssh2_agent_userauth.3 new file mode 100644 index 0000000..3c956fe --- /dev/null +++ b/deps/share/man/man3/libssh2_agent_userauth.3 @@ -0,0 +1,29 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_userauth 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_userauth - authenticate a session with a public key, with the help of ssh-agent +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_agent_userauth(LIBSSH2_AGENT *agent, + const char *username, + struct libssh2_agent_publickey *identity); +.SH DESCRIPTION +\fIagent\fP - ssh-agent handle as returned by +.BR libssh2_agent_init(3) + +\fIusername\fP - Remote user name to authenticate as. + +\fIidentity\fP - Public key to authenticate with, as returned by +.BR libssh2_agent_get_identity(3) + +Attempt public key authentication with the help of ssh-agent. +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_get_identity(3) diff --git a/deps/share/man/man3/libssh2_banner_set.3 b/deps/share/man/man3/libssh2_banner_set.3 new file mode 100644 index 0000000..2baa121 --- /dev/null +++ b/deps/share/man/man3/libssh2_banner_set.3 @@ -0,0 +1,32 @@ +.TH libssh2_banner_set 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_banner_set - set the SSH protocol banner for the local client +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_banner_set(LIBSSH2_SESSION *session, const char *banner); + +.SH DESCRIPTION +This function is \fBDEPRECATED\fP. Use \fIlibssh2_session_banner_set(3)\fP +instead! + +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIbanner\fP - A pointer to a user defined banner + +Set the banner that will be sent to the remote host when the SSH session is +started with +.BR libssh2_session_handshake(3) + This is optional; a banner corresponding to the protocol and libssh2 version will be sent by default. +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH AVAILABILITY +Marked as deprecated since 1.4.0 +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +.SH SEE ALSO +.BR libssh2_session_handshake(3) diff --git a/deps/share/man/man3/libssh2_base64_decode.3 b/deps/share/man/man3/libssh2_base64_decode.3 new file mode 100644 index 0000000..932f03a --- /dev/null +++ b/deps/share/man/man3/libssh2_base64_decode.3 @@ -0,0 +1,25 @@ +.TH libssh2_base64_decode 3 "23 Dec 2008" "libssh2 1.0" "libssh2 manual" +.SH NAME +libssh2_base64_decode - decode a base64 encoded string +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_base64_decode(LIBSSH2_SESSION *session, char **dest, + unsigned int *dest_len, const char *src, + unsigned int src_len); +.SH DESCRIPTION +This function is deemed DEPRECATED and will be removed from libssh2 in a +future version. Don't use it! + +Decode a base64 chunk and store it into a newly allocated buffer. 'dest_len' +will be set to hold the length of the returned buffer that '*dest' will point +to. + +The returned buffer is allocated by this function, but it is not clear how to +free that memory! +.SH BUGS +The memory that *dest points to is allocated by the malloc function libssh2 +uses, but there's no way for an application to free this data in a safe and +reliable way! +.SH RETURN VALUE +0 if successful, \-1 if any error occurred. diff --git a/deps/share/man/man3/libssh2_channel_close.3 b/deps/share/man/man3/libssh2_channel_close.3 new file mode 100644 index 0000000..2fe0a0d --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_close.3 @@ -0,0 +1,29 @@ +.TH libssh2_channel_close 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_close - close a channel +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_close(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +\fIchannel\fP - active channel stream to set closed status on. + +Close an active data channel. In practice this means sending an SSH_MSG_CLOSE +packet to the remote host which serves as instruction that no further data +will be sent to it. The remote host may still send data back until it sends +its own close message in response. To wait for the remote end to close its +connection as well, follow this command with +.BR libssh2_channel_wait_closed(3) + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_direct_tcpip.3 b/deps/share/man/man3/libssh2_channel_direct_tcpip.3 new file mode 100644 index 0000000..742769d --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_direct_tcpip.3 @@ -0,0 +1,18 @@ +.TH libssh2_channel_direct_tcpip 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_direct_tcpip - convenience macro for \fIlibssh2_channel_direct_tcpip_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session, const char *host, int port); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_direct_tcpip_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_direct_tcpip_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_direct_tcpip_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_direct_tcpip_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_direct_tcpip_ex.3 b/deps/share/man/man3/libssh2_channel_direct_tcpip_ex.3 new file mode 100644 index 0000000..481c55c --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_direct_tcpip_ex.3 @@ -0,0 +1,35 @@ +.TH libssh2_channel_direct_tcpip_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_direct_tcpip_ex - Tunnel a TCP connection through an SSH session +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_channel_direct_tcpip_ex(LIBSSH2_SESSION *session, const char *host, int port, const char *shost, int sport); + +LIBSSH2_CHANNEL * +libssh2_channel_direct_tcpip(LIBSSH2_SESSION *session, const char *host, int port); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIhost\fP - Third party host to connect to using the SSH host as a proxy. + +\fIport\fP - Port on third party host to connect to. + +\fIshost\fP - Host to tell the SSH server the connection originated on. + +\fIsport\fP - Port to tell the SSH server the connection originated from. + +Tunnel a TCP/IP connection through the SSH transport via the remote host to +a third party. Communication from the client to the SSH server remains +encrypted, communication from the server to the 3rd party host travels +in cleartext. + +.SH RETURN VALUE +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_eof.3 b/deps/share/man/man3/libssh2_channel_eof.3 new file mode 100644 index 0000000..ed4a074 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_eof.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_eof 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_eof - check a channel's EOF status +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_eof(LIBSSH2_CHANNEL *channel); +.SH DESCRIPTION +\fIchannel\fP - active channel stream to set closed status on. + +Check if the remote host has sent an EOF status for the selected stream. +.SH RETURN VALUE +Returns 1 if the remote host has sent EOF, otherwise 0. Negative on +failure. +.SH SEE ALSO +.BR libssh2_channel_close(3) diff --git a/deps/share/man/man3/libssh2_channel_exec.3 b/deps/share/man/man3/libssh2_channel_exec.3 new file mode 100644 index 0000000..3ab069d --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_exec.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_exec 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_exec - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_exec(LIBSSH2_CHANNEL *channel, const char *command); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_process_startup(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_process_startup(3)\fP +.SH ERRORS +See \fIlibssh2_channel_process_startup(3)\fP +.SH SEE ALSO +.BR libssh2_channel_process_startup(3) diff --git a/deps/share/man/man3/libssh2_channel_flush.3 b/deps/share/man/man3/libssh2_channel_flush.3 new file mode 100644 index 0000000..b449945 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_flush.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_flush 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_flush - convenience macro for \fIlibssh2_channel_flush_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_flush(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_flush_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_flush_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_flush_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_flush_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_flush_ex.3 b/deps/share/man/man3/libssh2_channel_flush_ex.3 new file mode 100644 index 0000000..1885176 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_flush_ex.3 @@ -0,0 +1,32 @@ +.TH libssh2_channel_flush_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_flush_ex - flush a channel +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_flush_ex(LIBSSH2_CHANNEL *channel, int streamid); + +int +libssh2_channel_flush(LIBSSH2_CHANNEL *channel); + +int +libssh2_channel_flush_stderr(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +\fIchannel\fP - Active channel stream to flush. + +\fIstreamid\fP - Specific substream number to flush. Groups of substreams may +be flushed by passing on of the following Constants. +.br +\fBLIBSSH2_CHANNEL_FLUSH_EXTENDED_DATA\fP: Flush all extended data substreams +.br +\fBLIBSSH2_CHANNEL_FLUSH_ALL\fP: Flush all substreams + +Flush the read buffer for a given channel instance. Individual substreams may +be flushed by number or using one of the provided macros. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. diff --git a/deps/share/man/man3/libssh2_channel_flush_stderr.3 b/deps/share/man/man3/libssh2_channel_flush_stderr.3 new file mode 100644 index 0000000..156bb06 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_flush_stderr.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_flush_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_flush_stderr - convenience macro for \fIlibssh2_channel_flush_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_flush_stderr(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_flush_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_flush_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_flush_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_flush_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_forward_accept.3 b/deps/share/man/man3/libssh2_channel_forward_accept.3 new file mode 100644 index 0000000..176ac1c --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_forward_accept.3 @@ -0,0 +1,20 @@ +.TH libssh2_channel_forward_accept 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_forward_accept - accept a queued connection +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_channel_forward_accept(LIBSSH2_LISTENER *listener); + +.SH DESCRIPTION +\fIlistener\fP is a forwarding listener instance as returned by +\fBlibssh2_channel_forward_listen_ex(3)\fP. +.SH RETURN VALUE +A newly allocated channel instance or NULL on failure. +.SH ERRORS +When this function returns NULL use \fIlibssh2_session_last_errno(3)\fP to +extract the error code. If that code is \fILIBSSH2_ERROR_EAGAIN\fP, the +session is set to do non-blocking I/O but the call would block. +.SH SEE ALSO +.BR libssh2_channel_forward_listen_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_forward_cancel.3 b/deps/share/man/man3/libssh2_channel_forward_cancel.3 new file mode 100644 index 0000000..16f826f --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_forward_cancel.3 @@ -0,0 +1,27 @@ +.TH libssh2_channel_forward_cancel 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_forward_cancel - cancel a forwarded TCP port +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_forward_cancel(LIBSSH2_LISTENER *listener); + +.SH DESCRIPTION +\fIlistener\fP - Forwarding listener instance as returned by +.BR libssh2_channel_forward_listen_ex(3) + +Instruct the remote host to stop listening for new connections on a previously requested host/port. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +.SH SEE ALSO +.BR libssh2_channel_forward_listen_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_forward_listen.3 b/deps/share/man/man3/libssh2_channel_forward_listen.3 new file mode 100644 index 0000000..6cb54e7 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_forward_listen.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_forward_listen 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_forward_listen - convenience macro for \fIlibssh2_channel_forward_listen_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_forward_listen(LIBSSH2_SESSION *session, int port); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_forward_listen_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_forward_listen_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_forward_listen_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_forward_listen_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_forward_listen_ex.3 b/deps/share/man/man3/libssh2_channel_forward_listen_ex.3 new file mode 100644 index 0000000..a358f6c --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_forward_listen_ex.3 @@ -0,0 +1,46 @@ +.TH libssh2_channel_forward_listen_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_forward_listen_ex - listen to inbound connections +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_LISTENER * +libssh2_channel_forward_listen_ex(LIBSSH2_SESSION *session, char *host, int port, int *bound_port, int queue_maxsize); + +LIBSSH2_LISTENER * +libssh2_channel_forward_listen(LIBSSH2_SESSION *session, int port); + +.SH DESCRIPTION +Instruct the remote SSH server to begin listening for inbound TCP/IP +connections. New connections will be queued by the library until accepted by +\fIlibssh2_channel_forward_accept(3)\fP. + +\fIsession\fP - instance as returned by libssh2_session_init(). + +\fIhost\fP - specific address to bind to on the remote host. Binding to +0.0.0.0 (default when NULL is passed) will bind to all available addresses. + +\fIport\fP - port to bind to on the remote host. When 0 is passed, the remote +host will select the first available dynamic port. + +\fIbound_port\fP - Populated with the actual port bound on the remote +host. Useful when requesting dynamic port numbers. + +\fIqueue_maxsize\fP - Maximum number of pending connections to queue before +rejecting further attempts. + +\fIlibssh2_channel_forward_listen(3)\fP is a macro. +.SH RETURN VALUE +A newly allocated LIBSSH2_LISTENER instance or NULL on failure. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_PROTO\fP - An invalid SSH protocol response was received on the socket. + +\fILIBSSH2_ERROR_REQUEST_DENIED\fP - The remote server refused the request. + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. +.SH SEE ALSO +.BR libssh2_channel_forward_accept(3) diff --git a/deps/share/man/man3/libssh2_channel_free.3 b/deps/share/man/man3/libssh2_channel_free.3 new file mode 100644 index 0000000..fc76f5a --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_free.3 @@ -0,0 +1,25 @@ +.TH libssh2_channel_free 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_free - free all resources associated with a channel +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_free(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +\fIchannel\fP - Channel stream to free. + +Release all resources associated with a channel stream. If the channel has +not yet been closed with +.BR libssh2_channel_close(3) +, it will be called automatically so that the remote end may know that it +can safely free its own resources. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH SEE ALSO +.BR libssh2_channel_close(3) diff --git a/deps/share/man/man3/libssh2_channel_get_exit_signal.3 b/deps/share/man/man3/libssh2_channel_get_exit_signal.3 new file mode 100644 index 0000000..138e7c7 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_get_exit_signal.3 @@ -0,0 +1,34 @@ +.TH libssh2_channel_get_exit_signal 3 "4 Oct 2010" "libssh2 1.2.8" "libssh2 manual" +.SH NAME +libssh2_channel_get_exit_signal - get the remote exit signal +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_get_exit_signal(LIBSSH2_CHANNEL *channel, char **exitsignal, size_t *exitsignal_len, char **errmsg, size_t *errmsg_len, char **langtag, size_t *langtag_len); + +.SH DESCRIPTION +\fIchannel\fP - Closed channel stream to retrieve exit signal from. + +\fIexitsignal\fP - If not NULL, is populated by reference with the exit signal +(without leading "SIG"). Note that the string is stored in a newly allocated +buffer. If the remote program exited cleanly, the referenced string pointer +will be set to NULL. + +\fIexitsignal_len\fP - If not NULL, is populated by reference with the length +of exitsignal. + +\fIerrmsg\fP - If not NULL, is populated by reference with the error message +(if provided by remote server, if not it will be set to NULL). Note that the +string is stored in a newly allocated buffer. + +\fIerrmsg_len\fP - If not NULL, is populated by reference with the length of errmsg. + +\fIlangtag\fP - If not NULL, is populated by reference with the language tag +(if provided by remote server, if not it will be set to NULL). Note that the +string is stored in a newly allocated buffer. + +\fIlangtag_len\fP - If not NULL, is populated by reference with the length of langtag. + +.SH RETURN VALUE +Numeric error code corresponding to the the Error Code constants. diff --git a/deps/share/man/man3/libssh2_channel_get_exit_status.3 b/deps/share/man/man3/libssh2_channel_get_exit_status.3 new file mode 100644 index 0000000..4a8c9e2 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_get_exit_status.3 @@ -0,0 +1,18 @@ +.TH libssh2_channel_get_exit_status 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_get_exit_status - get the remote exit code +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_get_exit_status(LIBSSH2_CHANNEL* channel) + +.SH DESCRIPTION +\fIchannel\fP - Closed channel stream to retrieve exit status from. + +Returns the exit code raised by the process running on the remote host at +the other end of the named channel. Note that the exit status may not be +available if the remote end has not yet set its status to closed. + +.SH RETURN VALUE +Returns 0 on failure, otherwise the \fIExit Status\fP reported by remote host diff --git a/deps/share/man/man3/libssh2_channel_handle_extended_data.3 b/deps/share/man/man3/libssh2_channel_handle_extended_data.3 new file mode 100644 index 0000000..8ab2488 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_handle_extended_data.3 @@ -0,0 +1,35 @@ +.TH libssh2_channel_handle_extended_data 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_handle_extended_data - set extended data handling mode +.SH SYNOPSIS +#include <libssh2.h> + +void +libssh2_channel_handle_extended_data(LIBSSH2_CHANNEL *channel, int ignore_mode); + +.SH DESCRIPTION +This function is deprecated. Use the +\fIlibssh2_channel_handle_extended_data2(3)\fP function instead! + +\fIchannel\fP - Active channel stream to change extended data handling on. + +\fIignore_mode\fP - One of the three LIBSSH2_CHANNEL_EXTENDED_DATA_* Constants. +.br +\fBLIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL\fP: Queue extended data for eventual +reading +.br +\fBLIBSSH2_CHANNEL_EXTENDED_DATA_MERGE\fP: Treat extended data and ordinary +data the same. Merge all substreams such that calls to +\fIlibssh2_channel_read(3)\fP will pull from all substreams on a +first-in/first-out basis. +.br +\fBLIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE\fP: Discard all extended data as it +arrives. + +Change how a channel deals with extended data packets. By default all extended +data is queued until read by \fIlibssh2_channel_read_ex(3)\fP +.SH RETURN VALUE +None. +.SH SEE ALSO +.BR libssh2_channel_handle_extended_data2(3) +.BR libssh2_channel_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_handle_extended_data2.3 b/deps/share/man/man3/libssh2_channel_handle_extended_data2.3 new file mode 100644 index 0000000..8910d8c --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_handle_extended_data2.3 @@ -0,0 +1,35 @@ +.TH libssh2_channel_handle_extended_data2 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_handle_extended_data2 - set extended data handling mode +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_handle_extended_data2(LIBSSH2_CHANNEL *channel, int ignore_mode); + +.SH DESCRIPTION +\fIchannel\fP - Active channel stream to change extended data handling on. + +\fIignore_mode\fP - One of the three LIBSSH2_CHANNEL_EXTENDED_DATA_* Constants. +.br +\fBLIBSSH2_CHANNEL_EXTENDED_DATA_NORMAL\fP: Queue extended data for eventual +reading +.br +\fBLIBSSH2_CHANNEL_EXTENDED_DATA_MERGE\fP: Treat extended data and ordinary +data the same. Merge all substreams such that calls to +.BR libssh2_channel_read(3) +will pull from all substreams on a first-in/first-out basis. +.br +\fBLIBSSH2_CHANNEL_EXTENDED_DATA_IGNORE\fP: Discard all extended data as it +arrives. + +Change how a channel deals with extended data packets. By default all +extended data is queued until read by +.BR libssh2_channel_read_ex(3) + +.SH RETURN VALUE +Return 0 on success or LIBSSH2_ERROR_EAGAIN when it would otherwise block. + +.SH SEE ALSO +.BR libssh2_channel_handle_extended_data(3) +.BR libssh2_channel_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_ignore_extended_data.3 b/deps/share/man/man3/libssh2_channel_ignore_extended_data.3 new file mode 100644 index 0000000..342c620 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_ignore_extended_data.3 @@ -0,0 +1,20 @@ +.TH libssh2_channel_ignore_extended_data 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_ignore_extended_data - convenience macro for \fIlibssh2_channel_handle_extended_data(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +libssh2_channel_ignore_extended_data(arguments) + +.SH DESCRIPTION +This function is deprecated. Use the +\fIlibssh2_channel_handle_extended_data2(3)\fP function instead! + +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_handle_extended_data(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_handle_extended_data(3)\fP +.SH ERRORS +See \fIlibssh2_channel_handle_extended_data(3)\fP +.SH SEE ALSO +.BR libssh2_channel_handle_extended_data(3) diff --git a/deps/share/man/man3/libssh2_channel_open_ex.3 b/deps/share/man/man3/libssh2_channel_open_ex.3 new file mode 100644 index 0000000..7dec294 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_open_ex.3 @@ -0,0 +1,54 @@ +.TH libssh2_channel_open_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_open_ex - establish a generic session channel +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_channel_open_ex(LIBSSH2_SESSION *session, const char *channel_type, unsigned int channel_type_len, unsigned int window_size, unsigned int packet_size, const char *message, unsigned int message_len); + +LIBSSH2_CHANNEL * +libssh2_channel_open_session(session); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIchannel_type\fP - Channel type to open. Typically one of session, +direct-tcpip, or tcpip-forward. The SSH2 protocol allowed for additional +types including local, custom channel types. + +\fIchannel_type_len\fP - Length of channel_type + +\fIwindow_size\fP - Maximum amount of unacknowledged data remote host is +allowed to send before receiving an SSH_MSG_CHANNEL_WINDOW_ADJUST packet. + +\fIpacket_size\fP - Maximum number of bytes remote host is allowed to send +in a single SSH_MSG_CHANNEL_DATA or SSG_MSG_CHANNEL_EXTENDED_DATA packet. + +\fImessage\fP - Additional data as required by the selected channel_type. + +\fImessage_len\fP - Length of message parameter. + +Allocate a new channel for exchanging data with the server. This method is +typically called through its macroized form: +.BR libssh2_channel_open_session(3) +or via +.BR libssh2_channel_direct_tcpip(3) +or +.BR libssh2_channel_forward_listen(3) + +.SH RETURN VALUE +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_CHANNEL_FAILURE\fP - + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. + +.SH SEE ALSO +Add related functions diff --git a/deps/share/man/man3/libssh2_channel_open_session.3 b/deps/share/man/man3/libssh2_channel_open_session.3 new file mode 100644 index 0000000..4306f4c --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_open_session.3 @@ -0,0 +1,18 @@ +.TH libssh2_channel_open_session 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_open_session - convenience macro for \fIlibssh2_channel_open_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_channel_open_session(LIBSSH2_SESSION *session); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_open_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_open_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_open_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_process_startup.3 b/deps/share/man/man3/libssh2_channel_process_startup.3 new file mode 100644 index 0000000..7c27982 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_process_startup.3 @@ -0,0 +1,38 @@ +.TH libssh2_channel_process_startup 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_process_startup - request a shell on a channel +.SH SYNOPSIS +.nf +#include <libssh2.h> + +int libssh2_channel_process_startup(LIBSSH2_CHANNEL *channel, + const char *request, + unsigned int request_len, + const char *message, + unsigned int message_len); +.SH DESCRIPTION +\fIchannel\fP - Active session channel instance. + +\fIrequest\fP - Type of process to startup. The SSH2 protocol currently +defines shell, exec, and subsystem as standard process services. + +\fIrequest_len\fP - Length of request parameter. + +\fImessage\fP - Request specific message data to include. + +\fImessage_len\fP - Length of message parameter. + +Initiate a request on a session type channel such as returned by +.BR libssh2_channel_open_ex(3) +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_read.3 b/deps/share/man/man3/libssh2_channel_read.3 new file mode 100644 index 0000000..f185716 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_read.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_read 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_read - convenience macro for \fIlibssh2_channel_read_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +ssize_t libssh2_channel_read(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_read_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_read_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_read_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_read_ex.3 b/deps/share/man/man3/libssh2_channel_read_ex.3 new file mode 100644 index 0000000..83d7c3e --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_read_ex.3 @@ -0,0 +1,45 @@ +.TH libssh2_channel_read_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_read_ex - read data from a channel stream +.SH SYNOPSIS +#include <libssh2.h> + +ssize_t +libssh2_channel_read_ex(LIBSSH2_CHANNEL *channel, int stream_id, char *buf, size_t buflen); + +ssize_t +libssh2_channel_read(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen); + +ssize_t +libssh2_channel_read_stderr(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen); + +.SH DESCRIPTION +Attempt to read data from an active channel stream. All channel streams have +one standard I/O substream (stream_id == 0), and may have up to 2^32 extended +data streams as identified by the selected \fIstream_id\fP. The SSH2 protocol +currently defines a stream ID of 1 to be the stderr substream. + +\fIchannel\fP - active channel stream to read from. + +\fIstream_id\fP - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR) + +\fIbuf\fP - pointer to storage buffer to read data into + +\fIbuflen\fP - size of the buf storage + +\fIlibssh2_channel_read(3)\fP and \fIlibssh2_channel_read_stderr(3)\fP are +macros. +.SH RETURN VALUE +Actual number of bytes read or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +Note that a return value of zero (0) can in fact be a legitimate value and +only signals that no payload data was read. It is not an error. +.SH ERRORS +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_CHANNEL_CLOSED\fP - The channel has been closed. + +.SH SEE ALSO +.BR libssh2_poll_channel_read(3) diff --git a/deps/share/man/man3/libssh2_channel_read_stderr.3 b/deps/share/man/man3/libssh2_channel_read_stderr.3 new file mode 100644 index 0000000..9324410 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_read_stderr.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_read_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_read_stderr - convenience macro for \fIlibssh2_channel_read_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +ssize_t libssh2_channel_read_stderr(LIBSSH2_CHANNEL *channel, char *buf, size_t buflen); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_read_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_read_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_read_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_receive_window_adjust.3 b/deps/share/man/man3/libssh2_channel_receive_window_adjust.3 new file mode 100644 index 0000000..a728811 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_receive_window_adjust.3 @@ -0,0 +1,29 @@ +.TH libssh2_channel_receive_window_adjust 3 "15 Mar 2009" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_receive_window_adjust - adjust the channel window +.SH SYNOPSIS +#include <libssh2.h> + +unsigned long +libssh2_channel_receive_window_adjust(LIBSSH2_CHANNEL * channel, + unsigned long adjustment, + unsigned char force); + +.SH DESCRIPTION +This function is deprecated in 1.1. Use +\fIlibssh2_channel_receive_window_adjust2(3)\fP! + +Adjust the receive window for a channel by adjustment bytes. If the amount to +be adjusted is less than LIBSSH2_CHANNEL_MINADJUST and force is 0 the +adjustment amount will be queued for a later packet. +.SH RETURN VALUE +Returns the new size of the receive window (as understood by remote end). Note +that the window value sent over the wire is strictly 32bit, but this API is +made to return a 'long' which may not be 32 bit on all platforms. +.SH ERRORS +In 1.0 and earlier, this function returns LIBSSH2_ERROR_EAGAIN for +non-blocking channels where it would otherwise block. However, that is a +negative number and this function only returns an unsigned value and this then +leads to a very strange value being returned. +.SH SEE ALSO +.BR libssh2_channel_window_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_receive_window_adjust2.3 b/deps/share/man/man3/libssh2_channel_receive_window_adjust2.3 new file mode 100644 index 0000000..dd2fcc1 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_receive_window_adjust2.3 @@ -0,0 +1,27 @@ +.TH libssh2_channel_receive_window_adjust2 3 "26 Mar 2009" "libssh2 1.1" "libssh2 manual" +.SH NAME +libssh2_channel_receive_window_adjust2 - adjust the channel window +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_receive_window_adjust2(LIBSSH2_CHANNEL * channel, + unsigned long adjustment, + unsigned char force, + unsigned int *window); + +.SH DESCRIPTION +Adjust the receive window for a channel by adjustment bytes. If the amount to +be adjusted is less than LIBSSH2_CHANNEL_MINADJUST and force is 0 the +adjustment amount will be queued for a later packet. + +This function stores the new size of the receive window (as understood by +remote end) in the variable 'window' points to. +.SH RETURN VALUE +Return 0 on success and a negative value on error. If used in non-blocking +mode it will return LIBSSH2_ERROR_EAGAIN when it would otherwise block. +.SH ERRORS +.SH AVAILABILITY +Added in libssh2 1.1 since the previous API has deficiencies. +.SH SEE ALSO +.BR libssh2_channel_window_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_request_pty.3 b/deps/share/man/man3/libssh2_channel_request_pty.3 new file mode 100644 index 0000000..f57352b --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_request_pty.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_request_pty 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_request_pty - convenience macro for \fIlibssh2_channel_request_pty_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_request_pty(LIBSSH2_SESSION *session, const char *term); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_request_pty_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_request_pty_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_request_pty_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_request_pty_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_request_pty_ex.3 b/deps/share/man/man3/libssh2_channel_request_pty_ex.3 new file mode 100644 index 0000000..35b5840 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_request_pty_ex.3 @@ -0,0 +1,47 @@ +.TH libssh2_channel_request_pty_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_request_pty_ex - short function description +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_request_pty_ex(LIBSSH2_CHANNEL *channel, const char *term, unsigned int term_len, const char *modes, unsigned int modes_len, int width, int height, int width_px, int height_px); + +int +libssh2_channel_request_pty(LIBSSH2_CHANNEL *channel, char *term); + +.SH DESCRIPTION +\fIchannel\fP - Previously opened channel instance such as returned by +.BR libssh2_channel_open_ex(3) + +\fIterm\fP - Terminal emulation (e.g. vt102, ansi, etc...) + +\fIterm_len\fP - Length of term parameter + +\fImodes\fP - Terminal mode modifier values + +\fImodes_len\fP - Length of modes parameter. + +\fIwidth\fP - Width of pty in characters + +\fIheight\fP - Height of pty in characters + +\fIwidth_px\fP - Width of pty in pixels + +\fIheight_px\fP - Height of pty in pixels + +Request a PTY on an established channel. Note that this does not make sense +for all channel types and may be ignored by the server despite returning +success. +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_request_pty_size.3 b/deps/share/man/man3/libssh2_channel_request_pty_size.3 new file mode 100644 index 0000000..4b0c12d --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_request_pty_size.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_request_pty_size 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_request_pty_size - convenience macro for \fIlibssh2_channel_request_pty_size_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_request_pty_size(LIBSSH2_CHANNEL *channel, int width, int height); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_request_pty_size_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_request_pty_size_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_request_pty_size_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_request_pty_size_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_request_pty_size_ex.3 b/deps/share/man/man3/libssh2_channel_request_pty_size_ex.3 new file mode 100644 index 0000000..b3cd619 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_request_pty_size_ex.3 @@ -0,0 +1,12 @@ +.TH libssh2_channel_request_pty_size_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_request_pty_size_ex - TODO +.SH SYNOPSIS + +.SH DESCRIPTION + +.SH RETURN VALUE + +.SH ERRORS + +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_channel_send_eof.3 b/deps/share/man/man3/libssh2_channel_send_eof.3 new file mode 100644 index 0000000..0e5975a --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_send_eof.3 @@ -0,0 +1,24 @@ +.TH libssh2_channel_send_eof 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_send_eof - send EOF to remote server +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_send_eof(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +Tell the remote host that no further data will be sent on the specified +channel. Processes typically interpret this as a closed stdin descriptor. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +.SH SEE ALSO +.BR libssh2_channel_wait_eof(3) +.BR libssh2_channel_eof(3) diff --git a/deps/share/man/man3/libssh2_channel_set_blocking.3 b/deps/share/man/man3/libssh2_channel_set_blocking.3 new file mode 100644 index 0000000..55ee4ff --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_set_blocking.3 @@ -0,0 +1,23 @@ +.TH libssh2_channel_set_blocking 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_set_blocking - set or clear blocking mode on channel +.SH SYNOPSIS +#include <libssh2.h> + +void +libssh2_channel_set_blocking(LIBSSH2_CHANNEL *channel, int blocking); +.SH DESCRIPTION +\fIchannel\fP - channel stream to set or clean blocking status on. + +\fIblocking\fP - Set to a non-zero value to make the channel block, or zero to +make it non-blocking. + +Currently this is just a short cut call to +.BR libssh2_session_set_blocking(3) +and therefore will affect the session and all channels. +.SH RETURN VALUE +None +.SH SEE ALSO +.BR libssh2_session_set_blocking(3) +.BR libssh2_channel_read_ex(3) +.BR libssh2_channel_write_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_setenv.3 b/deps/share/man/man3/libssh2_channel_setenv.3 new file mode 100644 index 0000000..b30d471 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_setenv.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_setenv 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_setenv - convenience macro for \fIlibssh2_channel_setenv_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_setenv(LIBSSH2_CHANNEL *channel, const char *varname, const char *value); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_setenv_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_setenv_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_setenv_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_setenv_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_setenv_ex.3 b/deps/share/man/man3/libssh2_channel_setenv_ex.3 new file mode 100644 index 0000000..4a5fd3e --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_setenv_ex.3 @@ -0,0 +1,41 @@ +.TH libssh2_channel_setenv_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_setenv_ex - set an environment variable on the channel +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_setenv_ex(LIBSSH2_CHANNEL *channel, char *varname, unsigned int varname_len, const char *value, unsigned int value_len); + +int +libssh2_channel_setenv(LIBSSH2_CHANNEL *channel, char *varname, const char *value); + +.SH DESCRIPTION +\fIchannel\fP - Previously opened channel instance such as returned by +.BR libssh2_channel_open_ex(3) + +\fIvarname\fP - Name of environment variable to set on the remote +channel instance. + +\fIvarname_len\fP - Length of passed varname parameter. + +\fIvalue\fP - Value to set varname to. + +\fIvalue_len\fP - Length of value parameter. + +Set an environment variable in the remote channel's process space. Note that +this does not make sense for all channel types and may be ignored by the +server despite returning success. +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_shell.3 b/deps/share/man/man3/libssh2_channel_shell.3 new file mode 100644 index 0000000..4ba6e69 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_shell.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_shell 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_shell - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_shell(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_process_startup(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_process_startup(3)\fP +.SH ERRORS +See \fIlibssh2_channel_process_startup(3)\fP +.SH SEE ALSO +.BR libssh2_channel_process_startup(3) diff --git a/deps/share/man/man3/libssh2_channel_subsystem.3 b/deps/share/man/man3/libssh2_channel_subsystem.3 new file mode 100644 index 0000000..dd29f2c --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_subsystem.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_subsystem 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_subsystem - convenience macro for \fIlibssh2_channel_process_startup(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_subsystem(LIBSSH2_CHANNEL *channel, const char *subsystem); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_process_startup(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_process_startup(3)\fP +.SH ERRORS +See \fIlibssh2_channel_process_startup(3)\fP +.SH SEE ALSO +.BR libssh2_channel_process_startup(3) diff --git a/deps/share/man/man3/libssh2_channel_wait_closed.3 b/deps/share/man/man3/libssh2_channel_wait_closed.3 new file mode 100644 index 0000000..4471736 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_wait_closed.3 @@ -0,0 +1,22 @@ +.TH libssh2_channel_wait_closed 3 "29 Nov 2007" "libssh2 0.19" "libssh2 manual" +.SH NAME +libssh2_channel_wait_closed - wait for the remote to close the channel +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_wait_closed(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +Enter a temporary blocking state until the remote host closes the named +channel. Typically sent after \fIlibssh2_channel_close(3)\fP in order to +examine the exit status. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN +when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative +number, it isn't really a failure per se. +.SH SEE ALSO +.BR libssh2_channel_send_eof(3) +.BR libssh2_channel_eof(3) +.BR libssh2_channel_wait_eof(3) diff --git a/deps/share/man/man3/libssh2_channel_wait_eof.3 b/deps/share/man/man3/libssh2_channel_wait_eof.3 new file mode 100644 index 0000000..8a3dc47 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_wait_eof.3 @@ -0,0 +1,19 @@ +.TH libssh2_channel_wait_eof 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_wait_eof - wait for the remote to reply to an EOF request +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_wait_eof(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +Wait for the remote end to send EOF. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH SEE ALSO +.BR libssh2_channel_send_eof(3) +.BR libssh2_channel_eof(3) diff --git a/deps/share/man/man3/libssh2_channel_window_read.3 b/deps/share/man/man3/libssh2_channel_window_read.3 new file mode 100644 index 0000000..70938d3 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_window_read.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_window_read 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_window_read - convenience macro for \fIlibssh2_channel_window_read_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +unsigned long libssh2_channel_window_read(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_window_read_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_window_read_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_window_read_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_window_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_window_read_ex.3 b/deps/share/man/man3/libssh2_channel_window_read_ex.3 new file mode 100644 index 0000000..b528096 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_window_read_ex.3 @@ -0,0 +1,24 @@ +.TH libssh2_channel_window_read_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_window_read_ex - Check the status of the read window +.SH SYNOPSIS +#include <libssh2.h> + +unsigned long +libssh2_channel_window_read_ex(LIBSSH2_CHANNEL *channel, + unsigned long *read_avail, + unsigned long *window_size_initial) +.SH DESCRIPTION +Check the status of the read window. Returns the number of bytes which the +remote end may send without overflowing the window limit read_avail (if +passed) will be populated with the number of bytes actually available to be +read window_size_initial (if passed) will be populated with the +window_size_initial as defined by the channel_open request +.SH RETURN VALUE +The number of bytes which the remote end may send without overflowing the +window limit +.SH ERRORS + +.SH SEE ALSO +.BR libssh2_channel_receive_window_adjust(3), +.BR libssh2_channel_window_write_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_window_write.3 b/deps/share/man/man3/libssh2_channel_window_write.3 new file mode 100644 index 0000000..d8c3993 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_window_write.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_window_write 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_window_write - convenience macro for \fIlibssh2_channel_window_write_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +unsigned long libssh2_channel_window_write(LIBSSH2_CHANNEL *channel); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_window_write_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_window_write_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_window_write_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_window_write_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_window_write_ex.3 b/deps/share/man/man3/libssh2_channel_window_write_ex.3 new file mode 100644 index 0000000..d34cd40 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_window_write_ex.3 @@ -0,0 +1,21 @@ +.TH libssh2_channel_window_write_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_window_write_ex - Check the status of the write window +.SH SYNOPSIS +#include <libssh2.h> + +unsigned long +libssh2_channel_window_write_ex(LIBSSH2_CHANNEL *channel, + unsigned long *window_size_initial) +.SH DESCRIPTION +Check the status of the write window Returns the number of bytes which may be +safely written on the channel without blocking. 'window_size_initial' (if +passed) will be populated with the size of the initial window as defined by +the channel_open request +.SH RETURN VALUE +Number of bytes which may be safely written on the channel without blocking. +.SH ERRORS + +.SH SEE ALSO +.BR libssh2_channel_window_read_ex(3), +.BR libssh2_channel_receive_window_adjust(3) diff --git a/deps/share/man/man3/libssh2_channel_write.3 b/deps/share/man/man3/libssh2_channel_write.3 new file mode 100644 index 0000000..b9de747 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_write.3 @@ -0,0 +1,18 @@ +.TH libssh2_channel_write 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_write - convenience macro for \fIlibssh2_channel_write_ex(3)\fP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +ssize_t libssh2_channel_write(LIBSSH2_CHANNEL *channel, const char *buf, size_t buflen); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_write_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_write_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_write_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_write_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_write_ex.3 b/deps/share/man/man3/libssh2_channel_write_ex.3 new file mode 100644 index 0000000..4ef7df1 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_write_ex.3 @@ -0,0 +1,47 @@ +.TH libssh2_channel_write_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_write_ex - write data to a channel stream blocking +.SH SYNOPSIS +.nf +#include <libssh2.h> + +ssize_t libssh2_channel_write_ex(LIBSSH2_CHANNEL *channel, + int stream_id, char *buf, + size_t buflen); +.SH DESCRIPTION +Write data to a channel stream. All channel streams have one standard I/O +substream (stream_id == 0), and may have up to 2^32 extended data streams as +identified by the selected \fIstream_id\fP. The SSH2 protocol currently +defines a stream ID of 1 to be the stderr substream. + +\fIchannel\fP - active channel stream to write to. + +\fIstream_id\fP - substream ID number (e.g. 0 or SSH_EXTENDED_DATA_STDERR) + +\fIbuf\fP - pointer to buffer to write + +\fIbuflen\fP - size of the data to write + +\fIlibssh2_channel_write(3)\fP and \fIlibssh2_channel_write_stderr(3)\fP are +convenience macros for this function. + +\fIlibssh2_channel_write_ex(3)\fP will use as much as possible of the buffer +and put it into a single SSH protocol packet. This means that to get maximum +performance when sending larger files, you should try to always pass in at +least 32K of data to this function. +.SH RETURN VALUE +Actual number of bytes written or negative on failure. +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_CHANNEL_CLOSED\fP - The channel has been closed. + +\fILIBSSH2_ERROR_CHANNEL_EOF_SENT\fP - The channel has been requested to be +closed. +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) +.BR libssh2_channel_read_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_write_stderr.3 b/deps/share/man/man3/libssh2_channel_write_stderr.3 new file mode 100644 index 0000000..ac4d387 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_write_stderr.3 @@ -0,0 +1,18 @@ +.TH libssh2_channel_write_stderr 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_write_stderr - convenience macro for \fIlibssh2_channel_write_ex(3)\fP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +ssize_t libssh2_channel_write_stderr(LIBSSH2_CHANNEL *channel, const char *buf, size_t buflen); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_write_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_write_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_write_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_write_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_x11_req.3 b/deps/share/man/man3/libssh2_channel_x11_req.3 new file mode 100644 index 0000000..c558e40 --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_x11_req.3 @@ -0,0 +1,17 @@ +.TH libssh2_channel_x11_req 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_channel_x11_req - convenience macro for \fIlibssh2_channel_x11_req_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_channel_x11_req(LIBSSH2_CHANNEL *channel, int screen_number); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_channel_x11_req_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_channel_x11_req_ex(3)\fP +.SH ERRORS +See \fIlibssh2_channel_x11_req_ex(3)\fP +.SH SEE ALSO +.BR libssh2_channel_x11_req_ex(3) diff --git a/deps/share/man/man3/libssh2_channel_x11_req_ex.3 b/deps/share/man/man3/libssh2_channel_x11_req_ex.3 new file mode 100644 index 0000000..e0121bd --- /dev/null +++ b/deps/share/man/man3/libssh2_channel_x11_req_ex.3 @@ -0,0 +1,44 @@ +.TH libssh2_channel_x11_req_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_channel_x11_req_ex - request an X11 forwarding channel +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_channel_x11_req_ex(LIBSSH2_CHANNEL *channel, int single_connection, const char *auth_proto, const char *auth_cookie, int screen_number); + +int +libssh2_channel_x11_req(LIBSSH2_CHANNEL *channel, int screen_number); + +.SH DESCRIPTION +\fIchannel\fP - Previously opened channel instance such as returned by +.BR libssh2_channel_open_ex(3) + +\fIsingle_connection\fP - non-zero to only forward a single connection. + +\fIauth_proto\fP - X11 authentication protocol to use + +\fIauth_cookie\fP - the cookie (hexadecimal encoded). + +\fIscreen_number\fP - the XLL screen to forward + +Request an X11 forwarding on \fIchannel\fP. To use X11 forwarding, +.BR libssh2_session_callback_set(3) +must first be called to set \fBLIBSSH2_CALLBACK_X11\fP. This callback will be +invoked when the remote host accepts the X11 forwarding. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_CHANNEL_REQUEST_DENIED\fP - + +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) +.BR libssh2_session_callback_set(3) diff --git a/deps/share/man/man3/libssh2_exit.3 b/deps/share/man/man3/libssh2_exit.3 new file mode 100644 index 0000000..2e7afd7 --- /dev/null +++ b/deps/share/man/man3/libssh2_exit.3 @@ -0,0 +1,14 @@ +.TH libssh2_exit 3 "19 Mar 2010" "libssh2 1.2.5" "libssh2 manual" +.SH NAME +libssh2_exit - global library deinitialization +.SH SYNOPSIS +#include <libssh2.h> + +void +libssh2_exit(void); +.SH DESCRIPTION +Exit the libssh2 functions and free's all memory used internal. +.SH AVAILABILITY +Added in libssh2 1.2.5 +.SH SEE ALSO +.BR libssh2_init(3) diff --git a/deps/share/man/man3/libssh2_free.3 b/deps/share/man/man3/libssh2_free.3 new file mode 100644 index 0000000..30176d5 --- /dev/null +++ b/deps/share/man/man3/libssh2_free.3 @@ -0,0 +1,19 @@ +.TH libssh2_exit 3 "13 Oct 2010" "libssh2 1.2.8" "libssh2 manual" +.SH NAME +libssh2_free - deallocate libssh2 memory +.SH SYNOPSIS +#include <libssh2.h> + +void +libssh2_free(LIBSSH2_SESSION *session, void *ptr); +.SH DESCRIPTION +Deallocate memory allocated by earlier call to libssh2 functions. It +uses the memory allocation callbacks provided by the application, if +any. Otherwise, this will just call free(). + +This function is mostly useful under Windows when libssh2 is linked to +one run-time library and the application to another. +.SH AVAILABILITY +Added in libssh2 1.2.8 +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_hostkey_hash.3 b/deps/share/man/man3/libssh2_hostkey_hash.3 new file mode 100644 index 0000000..d57fc0d --- /dev/null +++ b/deps/share/man/man3/libssh2_hostkey_hash.3 @@ -0,0 +1,26 @@ +.TH libssh2_hostkey_hash 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_hostkey_hash - return a hash of the remote host's key +.SH SYNOPSIS +#include <libssh2.h> + +const char * +libssh2_hostkey_hash(LIBSSH2_SESSION *session, int hash_type); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIhash_type\fP - One of: \fBLIBSSH2_HOSTKEY_HASH_MD5\fP, +\fBLIBSSH2_HOSTKEY_HASH_SHA1\fP or \fBLIBSSH2_HOSTKEY_HASH_SHA256\fP. + +Returns the computed digest of the remote system's hostkey. The length of +the returned string is hash_type specific (e.g. 16 bytes for MD5, +20 bytes for SHA1, 32 bytes for SHA256). +.SH RETURN VALUE +Computed hostkey hash value, or NULL if the information is not available +(either the session has not yet been started up, or the requested hash +algorithm was not available). The hash consists of raw binary bytes, not hex +digits, so it is not directly printable. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_init.3 b/deps/share/man/man3/libssh2_init.3 new file mode 100644 index 0000000..416a789 --- /dev/null +++ b/deps/share/man/man3/libssh2_init.3 @@ -0,0 +1,20 @@ +.TH libssh2_init 3 "19 Mar 2010" "libssh2 1.2.5" "libssh2 manual" +.SH NAME +libssh2_init - global library initialization +.SH SYNOPSIS +#include <libssh2.h> + +#define LIBSSH2_INIT_NO_CRYPTO 0x0001 + +int +libssh2_init(int flags); +.SH DESCRIPTION +Initialize the libssh2 functions. This typically initialize the +crypto library. It uses a global state, and is not thread safe -- you +must make sure this function is not called concurrently. +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2.5 +.SH SEE ALSO +.BR libssh2_exit(3) diff --git a/deps/share/man/man3/libssh2_keepalive_config.3 b/deps/share/man/man3/libssh2_keepalive_config.3 new file mode 100644 index 0000000..15e3ab9 --- /dev/null +++ b/deps/share/man/man3/libssh2_keepalive_config.3 @@ -0,0 +1,27 @@ +.TH libssh2_keepalive_config 3 "12 Apr 2011" "libssh2 1.2.5" "libssh2 manual" +.SH NAME +libssh2_keepalive_config - short function description +.SH SYNOPSIS +#include <libssh2.h> +.nf + +void libssh2_keepalive_config(LIBSSH2_SESSION *session, + int want_reply, + unsigned interval); +.fi +.SH DESCRIPTION +Set how often keepalive messages should be sent. \fBwant_reply\fP indicates +whether the keepalive messages should request a response from the server. +\fBinterval\fP is number of seconds that can pass without any I/O, use 0 (the +default) to disable keepalives. To avoid some busy-loop corner-cases, if you +specify an interval of 1 it will be treated as 2. + +Note that non-blocking applications are responsible for sending the keepalive +messages using \fBlibssh2_keepalive_send(3)\fP. +.SH RETURN VALUE +Nothing +.SH AVAILABILITY +Added in libssh2 1.2.5 +.SH SEE ALSO +.BR libssh2_keepalive_send(3) + diff --git a/deps/share/man/man3/libssh2_keepalive_send.3 b/deps/share/man/man3/libssh2_keepalive_send.3 new file mode 100644 index 0000000..f4f19d1 --- /dev/null +++ b/deps/share/man/man3/libssh2_keepalive_send.3 @@ -0,0 +1,18 @@ +.TH libssh2_keepalive_send 3 "13 Apr 2011" "libssh2 1.2.5" "libssh2 manual" +.SH NAME +libssh2_keepalive_send - short function description +.SH SYNOPSIS +#include <libssh2.h> +.nf + +int libssh2_keepalive_send(LIBSSH2_SESSION *session, + int *seconds_to_next); +.SH DESCRIPTION +Send a keepalive message if needed. \fBseconds_to_next\fP indicates how many +seconds you can sleep after this call before you need to call it again. +.SH RETURN VALUE +Returns 0 on success, or LIBSSH2_ERROR_SOCKET_SEND on I/O errors. +.SH AVAILABILITY +Added in libssh2 1.2.5 +.SH SEE ALSO +.BR libssh2_keepalive_config(3) diff --git a/deps/share/man/man3/libssh2_knownhost_add.3 b/deps/share/man/man3/libssh2_knownhost_add.3 new file mode 100644 index 0000000..00a69e0 --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_add.3 @@ -0,0 +1,66 @@ + +.\" Copyright (c) 2009, 2010 by Daniel Stenberg +.\" +.TH libssh2_knownhost_add 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_add - add a known host +.SH SYNOPSIS +.nf +#include <libssh2.h> + +int libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts, + char *host, char *salt, + char *key, size_t keylen, + int typemask, + struct libssh2_knownhost **store); +.SH DESCRIPTION +We discourage use of this function as of libssh2 1.2.5. Instead we strongly +urge users to use \fIlibssh2_knownhost_addc(3)\fP instead, which as a more +complete API. \fIlibssh2_knownhost_add(3)\fP is subject for removal in a +future release. + +Adds a known host to the collection of known hosts identified by the 'hosts' +handle. + +\fIhost\fP is a pointer the host name in plain text or hashed. If hashed, it +must be provided base64 encoded. The host name can be the IP numerical address +of the host or the full name. + +\fIsalt\P is a pointer to the salt used for the host hashing, if the host is +provided hashed. If the host is provided in plain text, salt has no meaning. +The salt has to be provided base64 encoded with a trailing zero byte. + +\fIkey\fP is a pointer to the key for the given host. + +\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +argument + +\fItypemask\fP is a bitmask that specifies format and info about the data +passed to this function. Specifically, it details what format the host name is, +what format the key is and what key type it is. + +The host name is given as one of the following types: +LIBSSH2_KNOWNHOST_TYPE_PLAIN, LIBSSH2_KNOWNHOST_TYPE_SHA1 or +LIBSSH2_KNOWNHOST_TYPE_CUSTOM. + +The key is encoded using one of the following encodings: +LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. + +The key is using one of these algorithms: +LIBSSH2_KNOWNHOST_KEY_RSA1, LIBSSH2_KNOWNHOST_KEY_SSHRSA or +LIBSSH2_KNOWNHOST_KEY_SSHDSS. + +\fIstore\fP should point to a pointer that gets filled in to point to the +known host data after the addition. NULL can be passed if you don't care about +this pointer. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2, deprecated since libssh2 1.2.5. Use +\fIlibssh2_knownhost_addc(3)\fP instead! +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_check(3) +.BR libssh2_knownhost_addc(3) diff --git a/deps/share/man/man3/libssh2_knownhost_addc.3 b/deps/share/man/man3/libssh2_knownhost_addc.3 new file mode 100644 index 0000000..73e262a --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_addc.3 @@ -0,0 +1,68 @@ + +.\" Copyright (c) 2009, 2010 by Daniel Stenberg +.\" +.TH libssh2_knownhost_add 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_add - add a known host +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_addc(LIBSSH2_KNOWNHOSTS *hosts, + char *host, char *salt, + char *key, size_t keylen, + const char *comment, size_t commentlen, + int typemask, + struct libssh2_knownhost **store); +.SH DESCRIPTION +Adds a known host to the collection of known hosts identified by the 'hosts' +handle. + +\fIhost\fP is a pointer the host name in plain text or hashed. If hashed, it +must be provided base64 encoded. The host name can be the IP numerical address +of the host or the full name. + +If you want to add a key for a specific port number for the given host, you +must provide the host name like '[host]:port' with the actual characters '[' +and ']' enclosing the host name and a colon separating the host part from the +port number. For example: \&"[host.example.com]:222". + +\fIsalt\fP is a pointer to the salt used for the host hashing, if the host is +provided hashed. If the host is provided in plain text, salt has no meaning. +The salt has to be provided base64 encoded with a trailing zero byte. + +\fIkey\fP is a pointer to the key for the given host. + +\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +argument + +\fIcomment\fP is a pointer to a comment for the key. + +\fIcommentlen\fP is the total size in bytes of the comment pointed to by the \fIcomment\fP argument + +\fItypemask\fP is a bitmask that specifies format and info about the data +passed to this function. Specifically, it details what format the host name is, +what format the key is and what key type it is. + +The host name is given as one of the following types: +LIBSSH2_KNOWNHOST_TYPE_PLAIN, LIBSSH2_KNOWNHOST_TYPE_SHA1 or +LIBSSH2_KNOWNHOST_TYPE_CUSTOM. + +The key is encoded using one of the following encodings: +LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. + +The key is using one of these algorithms: +LIBSSH2_KNOWNHOST_KEY_RSA1, LIBSSH2_KNOWNHOST_KEY_SSHRSA or +LIBSSH2_KNOWNHOST_KEY_SSHDSS. + +\fIstore\fP should point to a pointer that gets filled in to point to the +known host data after the addition. NULL can be passed if you don't care about +this pointer. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2.5 +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_check(3) diff --git a/deps/share/man/man3/libssh2_knownhost_check.3 b/deps/share/man/man3/libssh2_knownhost_check.3 new file mode 100644 index 0000000..889392c --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_check.3 @@ -0,0 +1,58 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_check 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_check - check a host+key against the list of known hosts +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_check(LIBSSH2_KNOWNHOSTS *hosts, + const char *host, + const char *key, size_t keylen, + int typemask, + struct libssh2_knownhost **knownhost); +.SH DESCRIPTION +Checks a host and its associated key against the collection of known hosts, +and returns info back about the (partially) matched entry. + +\fIhost\fP is a pointer the host name in plain text. The host name can be the +IP numerical address of the host or the full name. + +\fIkey\fP is a pointer to the key for the given host. + +\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +argument + +\fItypemask\fP is a bitmask that specifies format and info about the data +passed to this function. Specifically, it details what format the host name is, +what format the key is and what key type it is. + +The host name is given as one of the following types: +LIBSSH2_KNOWNHOST_TYPE_PLAIN or LIBSSH2_KNOWNHOST_TYPE_CUSTOM. + +The key is encoded using one of the following encodings: +LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. + +\fIknownhost\fP if set to non-NULL, it must be a pointer to a 'struct +libssh2_knownhost' pointer that gets filled in to point to info about a known +host that matches or partially matches. +.SH RETURN VALUE +\fIlibssh2_knownhost_check(3)\fP returns info about how well the provided +host + key pair matched one of the entries in the list of known hosts. + +LIBSSH2_KNOWNHOST_CHECK_FAILURE - something prevented the check to be made + +LIBSSH2_KNOWNHOST_CHECK_NOTFOUND - no host match was found + +LIBSSH2_KNOWNHOST_CHECK_MATCH - hosts and keys match. + +LIBSSH2_KNOWNHOST_CHECK_MISMATCH - host was found, but the keys didn't match! +.SH AVAILABILITY +Added in libssh2 1.2 +.SH EXAMPLE +See the ssh2_exec.c example as provided in the tarball. +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_add(3) diff --git a/deps/share/man/man3/libssh2_knownhost_checkp.3 b/deps/share/man/man3/libssh2_knownhost_checkp.3 new file mode 100644 index 0000000..434ed7b --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_checkp.3 @@ -0,0 +1,63 @@ +.\" +.\" Copyright (c) 2009-2010 by Daniel Stenberg +.\" +.TH libssh2_knownhost_check 3 "1 May 2010" "libssh2 1.2.6" "libssh2 manual" +.SH NAME +libssh2_knownhost_checkp - check a host+key against the list of known hosts +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_checkp(LIBSSH2_KNOWNHOSTS *hosts, + const char *host, int port, + const char *key, size_t keylen, + int typemask, + struct libssh2_knownhost **knownhost); +.SH DESCRIPTION +Checks a host and its associated key against the collection of known hosts, +and returns info back about the (partially) matched entry. + +\fIhost\fP is a pointer the host name in plain text. The host name can be the +IP numerical address of the host or the full name. + +\fIport\fP is the port number used by the host (or a negative number +to check the generic host). If the port number is given, libssh2 will +check the key for the specific host + port number combination in +addition to the plain host name only check. + +\fIkey\fP is a pointer to the key for the given host. + +\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +argument + +\fItypemask\fP is a bitmask that specifies format and info about the data +passed to this function. Specifically, it details what format the host name is, +what format the key is and what key type it is. + +The host name is given as one of the following types: +LIBSSH2_KNOWNHOST_TYPE_PLAIN or LIBSSH2_KNOWNHOST_TYPE_CUSTOM. + +The key is encoded using one of the following encodings: +LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. + +\fIknownhost\fP if set to non-NULL, it must be a pointer to a 'struct +libssh2_knownhost' pointer that gets filled in to point to info about a known +host that matches or partially matches. +.SH RETURN VALUE +\fIlibssh2_knownhost_check(3)\fP returns info about how well the provided +host + key pair matched one of the entries in the list of known hosts. + +LIBSSH2_KNOWNHOST_CHECK_FAILURE - something prevented the check to be made + +LIBSSH2_KNOWNHOST_CHECK_NOTFOUND - no host match was found + +LIBSSH2_KNOWNHOST_CHECK_MATCH - hosts and keys match. + +LIBSSH2_KNOWNHOST_CHECK_MISMATCH - host was found, but the keys didn't match! +.SH AVAILABILITY +Added in libssh2 1.2.6 +.SH EXAMPLE +See the ssh2_exec.c example as provided in the tarball. +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_add(3) diff --git a/deps/share/man/man3/libssh2_knownhost_del.3 b/deps/share/man/man3/libssh2_knownhost_del.3 new file mode 100644 index 0000000..75a8eaf --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_del.3 @@ -0,0 +1,26 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_del 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_del - delete a known host entry +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_del(LIBSSH2_KNOWNHOSTS *hosts, + struct libssh2_knownhost *entry); +.SH DESCRIPTION +Delete a known host entry from the collection of known hosts. + +\fIentry\fP is a pointer to a struct that you can extract with +\fIlibssh2_knownhost_check(3)\fP or \fIlibssh2_knownhost_get(3)\fP. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_add(3) +.BR libssh2_knownhost_check(3) diff --git a/deps/share/man/man3/libssh2_knownhost_free.3 b/deps/share/man/man3/libssh2_knownhost_free.3 new file mode 100644 index 0000000..8d8bcc2 --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_free.3 @@ -0,0 +1,20 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_free 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_free - free a collection of known hosts +.SH SYNOPSIS +#include <libssh2.h> + +void libssh2_knownhost_free(LIBSSH2_KNOWNHOSTS *hosts); +.SH DESCRIPTION +Free a collection of known hosts. +.SH RETURN VALUE +None. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_add(3) +.BR libssh2_knownhost_check(3) diff --git a/deps/share/man/man3/libssh2_knownhost_get.3 b/deps/share/man/man3/libssh2_knownhost_get.3 new file mode 100644 index 0000000..d725f8d --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_get.3 @@ -0,0 +1,35 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_get 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_get - get a known host off the collection of known hosts +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_get(LIBSSH2_KNOWNHOSTS *hosts, + struct libssh2_knownhost **store, + struct libssh2_knownhost *prev): +.SH DESCRIPTION +\fIlibssh2_knownhost_get(3)\fP allows an application to iterate over all known +hosts in the collection. + +\fIstore\fP should point to a pointer that gets filled in to point to the +known host data. + +\fIprev\fP is a pointer to a previous 'struct libssh2_knownhost' as returned +by a previous invoke of this function, or NULL to get the first entry in the +internal collection. +.SH RETURN VALUE +Returns 0 if everything is fine and information about a host was stored in +the \fIstore\fP struct. + +Returns 1 if it reached the end of hosts. + +Returns negative values for error +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_readfile(3) +.BR libssh2_knownhost_writefile(3) +.BR libssh2_knownhost_add(3) diff --git a/deps/share/man/man3/libssh2_knownhost_init.3 b/deps/share/man/man3/libssh2_knownhost_init.3 new file mode 100644 index 0000000..145f10c --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_init.3 @@ -0,0 +1,25 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_init 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_init - init a collection of known hosts +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_KNOWNHOSTS *libssh2_knownhost_init(LIBSSH2_SESSION *session); +.SH DESCRIPTION +Init a collection of known hosts for this session. Returns the handle to an +internal representation of a known host collection. + +Call \fBlibssh2_knownhost_free(3)\fP to free the collection again after you're +doing using it. +.SH RETURN VALUE +Returns a handle pointer or NULL if something went wrong. The returned handle +is used as input to all other known host related functions libssh2 provides. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_add(3) +.BR libssh2_knownhost_check(3) diff --git a/deps/share/man/man3/libssh2_knownhost_readfile.3 b/deps/share/man/man3/libssh2_knownhost_readfile.3 new file mode 100644 index 0000000..68aa940 --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_readfile.3 @@ -0,0 +1,29 @@ +.\" +.\" Copyright (c) 2009-2011 by Daniel Stenberg +.\" +.TH libssh2_knownhost_readfile 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_readfile - parse a file of known hosts +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_readfile(LIBSSH2_KNOWNHOSTS *hosts, + const char *filename, int type); +.SH DESCRIPTION +Reads a collection of known hosts from a specified file and adds them to the +collection of known hosts. + +\fIfilename\fP specifies which file to read + +\fItype\fP specifies what file type it is, and +\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +format. This file is normally found named ~/.ssh/known_hosts +.SH RETURN VALUE +Returns a negative value, a regular libssh2 error code for errors, or a +positive number as number of parsed known hosts in the file. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_check(3) diff --git a/deps/share/man/man3/libssh2_knownhost_readline.3 b/deps/share/man/man3/libssh2_knownhost_readline.3 new file mode 100644 index 0000000..a5881c4 --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_readline.3 @@ -0,0 +1,30 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_readline 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_readline - read a known host line +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_readline(LIBSSH2_KNOWNHOSTS *hosts, + const char *line, size_t len, int type): +.SH DESCRIPTION +Tell libssh2 to read a buffer as it if is a line from a known hosts file. + +\fIline\fP points to the start of the line + +\fIlen\fP is the length of the line in bytes + +\fItype\fP specifies what file type it is, and +\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +format. This file is normally found named ~/.ssh/known_hosts +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_get(3) +.BR libssh2_knownhost_writeline(3) +.BR libssh2_knownhost_readfile(3) diff --git a/deps/share/man/man3/libssh2_knownhost_writefile.3 b/deps/share/man/man3/libssh2_knownhost_writefile.3 new file mode 100644 index 0000000..48335a0 --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_writefile.3 @@ -0,0 +1,29 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_writefile 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_writefile - write a collection of known hosts to a file +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_knownhost_writefile(LIBSSH2_KNOWNHOSTS *hosts, + const char *filename, int type); +.SH DESCRIPTION +Writes all the known hosts to the specified file using the specified file +format. + +\fIfilename\fP specifies what filename to create + +\fItype\fP specifies what file type it is, and +\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +format. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_readfile(3) +.BR libssh2_knownhost_add(3) + diff --git a/deps/share/man/man3/libssh2_knownhost_writeline.3 b/deps/share/man/man3/libssh2_knownhost_writeline.3 new file mode 100644 index 0000000..c014a6a --- /dev/null +++ b/deps/share/man/man3/libssh2_knownhost_writeline.3 @@ -0,0 +1,46 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_writeline 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_writeline - convert a known host to a line for storage +.SH SYNOPSIS +#include <libssh2.h> + +libssh2_knownhost_writeline(LIBSSH2_KNOWNHOSTS *hosts, + struct libssh2_knownhost *known, + char *buffer, size_t buflen, + size_t *outlen, + int type); +.SH DESCRIPTION +Converts a single known host to a single line of output for storage, using +the 'type' output format. + +\fIknown\fP identifies which particular known host + +\fIbuffer\fP points to an allocated buffer + +\fIbuflen\fP is the size of the \fIbuffer\fP. See RETURN VALUE about the size. + +\fIoutlen\fP must be a pointer to a size_t variable that will get the output +length of the stored data chunk. The number does not included the trailing +zero! + +\fItype\fP specifies what file type it is, and +\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +format. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. + +If the provided buffer is deemed too small to fit the data libssh2 wants to +store in it, LIBSSH2_ERROR_BUFFER_TOO_SMALL will be returned. The application +is then advised to call the function again with a larger buffer. The +\fIoutlen\fP size will then hold the requested size. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_get(3) +.BR libssh2_knownhost_readline(3) +.BR libssh2_knownhost_writefile(3) + diff --git a/deps/share/man/man3/libssh2_poll.3 b/deps/share/man/man3/libssh2_poll.3 new file mode 100644 index 0000000..6656945 --- /dev/null +++ b/deps/share/man/man3/libssh2_poll.3 @@ -0,0 +1,21 @@ +.TH libssh2_poll 3 "14 Dec 2006" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_poll - poll for activity on a socket, channel or listener +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_poll(LIBSSH2_POLLFD *fds, unsigned int nfds, long timeout); +.SH DESCRIPTION +This function is deprecated. Do note use. We encourage users to instead use +the \fIpoll(3)\fP or \fIselect(3)\fP functions to check for socket activity or +when specific sockets are ready to get received from or send to. + +Poll for activity on a socket, channel, listener, or any combination of these +three types. The calling semantics for this function generally match +\fIpoll(2)\fP however the structure of fds is somewhat more complex in order +to accommodate the disparate datatypes, POLLFD constants have been namespaced +to avoid platform discrepancies, and revents has additional values defined. +.SH "RETURN VALUE" +Number of fds with interesting events. +.SH SEE ALSO +.BR libssh2_poll_channel_read(3) diff --git a/deps/share/man/man3/libssh2_poll_channel_read.3 b/deps/share/man/man3/libssh2_poll_channel_read.3 new file mode 100644 index 0000000..207275b --- /dev/null +++ b/deps/share/man/man3/libssh2_poll_channel_read.3 @@ -0,0 +1,18 @@ +.TH libssh2_poll_channel_read 3 "14 Dec 2006" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_poll_channel_read - check if data is available +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_poll_channel_read(LIBSSH2_CHANNEL *channel, int extended); +.SH DESCRIPTION +This function is deprecated. Do note use. + +\fIlibssh2_poll_channel_read(3)\fP checks to see if data is available in the +\fIchannel\fP's read buffer. No attempt is made with this method to see if +packets are available to be processed. For full polling support, use +\fIlibssh2_poll(3)\fP. +.SH RETURN VALUE +Returns 1 when data is available and 0 otherwise. +.SH SEE ALSO +.BR libssh2_poll(3) diff --git a/deps/share/man/man3/libssh2_publickey_add.3 b/deps/share/man/man3/libssh2_publickey_add.3 new file mode 100644 index 0000000..666cd94 --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_add.3 @@ -0,0 +1,20 @@ +.TH libssh2_publickey_add 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_publickey_add - convenience macro for \fIlibssh2_publickey_add_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_publickey_add(LIBSSH2_PUBLICKEY *pkey, + const unsigned char *name, + const unsigned char *blob, unsigned long blob_len, char overwrite, + unsigned long num_attrs, const libssh2_publickey_attribute attrs[]); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_publickey_add_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_publickey_add_ex(3)\fP +.SH ERRORS +See \fIlibssh2_publickey_add_ex(3)\fP +.SH SEE ALSO +.BR libssh2_publickey_add_ex(3) diff --git a/deps/share/man/man3/libssh2_publickey_add_ex.3 b/deps/share/man/man3/libssh2_publickey_add_ex.3 new file mode 100644 index 0000000..5c01d23 --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_add_ex.3 @@ -0,0 +1,25 @@ +.TH libssh2_publickey_add_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_publickey_add_ex - Add a public key entry +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_publickey_add_ex(LIBSSH2_PUBLICKEY *pkey, const unsigned char *name, + unsigned long name_len, const unsigned char *blob, + unsigned long blob_len, char overwrite, + unsigned long num_attrs, + const libssh2_publickey_attribute attrs[]) + +.SH DESCRIPTION +TBD +.SH RETURN VALUE +Returns 0 on success, negative on failure. +.SH ERRORS +LIBSSH2_ERROR_BAD_USE +LIBSSH2_ERROR_ALLOC, +LIBSSH2_ERROR_EAGAIN +LIBSSH2_ERROR_SOCKET_SEND, +LIBSSH2_ERROR_SOCKET_TIMEOUT, +LIBSSH2_ERROR_PUBLICKEY_PROTOCOL, +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_publickey_init.3 b/deps/share/man/man3/libssh2_publickey_init.3 new file mode 100644 index 0000000..448eb71 --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_init.3 @@ -0,0 +1,12 @@ +.TH libssh2_publickey_init 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_publickey_init - TODO +.SH SYNOPSIS + +.SH DESCRIPTION + +.SH RETURN VALUE + +.SH ERRORS + +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_publickey_list_fetch.3 b/deps/share/man/man3/libssh2_publickey_list_fetch.3 new file mode 100644 index 0000000..07a7024 --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_list_fetch.3 @@ -0,0 +1,12 @@ +.TH libssh2_publickey_list_fetch 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_publickey_list_fetch - TODO +.SH SYNOPSIS + +.SH DESCRIPTION + +.SH RETURN VALUE + +.SH ERRORS + +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_publickey_list_free.3 b/deps/share/man/man3/libssh2_publickey_list_free.3 new file mode 100644 index 0000000..d50e935 --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_list_free.3 @@ -0,0 +1,12 @@ +.TH libssh2_publickey_list_free 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_publickey_list_free - TODO +.SH SYNOPSIS + +.SH DESCRIPTION + +.SH RETURN VALUE + +.SH ERRORS + +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_publickey_remove.3 b/deps/share/man/man3/libssh2_publickey_remove.3 new file mode 100644 index 0000000..874fdbe --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_remove.3 @@ -0,0 +1,19 @@ +.TH libssh2_publickey_remove 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_publickey_remove - convenience macro for \fIlibssh2_publickey_remove_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_publickey_remove(LIBSSH2_PUBLICKEY *pkey, + const unsigned char *name, unsigned long name_len, + const unsigned char *blob, unsigned long blob_len); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_publickey_remove_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_publickey_remove_ex(3)\fP +.SH ERRORS +See \fIlibssh2_publickey_remove_ex(3)\fP +.SH SEE ALSO +.BR libssh2_publickey_remove_ex(3) diff --git a/deps/share/man/man3/libssh2_publickey_remove_ex.3 b/deps/share/man/man3/libssh2_publickey_remove_ex.3 new file mode 100644 index 0000000..a6cba50 --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_remove_ex.3 @@ -0,0 +1,12 @@ +.TH libssh2_publickey_list_remove_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_publickey_list_remove_ex - TODO +.SH SYNOPSIS + +.SH DESCRIPTION + +.SH RETURN VALUE + +.SH ERRORS + +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_publickey_shutdown.3 b/deps/share/man/man3/libssh2_publickey_shutdown.3 new file mode 100644 index 0000000..fe67a76 --- /dev/null +++ b/deps/share/man/man3/libssh2_publickey_shutdown.3 @@ -0,0 +1,12 @@ +.TH libssh2_publickey_shutdown 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_publickey_shutdown - TODO +.SH SYNOPSIS + +.SH DESCRIPTION + +.SH RETURN VALUE + +.SH ERRORS + +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_scp_recv.3 b/deps/share/man/man3/libssh2_scp_recv.3 new file mode 100644 index 0000000..2edcdd4 --- /dev/null +++ b/deps/share/man/man3/libssh2_scp_recv.3 @@ -0,0 +1,35 @@ +.TH libssh2_scp_recv 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_scp_recv - request a remote file via SCP +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_scp_recv(LIBSSH2_SESSION *session, const char *path, struct stat *sb); + +.SH DESCRIPTION +This function is \fBDEPRECATED\fP. Use \fIlibssh2_scp_recv2(3)\fP +instead! + +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIpath\fP - Full path and filename of file to transfer. That is the remote +file name. + +\fIsb\fP - Populated with remote file's size, mode, mtime, and atime + +Request a file from the remote host via SCP. +.SH RETURN VALUE +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +block. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) +.BR libssh2_channel_open_ex(3) + diff --git a/deps/share/man/man3/libssh2_scp_recv2.3 b/deps/share/man/man3/libssh2_scp_recv2.3 new file mode 100644 index 0000000..6b48fd1 --- /dev/null +++ b/deps/share/man/man3/libssh2_scp_recv2.3 @@ -0,0 +1,32 @@ +.TH libssh2_scp_recv2 3 "29 Jun 2015" "libssh2 1.6.1" "libssh2 manual" +.SH NAME +libssh2_scp_recv2 - request a remote file via SCP +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_scp_recv2(LIBSSH2_SESSION *session, const char *path, struct_stat *sb); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIpath\fP - Full path and filename of file to transfer. That is the remote +file name. + +\fIsb\fP - Populated with remote file's size, mode, mtime, and atime + +Request a file from the remote host via SCP. +.SH RETURN VALUE +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +block. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) +.BR libssh2_channel_open_ex(3) + diff --git a/deps/share/man/man3/libssh2_scp_send.3 b/deps/share/man/man3/libssh2_scp_send.3 new file mode 100644 index 0000000..5e29347 --- /dev/null +++ b/deps/share/man/man3/libssh2_scp_send.3 @@ -0,0 +1,18 @@ +.TH libssh2_scp_send 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_scp_send - convenience macro for \fIlibssh2_scp_send_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_scp_send(LIBSSH2_SESSION *session, const char *path, int mode, size_t size); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_scp_send_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_scp_send_ex(3)\fP +.SH ERRORS +See \fIlibssh2_scp_send_ex(3)\fP +.SH SEE ALSO +.BR libssh2_scp_send_ex(3) diff --git a/deps/share/man/man3/libssh2_scp_send64.3 b/deps/share/man/man3/libssh2_scp_send64.3 new file mode 100644 index 0000000..98d7e74 --- /dev/null +++ b/deps/share/man/man3/libssh2_scp_send64.3 @@ -0,0 +1,47 @@ +.TH libssh2_scp_send64 3 "17 Apr 2010" "libssh2 1.2.6" "libssh2 manual" +.SH NAME +libssh2_scp_send64 - Send a file via SCP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_scp_send64(LIBSSH2_SESSION *session, const char *path, int mode, + libssh2_uint64_t size, time_t mtime, time_t atime); +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIpath\fP - Full path and filename of file to transfer to. That is the remote +file name. + +\fImode\fP - File access mode to create file with + +\fIsize\fP - Size of file being transmitted (Must be known ahead of +time). Note that this needs to be passed on as variable type +libssh2_uint64_t. This type is 64 bit on modern operating systems and +compilers. + +\fImtime\fP - mtime to assign to file being created + +\fIatime\fP - atime to assign to file being created (Set this and +mtime to zero to instruct remote host to use current time). + +Send a file to the remote host via SCP. +.SH RETURN VALUE +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +block. +.SH AVAILABILITY +This function was added in libssh2 1.2.6 and is meant to replace the former +\fIlibssh2_scp_send_ex(3)\fP function. +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) diff --git a/deps/share/man/man3/libssh2_scp_send_ex.3 b/deps/share/man/man3/libssh2_scp_send_ex.3 new file mode 100644 index 0000000..8de7083 --- /dev/null +++ b/deps/share/man/man3/libssh2_scp_send_ex.3 @@ -0,0 +1,48 @@ +.TH libssh2_scp_send_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_scp_send_ex - Send a file via SCP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +LIBSSH2_CHANNEL * +libssh2_scp_send_ex(LIBSSH2_SESSION *session, const char *path, int mode, + size_t size, long mtime, long atime); +.SH DESCRIPTION +This function has been deemed deprecated since libssh2 1.2.6. See +\fIlibssh2_scp_send64(3)\fP. + +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIpath\fP - Full path and filename of file to transfer to. That is the remote +file name. + +\fImode\fP - File access mode to create file with + +\fIsize\fP - Size of file being transmitted (Must be known +ahead of time precisely) + +\fImtime\fP - mtime to assign to file being created + +\fIatime\fP - atime to assign to file being created (Set this and +mtime to zero to instruct remote host to use current time). + +Send a file to the remote host via SCP. +.SH RETURN VALUE +Pointer to a newly allocated LIBSSH2_CHANNEL instance, or NULL on errors. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SCP_PROTOCOL\fP - + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +block. +.SH AVAILABILITY +This function was marked deprecated in libssh2 1.2.6 as + \fIlibssh2_scp_send64(3)\fP has been introduced to replace this function. +.SH SEE ALSO +.BR libssh2_channel_open_ex(3) diff --git a/deps/share/man/man3/libssh2_session_abstract.3 b/deps/share/man/man3/libssh2_session_abstract.3 new file mode 100644 index 0000000..d880b09 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_abstract.3 @@ -0,0 +1,24 @@ +.TH libssh2_session_abstract 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_abstract - return a pointer to a session's abstract pointer +.SH SYNOPSIS +#include <libssh2.h> + +void ** +libssh2_session_abstract(LIBSSH2_SESSION *session); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +Return a pointer to where the abstract pointer provided to +\fBlibssh2_session_init_ex(3)\fP is stored. By providing a doubly +de-referenced pointer, the internal storage of the session instance may be +modified in place. + +.SH RETURN VALUE +A pointer to session internal storage who's contents point to previously +provided abstract data. + +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_banner_get.3 b/deps/share/man/man3/libssh2_session_banner_get.3 new file mode 100644 index 0000000..e253aa1 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_banner_get.3 @@ -0,0 +1,21 @@ +.TH libssh2_session_banner_get 3 "9 Sep 2011" "libssh2 1.4.0" "libssh2 manual" +.SH NAME +libssh2_session_banner_get - get the remote banner +.SH SYNOPSIS +#include <libssh2.h> + +const char *libssh2_session_banner_get(oLIBSSH2_SESSION *session); +.SH DESCRIPTION +Once the session has been setup and \fIlibssh2_session_handshake(3)\fP has +completed successfully, this function can be used to get the server id from +the banner each server presents. +.SH RETURN VALUE +A pointer to a string or NULL if something failed. The data pointed to will be +allocated and associated to the session handle and will be freed by libssh2 +when \fIlibssh2_session_free(3)\fP is used. +.SH AVAILABILITY +Added in 1.4.0 +.SH SEE ALSO +.BR libssh2_session_banner_set(3), +.BR libssh2_session_handshake(3), +.BR libssh2_session_free(3) diff --git a/deps/share/man/man3/libssh2_session_banner_set.3 b/deps/share/man/man3/libssh2_session_banner_set.3 new file mode 100644 index 0000000..5e4161e --- /dev/null +++ b/deps/share/man/man3/libssh2_session_banner_set.3 @@ -0,0 +1,32 @@ +.TH libssh2_session_banner_set 3 "9 Sep 2011" "libssh2 1.4.0" "libssh2 manual" +.SH NAME +libssh2_session_banner_set - set the SSH protocol banner for the local client +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_banner_set(LIBSSH2_SESSION *session, const char *banner); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIbanner\fP - A pointer to a zero-terminated string holding the user defined +banner + +Set the banner that will be sent to the remote host when the SSH session is +started with \fIlibssh2_session_handshake(3)\fP This is optional; a banner +corresponding to the protocol and libssh2 version will be sent by default. +.SH RETURN VALUE +Returns 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN +when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative +number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. +.SH AVAILABILITY +Added in 1.4.0. + +Before 1.4.0 this function was known as libssh2_banner_set(3) +.SH SEE ALSO +.BR libssh2_session_handshake(3), +.BR libssh2_session_banner_get(3) diff --git a/deps/share/man/man3/libssh2_session_block_directions.3 b/deps/share/man/man3/libssh2_session_block_directions.3 new file mode 100644 index 0000000..48ffca3 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_block_directions.3 @@ -0,0 +1,29 @@ +.TH libssh2_session_block_directions 3 "1 Oct 2008" "libssh2 1.0" "libssh2 manual" +.SH NAME +libssh2_session_block_directions - get directions to wait for +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_block_directions(LIBSSH2_SESSION *session); +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by \fBlibssh2_session_init_ex(3)\fP + +When any of libssh2 functions return \fBLIBSSH2_ERROR_EAGAIN\fP an application +should wait for the socket to have data available for reading or +writing. Depending on the return value of +\fIlibssh2_session_block_directions(3)\fP an application should wait for read, +write or both. +.SH RETURN VALUE +Returns the set of directions as a binary mask. Can be a combination of: + +LIBSSH2_SESSION_BLOCK_INBOUND: Inbound direction blocked. + +LIBSSH2_SESSION_BLOCK_OUTBOUND: Outbound direction blocked. + +Application should wait for data to be available for socket prior to calling a +libssh2 function again. If \fBLIBSSH2_SESSION_BLOCK_INBOUND\fP is set select +should contain the session socket in readfds set. Correspondingly in case of +\fBLIBSSH2_SESSION_BLOCK_OUTBOUND\fP writefds set should contain the socket. +.SH AVAILABILITY +Added in 1.0 diff --git a/deps/share/man/man3/libssh2_session_callback_set.3 b/deps/share/man/man3/libssh2_session_callback_set.3 new file mode 100644 index 0000000..3901f88 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_callback_set.3 @@ -0,0 +1,44 @@ +.TH libssh2_session_callback_set 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_callback_set - set a callback function +.SH SYNOPSIS +.nf +#include <libssh2.h> + +void *libssh2_session_callback_set(LIBSSH2_SESSION *session, + int cbtype, void *callback); +.SH DESCRIPTION +Sets a custom callback handler for a previously initialized session +object. Callbacks are triggered by the receipt of special packets at the +Transport layer. To disable a callback, set it to NULL. + +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIcbtype\fP - Callback type. One of the types listed in Callback Types. + +\fIcallback\fP - Pointer to custom callback function. The prototype for +this function must match the associated callback declaration macro. +.SH CALLBACK TYPES +.IP LIBSSH2_CALLBACK_IGNORE +Called when a SSH_MSG_IGNORE message is received +.IP LIBSSH2_CALLBACK_DEBUG +Called when a SSH_MSG_DEBUG message is received +.IP LIBSSH2_CALLBACK_DISCONNECT +Called when a SSH_MSG_DISCONNECT message is received +.IP LIBSSH2_CALLBACK_MACERROR +Called when a mismatched MAC has been detected in the transport layer. If the +function returns 0, the packet will be accepted nonetheless. +.IP LIBSSH2_CALLBACK_X11 +Called when an X11 connection has been accepted +.IP LIBSSH2_CALLBACK_SEND +Called when libssh2 wants to send some data on the connection. +Can be set to a custom function to handle I/O your own way. +.IP LIBSSH2_CALLBACK_RECV +Called when libssh2 wants to receive some data from the connection. +Can be set to a custom function to handle I/O your own way. +.SH RETURN VALUE +Pointer to previous callback handler. Returns NULL if no prior callback +handler was set or the callback type was unknown. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_disconnect.3 b/deps/share/man/man3/libssh2_session_disconnect.3 new file mode 100644 index 0000000..32d5e87 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_disconnect.3 @@ -0,0 +1,17 @@ +.TH libssh2_session_disconnect 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_session_disconnect - convenience macro for \fIlibssh2_session_disconnect_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_session_disconnect(LIBSSH2_SESSION *session, const char *description); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_session_disconnect_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_session_disconnect_ex(3)\fP +.SH ERRORS +See \fIlibssh2_session_disconnect_ex(3)\fP +.SH SEE ALSO +.BR libssh2_session_disconnect_ex(3) diff --git a/deps/share/man/man3/libssh2_session_disconnect_ex.3 b/deps/share/man/man3/libssh2_session_disconnect_ex.3 new file mode 100644 index 0000000..82174f9 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_disconnect_ex.3 @@ -0,0 +1,38 @@ +.TH libssh2_session_disconnect_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_disconnect_ex - terminate transport layer +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_disconnect_ex(LIBSSH2_SESSION *session, int reason, const char *description, const char *lang); + +int +libssh2_session_disconnect(LIBSSH2_SESSION *session, const char *description); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIreason\fP - One of the Disconnect Reason constants. + +\fIdescription\fP - Human readable reason for disconnection. + +\fIlang\fP - Localization string describing the language/encoding of the description provided. + +Send a disconnect message to the remote host associated with \fIsession\fP, +along with a \fIreason\fP symbol and a verbose \fIdescription\fP. + +As a convenience, the macro +.BR libssh2_session_disconnect(3) +is provided. It calls +.BR libssh2_session_disconnect_ex(3) +with \fIreason\fP set to SSH_DISCONNECT_BY_APPLICATION +and \fIlang\fP set to an empty string. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_flag.3 b/deps/share/man/man3/libssh2_session_flag.3 new file mode 100644 index 0000000..3a9e5e5 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_flag.3 @@ -0,0 +1,23 @@ +.TH libssh2_session_flag 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_flag - TODO +.SH SYNOPSIS +int +libssh2_session_flag(LIBSSH2_SESSION *session, int flag, int value); +.SH DESCRIPTION +Set options for the created session. \fIflag\fP is the option to set, while +\fIvalue\fP is typically set to 1 or 0 to enable or disable the option. +.SH FLAGS +.IP LIBSSH2_FLAG_SIGPIPE +If set, libssh2 will not attempt to block SIGPIPEs but will let them trigger +from the underlying socket layer. +.IP LIBSSH2_FLAG_COMPRESS +If set - before the connection negotiation is performed - libssh2 will try to +negotiate compression enabling for this connection. By default libssh2 will +not attempt to use compression. +.SH RETURN VALUE +Returns regular libssh2 error code. +.SH AVAILABILITY +This function has existed since the age of dawn. LIBSSH2_FLAG_COMPRESS was +added in version 1.2.8. +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_session_free.3 b/deps/share/man/man3/libssh2_session_free.3 new file mode 100644 index 0000000..96eff0c --- /dev/null +++ b/deps/share/man/man3/libssh2_session_free.3 @@ -0,0 +1,18 @@ +.TH libssh2_session_free 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_free - frees resources associated with a session instance +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_free(LIBSSH2_SESSION *session); +.SH DESCRIPTION +Frees all resources associated with a session instance. Typically called after +.BR libssh2_session_disconnect_ex(3) +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) +.BR libssh2_session_disconnect_ex(3) diff --git a/deps/share/man/man3/libssh2_session_get_blocking.3 b/deps/share/man/man3/libssh2_session_get_blocking.3 new file mode 100644 index 0000000..8d98fa3 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_get_blocking.3 @@ -0,0 +1,12 @@ +.TH libssh2_session_get_blocking 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_get_blocking - TODO +.SH SYNOPSIS +int libssh2_session_get_blocking(LIBSSH2_SESSION *session); +.SH DESCRIPTION +Returns 0 if the state of the session has previously be set to non-blocking +and it returns 1 if the state was set to blocking. +.SH RETURN VALUE +See description. +.SH SEE ALSO +.BR libssh2_session_set_blocking(3) diff --git a/deps/share/man/man3/libssh2_session_get_timeout.3 b/deps/share/man/man3/libssh2_session_get_timeout.3 new file mode 100644 index 0000000..94aacd6 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_get_timeout.3 @@ -0,0 +1,19 @@ +.TH libssh2_session_get_timeout 3 "4 May 2011" "libssh2 1.2.9" "libssh2 manual" +.SH NAME +libssh2_session_get_timeout - get the timeout for blocking functions +.SH SYNOPSIS +#include <libssh2.h> +.nf +long libssh2_session_get_timeout(LIBSSH2_SESSION *session); +.SH DESCRIPTION +Returns the \fBtimeout\fP (in milliseconds) for how long a blocking the +libssh2 function calls may wait until they consider the situation an error and +return LIBSSH2_ERROR_TIMEOUT. + +By default libssh2 has no timeout (zero) for blocking functions. +.SH RETURN VALUE +The value of the timeout setting. +.SH AVAILABILITY +Added in 1.2.9 +.SH SEE ALSO +.BR libssh2_session_set_timeout(3) diff --git a/deps/share/man/man3/libssh2_session_handshake.3 b/deps/share/man/man3/libssh2_session_handshake.3 new file mode 100644 index 0000000..33908c6 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_handshake.3 @@ -0,0 +1,40 @@ +.TH libssh2_session_handshake 3 "7 Oct 2010" "libssh2 1.2.8" "libssh2 manual" +.SH NAME +libssh2_session_handshake - perform the SSH handshake +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_handshake(LIBSSH2_SESSION *session, libssh2_socket_t socket); +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIsocket\fP - Connected socket descriptor. Typically a TCP connection +though the protocol allows for any reliable transport and the library will +attempt to use any berkeley socket. + +Begin transport layer protocol negotiation with the connected host. +.SH RETURN VALUE +Returns 0 on success, negative on failure. +.SH ERRORS +\fILIBSSH2_ERROR_SOCKET_NONE\fP - The socket is invalid. + +\fILIBSSH2_ERROR_BANNER_SEND\fP - Unable to send banner to remote host. + +\fILIBSSH2_ERROR_KEX_FAILURE\fP - >Encryption key exchange with the remote +host failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_DISCONNECT\fP - The socket was disconnected. + +\fILIBSSH2_ERROR_PROTO\fP - An invalid SSH protocol response was received on +the socket. + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. +.SH AVAILABILITY +Added in 1.2.8 +.SH SEE ALSO +.BR libssh2_session_free(3) +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_hostkey.3 b/deps/share/man/man3/libssh2_session_hostkey.3 new file mode 100644 index 0000000..5d04440 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_hostkey.3 @@ -0,0 +1,21 @@ +.TH libssh2_session_hostkey 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_hostkey - get the remote key +.SH SYNOPSIS +#include <libssh2.h> + +const char *libssh2_session_hostkey(LIBSSH2_SESSION *session, + size_t *len, int *type); +.SH DESCRIPTION +Returns a pointer to the current host key, the value \fIlen\fP points to will +get the length of the key. + +The value \fItype\fP points to the type of hostkey which is one of: +LIBSSH2_HOSTKEY_TYPE_RSA, LIBSSH2_HOSTKEY_TYPE_DSS, or +LIBSSH2_HOSTKEY_TYPE_UNKNOWN. + +.SH RETURN VALUE +A pointer, or NULL if something went wrong. +.SH SEE ALSO +.BR libssh2_knownhost_check(3) +.BR libssh2_knownhost_add(3) diff --git a/deps/share/man/man3/libssh2_session_init.3 b/deps/share/man/man3/libssh2_session_init.3 new file mode 100644 index 0000000..476a3b4 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_init.3 @@ -0,0 +1,18 @@ +.TH libssh2_session_init 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_session_init - convenience macro for \fIlibssh2_session_init_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_SESSION * +libssh2_session_init(void); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_session_init_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_session_init_ex(3)\fP +.SH ERRORS +See \fIlibssh2_session_init_ex(3)\fP +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_init_ex.3 b/deps/share/man/man3/libssh2_session_init_ex.3 new file mode 100644 index 0000000..5e4ef06 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_init_ex.3 @@ -0,0 +1,42 @@ +.TH libssh2_session_init_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_init_ex - initializes an SSH session object +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_SESSION * +libssh2_session_init_ex(LIBSSH2_ALLOC_FUNC((*myalloc)), LIBSSH2_FREE_FUNC((*myfree)), LIBSSH2_REALLOC_FUNC((*myrealloc)), void *abstract); + +LIBSSH2_SESSION * +libssh2_session_init(void); + +.SH DESCRIPTION +\fImyalloc\fP - Custom allocator function. Refer to the section on Callbacks +for implementing an allocator callback. Pass a value of NULL to use the +default system allocator. + +\fImyfree\fP - Custom de-allocator function. Refer to the section on Callbacks +for implementing a deallocator callback. Pass a value of NULL to use the +default system deallocator. + +\fImyrealloc\fP - Custom re-allocator function. Refer to the section on +Callbacks for implementing a reallocator callback. Pass a value of NULL to +use the default system reallocator. + +\fIabstract\fP - Arbitrary pointer to application specific callback data. +This value will be passed to any callback function associated with the named +session instance. + +Initializes an SSH session object. By default system memory allocators +(malloc(), free(), realloc()) will be used for any dynamically allocated memory +blocks. Alternate memory allocation functions may be specified using the +extended version of this API call, and/or optional application specific data +may be attached to the session object. + +This method must be called first, prior to configuring session options or +starting up an SSH session with a remote server. +.SH RETURN VALUE +Pointer to a newly allocated LIBSSH2_SESSION instance, or NULL on errors. +.SH SEE ALSO +.BR libssh2_session_free(3) +.BR libssh2_session_handshake(3) diff --git a/deps/share/man/man3/libssh2_session_last_errno.3 b/deps/share/man/man3/libssh2_session_last_errno.3 new file mode 100644 index 0000000..f9172cb --- /dev/null +++ b/deps/share/man/man3/libssh2_session_last_errno.3 @@ -0,0 +1,21 @@ +.TH libssh2_session_last_errno 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_last_errno - get the most recent error number +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_last_errno(LIBSSH2_SESSION *session); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +Determine the most recent error condition. + +.SH RETURN VALUE +Numeric error code corresponding to the the Error Code constants. + +.SH SEE ALSO +.BR libssh2_session_last_error(3) +.BR libssh2_session_set_last_error(3) diff --git a/deps/share/man/man3/libssh2_session_last_error.3 b/deps/share/man/man3/libssh2_session_last_error.3 new file mode 100644 index 0000000..2a64dbb --- /dev/null +++ b/deps/share/man/man3/libssh2_session_last_error.3 @@ -0,0 +1,32 @@ +.TH libssh2_session_last_error 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_last_error - get the most recent error +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_last_error(LIBSSH2_SESSION *session, char **errmsg, int *errmsg_len, int want_buf); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIerrmsg\fP - If not NULL, is populated by reference with the human +readable form of the most recent error message. + +\fIerrmsg_len\fP - If not NULL, is populated by reference with the length +of errmsg. (The string is NUL-terminated, so the length is only useful as +an optimization, to avoid calling strlen.) + +\fIwant_buf\fP - If set to a non-zero value, "ownership" of the errmsg +buffer will be given to the calling scope. If necessary, the errmsg buffer +will be duplicated. + +Determine the most recent error condition and its cause. + +.SH RETURN VALUE +Numeric error code corresponding to the the Error Code constants. + +.SH SEE ALSO +.BR libssh2_session_last_errno(3) +.BR libssh2_session_set_last_error(3) diff --git a/deps/share/man/man3/libssh2_session_method_pref.3 b/deps/share/man/man3/libssh2_session_method_pref.3 new file mode 100644 index 0000000..dcf77f6 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_method_pref.3 @@ -0,0 +1,40 @@ +.TH libssh2_session_method_pref 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_method_pref - set preferred key exchange method +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_method_pref(LIBSSH2_SESSION *session, int method_type, const char *prefs); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fImethod_type\fP - One of the Method Type constants. + +\fIprefs\fP - Coma delimited list of preferred methods to use with +the most preferred listed first and the least preferred listed last. +If a method is listed which is not supported by libssh2 it will be +ignored and not sent to the remote host during protocol negotiation. + +Set preferred methods to be negotiated. These +preferences must be set prior to calling +.BR libssh2_session_handshake(3) +as they are used during the protocol initiation phase. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_INVAL\fP - The requested method type was invalid. + +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_METHOD_NOT_SUPPORTED\fP - The requested method is not supported. + +.SH SEE ALSO +.BR libssh2_session_init_ex(3) +.BR libssh2_session_handshake(3) diff --git a/deps/share/man/man3/libssh2_session_methods.3 b/deps/share/man/man3/libssh2_session_methods.3 new file mode 100644 index 0000000..cc4f6d4 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_methods.3 @@ -0,0 +1,27 @@ +.TH libssh2_session_methods 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_methods - return the currently active algorithms +.SH SYNOPSIS +#include <libssh2.h> + +const char * +libssh2_session_methods(LIBSSH2_SESSION *session, int method_type); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fImethod_type\fP - one of the method type constants: LIBSSH2_METHOD_KEX, +LIBSSH2_METHOD_HOSTKEY, LIBSSH2_METHOD_CRYPT_CS, LIBSSH2_METHOD_CRYPT_SC, +LIBSSH2_METHOD_MAC_CS, LIBSSH2_METHOD_MAC_SC, LIBSSH2_METHOD_COMP_CS, +LIBSSH2_METHOD_COMP_SC, LIBSSH2_METHOD_LANG_CS, LIBSSH2_METHOD_LANG_SC. + +Returns the actual method negotiated for a particular transport parameter. +.SH RETURN VALUE +Negotiated method or NULL if the session has not yet been started. +.SH ERRORS +\fILIBSSH2_ERROR_INVAL\fP - The requested method type was invalid. + +\fILIBSSH2_ERROR_METHOD_NONE\fP - no method has been set +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_set_blocking.3 b/deps/share/man/man3/libssh2_session_set_blocking.3 new file mode 100644 index 0000000..b16e009 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_set_blocking.3 @@ -0,0 +1,30 @@ +.TH libssh2_session_set_blocking 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_set_blocking - set or clear blocking mode on session +.SH SYNOPSIS +#include <libssh2.h> + +void +libssh2_session_set_blocking(LIBSSH2_SESSION *session, int blocking); + +.SH DESCRIPTION +\fIsession\fP - session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIblocking\fP - Set to a non-zero value to make the channel block, or zero to +make it non-blocking. + +Set or clear blocking mode on the selected on the session. This will +instantly affect any channels associated with this session. If a read is +performed on a session with no data currently available, a blocking session +will wait for data to arrive and return what it receives. A non-blocking +session will return immediately with an empty buffer. If a write is performed +on a session with no room for more data, a blocking session will wait for +room. A non-blocking session will return immediately without writing +anything. + +.SH RETURN VALUE +None + +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_set_last_error.3 b/deps/share/man/man3/libssh2_session_set_last_error.3 new file mode 100644 index 0000000..fca6d1d --- /dev/null +++ b/deps/share/man/man3/libssh2_session_set_last_error.3 @@ -0,0 +1,33 @@ +.TH libssh2_session_set_last_error 3 "26 Oct 2015" "libssh2 1.6.1" "libssh2 manual" +.SH NAME +libssh2_session_set_last_error - sets the internal error state +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_set_last_error(LIBSSH2_SESSION *session, int errcode, const char *errmsg) + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIerrcode\fP - One of the error codes as defined in the public +libssh2 header file. + +\fIerrmsg\fP - If not NULL, a copy of the given string is stored +inside the session object as the error message. + +This function is provided for high level language wrappers +(i.e. Python or Perl) and other libraries that may extend libssh2 with +additional features while still relying on its error reporting +mechanism. + +.SH RETURN VALUE +Numeric error code corresponding to the the Error Code constants. + +.SH AVAILABILITY +Added in 1.6.1 + +.SH SEE ALSO +.BR libssh2_session_last_error(3) +.BR libssh2_session_last_errno(3) diff --git a/deps/share/man/man3/libssh2_session_set_timeout.3 b/deps/share/man/man3/libssh2_session_set_timeout.3 new file mode 100644 index 0000000..2d4f10f --- /dev/null +++ b/deps/share/man/man3/libssh2_session_set_timeout.3 @@ -0,0 +1,20 @@ +.TH libssh2_session_set_timeout 3 "4 May 2011" "libssh2 1.2.9" "libssh2 manual" +.SH NAME +libssh2_session_set_timeout - set timeout for blocking functions +.SH SYNOPSIS +#include <libssh2.h> +.nf +void libssh2_session_set_timeout(LIBSSH2_SESSION *session, long timeout); +.SH DESCRIPTION +Set the \fBtimeout\fP in milliseconds for how long a blocking the libssh2 +function calls may wait until they consider the situation an error and return +LIBSSH2_ERROR_TIMEOUT. + +By default or if you set the timeout to zero, libssh2 has no timeout for +blocking functions. +.SH RETURN VALUE +Nothing +.SH AVAILABILITY +Added in 1.2.9 +.SH SEE ALSO +.BR libssh2_session_get_timeout(3) diff --git a/deps/share/man/man3/libssh2_session_startup.3 b/deps/share/man/man3/libssh2_session_startup.3 new file mode 100644 index 0000000..b59056f --- /dev/null +++ b/deps/share/man/man3/libssh2_session_startup.3 @@ -0,0 +1,42 @@ +.TH libssh2_session_startup 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_session_startup - begin transport layer +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_session_startup(LIBSSH2_SESSION *session, int socket); +.SH DESCRIPTION +Starting in libssh2 version 1.2.8 this function is considered deprecated. Use +\fIlibssh2_session_handshake(3)\fP instead. + +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIsocket\fP - Connected socket descriptor. Typically a TCP connection +though the protocol allows for any reliable transport and the library will +attempt to use any berkeley socket. + +Begin transport layer protocol negotiation with the connected host. +.SH RETURN VALUE +Returns 0 on success, negative on failure. +.SH ERRORS +\fILIBSSH2_ERROR_SOCKET_NONE\fP - The socket is invalid. + +\fILIBSSH2_ERROR_BANNER_SEND\fP - Unable to send banner to remote host. + +\fILIBSSH2_ERROR_KEX_FAILURE\fP - >Encryption key exchange with the remote +host failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_DISCONNECT\fP - The socket was disconnected. + +\fILIBSSH2_ERROR_PROTO\fP - An invalid SSH protocol response was received on +the socket. + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would block. + +.SH SEE ALSO +.BR libssh2_session_free(3) +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_session_supported_algs.3 b/deps/share/man/man3/libssh2_session_supported_algs.3 new file mode 100644 index 0000000..6e414a9 --- /dev/null +++ b/deps/share/man/man3/libssh2_session_supported_algs.3 @@ -0,0 +1,74 @@ +.TH libssh2_session_supported_algs 3 "23 Oct 2011" "libssh2 1.4.0" "libssh2 manual" +.SH NAME +libssh2_session_supported_algs - get list of supported algorithms +.SH SYNOPSIS +.nf +#include <libssh2.h> + +int libssh2_session_supported_algs(LIBSSH2_SESSION* session, + int method_type, + const char*** algs); +.SH DESCRIPTION +\fIsession\fP - An instance of initialized LIBSSH2_SESSION (the function will +use its pointer to the memory allocation function). \fImethod_type\fP - +Method type. See \fIlibssh2_session_method_pref(3)\fP. \fIalgs\fP - Address +of a pointer that will point to an array of returned algorithms + +Get a list of supported algorithms for the given \fImethod_type\fP. The +method_type parameter is equivalent to method_type in +\fIlibssh2_session_method_pref(3)\fP. If successful, the function will +allocate the appropriate amount of memory. When not needed anymore, it must be +deallocated by calling \fIlibssh2_free(3)\fP. When this function is +unsuccessful, this must not be done. + +In order to get a list of all supported compression algorithms, +libssh2_session_flag(session, LIBSSH2_FLAG_COMPRESS, 1) must be called before +calling this function, otherwise only "none" will be returned. + +If successful, the function will allocate and fill the array with supported +algorithms (the same names as defined in RFC 4253). The array is not NULL +terminated. +.SH EXAMPLE +.nf +#include "libssh2.h" + +const char **algorithms; +int rc, i; +LIBSSH2_SESSION *session; + +/* initialize session */ +session = libssh2_session_init(); +rc = libssh2_session_supported_algs(session, + LIBSSH2_METHOD_CRYPT_CS, + &algorithms); +if (rc>0) { + /* the call succeeded, do sth. with the list of algorithms + (e.g. list them)... */ + printf("Supported symmetric algorithms:\\n"); + for ( i=0; i<rc; i++ ) + printf("\\t%s\\n", algorithms[i]); + + /* ... and free the allocated memory when not needed anymore */ + libssh2_free(session, algorithms); +} +else { + /* call failed, error handling */ +} +.SH RETURN VALUE +On success, a number of returned algorithms (i.e a positive number will be +returned). In case of a failure, an error code (a negative number, see below) +is returned. 0 should never be returned. +.SH ERRORS +\fILIBSSH2_ERROR_BAD_USE\fP - Invalid address of algs. + +\fILIBSSH2_ERROR_METHOD_NOT_SUPPORTED\fP - Unknown method type. + +\fILIBSSH2_ERROR_INVAL\fP - Internal error (normally should not occur). + +\fILIBSSH2_ERROR_ALLOC\fP - Allocation of memory failed. +.SH AVAILABILITY +Added in 1.4.0 +.SH SEE ALSO +.BR libssh2_session_methods(3), +.BR libssh2_session_method_pref(3) +.BR libssh2_free(3) diff --git a/deps/share/man/man3/libssh2_sftp_close.3 b/deps/share/man/man3/libssh2_sftp_close.3 new file mode 100644 index 0000000..b169b1b --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_close.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_close 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_close - convenience macro for \fIlibssh2_sftp_close_handle(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_close(LIBSSH2_SFTP_HANDLE *handle); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_close_handle(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_close_handle(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_close_handle(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_close_handle(3) diff --git a/deps/share/man/man3/libssh2_sftp_close_handle.3 b/deps/share/man/man3/libssh2_sftp_close_handle.3 new file mode 100644 index 0000000..30e299c --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_close_handle.3 @@ -0,0 +1,43 @@ +.TH libssh2_sftp_close_handle 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_close_handle - close filehandle +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_close_handle(LIBSSH2_SFTP_HANDLE *handle); + +int +libssh2_sftp_close(LIBSSH2_SFTP_HANDLE *handle); + +int +libssh2_sftp_closedir(LIBSSH2_SFTP_HANDLE *handle); + +.SH DESCRIPTION +\fIhandle\fP - SFTP File Handle as returned by \fBlibssh2_sftp_open_ex(3)\fP +or \fBlibssh2_sftp_opendir(3)\fP (which is a macro). + +Close an active LIBSSH2_SFTP_HANDLE. Because files and directories share the +same underlying storage mechanism these methods may be used +interchangeably. \fBlibssh2_sftp_close(3)\fP and \fBlibssh2_sftp_closedir(3)\fP +are macros for \fBlibssh2_sftp_close_handle(3)\fP. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. + +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_closedir.3 b/deps/share/man/man3/libssh2_sftp_closedir.3 new file mode 100644 index 0000000..3e032a7 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_closedir.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_closedir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_closedir - convenience macro for \fIlibssh2_sftp_close_handle(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_closedir(LIBSSH2_SFTP_HANDLE *handle) + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_close_handle(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_close_handle(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_close_handle(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_close_handle(3) diff --git a/deps/share/man/man3/libssh2_sftp_fsetstat.3 b/deps/share/man/man3/libssh2_sftp_fsetstat.3 new file mode 100644 index 0000000..e77dd21 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_fsetstat.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_fsetstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_fsetstat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_fsetstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_fstat_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_fstat_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_fstat_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_fstat_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_fstat.3 b/deps/share/man/man3/libssh2_sftp_fstat.3 new file mode 100644 index 0000000..66116a3 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_fstat.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_fstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_fstat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_fstat(LIBSSH2_SFTP_HANDLE *handle, LIBSSH2_SFTP_ATTRIBUTES *attrs); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_fstat_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_fstat_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_fstat_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_fstat_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_fstat_ex.3 b/deps/share/man/man3/libssh2_sftp_fstat_ex.3 new file mode 100644 index 0000000..107594c --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_fstat_ex.3 @@ -0,0 +1,104 @@ +.TH libssh2_sftp_fstat_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_fstat_ex - get or set attributes on an SFTP file handle +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_fstat_ex(LIBSSH2_SFTP_HANDLE *handle, + LIBSSH2_SFTP_ATTRIBUTES *attrs, int setstat) + +#define libssh2_sftp_fstat(handle, attrs) \\ + libssh2_sftp_fstat_ex((handle), (attrs), 0) +#define libssh2_sftp_fsetstat(handle, attrs) \\ + libssh2_sftp_fstat_ex((handle), (attrs), 1) +.fi +.SH DESCRIPTION +\fIhandle\fP - SFTP File Handle as returned by +.BR libssh2_sftp_open_ex(3) + +\fIattrs\fP - Pointer to an LIBSSH2_SFTP_ATTRIBUTES structure to set file +metadata from or into depending on the value of setstat. + +\fIsetstat\fP - When non-zero, the file's metadata will be updated +with the data found in attrs according to the values of attrs->flags +and other relevant member attributes. + +Get or Set statbuf type data for a given LIBSSH2_SFTP_HANDLE instance. +.SH DATA TYPES +LIBSSH2_SFTP_ATTRIBUTES is a typedefed struct that is defined as below + +.nf +struct _LIBSSH2_SFTP_ATTRIBUTES { + + /* If flags & ATTR_* bit is set, then the value in this + * struct will be meaningful Otherwise it should be ignored + */ + unsigned long flags; + + /* size of file, in bytes */ + libssh2_uint64_t filesize; + + /* numerical representation of the user and group owner of + * the file + */ + unsigned long uid, gid; + + /* bitmask of permissions */ + unsigned long permissions; + + /* access time and modified time of file */ + unsigned long atime, mtime; +}; +.fi + +You will find a full set of defines and macros to identify flags and +permissions on the \fBlibssh2_sftp.h\fP header file, but some of the +most common ones are: + +To check for specific user permissions, the set of defines are in the +pattern LIBSSH2_SFTP_S_I<action><who> where <action> is R, W or X for +read, write and executable and <who> is USR, GRP and OTH for user, +group and other. So, you check for a user readable file, use the bit +\fILIBSSH2_SFTP_S_IRUSR\fP while you want to see if it is executable +for other, you use \fILIBSSH2_SFTP_S_IXOTH\fP and so on. + +To check for specific file types, you would previously (before libssh2 +1.2.5) use the standard posix S_IS***() macros, but since 1.2.5 +libssh2 offers its own set of macros for this functionality: +.IP LIBSSH2_SFTP_S_ISLNK +Test for a symbolic link +.IP LIBSSH2_SFTP_S_ISREG +Test for a regular file +.IP LIBSSH2_SFTP_S_ISDIR +Test for a directory +.IP LIBSSH2_SFTP_S_ISCHR +Test for a character special file +.IP LIBSSH2_SFTP_S_ISBLK +Test for a block special file +.IP LIBSSH2_SFTP_S_ISFIFO +Test for a pipe or FIFO special file +.IP LIBSSH2_SFTP_S_ISSOCK +Test for a socket +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. +.SH AVAILABILITY +This function has been around since forever, but most of the +LIBSSH2_SFTP_S_* defines were introduced in libssh2 0.14 and the +LIBSSH2_SFTP_S_IS***() macros were introduced in libssh2 1.2.5. +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_fstatvfs.3 b/deps/share/man/man3/libssh2_sftp_fstatvfs.3 new file mode 100644 index 0000000..934d2a1 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_fstatvfs.3 @@ -0,0 +1 @@ +.so man3/libssh2_sftp_statvfs.3 diff --git a/deps/share/man/man3/libssh2_sftp_fsync.3 b/deps/share/man/man3/libssh2_sftp_fsync.3 new file mode 100644 index 0000000..646760a --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_fsync.3 @@ -0,0 +1,39 @@ +.TH libssh2_sftp_fsync 3 "8 Apr 2013" "libssh2 1.4.4" "libssh2 manual" +.SH NAME +libssh2_sftp_fsync - synchronize file to disk +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_fsync(LIBSSH2_SFTP_HANDLE *handle) +.fi +.SH DESCRIPTION +This function causes the remote server to synchronize the file +data and metadata to disk (like fsync(2)). + +For this to work requires [email protected] support on the server. + +\fIhandle\fP - SFTP File Handle as returned by +.BR libssh2_sftp_open_ex(3) + +.SH RETURN VALUE +Returns 0 on success or negative on failure. If used in non-blocking mode, it +returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response +was received on the socket, or an SFTP operation caused an errorcode +to be returned by the server. In particular, this can be returned if +the SSH server does not support the fsync operation: the SFTP subcode +\fILIBSSH2_FX_OP_UNSUPPORTED\fP will be returned in this case. + +.SH AVAILABILITY +Added in libssh2 1.4.4 and OpenSSH 6.3. +.SH SEE ALSO +.BR fsync(2) diff --git a/deps/share/man/man3/libssh2_sftp_get_channel.3 b/deps/share/man/man3/libssh2_sftp_get_channel.3 new file mode 100644 index 0000000..d1d82bc --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_get_channel.3 @@ -0,0 +1,21 @@ +.TH libssh2_sftp_get_channel 3 "9 Sep 2011" "libssh2 1.4.0" "libssh2 manual" +.SH NAME +libssh2_sftp_get_channel - return the channel of sftp +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +.fi +LIBSSH2_CHANNEL *libssh2_sftp_get_channel(LIBSSH2_SFTP *sftp); +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +Return the channel of the given sftp handle. +.SH RETURN VALUE +The channel of the SFTP instance or NULL if something was wrong. +.SH AVAILABILITY +Added in 1.4.0 +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_init.3 b/deps/share/man/man3/libssh2_sftp_init.3 new file mode 100644 index 0000000..a59d030 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_init.3 @@ -0,0 +1,39 @@ +.TH libssh2_sftp_init 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_init - open SFTP channel for the given SSH session. +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +LIBSSH2_SFTP * +libssh2_sftp_init(LIBSSH2_SESSION *session); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +Open a channel and initialize the SFTP subsystem. Although the SFTP subsystem +operates over the same type of channel as those exported by the Channel API, +the protocol itself implements its own unique binary packet protocol which +must be managed with the libssh2_sftp_*() family of functions. When an SFTP +session is complete, it must be destroyed using the +.BR libssh2_sftp_shutdown(3) +function. +.SH RETURN VALUE +A pointer to the newly allocated SFTP instance or NULL on failure. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +block. +.SH SEE ALSO +.BR libssh2_sftp_shutdown(3) +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_last_error.3 b/deps/share/man/man3/libssh2_sftp_last_error.3 new file mode 100644 index 0000000..aadbd5d --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_last_error.3 @@ -0,0 +1,24 @@ +.TH libssh2_sftp_last_error 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_last_error - return the last SFTP-specific error code +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +unsigned long +libssh2_sftp_last_error(LIBSSH2_SFTP *sftp); + +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +Returns the last error code produced by the SFTP layer. Note that this only +returns a sensible error code if libssh2 returned LIBSSH2_ERROR_SFTP_PROTOCOL +in a previous call. Using \fBlibssh2_sftp_last_error(3)\fP without a +preceding SFTP protocol error, it will return an unspecified value. + +.SH RETURN VALUE +Current error code state of the SFTP instance. + +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_lstat.3 b/deps/share/man/man3/libssh2_sftp_lstat.3 new file mode 100644 index 0000000..78c9057 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_lstat.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_lstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_lstat - convenience macro for \fIlibssh2_sftp_stat_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_lstat(LIBSSH2_SFTP *sftp, const char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_stat_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_stat_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_stat_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_stat_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_mkdir.3 b/deps/share/man/man3/libssh2_sftp_mkdir.3 new file mode 100644 index 0000000..999bd01 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_mkdir.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_mkdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_mkdir - convenience macro for \fIlibssh2_sftp_mkdir_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp, const char *path, long mode); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_mkdir_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_mkdir_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_mkdir_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_mkdir_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_mkdir_ex.3 b/deps/share/man/man3/libssh2_sftp_mkdir_ex.3 new file mode 100644 index 0000000..20df03c --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_mkdir_ex.3 @@ -0,0 +1,40 @@ +.TH libssh2_sftp_mkdir_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_mkdir_ex - create a directory on the remote file system +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_mkdir_ex(LIBSSH2_SFTP *sftp, const char *path, unsigned int path_len, long mode); + +int +libssh2_sftp_mkdir(LIBSSH2_SFTP *sftp, const char *path, long mode); +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +\fIpath\fP - full path of the new directory to create. Note that the new +directory's parents must all exist prior to making this call. + +\fIpath_len\fP - length of the full path of the new directory to create. + +\fImode\fP - directory creation mode (e.g. 0755). + +Create a directory on the remote file system. +.SH RETURN VALUE +Return 0 on success or negative on failure. +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_open.3 b/deps/share/man/man3/libssh2_sftp_open.3 new file mode 100644 index 0000000..9096986 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_open.3 @@ -0,0 +1,18 @@ +.TH libssh2_sftp_open 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_open - convenience macro for \fIlibssh2_sftp_open_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_SFTP_HANDLE * +libssh2_sftp_open(LIBSSH2_SFTP *sftp, const char *path, unsigned long flags, long mode); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_open_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_open_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_open_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_open_ex.3 b/deps/share/man/man3/libssh2_sftp_open_ex.3 new file mode 100644 index 0000000..32cc23f --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_open_ex.3 @@ -0,0 +1,65 @@ +.TH libssh2_sftp_open_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_open - open filehandle for file on SFTP. +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +LIBSSH2_SFTP_HANDLE * +libssh2_sftp_open_ex(LIBSSH2_SFTP *sftp, const char *filename, + unsigned int filename_len, unsigned long flags, + long mode, int open_type); +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by \fIlibssh2_sftp_init(3)\fP + +\fIfilename\fP - Remote file/directory resource to open + +\fIfilename_len\fP - Length of filename + +\fIflags\fP - Any reasonable combination of the LIBSSH2_FXF_* constants: +.RS +.IP LIBSSH2_FXF_READ +Open the file for reading. +.IP LIBSSH2_FXF_WRITE +Open the file for writing. If both this and LIBSSH2_FXF_READ are specified, +the file is opened for both reading and writing. +.IP LIBSSH2_FXF_APPEND +Force all writes to append data at the end of the file. +.IP LIBSSH2_FXF_CREAT, +If this flag is specified, then a new file will be created if one does not +already exist (if LIBSSH2_FXF_TRUNC is specified, the new file will be +truncated to zero length if it previously exists) +.IP LIBSSH2_FXF_TRUNC +Forces an existing file with the same name to be truncated to zero length when +creating a file by specifying LIBSSH2_FXF_CREAT. LIBSSH2_FXF_CREAT MUST also +be specified if this flag is used. +.IP LIBSSH2_FXF_EXCL +Causes the request to fail if the named file already exists. +LIBSSH2_FXF_CREAT MUST also be specified if this flag is used. + +.RE +\fImode\fP - POSIX file permissions to assign if the file is being newly +created. See the LIBSSH2_SFTP_S_* convenience defines in <libssh2_sftp.h> + +\fIopen_type\fP - Either of LIBSSH2_SFTP_OPENFILE (to open a file) or +LIBSSH2_SFTP_OPENDIR (to open a directory). +.SH RETURN VALUE +A pointer to the newly created LIBSSH2_SFTP_HANDLE instance or NULL on +failure. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call would +block. +.SH SEE ALSO +.BR libssh2_sftp_close_handle(3) + diff --git a/deps/share/man/man3/libssh2_sftp_opendir.3 b/deps/share/man/man3/libssh2_sftp_opendir.3 new file mode 100644 index 0000000..d345103 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_opendir.3 @@ -0,0 +1,18 @@ +.TH libssh2_sftp_opendir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_opendir - convenience macro for \fIlibssh2_sftp_open_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +LIBSSH2_SFTP_HANDLE * +libssh2_sftp_opendir(LIBSSH2_SFTP *sftp, const char *path); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_open_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_open_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_open_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_read.3 b/deps/share/man/man3/libssh2_sftp_read.3 new file mode 100644 index 0000000..36bc979 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_read.3 @@ -0,0 +1,43 @@ +.TH libssh2_sftp_read 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_read - read data from an SFTP handle +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +ssize_t +libssh2_sftp_read(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen); + +.SH DESCRIPTION +\fIhandle\fP is the SFTP File Handle as returned by +.BR libssh2_sftp_open_ex(3) + +\fIbuffer\fP is a pointer to a pre-allocated buffer of at least + +\fIbuffer_maxlen\fP bytes to read data into. + +Reads a block of data from an LIBSSH2_SFTP_HANDLE. This method is modelled +after the POSIX +.BR read(2) +function and uses the same calling semantics. +.BR libssh2_sftp_read(3) +will attempt to read as much as possible however it may not fill all of buffer +if the file pointer reaches the end or if further reads would cause the socket +to block. +.SH RETURN VALUE +Number of bytes actually populated into buffer, or negative on failure. +It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) +.BR libssh2_sftp_read(3) diff --git a/deps/share/man/man3/libssh2_sftp_readdir.3 b/deps/share/man/man3/libssh2_sftp_readdir.3 new file mode 100644 index 0000000..adecbcb --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_readdir.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_readdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_readdir - convenience macro for \fIlibssh2_sftp_readdir_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_readdir(LIBSSH2_SFTP_HANDLE *handle, char *buffer, size_t buffer_maxlen, LIBSSH2_SFTP_ATTRIBUTES *attrs); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_readdir_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_readdir_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_readdir_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_readdir_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_readdir_ex.3 b/deps/share/man/man3/libssh2_sftp_readdir_ex.3 new file mode 100644 index 0000000..a40e4df --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_readdir_ex.3 @@ -0,0 +1,65 @@ +.TH libssh2_sftp_readdir_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_readdir_ex - read directory data from an SFTP handle +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_readdir_ex(LIBSSH2_SFTP_HANDLE *handle, + char *buffer, size_t buffer_maxlen, + char *longentry, size_t longentry_maxlen, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +.SH DESCRIPTION +Reads a block of data from a LIBSSH2_SFTP_HANDLE and returns file entry +information for the next entry, if any. + +\fIhandle\fP - is the SFTP File Handle as returned by +.BR libssh2_sftp_open_ex(3) + +\fIbuffer\fP - is a pointer to a pre-allocated buffer of at least +\fIbuffer_maxlen\fP bytes to read data into. + +\fIbuffer_maxlen\fP - is the length of buffer in bytes. If the length of the +filename is longer than the space provided by buffer_maxlen it will be +truncated to fit. + +\fIlongentry\fP - is a pointer to a pre-allocated buffer of at least +\fIlongentry_maxlen\fP bytes to read data into. The format of the `longname' +field is unspecified by SFTP protocol. It MUST be suitable for use in the +output of a directory listing command (in fact, the recommended operation for +a directory listing command is to simply display this data). + +\fIlongentry_maxlen\fP - is the length of longentry in bytes. If the length of +the full directory entry is longer than the space provided by +\fIlongentry_maxlen\fP it will be truncated to fit. + +\fIattrs\fP - is a pointer to LIBSSH2_SFTP_ATTRIBUTES storage to populate +statbuf style data into. +.SH RETURN VALUE +Number of bytes actually populated into buffer (not counting the terminating +zero), or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would +otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it isn't +really a failure per se. +.SH BUG +Passing in a too small buffer for 'buffer' or 'longentry' when receiving data +only results in libssh2 1.2.7 or earlier to not copy the entire data amount, +and it is not possible for the application to tell when it happens! +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be +returned by the server. + +From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if any of the +given 'buffer' or 'longentry' buffers are too small to fit the requested +object name. +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3), +.BR libssh2_sftp_close_handle(3) diff --git a/deps/share/man/man3/libssh2_sftp_readlink.3 b/deps/share/man/man3/libssh2_sftp_readlink.3 new file mode 100644 index 0000000..7425074 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_readlink.3 @@ -0,0 +1,19 @@ +.TH libssh2_sftp_readlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_readlink - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +#define libssh2_sftp_readlink(sftp, path, target, maxlen) \\ + libssh2_sftp_symlink_ex((sftp), (path), strlen(path), (target), (maxlen), \\ + LIBSSH2_SFTP_READLINK) +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_symlink_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_symlink_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_symlink_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_symlink_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_realpath.3 b/deps/share/man/man3/libssh2_sftp_realpath.3 new file mode 100644 index 0000000..33f0fa8 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_realpath.3 @@ -0,0 +1,19 @@ +.TH libssh2_sftp_realpath 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_realpath - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +#define libssh2_sftp_realpath(sftp, path, target, maxlen) \\ + libssh2_sftp_symlink_ex((sftp), (path), strlen(path), (target), (maxlen), \\ + LIBSSH2_SFTP_REALPATH) +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_symlink_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_symlink_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_symlink_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_symlink_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_rename.3 b/deps/share/man/man3/libssh2_sftp_rename.3 new file mode 100644 index 0000000..4939e3c --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_rename.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_rename 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_rename - convenience macro for \fIlibssh2_sftp_rename_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_rename(LIBSSH2_SFTP *sftp, const char *source_filename, const char *destination_filename); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_rename_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_rename_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_rename_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_rename_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_rename_ex.3 b/deps/share/man/man3/libssh2_sftp_rename_ex.3 new file mode 100644 index 0000000..20a3b9d --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_rename_ex.3 @@ -0,0 +1,56 @@ +.TH libssh2_sftp_rename_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_rename_ex - rename an SFTP file +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, const char *source_filename, unsigned int source_filename_len, const char *dest_filename, unsigned int dest_filename_len, long flags); + +int +libssh2_sftp_rename_ex(LIBSSH2_SFTP *sftp, const char *source_filename, const char *dest_filename); + +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +\fIsourcefile\fP - Path and name of the existing filesystem entry + +\fIsourcefile_len\fP - Length of the path and name of the existing +filesystem entry + +\fIdestfile\fP - Path and name of the target filesystem entry + +\fIdestfile_len\fP - Length of the path and name of the target +filesystem entry + +\fIflags\fP - +Bitmask flags made up of LIBSSH2_SFTP_RENAME_* constants. + +Rename a filesystem object on the remote filesystem. The semantics of +this command typically include the ability to move a filesystem object +between folders and/or filesystem mounts. If the LIBSSH2_SFTP_RENAME_OVERWRITE +flag is not set and the destfile entry already exists, the operation +will fail. Use of the other two flags indicate a preference (but not a +requirement) for the remote end to perform an atomic rename operation +and/or using native system calls when possible. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. + +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_rewind.3 b/deps/share/man/man3/libssh2_sftp_rewind.3 new file mode 100644 index 0000000..92d99e2 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_rewind.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_rewind 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_rewind - convenience macro for \fIlibssh2_sftp_seek64(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_rewind(LIBSSH2_SFTP_HANDLE *handle); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_seek64(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_seek64(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_seek64(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_seek64(3) diff --git a/deps/share/man/man3/libssh2_sftp_rmdir.3 b/deps/share/man/man3/libssh2_sftp_rmdir.3 new file mode 100644 index 0000000..0d4b67f --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_rmdir.3 @@ -0,0 +1,18 @@ +.TH libssh2_sftp_rmdir 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_rmdir - convenience macro for \fIlibssh2_sftp_rmdir_ex(3)\fP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +#define libssh2_sftp_rmdir(sftp, path) \\ + libssh2_sftp_rmdir_ex((sftp), (path), strlen(path)) +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_rmdir_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_rmdir_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_rmdir_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_rmdir_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_rmdir_ex.3 b/deps/share/man/man3/libssh2_sftp_rmdir_ex.3 new file mode 100644 index 0000000..daa85cf --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_rmdir_ex.3 @@ -0,0 +1,36 @@ +.TH libssh2_sftp_rmdir_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_rmdir_ex - remove an SFTP directory +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +int libssh2_sftp_rmdir_ex(LIBSSH2_SFTP *sftp, const char *path, + unsigned int path_len); +.SH DESCRIPTION +Remove a directory from the remote file system. + +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +\fIsourcefile\fP - Full path of the existing directory to remove. + +\fIsourcefile_len\fP - Length of the full path of the existing directory to +remove. +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_seek.3 b/deps/share/man/man3/libssh2_sftp_seek.3 new file mode 100644 index 0000000..ccf5e10 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_seek.3 @@ -0,0 +1,25 @@ +.TH libssh2_sftp_seek 3 "22 Dec 2008" "libssh2 1.0" "libssh2 manual" +.SH NAME +libssh2_sftp_seek - set the read/write position indicator within a file +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +void libssh2_sftp_seek(LIBSSH2_SFTP_HANDLE *handle, size_t offset); +.SH DESCRIPTION +Deprecated function. Use \fIlibssh2_sftp_seek64(3)\fP instead! + +\fIhandle\fP - SFTP File Handle as returned by +.BR libssh2_sftp_open_ex(3) + +\fIoffset\fP - Number of bytes from the beginning of file to seek to. + +Move the file handle's internal pointer to an arbitrary location. +Note that libssh2 implements file pointers as a localized concept to make +file access appear more POSIX like. No packets are exchanged with the server +during a seek operation. The localized file pointer is simply used as a +convenience offset during read/write operations. +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3), +.BR libssh2_sftp_seek64(3) diff --git a/deps/share/man/man3/libssh2_sftp_seek64.3 b/deps/share/man/man3/libssh2_sftp_seek64.3 new file mode 100644 index 0000000..57c9a48 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_seek64.3 @@ -0,0 +1,29 @@ +.TH libssh2_sftp_seek64 3 "22 Dec 2008" "libssh2 1.0" "libssh2 manual" +.SH NAME +libssh2_sftp_seek64 - set the read/write position within a file +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +void libssh2_sftp_seek64(LIBSSH2_SFTP_HANDLE *handle, + libssh2_uint64_t offset); +.SH DESCRIPTION +\fIhandle\fP - SFTP File Handle as returned by +.BR libssh2_sftp_open_ex(3) + +\fIoffset\fP - Number of bytes from the beginning of file to seek to. + +Move the file handle's internal pointer to an arbitrary location. libssh2 +implements file pointers as a localized concept to make file access appear +more POSIX like. No packets are exchanged with the server during a seek +operation. The localized file pointer is simply used as a convenience offset +during read/write operations. + +You MUST NOT seek during writing or reading a file with SFTP, as the internals +use outstanding packets and changing the "file position" during transit will +results in badness. +.SH AVAILABILITY +Added in 1.0 +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_setstat.3 b/deps/share/man/man3/libssh2_sftp_setstat.3 new file mode 100644 index 0000000..198703e --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_setstat.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_setstat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_setstat - convenience macro for \fIlibssh2_sftp_stat_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_setstat(LIBSSH2_SFTP *sftp, const char *path, LIBSSH2_SFTP_ATTRIBUTES *attr); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_stat_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_stat_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_stat_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_stat_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_shutdown.3 b/deps/share/man/man3/libssh2_sftp_shutdown.3 new file mode 100644 index 0000000..42cc1c4 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_shutdown.3 @@ -0,0 +1,24 @@ +.TH libssh2_sftp_shutdown 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_shutdown - shut down an SFTP session +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_shutdown(LIBSSH2_SFTP *sftp); + +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +Destroys a previously initialized SFTP session and frees all resources +associated with it. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_stat.3 b/deps/share/man/man3/libssh2_sftp_stat.3 new file mode 100644 index 0000000..96cb2a5 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_stat.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_stat 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_stat - convenience macro for \fIlibssh2_sftp_fstat_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_stat(LIBSSH2_SFTP *sftp, const char *path, LIBSSH2_SFTP_ATTRIBUTES *attrs); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_fstat_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_fstat_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_fstat_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_fstat_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_stat_ex.3 b/deps/share/man/man3/libssh2_sftp_stat_ex.3 new file mode 100644 index 0000000..2fd9507 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_stat_ex.3 @@ -0,0 +1,74 @@ +.TH libssh2_sftp_stat_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_stat_ex - get status about an SFTP file +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +int libssh2_sftp_stat_ex(LIBSSH2_SFTP *sftp, const char *path, + unsigned int path_len, int stat_type, + LIBSSH2_SFTP_ATTRIBUTES *attrs); +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +\fIpath\fP - Remote filesystem object to stat/lstat/setstat. + +\fIpath_len\fP - Length of the name of the remote filesystem object +to stat/lstat/setstat. + +\fIstat_type\fP - One of the three constants specifying the type of +stat operation to perform: + +.br +\fBLIBSSH2_SFTP_STAT\fP: performs stat(2) operation +.br +\fBLIBSSH2_SFTP_LSTAT\fP: performs lstat(2) operation +.br +\fBLIBSSH2_SFTP_SETSTAT\fP: performs operation to set stat info on file + +\fIattrs\fP - Pointer to a \fBLIBSSH2_SFTP_ATTRIBUTES\fP structure to set file +metadata from or into depending on the value of stat_type. + +Get or Set statbuf type data on a remote filesystem object. When getting +statbuf data, +.BR libssh2_sftp_stat(3) +will follow all symlinks, while +.BR libssh2_sftp_lstat(3) +will return data about the object encountered, even if that object +happens to be a symlink. + +The LIBSSH2_SFTP_ATTRIBUTES struct looks like this: + +.nf +struct LIBSSH2_SFTP_ATTRIBUTES { + /* If flags & ATTR_* bit is set, then the value in this struct will be + * meaningful Otherwise it should be ignored + */ + unsigned long flags; + + libssh2_uint64_t filesize; + unsigned long uid; + unsigned long gid; + unsigned long permissions; + unsigned long atime; + unsigned long mtime; +}; +.fi +.SH RETURN VALUE +Returns 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN +when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative +number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_statvfs.3 b/deps/share/man/man3/libssh2_sftp_statvfs.3 new file mode 100644 index 0000000..6327030 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_statvfs.3 @@ -0,0 +1,79 @@ +.TH libssh2_sftp_statvfs 3 "22 May 2010" "libssh2 1.2.6" "libssh2 manual" +.SH NAME +libssh2_sftp_statvfs, libssh2_sftp_fstatvfs - get file system statistics +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_statvfs(LIBSSH2_SFTP *sftp, const char *path, + size_t path_len, LIBSSH2_SFTP_STATVFS *st); + +int +libssh2_sftp_fstatvfs(LIBSSH2_SFTP_HANDLE *handle, + LIBSSH2_SFTP_STATVFS *st) +.fi +.SH DESCRIPTION +These functions provide statvfs(2)-like operations and require [email protected] and [email protected] extension support on the server. + +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +\fIhandle\fP - SFTP File Handle as returned by +.BR libssh2_sftp_open_ex(3) + +\fIpath\fP - full path of any file within the mounted file system. + +\fIpath_len\fP - length of the full path. + +\fIst\fP - Pointer to a LIBSSH2_SFTP_STATVFS structure to place file system +statistics into. + +.SH DATA TYPES +LIBSSH2_SFTP_STATVFS is a typedefed struct that is defined as below + +.nf +struct _LIBSSH2_SFTP_STATVFS { + libssh2_uint64_t f_bsize; /* file system block size */ + libssh2_uint64_t f_frsize; /* fragment size */ + libssh2_uint64_t f_blocks; /* size of fs in f_frsize units */ + libssh2_uint64_t f_bfree; /* # free blocks */ + libssh2_uint64_t f_bavail; /* # free blocks for non-root */ + libssh2_uint64_t f_files; /* # inodes */ + libssh2_uint64_t f_ffree; /* # free inodes */ + libssh2_uint64_t f_favail; /* # free inodes for non-root */ + libssh2_uint64_t f_fsid; /* file system ID */ + libssh2_uint64_t f_flag; /* mount flags */ + libssh2_uint64_t f_namemax; /* maximum filename length */ +}; +.fi + +It is unspecified whether all members of the returned struct have meaningful +values on all file systems. + +The field \fIf_flag\fP is a bit mask. Bits are defined as follows: +.IP LIBSSH2_SFTP_ST_RDONLY +Read-only file system. +.IP LIBSSH2_SFTP_ST_NOSUID +Set-user-ID/set-group-ID bits are ignored by \fBexec\fP(3). + +.SH RETURN VALUE +Returns 0 on success or negative on failure. If used in non-blocking mode, it +returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to be returned +by the server. +.SH AVAILABILITY +Added in libssh2 1.2.6 +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_symlink.3 b/deps/share/man/man3/libssh2_sftp_symlink.3 new file mode 100644 index 0000000..3de7b29 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_symlink.3 @@ -0,0 +1,19 @@ +.TH libssh2_sftp_symlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_symlink - convenience macro for \fIlibssh2_sftp_symlink_ex(3)\fP +.SH SYNOPSIS +.nf +#include <libssh2.h> + +#define libssh2_sftp_symlink(sftp, orig, linkpath) \\ + libssh2_sftp_symlink_ex((sftp), (orig), strlen(orig), (linkpath), \\ + strlen(linkpath), LIBSSH2_SFTP_SYMLINK) +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_symlink_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_symlink_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_symlink_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_symlink_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_symlink_ex.3 b/deps/share/man/man3/libssh2_sftp_symlink_ex.3 new file mode 100644 index 0000000..fc0bc93 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_symlink_ex.3 @@ -0,0 +1,79 @@ +.TH libssh2_sftp_symlink_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_symlink_ex - read or set a symbolic link +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_symlink_ex(LIBSSH2_SFTP *sftp, const char *path, + unsigned int path_len, char *target, + unsigned int target_len, int link_type); +.SH DESCRIPTION +Create a symlink or read out symlink information from the remote side. + +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +\fIpath\fP - Remote filesystem object to create a symlink from or resolve. + +\fIpath_len\fP - Length of the name of the remote filesystem object to +create a symlink from or resolve. + +\fItarget\fP - a pointer to a buffer. The buffer has different uses depending +what the \fIlink_type\fP argument is set to. +.br +\fBLIBSSH2_SFTP_SYMLINK\fP: Remote filesystem object to link to. +.br +\fBLIBSSH2_SFTP_READLINK\fP: Pre-allocated buffer to resolve symlink target +into. +.br +\fBLIBSSH2_SFTP_REALPATH\fP: Pre-allocated buffer to resolve realpath target +into. + +\fItarget_len\fP - Length of the name of the remote filesystem target object. + +\fIlink_type\fP - One of the three previously mentioned constants which +determines the resulting behavior of this function. + +These are convenience macros: + +.BR libssh2_sftp_symlink(3) +: Create a symbolic link between two filesystem objects. +.br +.BR libssh2_sftp_readlink(3) +: Resolve a symbolic link filesystem object to its next target. +.br +.BR libssh2_sftp_realpath(3) +: Resolve a complex, relative, or symlinked filepath to its effective target. +.SH RETURN VALUE +When using LIBSSH2_SFTP_SYMLINK, this function returns 0 on success or negative +on failure. + +When using LIBSSH2_SFTP_READLINK or LIBSSH2_SFTP_REALPATH, it returns the +number of bytes it copied to the target buffer (not including the terminating +zero) or negative on failure. + +It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +From 1.2.8, LIBSSH2_ERROR_BUFFER_TOO_SMALL is returned if the given 'target' +buffer is too small to fit the requested object name. +.SH BUG +Passing in a too small buffer when receiving data only results in libssh2 +1.2.7 or earlier to not copy the entire data amount, and it is not possible +for the application to tell when it happens! +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. + +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_tell.3 b/deps/share/man/man3/libssh2_sftp_tell.3 new file mode 100644 index 0000000..2ff1fba --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_tell.3 @@ -0,0 +1,20 @@ +.TH libssh2_sftp_tell 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_tell - get the current read/write position indicator for a file +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +size_t +libssh2_sftp_tell(LIBSSH2_SFTP_HANDLE *handle); + +.SH DESCRIPTION +\fIhandle\fP - SFTP File Handle as returned by \fBlibssh2_sftp_open_ex(3)\fP. + +Returns the current offset of the file handle's internal pointer. Note that +this is now deprecated. Use the newer \fBlibssh2_sftp_tell64(3)\fP instead! +.SH RETURN VALUE +Current offset from beginning of file in bytes. +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3), +.BR libssh2_sftp_tell64(3) diff --git a/deps/share/man/man3/libssh2_sftp_tell64.3 b/deps/share/man/man3/libssh2_sftp_tell64.3 new file mode 100644 index 0000000..827601f --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_tell64.3 @@ -0,0 +1,21 @@ +.TH libssh2_sftp_tell64 3 "22 Dec 2008" "libssh2 1.0" "libssh2 manual" +.SH NAME +libssh2_sftp_tell64 - get the current read/write position indicator for a file +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +libssh2_uint64_t +libssh2_sftp_tell64(LIBSSH2_SFTP_HANDLE *handle); + +.SH DESCRIPTION +\fIhandle\fP - SFTP File Handle as returned by \fBlibssh2_sftp_open_ex(3)\fP + +Identify the current offset of the file handle's internal pointer. +.SH RETURN VALUE +Current offset from beginning of file in bytes. +.SH AVAILABILITY +Added in libssh2 1.0 +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3), +.BR libssh2_sftp_tell(3) diff --git a/deps/share/man/man3/libssh2_sftp_unlink.3 b/deps/share/man/man3/libssh2_sftp_unlink.3 new file mode 100644 index 0000000..32bbbf9 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_unlink.3 @@ -0,0 +1,17 @@ +.TH libssh2_sftp_unlink 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_sftp_unlink - convenience macro for \fIlibssh2_sftp_unlink_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_sftp_unlink(LIBSSH2_SFTP *sftp, const char *filename); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_sftp_unlink_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_sftp_unlink_ex(3)\fP +.SH ERRORS +See \fIlibssh2_sftp_unlink_ex(3)\fP +.SH SEE ALSO +.BR libssh2_sftp_unlink_ex(3) diff --git a/deps/share/man/man3/libssh2_sftp_unlink_ex.3 b/deps/share/man/man3/libssh2_sftp_unlink_ex.3 new file mode 100644 index 0000000..6672a8c --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_unlink_ex.3 @@ -0,0 +1,42 @@ +.TH libssh2_sftp_unlink_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_unlink_ex - unlink an SFTP file +.SH SYNOPSIS +#include <libssh2.h> +#include <libssh2_sftp.h> + +int +libssh2_sftp_unlink_ex(LIBSSH2_SFTP *sftp, const char *filename, unsigned int filename_len); + +int +libssh2_sftp_unlink(LIBSSH2_SFTP *sftp, const char *filename); + +.SH DESCRIPTION +\fIsftp\fP - SFTP instance as returned by +.BR libssh2_sftp_init(3) + +\fIfilename\fP - Path and name of the existing filesystem entry + +\fIfilename_len\fP - Length of the path and name of the existing +filesystem entry + +Unlink (delete) a file from the remote filesystem. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. + +.SH SEE ALSO +.BR libssh2_sftp_init(3) diff --git a/deps/share/man/man3/libssh2_sftp_write.3 b/deps/share/man/man3/libssh2_sftp_write.3 new file mode 100644 index 0000000..8d81912 --- /dev/null +++ b/deps/share/man/man3/libssh2_sftp_write.3 @@ -0,0 +1,71 @@ +.TH libssh2_sftp_write 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_sftp_write - write SFTP data +.SH SYNOPSIS +.nf +#include <libssh2.h> +#include <libssh2_sftp.h> + +ssize_t libssh2_sftp_write(LIBSSH2_SFTP_HANDLE *handle, + const char *buffer, + size_t count); +.SH DESCRIPTION +\fBlibssh2_sftp_write(3)\fP writes a block of data to the SFTP server. This +method is modeled after the POSIX write() function and uses the same calling +semantics. + +\fIhandle\fP - SFTP file handle as returned by \fIlibssh2_sftp_open_ex(3)\fP. + +\fIbuffer\fP - points to the data to send off. + +\fIcount\fP - Number of bytes from 'buffer' to write. Note that it may not be +possible to write all bytes as requested. + +\fIlibssh2_sftp_handle(3)\fP will use as much as possible of the buffer and +put it into a single SFTP protocol packet. This means that to get maximum +performance when sending larger files, you should try to always pass in at +least 32K of data to this function. + +.SH WRITE AHEAD +Starting in libssh2 version 1.2.8, the default behavior of libssh2 is to +create several smaller outgoing packets for all data you pass to this function +and it will return a positive number as soon as the first packet is +acknowledged from the server. + +This has the effect that sometimes more data has been sent off but isn't acked +yet when this function returns, and when this function is subsequently called +again to write more data, libssh2 will immediately figure out that the data is +already received remotely. + +In most normal situation this should not cause any problems, but it should be +noted that if you've once called libssh2_sftp_write() with data and it returns +short, you MUST still assume that the rest of the data might've been cached so +you need to make sure you don't alter that data and think that the version you +have in your next function invoke will be detected or used. + +The reason for this funny behavior is that SFTP can only send 32K data in each +packet and it gets all packets acked individually. This means we cannot use a +simple serial approach if we want to reach high performance even on high +latency connections. And we want that. +.SH RETURN VALUE +Actual number of bytes written or negative on failure. + +If used in non-blocking mode, it returns LIBSSH2_ERROR_EAGAIN when it would +otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative number, it isn't +really a failure per se. + +If this function returns 0 (zero) it should not be considered an error, but +simply that there was no error but yet no payload data got sent to the other +end. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_SFTP_PROTOCOL\fP - An invalid SFTP protocol response was +received on the socket, or an SFTP operation caused an errorcode to +be returned by the server. +.SH SEE ALSO +.BR libssh2_sftp_open_ex(3) diff --git a/deps/share/man/man3/libssh2_trace.3 b/deps/share/man/man3/libssh2_trace.3 new file mode 100644 index 0000000..4d01bf7 --- /dev/null +++ b/deps/share/man/man3/libssh2_trace.3 @@ -0,0 +1,35 @@ +.TH libssh2_trace 3 "26 Dec 2008" "libssh2 1.0" "libssh2 manual" +.SH NAME +libssh2_trace - enable debug info from inside libssh2 +.SH SYNOPSIS +#include <libssh2.h> + +void libssh2_trace(LIBSSH2_SESSION *session, int bitmask); + +.SH DESCRIPTION +This is a function present in the library that can be used to get debug info +from within libssh2 when it is running. Helpful when trying to trace or debug +behaviors. Note that this function has no effect unless libssh2 was built to +support tracing! It is usually disabled in release builds. + +\fBbitmask\fP can be set to the logical OR of none, one or more of these: +.RS +.IP LIBSSH2_TRACE_SOCKET +Socket low-level debugging +.IP LIBSSH2_TRACE_TRANS +Transport layer debugging +.IP LIBSSH2_TRACE_KEX +Key exchange debugging +.IP LIBSSH2_TRACE_AUTH +Authentication debugging +.IP LIBSSH2_TRACE_CONN +Connection layer debugging +.IP LIBSSH2_TRACE_SCP +SCP debugging +.IP LIBSSH2_TRACE_SFTP +SFTP debugging +.IP LIBSSH2_TRACE_ERROR +Error debugging +.IP LIBSSH2_TRACE_PUBLICKEY +Public Key debugging +.RE diff --git a/deps/share/man/man3/libssh2_trace_sethandler.3 b/deps/share/man/man3/libssh2_trace_sethandler.3 new file mode 100644 index 0000000..57d84ba --- /dev/null +++ b/deps/share/man/man3/libssh2_trace_sethandler.3 @@ -0,0 +1,28 @@ +.TH libssh2_trace_sethandler 3 "15 Jan 2010" "libssh2 1.2.3" "libssh2 manual" +.SH NAME +libssh2_trace_sethandler - set a trace output handler +.SH SYNOPSIS +.nf +#include <libssh2.h> + +typedef void (*libssh2_trace_handler_func)(LIBSSH2_SESSION *session, + void* context, + const char *data, + size_t length); + +int libssh2_trace_sethandler(LIBSSH2_SESSION *session, + void* context, + libssh2_trace_handler_func callback); +.SH DESCRIPTION +libssh2_trace_sethandler installs a trace output handler for your application. +By default, when tracing has been switched on via a call to libssh2_trace(), +all output is written to stderr. By calling this method and passing a +function pointer that matches the libssh2_trace_handler_func prototype, +libssh2 will call back as it generates trace output. This can be used to +capture the trace output and put it into a log file or diagnostic window. +This function has no effect unless libssh2 was built to support this option, +and a typical "release build" might not. + +\fBcontext\fP can be used to pass arbitrary user defined data back into the callback when invoked. +.SH AVAILABILITY +Added in libssh2 version 1.2.3 diff --git a/deps/share/man/man3/libssh2_userauth_authenticated.3 b/deps/share/man/man3/libssh2_userauth_authenticated.3 new file mode 100644 index 0000000..786e0f0 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_authenticated.3 @@ -0,0 +1,20 @@ +.TH libssh2_userauth_authenticated 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_userauth_authenticated - return authentication status +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_userauth_authenticated(LIBSSH2_SESSION *session); + +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +Indicates whether or not the named session has been successfully authenticated. + +.SH RETURN VALUE +Returns 1 if authenticated and 0 if not. + +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_hostbased_fromfile.3 b/deps/share/man/man3/libssh2_userauth_hostbased_fromfile.3 new file mode 100644 index 0000000..2115356 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_hostbased_fromfile.3 @@ -0,0 +1,17 @@ +.TH libssh2_userauth_hostbased_fromfile 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_userauth_hostbased_fromfile - convenience macro for \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_userauth_hostbased_fromfile(LIBSSH2_SESSION *session, const char *username, const char *publickey, const char *privatekey, const char *passphrase, const char *hostname); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP +.SH ERRORS +See \fIlibssh2_userauth_hostbased_fromfile_ex(3)\fP +.SH SEE ALSO +.BR libssh2_userauth_hostbased_fromfile_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_hostbased_fromfile_ex.3 b/deps/share/man/man3/libssh2_userauth_hostbased_fromfile_ex.3 new file mode 100644 index 0000000..a65f802 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_hostbased_fromfile_ex.3 @@ -0,0 +1,12 @@ +.TH libssh2_userauth_hostbased_fromfile_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_userauth_hostbased_fromfile_ex - TODO +.SH SYNOPSIS + +.SH DESCRIPTION + +.SH RETURN VALUE + +.SH ERRORS + +.SH SEE ALSO diff --git a/deps/share/man/man3/libssh2_userauth_keyboard_interactive.3 b/deps/share/man/man3/libssh2_userauth_keyboard_interactive.3 new file mode 100644 index 0000000..a85de32 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_keyboard_interactive.3 @@ -0,0 +1,20 @@ +.TH libssh2_userauth_keyboard_interactive 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_userauth_keyboard_interactive - convenience macro for \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> +.nf + +int +libssh2_userauth_keyboard_interactive(LIBSSH2_SESSION* session, + const char *username, + LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC((*response_callback))); +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP +.SH ERRORS +See \fIlibssh2_userauth_keyboard_interactive_ex(3)\fP +.SH SEE ALSO +.BR libssh2_userauth_keyboard_interactive_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_keyboard_interactive_ex.3 b/deps/share/man/man3/libssh2_userauth_keyboard_interactive_ex.3 new file mode 100644 index 0000000..ada012a --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_keyboard_interactive_ex.3 @@ -0,0 +1,58 @@ +.TH libssh2_userauth_keyboard_interactive_ex 3 "8 Mar 2008" "libssh2 0.19" "libssh2 manual" +.SH NAME +libssh2_userauth_keyboard_interactive_ex - authenticate a session using +keyboard-interactive authentication +.SH SYNOPSIS +.nf +#include <libssh2.h> + +int +libssh2_userauth_keyboard_interactive_ex(LIBSSH2_SESSION *session, + const char *username, + unsigned int username_len, + LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC(*response_callback)); +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +\fIlibssh2_session_init_ex(3)\fP. + +\fIusername\fP - Name of user to attempt keyboard-interactive authentication +for. + +\fIusername_len\fP - Length of username parameter. + +\fIresponse_callback\fP - As authentication proceeds, the host issues several +(1 or more) challenges and requires responses. This callback will be called at +this moment. The callback is responsible to obtain responses for the +challenges, fill the provided data structure and then return +control. Responses will be sent to the host. String values will be free(3)ed +by the library. The callback prototype must match this: + +.nf + void response(const char *name, + int name_len, const char *instruction, + int instruction_len, + int num_prompts, + const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts, + LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses, + void **abstract); +.fi + +Attempts keyboard-interactive (challenge/response) authentication. + +Note that many SSH servers will always issue a single "password" challenge, +requesting actual password as response, but it is not required by the +protocol, and various authentication schemes, such as smartcard authentication +may use keyboard-interactive authentication type too. +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN +when it would otherwise block. While LIBSSH2_ERROR_EAGAIN is a negative +number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fLIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - failed, invalid username/password +or public/private key. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_list.3 b/deps/share/man/man3/libssh2_userauth_list.3 new file mode 100644 index 0000000..de349f1 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_list.3 @@ -0,0 +1,39 @@ +.TH libssh2_userauth_list 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_userauth_list - list supported authentication methods +.SH SYNOPSIS +.nf +#include <libssh2.h> + +char * +libssh2_userauth_list(LIBSSH2_SESSION *session, const char *username, + unsigned int username_len); +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIusername\fP - Username which will be used while authenticating. Note that +most server implementations do not permit attempting authentication with +different usernames between requests. Therefore this must be the same username +you will use on later userauth calls. + +\fIusername_len\fP - Length of username parameter. + +Send a \fBSSH_USERAUTH_NONE\fP request to the remote host. Unless the remote +host is configured to accept none as a viable authentication scheme +(unlikely), it will return \fBSSH_USERAUTH_FAILURE\fP along with a listing of +what authentication schemes it does support. In the unlikely event that none +authentication succeeds, this method with return NULL. This case may be +distinguished from a failing case by examining +\fIlibssh2_userauth_authenticated(3)\fP. +.SH RETURN VALUE +On success a comma delimited list of supported authentication schemes. This +list is internally managed by libssh2. On failure returns NULL. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_EAGAIN\fP - Marked for non-blocking I/O but the call +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_password.3 b/deps/share/man/man3/libssh2_userauth_password.3 new file mode 100644 index 0000000..15e5511 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_password.3 @@ -0,0 +1,19 @@ +.TH libssh2_userauth_password 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_userauth_password - convenience macro for \fIlibssh2_userauth_password_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int libssh2_userauth_password(LIBSSH2_SESSION *session, + const char *username, + const char *password); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_userauth_password_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_userauth_password_ex(3)\fP +.SH ERRORS +See \fIlibssh2_userauth_password_ex(3)\fP +.SH SEE ALSO +.BR libssh2_userauth_password_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_password_ex.3 b/deps/share/man/man3/libssh2_userauth_password_ex.3 new file mode 100644 index 0000000..dc9e108 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_password_ex.3 @@ -0,0 +1,57 @@ +.TH libssh2_userauth_password_ex 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_userauth_password_ex - authenticate a session with username and password +.SH SYNOPSIS +#include <libssh2.h> +.nf +int libssh2_userauth_password_ex(LIBSSH2_SESSION *session, + const char *username, + unsigned int username_len, + const char *password, + unsigned int password_len, + LIBSSH2_PASSWD_CHANGEREQ_FUNC((*passwd_change_cb))); + +#define libssh2_userauth_password(session, username, password) \\ + libssh2_userauth_password_ex((session), (username), \\ + strlen(username), \\ + (password), strlen(password), NULL) +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIusername\fP - Name of user to attempt plain password authentication for. + +\fIusername_len\fP - Length of username parameter. + +\fIpassword\fP - Password to use for authenticating username. + +\fIpassword_len\fP - Length of password parameter. + +\fIpasswd_change_cb\fP - If the host accepts authentication but +requests that the password be changed, this callback will be issued. +If no callback is defined, but server required password change, +authentication will fail. + +Attempt basic password authentication. Note that many SSH servers +which appear to support ordinary password authentication actually have +it disabled and use Keyboard Interactive authentication (routed via +PAM or another authentication backed) instead. + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +Some of the errors this function may return include: + +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_PASSWORD_EXPIRED\fP - + +\fLIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - failed, invalid username/password +or public/private key. +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_publickey.3 b/deps/share/man/man3/libssh2_userauth_publickey.3 new file mode 100644 index 0000000..0081a24 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_publickey.3 @@ -0,0 +1,27 @@ +.TH libssh2_userauth_publickey 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_userauth_publickey - authenticate using a callback function +.SH SYNOPSIS +#include <libssh2.h> + +.nf +int libssh2_userauth_publickey(LIBSSH2_SESSION *session, + const char *user, + const unsigned char *pubkeydata, + size_t pubkeydata_len, + sign_callback, + void **abstract); +.SH DESCRIPTION +Authenticate with the \fIsign_callback\fP callback that matches the prototype +below +.SH CALLBACK +.nf +int name(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, + const unsigned char *data, size_t data_len, void **abstract); +.fi + +This function gets called... +.SH RETURN VALUE +Return 0 on success or negative on failure. +.SH SEE ALSO +.BR libssh2_userauth_publickey_fromfile_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_publickey_fromfile.3 b/deps/share/man/man3/libssh2_userauth_publickey_fromfile.3 new file mode 100644 index 0000000..f4799a1 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_publickey_fromfile.3 @@ -0,0 +1,22 @@ +.TH libssh2_userauth_publickey_fromfile 3 "20 Feb 2010" "libssh2 1.2.4" "libssh2 manual" +.SH NAME +libssh2_userauth_publickey_fromfile - convenience macro for \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP calls +.SH SYNOPSIS +#include <libssh2.h> + +int +libssh2_userauth_publickey_fromfile(LIBSSH2_SESSION *session, + const char *username, + const char *publickey, + const char *privatekey, + const char *passphrase); + +.SH DESCRIPTION +This is a macro defined in a public libssh2 header file that is using the +underlying function \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP. +.SH RETURN VALUE +See \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP +.SH ERRORS +See \fIlibssh2_userauth_publickey_fromfile_ex(3)\fP +.SH SEE ALSO +.BR libssh2_userauth_publickey_fromfile_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_publickey_fromfile_ex.3 b/deps/share/man/man3/libssh2_userauth_publickey_fromfile_ex.3 new file mode 100644 index 0000000..0d77c9a --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_publickey_fromfile_ex.3 @@ -0,0 +1,52 @@ +.TH libssh2_userauth_publickey_fromfile 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual" +.SH NAME +libssh2_userauth_publickey_fromfile - authenticate a session with a public key, read from a file +.SH SYNOPSIS +#include <libssh2.h> + +.nf +int libssh2_userauth_publickey_fromfile_ex(LIBSSH2_SESSION *session, + const char *username, + unsigned int ousername_len, + const char *publickey, + const char *privatekey, + const char *passphrase); +.SH DESCRIPTION +\fIsession\fP - Session instance as returned by +\fBlibssh2_session_init_ex(3)\fP + +\fIusername\fP - Pointer to user name to authenticate as. + +\fIusername_len\fP - Length of \fIusername\fP. + +\fIpublickey\fP - Path name of the public key file. +(e.g. /etc/ssh/hostkey.pub). If libssh2 is built against OpenSSL, this option +can be set to NULL. + +\fIprivatekey\fP - Path name of the private key file. (e.g. /etc/ssh/hostkey) + +\fIpassphrase\fP - Passphrase to use when decoding \fIprivatekey\fP. + +Attempt public key authentication using a PEM encoded private key file stored +on disk + +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. + +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_PUBLICKEY_UNVERIFIED\fP - The username/public key +combination was invalid. + +\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - Authentication using the supplied +public key was not accepted. + +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_userauth_publickey_frommemory.3 b/deps/share/man/man3/libssh2_userauth_publickey_frommemory.3 new file mode 100644 index 0000000..685bd59 --- /dev/null +++ b/deps/share/man/man3/libssh2_userauth_publickey_frommemory.3 @@ -0,0 +1,56 @@ +.TH libssh2_userauth_publickey_frommemory 3 "1 Sep 2014" "libssh2 1.5" "libssh2 manual" +.SH NAME +libssh2_userauth_publickey_frommemory - authenticate a session with a public key, read from memory +.SH SYNOPSIS +#include <libssh2.h> + +.nf +int libssh2_userauth_publickey_frommemory(LIBSSH2_SESSION *session, + const char *username, + size_t username_len, + const char *publickeydata, + size_t publickeydata_len, + const char *privatekeydata, + size_t privatekeydata_len, + const char *passphrase); +.SH DESCRIPTION +This function allows to authenticate a session with a public key read from memory. +It's only supported when libssh2 is backed by OpenSSL. +\fIsession\fP - Session instance as returned by +.BR libssh2_session_init_ex(3) + +\fIusername\fP - Remote user name to authenticate as. + +\fIusername_len\fP - Length of username. + +\fIpublickeydata\fP - Buffer containing the contents of a public key file. + +\fIpublickeydata_len\fP - Length of public key data. + +\fIprivatekeydata\fP - Buffer containing the contents of a private key file. + +\fIprivatekeydata_len\fP - Length of private key data. + +\fIpassphrase\fP - Passphrase to use when decoding private key file. + +Attempt public key authentication using a PEM encoded private key file stored in memory. +.SH RETURN VALUE +Return 0 on success or negative on failure. It returns +LIBSSH2_ERROR_EAGAIN when it would otherwise block. While +LIBSSH2_ERROR_EAGAIN is a negative number, it isn't really a failure per se. +.SH ERRORS +\fILIBSSH2_ERROR_ALLOC\fP - An internal memory allocation call failed. + +\fILIBSSH2_ERROR_SOCKET_SEND\fP - Unable to send data on socket. + +\fILIBSSH2_ERROR_SOCKET_TIMEOUT\fP - + +\fILIBSSH2_ERROR_PUBLICKEY_UNVERIFIED\fP - The username/public key +combination was invalid. + +\fILIBSSH2_ERROR_AUTHENTICATION_FAILED\fP - Authentication using the supplied +public key was not accepted. +.SH AVAILABILITY +libssh2_userauth_publickey_frommemory was added in libssh2 1.6.0 +.SH SEE ALSO +.BR libssh2_session_init_ex(3) diff --git a/deps/share/man/man3/libssh2_version.3 b/deps/share/man/man3/libssh2_version.3 new file mode 100644 index 0000000..f98ca96 --- /dev/null +++ b/deps/share/man/man3/libssh2_version.3 @@ -0,0 +1,36 @@ +.TH libssh2_version 3 "23 Feb 2009" "libssh2 1.1" "libssh2 manual" +.SH NAME +libssh2_version - return the libssh2 version number +.SH SYNOPSIS +#include <libssh2.h> + +const char * +libssh2_version(int required_version); +.SH DESCRIPTION +If \fIrequired_version\fP is lower than or equal to the version number of the +libssh2 in use, the version number of libssh2 is returned as a pointer to a +zero terminated string. + +The \fIrequired_version\fP should be the version number as constructed by the +LIBSSH2_VERSION_NUM define in the libssh2.h public header file, which is a 24 +bit number in the 0xMMmmpp format. MM for major, mm for minor and pp for patch +number. +.SH RETURN VALUE +The version number of libssh2 is returned as a pointer to a zero terminated +string or NULL if the \fIrequired_version\fP isn't fulfilled. +.SH EXAMPLE +To make sure you run with the correct libssh2 version: + +.nf +if (!libssh2_version(LIBSSH2_VERSION_NUM)) { + fprintf (stderr, \&"Runtime libssh2 version too old!\&"); + exit(1); +} +.fi + +Unconditionally get the version number: + +printf(\&"libssh2 version: %s\&", libssh2_version(0) ); +.SH AVAILABILITY +This function was added in libssh2 1.1, in previous versions there way no way +to extract this info in run-time. diff --git a/deps/share/man/man3/zlib.3 b/deps/share/man/man3/zlib.3 new file mode 100644 index 0000000..bda4eb0 --- /dev/null +++ b/deps/share/man/man3/zlib.3 @@ -0,0 +1,149 @@ +.TH ZLIB 3 "15 Jan 2017" +.SH NAME +zlib \- compression/decompression library +.SH SYNOPSIS +[see +.I zlib.h +for full description] +.SH DESCRIPTION +The +.I zlib +library is a general purpose data compression library. +The code is thread safe, assuming that the standard library functions +used are thread safe, such as memory allocation routines. +It provides in-memory compression and decompression functions, +including integrity checks of the uncompressed data. +This version of the library supports only one compression method (deflation) +but other algorithms may be added later +with the same stream interface. +.LP +Compression can be done in a single step if the buffers are large enough +or can be done by repeated calls of the compression function. +In the latter case, +the application must provide more input and/or consume the output +(providing more output space) before each call. +.LP +The library also supports reading and writing files in +.IR gzip (1) +(.gz) format +with an interface similar to that of stdio. +.LP +The library does not install any signal handler. +The decoder checks the consistency of the compressed data, +so the library should never crash even in the case of corrupted input. +.LP +All functions of the compression library are documented in the file +.IR zlib.h . +The distribution source includes examples of use of the library +in the files +.I test/example.c +and +.IR test/minigzip.c, +as well as other examples in the +.IR examples/ +directory. +.LP +Changes to this version are documented in the file +.I ChangeLog +that accompanies the source. +.LP +.I zlib +is built in to many languages and operating systems, including but not limited to +Java, Python, .NET, PHP, Perl, Ruby, Swift, and Go. +.LP +An experimental package to read and write files in the .zip format, +written on top of +.I zlib +by Gilles Vollant ([email protected]), +is available at: +.IP +http://www.winimage.com/zLibDll/minizip.html +and also in the +.I contrib/minizip +directory of the main +.I zlib +source distribution. +.SH "SEE ALSO" +The +.I zlib +web site can be found at: +.IP +http://zlib.net/ +.LP +The data format used by the +.I zlib +library is described by RFC +(Request for Comments) 1950 to 1952 in the files: +.IP +http://tools.ietf.org/html/rfc1950 (for the zlib header and trailer format) +.br +http://tools.ietf.org/html/rfc1951 (for the deflate compressed data format) +.br +http://tools.ietf.org/html/rfc1952 (for the gzip header and trailer format) +.LP +Mark Nelson wrote an article about +.I zlib +for the Jan. 1997 issue of Dr. Dobb's Journal; +a copy of the article is available at: +.IP +http://marknelson.us/1997/01/01/zlib-engine/ +.SH "REPORTING PROBLEMS" +Before reporting a problem, +please check the +.I zlib +web site to verify that you have the latest version of +.IR zlib ; +otherwise, +obtain the latest version and see if the problem still exists. +Please read the +.I zlib +FAQ at: +.IP +http://zlib.net/zlib_faq.html +.LP +before asking for help. +Send questions and/or comments to [email protected], +or (for the Windows DLL version) to Gilles Vollant ([email protected]). +.SH AUTHORS AND LICENSE +Version 1.2.11 +.LP +Copyright (C) 1995-2017 Jean-loup Gailly and Mark Adler +.LP +This software is provided 'as-is', without any express or implied +warranty. In no event will the authors be held liable for any damages +arising from the use of this software. +.LP +Permission is granted to anyone to use this software for any purpose, +including commercial applications, and to alter it and redistribute it +freely, subject to the following restrictions: +.LP +.nr step 1 1 +.IP \n[step]. 3 +The origin of this software must not be misrepresented; you must not +claim that you wrote the original software. If you use this software +in a product, an acknowledgment in the product documentation would be +appreciated but is not required. +.IP \n+[step]. +Altered source versions must be plainly marked as such, and must not be +misrepresented as being the original software. +.IP \n+[step]. +This notice may not be removed or altered from any source distribution. +.LP +Jean-loup Gailly Mark Adler +.br +.LP +The deflate format used by +.I zlib +was defined by Phil Katz. +The deflate and +.I zlib +specifications were written by L. Peter Deutsch. +Thanks to all the people who reported problems and suggested various +improvements in +.IR zlib ; +who are too numerous to cite here. +.LP +UNIX manual page by R. P. C. Rodgers, +U.S. National Library of Medicine ([email protected]). +.\" end of man page |