From dd76e45c20acc3f352ffe8257208cc617ba33eba Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 19:23:08 +0200 Subject: Adding upstream version 1:4.6.1. Signed-off-by: Daniel Baumann --- .gitattributes | 8 + ACKNOWLEDGEMENTS | 162 + ACTIONS-README | 774 +++ CHANGES | 914 ++++ COPYING | 339 ++ INSTALL | 47 + README-4.6.1 | 340 ++ TECHNICAL-INFO | 289 + USAGE-4.6 | 94 + USAGE-MKSQUASHFS-4.6 | 1069 ++++ USAGE-SQFSCAT-4.6 | 74 + USAGE-SQFSTAR-4.6 | 812 +++ USAGE-UNSQUASHFS-4.6 | 498 ++ examples/pseudo-file.example | 74 + generate-manpages/functions.sh | 18 + generate-manpages/install-manpages.sh | 82 + generate-manpages/mksquashfs-manpage.sh | 253 + generate-manpages/mksquashfs.h2m | 150 + generate-manpages/sqfscat-manpage.sh | 189 + generate-manpages/sqfscat.h2m | 29 + generate-manpages/sqfstar-manpage.sh | 241 + generate-manpages/sqfstar.h2m | 84 + generate-manpages/unsquashfs-manpage.sh | 189 + generate-manpages/unsquashfs.h2m | 89 + manpages/.gitattributes | 1 + manpages/README | 13 + manpages/mksquashfs.1 | 554 ++ manpages/sqfscat.1 | 103 + manpages/sqfstar.1 | 400 ++ manpages/unsquashfs.1 | 279 + squashfs-tools/.gitignore | 5 + squashfs-tools/Makefile | 470 ++ squashfs-tools/action.c | 3574 +++++++++++++ squashfs-tools/action.h | 351 ++ squashfs-tools/caches-queues-lists.c | 647 +++ squashfs-tools/caches-queues-lists.h | 200 + squashfs-tools/compressor.c | 145 + squashfs-tools/compressor.h | 132 + squashfs-tools/date.c | 129 + squashfs-tools/date.h | 28 + squashfs-tools/endian_compat.h | 34 + squashfs-tools/error.h | 43 + squashfs-tools/fnmatch_compat.h | 32 + squashfs-tools/gzip_wrapper.c | 513 ++ squashfs-tools/gzip_wrapper.h | 69 + squashfs-tools/info.c | 174 + squashfs-tools/info.h | 30 + squashfs-tools/lz4_wrapper.c | 307 ++ squashfs-tools/lz4_wrapper.h | 55 + squashfs-tools/lzma_wrapper.c | 127 + squashfs-tools/lzma_xz_wrapper.c | 169 + squashfs-tools/lzo_wrapper.c | 450 ++ squashfs-tools/lzo_wrapper.h | 72 + squashfs-tools/merge_sort.h | 116 + squashfs-tools/mksquashfs.c | 8902 +++++++++++++++++++++++++++++++ squashfs-tools/mksquashfs.h | 285 + squashfs-tools/mksquashfs_error.h | 74 + squashfs-tools/process_fragments.c | 373 ++ squashfs-tools/process_fragments.h | 28 + squashfs-tools/progressbar.c | 300 ++ squashfs-tools/progressbar.h | 35 + squashfs-tools/pseudo.c | 1376 +++++ squashfs-tools/pseudo.h | 107 + squashfs-tools/pseudo_xattr.c | 176 + squashfs-tools/read_fs.c | 1090 ++++ squashfs-tools/read_fs.h | 36 + squashfs-tools/read_xattrs.c | 454 ++ squashfs-tools/reader.c | 715 +++ squashfs-tools/reader.h | 39 + squashfs-tools/restore.c | 168 + squashfs-tools/restore.h | 28 + squashfs-tools/signals.h | 54 + squashfs-tools/sort.c | 373 ++ squashfs-tools/sort.h | 37 + squashfs-tools/squashfs_compat.h | 833 +++ squashfs-tools/squashfs_fs.h | 502 ++ squashfs-tools/squashfs_swap.h | 425 ++ squashfs-tools/swap.c | 117 + squashfs-tools/tar.c | 1682 ++++++ squashfs-tools/tar.h | 153 + squashfs-tools/tar_xattr.c | 122 + squashfs-tools/unsquash-1.c | 582 ++ squashfs-tools/unsquash-12.c | 30 + squashfs-tools/unsquash-123.c | 79 + squashfs-tools/unsquash-1234.c | 95 + squashfs-tools/unsquash-2.c | 715 +++ squashfs-tools/unsquash-3.c | 824 +++ squashfs-tools/unsquash-34.c | 183 + squashfs-tools/unsquash-4.c | 832 +++ squashfs-tools/unsquashfs.c | 4655 ++++++++++++++++ squashfs-tools/unsquashfs.h | 345 ++ squashfs-tools/unsquashfs_error.h | 64 + squashfs-tools/unsquashfs_info.c | 125 + squashfs-tools/unsquashfs_info.h | 30 + squashfs-tools/unsquashfs_xattr.c | 302 ++ squashfs-tools/version.mk | 2 + squashfs-tools/xattr.c | 1322 +++++ squashfs-tools/xattr.h | 241 + squashfs-tools/xz_wrapper.c | 551 ++ squashfs-tools/xz_wrapper.h | 65 + squashfs-tools/zstd_wrapper.c | 265 + squashfs-tools/zstd_wrapper.h | 42 + 102 files changed, 45873 insertions(+) create mode 100644 .gitattributes create mode 100644 ACKNOWLEDGEMENTS create mode 100644 ACTIONS-README create mode 100644 CHANGES create mode 100644 COPYING create mode 100644 INSTALL create mode 100644 README-4.6.1 create mode 100644 TECHNICAL-INFO create mode 100644 USAGE-4.6 create mode 100644 USAGE-MKSQUASHFS-4.6 create mode 100644 USAGE-SQFSCAT-4.6 create mode 100644 USAGE-SQFSTAR-4.6 create mode 100644 USAGE-UNSQUASHFS-4.6 create mode 100644 examples/pseudo-file.example create mode 100755 generate-manpages/functions.sh create mode 100755 generate-manpages/install-manpages.sh create mode 100755 generate-manpages/mksquashfs-manpage.sh create mode 100644 generate-manpages/mksquashfs.h2m create mode 100755 generate-manpages/sqfscat-manpage.sh create mode 100644 generate-manpages/sqfscat.h2m create mode 100755 generate-manpages/sqfstar-manpage.sh create mode 100644 generate-manpages/sqfstar.h2m create mode 100755 generate-manpages/unsquashfs-manpage.sh create mode 100644 generate-manpages/unsquashfs.h2m create mode 100644 manpages/.gitattributes create mode 100644 manpages/README create mode 100644 manpages/mksquashfs.1 create mode 100644 manpages/sqfscat.1 create mode 100644 manpages/sqfstar.1 create mode 100644 manpages/unsquashfs.1 create mode 100644 squashfs-tools/.gitignore create mode 100755 squashfs-tools/Makefile create mode 100644 squashfs-tools/action.c create mode 100644 squashfs-tools/action.h create mode 100644 squashfs-tools/caches-queues-lists.c create mode 100644 squashfs-tools/caches-queues-lists.h create mode 100644 squashfs-tools/compressor.c create mode 100644 squashfs-tools/compressor.h create mode 100644 squashfs-tools/date.c create mode 100644 squashfs-tools/date.h create mode 100644 squashfs-tools/endian_compat.h create mode 100644 squashfs-tools/error.h create mode 100644 squashfs-tools/fnmatch_compat.h create mode 100644 squashfs-tools/gzip_wrapper.c create mode 100644 squashfs-tools/gzip_wrapper.h create mode 100644 squashfs-tools/info.c create mode 100644 squashfs-tools/info.h create mode 100644 squashfs-tools/lz4_wrapper.c create mode 100644 squashfs-tools/lz4_wrapper.h create mode 100644 squashfs-tools/lzma_wrapper.c create mode 100644 squashfs-tools/lzma_xz_wrapper.c create mode 100644 squashfs-tools/lzo_wrapper.c create mode 100644 squashfs-tools/lzo_wrapper.h create mode 100644 squashfs-tools/merge_sort.h create mode 100644 squashfs-tools/mksquashfs.c create mode 100644 squashfs-tools/mksquashfs.h create mode 100644 squashfs-tools/mksquashfs_error.h create mode 100644 squashfs-tools/process_fragments.c create mode 100644 squashfs-tools/process_fragments.h create mode 100644 squashfs-tools/progressbar.c create mode 100644 squashfs-tools/progressbar.h create mode 100644 squashfs-tools/pseudo.c create mode 100644 squashfs-tools/pseudo.h create mode 100644 squashfs-tools/pseudo_xattr.c create mode 100644 squashfs-tools/read_fs.c create mode 100644 squashfs-tools/read_fs.h create mode 100644 squashfs-tools/read_xattrs.c create mode 100644 squashfs-tools/reader.c create mode 100644 squashfs-tools/reader.h create mode 100644 squashfs-tools/restore.c create mode 100644 squashfs-tools/restore.h create mode 100644 squashfs-tools/signals.h create mode 100644 squashfs-tools/sort.c create mode 100644 squashfs-tools/sort.h create mode 100644 squashfs-tools/squashfs_compat.h create mode 100644 squashfs-tools/squashfs_fs.h create mode 100644 squashfs-tools/squashfs_swap.h create mode 100644 squashfs-tools/swap.c create mode 100644 squashfs-tools/tar.c create mode 100644 squashfs-tools/tar.h create mode 100644 squashfs-tools/tar_xattr.c create mode 100644 squashfs-tools/unsquash-1.c create mode 100644 squashfs-tools/unsquash-12.c create mode 100644 squashfs-tools/unsquash-123.c create mode 100644 squashfs-tools/unsquash-1234.c create mode 100644 squashfs-tools/unsquash-2.c create mode 100644 squashfs-tools/unsquash-3.c create mode 100644 squashfs-tools/unsquash-34.c create mode 100644 squashfs-tools/unsquash-4.c create mode 100644 squashfs-tools/unsquashfs.c create mode 100644 squashfs-tools/unsquashfs.h create mode 100644 squashfs-tools/unsquashfs_error.h create mode 100644 squashfs-tools/unsquashfs_info.c create mode 100644 squashfs-tools/unsquashfs_info.h create mode 100644 squashfs-tools/unsquashfs_xattr.c create mode 100644 squashfs-tools/version.mk create mode 100644 squashfs-tools/xattr.c create mode 100644 squashfs-tools/xattr.h create mode 100644 squashfs-tools/xz_wrapper.c create mode 100644 squashfs-tools/xz_wrapper.h create mode 100644 squashfs-tools/zstd_wrapper.c create mode 100644 squashfs-tools/zstd_wrapper.h diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..bf8e7a0 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,8 @@ +version.mk export-subst +kernel export-ignore +README export-ignore +README-4.5 export-ignore +README-4.5.1 export-ignore +README-4.6 export-ignore +USAGE export-ignore +RELEASE-READMEs export-ignore diff --git a/ACKNOWLEDGEMENTS b/ACKNOWLEDGEMENTS new file mode 100644 index 0000000..2097bb7 --- /dev/null +++ b/ACKNOWLEDGEMENTS @@ -0,0 +1,162 @@ + ACKNOWLEDGEMENTS + +Thanks to everyone who have downloaded Squashfs. I appreciate people +using it, and any feedback you have. + +The following have provided useful feedback, which has guided +some of the extra features in squashfs. This is a randomly ordered +(roughly in chronological order) list, which is updated when +I remember... + +Acknowledgements for Squashfs 4.3 +--------------------------------- + +Thanks to Bruno Wolff III and Andy Lutomirski for useful feedback +during the long development process of Squashfs 4.3. + +Acknowledgements for Squashfs 4.2 +--------------------------------- + +Thanks to Lasse Collin (http://tukaani.org/xz/) for mainlining XZ +decompression support. + +Acknowledgements for Squashfs 4.1 +--------------------------------- + +Thanks to Chan Jeong and LG for the patches to support LZO +compression. + +Acknowledgements for Squashfs 4.0 +--------------------------------- + +Thanks to Tim Bird and CELF (Consumer Electronics Linux Forum) for helping +fund mainstreaming of Squashfs into the 2.6.29 kernel and the +changes to the Squashfs tools to support the new 4.0 file system layout. + +Acknowledgements for Squashfs-3.3 +------------------------------------ + +Peter Korsgaard and others sent patches updating Squashfs to changes in the +VFS interface for 2.6.22/2.6.23/2.6.24-rc1. Peter also sent some small patches +for the Squashfs kernel code. + +Vito Di Leo sent a patch extending Mksquashfs to support regex filters. +While his patched worked, it unfortunately made it easy to make Mksquashfs +perform unpredictably with poorly choosen regex expressions. It, however, +encouraged myself to add support for wildcard pattern matching and regex +filters in a different way. + +Acknowledgements for Squashfs-3.2-r2 +------------------------------------ + +Junjiro Okajima discovered a couple of SMP issues, thanks. + +Junjiro Okajima and Tomas Matejicek have produced some good LZMA patches +for Squashfs. + +Acknowledgements for Squashfs-3.2 +--------------------------------- + +Peter Korsgaard sent a patch updating Squashfs to changes in the VFS interface +in Linux 2.6.20. + +Acknowledgements for Squashfs-3.1 +--------------------------------- + +Kenneth Duda and Ed Swierk of Arastra Inc. identified numerous bugs with +Squashfs, and provided patches which were the basis for some of the +fixes. In particular they identified the fragment rounding bug, the +NFS bug, the initrd bug, and helped identify the 4K stack overflow bug. + +Scott James Remnant (Ubuntu) also identified the fragment rounding bug, +and he also provided a patch. + +Ming Zhang identified the Lseek bug in Mksquashfs. His tests on the +performance of Mksquashfs on SMP systems encouraged the rewrite of +Mksquashfs. + +Peter Korsgaard, Daniel Olivera and Zilvinas Valinskas noticed +Squashfs 3.0 didn't compile on Linux-2.6.18-rc[1-4] due to changes +in the Linux VFS interfaces, and provided patches. + +Tomas Matejicek (SLAX) suggested the -force option on Unsquashfs, and noticed +Unsquashfs didn't return the correct exit status. + +Yann Le Doare reported a kernel oops and provided a Qemu image that led +to the identification of the simultaneously accessing multiply mounted Squashfs +filesystems bug. + + +Older acknowledgements +---------------------- + +Mark Robson - pointed out early on that initrds didn't work + +Adam Warner - pointed out that greater than 2GB filesystems didn't work. + +John Sutton - raised the problem when archiving the entire filesystem +(/) there was no way to prevent /proc being archived. This prompted +exclude files. + +Martin Mueller (LinuxTV) - noticed that the filesystem length in the +superblock doesn't match the output filesystem length. This is due to +padding to a 4K boundary. This prompted the addition of the -nopad option. +He also reported a problem where 32K block filesystems hung when used as +initrds. + +Arkadiusz Patyk (Polish Linux Distribution - PLD) reported a problem where 32K +block filesystems hung when used as a root filesystem mounted as a loopback +device. + +David Fox (Lindows) noticed that the exit codes returned by Mksquashfs were +wrong. He also noticed that a lot of time was spent in the duplicate scan +routine. + +Cameron Rich complained that Squashfs did not support FIFOs or sockets. + +Steve Chadsey and Thomas Weissmuller noticed that files larger than the +available memory could not be compressed by Mksquashfs. + +"Ptwahyu" and "Hoan" (I have no full names and I don't like giving people's +email addresses), noticed that Mksquashfs 1.3 SEGV'd occasionally. Even though +I had already noticed this bug, it is useful to be informed by other people. + +Don Elwell, Murray Jensen and Cameron Rich, have all sent in patches. Thanks, +I have not had time to do anything about them yet... + +Drew Scott Daniels has been a good advocate for Squashfs. + +Erik Andersen has made some nice suggestions, unfortunately, I have +not had time to implement anything. + +Artemiy I. Pavlov has written a useful LDP mini-howto for Squashfs +(http://linuxdoc.artemio.net/squashfs). + +Yves Combe reported the Apple G5 bug, when using Squashfs for +his PPC Knoppix-mib livecd project. + +Jaco Greeff (mklivecd project, and maintainer of the Mandrake +squashfs-tools package) suggested the new mksquashfs -ef option, and the +standalone build for mksquashfs. + +Mike Schaudies made a donation. + +Arkadiusz Patyk from the Polish Linux Distribution reported that Squashfs +didn't work on amd64 machines. He gave me an account on a PLD amd64 machine +which allowed myself to track down these bugs. + +Miles Roper, Peter Kjellerstedt and Willy Tarreau reported that release 2.1 did +not compile with gcc < 3.x. + +Marcel J.E. Mol reported lack of kernel memory issues when using Squashfs +on small memory embedded systems. This prompted the addition of the embedded +system kernel configuration options. + +Era Scarecrow noticed that Mksquashfs had not been updated to reflect that +smaller than 4K blocks are no longer supported. + +Kenichi Shima reported the Kconfig file had not been updated to 2.2. + +Aaron Ten Clay made a donation! + +Tomas Matejicek (SLAX) made a donation! diff --git a/ACTIONS-README b/ACTIONS-README new file mode 100644 index 0000000..ede4f76 --- /dev/null +++ b/ACTIONS-README @@ -0,0 +1,774 @@ + MKSQUASHFS ACTIONS + ================== + +The new Mksquashfs Actions code allows an "action" to be executed +on a file if one or more "tests" succeed. If you're familiar +with the "find" command, then an action is similar to "-print", +and a test is similar to say "-name" or "-type". + +Actions add greater flexibility when building images from sources. +They can be used to optimise compression, I/O performance, and they +also allow more control on the exclusion of files from the source, and +allow uid/gid and mode to be changed on a file basis. + +1. Specification +================ + +Actions can be specified on the command line with the -action option. +They can also be put into a file, and added with the -action-file +option. If put into a file, there is one action per line. But, lines +can be extended over many lines with continuation (\). + +If you want to get a log of what actions were performed, and the values +returned by the tests for each file, you can use the -log-action option +for the command line and -log-action-file for action files. + +Similarly there are -true-action (-true-action-file) and -false-action +(-false-action-file) options which log if the tests evaluated to TRUE, +and vice-versa: + +2. Syntax +========= + +An action consists of two parts, separated by an "@". The action to +be executed is placed before the @, and one or more tests are +placed afer the @. If the action or tests has an argument, it is +given in brackets. Brackets are optional if no argument is needed, +e.g. + +compressed()@name("filename") + +compressed@name("filename") + +do exactly the same thing. + +Arguments can be either numeric or string, depending on the +action and test. + +String arguments can be enclosed in double-quotes ("), to prevent the +parser from treating characters within it specially. Within double-quotes +only '\' is treatedly specially, and only at the end of a line. Special +characters can also be backslashed (\) to prevent interpretation by the +parser, e.g. the following is equivalent: + +compressed@name(file\ name\ with\ \&&\ and\ spaces) + +compressed@name("file name with && and spaces") + +Numeric arguments are of the form [range]number[size], where +[range] is either + + '<' or '-', match on less than number + '>' or '+', match on greater than number + "" (nothing), match on exactly number + +[size] is either: + "" (nothing), number + 'k' or 'K', number * 2^10 + 'm' or 'M', number * 2^20 + 'g' or 'G', number * 2^30 + +e.g. the following is equivalent: + +compressed@filesize(-81920) +compressed@filesize(<80K) + +Both will match on files less than 80K in size. + +Characters which are treated specially by the parser are * ( ) && || +! , @. Plus whitespace (spaces and tabs). + +Note: if the action is typed on the command line, then many special +characters will be evaluated by the shell, and you should always +check what is actually being passed to Mksquashfs. If in doubt use +-action-file where the additional complexities of shell evaluation is +avoided. + +For example this action line will work in an action file + +compressed()@name("file name") + +But, if typed on the command line, it will need to be: + +% mksquashfs source image -action "compressed()@name(\"file name\")" + + +3. Logical operators +==================== + +Tests can be combined with the logical operators && (and), || (or) and +can be negated with the unary ! (not). Expressions thus formed can also +be bracketed with "(" and ")", to create nested expressions. + +Operators do not have precedence and are evaluated strictly left to +right. To enforce precedence use brackets, e.g. + +test1 && test2 || test3 + +will be evaluated as + +(test1 && test2) || test3 + +&& and || are short-circuit operators, where the rhs (right hand side) +is only evaluated if the lhs (left hand side) has been insufficient +to determine the value. For example in the above, test3 will only be +evaluated if (test1 && test2) evaluates to FALSE. + +4. Test operators +================= + +The following test operators are supported: + +4.1 name(pattern) + +Returns TRUE if the filename (basename without leading directory components) +matches pattern. Pattern can have wildcards. + +4.2 pathname(pattern) +--------------------- + +Returns TRUE if the full pathname of the file matches pattern. +Pattern can have wildcards. + +4.3 subpathname(pattern) +------------------------ + +Returns TRUE if the directory components of pattern match the first +directory components of the pathname. + +For example, if pattern has one component: + +subpathname(dir1) will match "dir1/somefile", "dir1/dir2/somefile" etc. + +If pattern had two components: + +subpathname(dir1/dir2) will match ""dir1/dir2/somefile" etc. + +Pattern can have wildcards. + +4.4 filesize(value) +------------------- + +Return TRUE if the size of the file is less than, equal to, or larger than +, where can be [<-]number, number, [>+]number. Returns FALSE +on anything not a file. + +4.5 dirsize(value) +------------------ + +Return TRUE if the size of the directory is less than, equal to, or larger than +, where can be [<-]number, number, [>+]number. Returns FALSE +on anything not a directory. + +4.6 size(value) +--------------- + +Return TRUE if the size of the file is less than, equal to, or larger than +, where can be [<-]number, number, [>+]number. Works on any +file type. + +4.7 inode(value) +---------------- + +Return TRUE if the inode number is less than, equal to, or larger than +, where can be [<-]number, number, [>+]number. + +4.8 nlink(value) +---------------- + +Return TRUE if the nlink count is less than, equal to, or larger than +, where can be [<-]number, number, [>+]number. + +4.9 fileblocks(value) +--------------------- + +Return TRUE if the size of the file in blocks (512 bytes) is less than, equal +to, or larger than , where can be [<-]number, number, [>+]number. +Returns FALSE on anything not a file. + +4.10 dirblocks(value) +--------------------- + +Return TRUE if the size of the directory in blocks (512 bytes) is less than, +equal to, or larger than , where can be [<-]number, number, +[>+]number. Returns FALSE on anything not a directory. + +4.11 blocks(value) +------------------ + +Return TRUE if the size of the file in blocks (512 bytes) is less than, equal +to, or larger than , where can be [<-]number, number, [>+]number. +Works on any file type. + +4.12 uid(value) +--------------- +Return TRUE if the uid value is less than, equal to, or larger than +, where can be [<-]number, number, [>+]number. + +4.13 gid(value) +--------------- + +Return TRUE if the gid value is less than, equal to, or larger than +, where can be [<-]number, number, [>+]number. + +4.14 user(string) +----------------- + +Return TRUE if the file owner matches . + +4.15 group(string) +------------------ + +Return TRUE if the file group matches . + +4.16 depth(value) +----------------- + +Return TRUE if file is at depth less than, equal to, or larger than , +where can be [<-]number, number, [>+]number. Top level directory is +depth 1. + +4.17 dircount(value) +-------------------- + +Return TRUE if the number of files in the directory is less than, equal to, or +larger than , where can be [<-]number, number, [>+]number. +Returns FALSE on anything not a directory. + +4.18 filesize_range(minimum, maximum) +------------------------------------- + +Return TRUE if the size of the file is within the range [, ] +inclusive. Returns FALSE on anything not a file. + +4.19 dirsize_range(minimum, maximum) +------------------------------------ + +Return TRUE if the size of the directory is within the rang +[, ] inclusive. Returns FALSE on anything not a directory. + +4.20 size_range(minimum, maximum) +--------------------------------- + +Return TRUE if the size of the file is within the range [, ] +inclusive. Works on any file type. + +4.21 inode_range(minimum, maximum) +---------------------------------- + +Return TRUE if the inode number is within the range [, ] +inclusive. + +4.22 fileblocks_range(minimum, maximum) +--------------------------------------- + +Return TRUE if the size of the file in blocks (512 bytes) is within the range +[, ] inclusive. Returns FALSE on anything not a file. + +4.23 dirblocks_range(minimum, maximum) +-------------------------------------- + +Return TRUE if the size of the directory in blocks (512 bytes) is within the +range [, ] inclusive. Returns FALSE on anything not a +directory. + +4.24 blocks_range(minimum, maximum) +----------------------------------- + +Return TRUE if the size of the file in blocks (512 bytes) is within the range +[, ] inclusive. Works on any file type. + +4.25 uid_range(minimum, maximum) +-------------------------------- + +Return TRUE if the file uid is within the range [, ] +inclusive. + +4.26 gid_range(minimum, maximum) +-------------------------------- + +Return TRUE if the file gid is within the range [, ] +inclusive. + +4.27 depth_range(minimum, maximum) +---------------------------------- + +Return TRUE if file is at depth within the range [, ]. +Top level directory is depth 1. + +4.28 dircount_range(minimum, maximum) +------------------------------------- + +Returns TRUE is the number of files in the directory is within the range +[, ]. Returns FALSE on anything not a directory. + +4.29 type(c) +------------ + +Returns TRUE if the file matches type . can be + f - regular file + d - directory + l - symbolic link + c - character device + b - block device + p - Named Pipe / FIFO + s - socket + + +4.30 perm(mode) +--------------- + +Return TRUE if file permissions match . is the same as +find's -perm option: + + perm(mode) - TRUE if file's permission bits are exactly . + can be octal or symbolic. + + perm(-mode) - TRUE if all permission bits are set for this file. + can be octal or symbolic. + + perm(/mode) - TRUE if any permission bits are set for this file. + can be octal or symbolic. + + The symbolic mode is of the format [ugoa]*[[+-=]PERMS]+ + PERMS = [rwxXst]+ or [ugo] + and can be repeated separated with commas. + +Examples: + +perm(0644) match on a file with permissions exactly rw-r--r--. +perm(u=rw,go=r) as above, but expressed symbolically. + +perm(/222) match on a file which is writable for any of user, group, other, +perm(/u=w,g=w,o=w) as above but expressed symbolically, +perm(/ugo=w) as above but specified more concisely. + +4.31 file(string) +----------------- + +Execute "file command" on file, and return TRUE if the output +matches the substring , for example + +file(ASCII text) will return TRUE if the file is ASCII text. + +Note, this is an expensive test, and should only be run if the file +has matched a number of other short-circuit tests. + +4.32 exists() +------------- + +Test if the file pointed to by the symbolic link exists within the +output filesystem, that is, whether the symbolic link has a relative +path and the relative path can be resolved to an entry within the +output filesystem. + +If the file isn't a symbolic link then the test always returns TRUE. + +4.33 absolute() +--------------- + +Test if the symbolic link is absolute, which by definition means +it points outside of the output filesystem (unless it is to be mounted +as root). If the file isn't a symbolic link then the test always returns +FALSE. + +4.34 readlink(expression) +------------------------- + +Follow or dereference the symbolic link, and evaluate in +the context of the file pointed to by the symbolic link. All inode +attributes, pathname, name and depth all refer to the dereferenced +file. + +If the symbolic link cannot be dereferenced because it points to something +not in the output filesystem (see exists() function above), then FALSE is +returned. If the file is not a symbolic link, the result is the same as +, i.e. readlink() == . + +Examples: + +readlink("name(*.[ch])") returns TRUE if the file referenced by the symbolic +link matches *.[ch]. + +Obviously, expressions created with && || etc. can be specified. + +readlink("depth(1) && filesize(<20K)") returns TRUE if the file referenced +by the symbolic link is a regular file less than 20K in size and in the +top level directory. + +Note: in the above tests the embedded expression to be evaluated is enclosed +in double-quotes ("), this is to prevent the special characters being +evaluated by the parser when parsed at the top-level. Readlink causes +re-evaluation of the embedded string. + +4.36 eval(path, expression) +--------------------------- + +Follow (arg1), and evaluate the (arg2) in the +context of the file discovered by following . All inode attributes, +pathname, name and depth all refer to the file discovered by following +. + +This test operation allows you to add additional context to the evaluation +of the file being scanned, such as "if the current file is XXX, test if the +parent is YYY, and then do ...". Often times you need or want to test +a combination of file status. + +The can be absolute (in which case it is from the root directory of the +output filesystem), or it can be relative to the current file. Obviously +relative paths are more useful. + +If the file referenced by does not exist in the output filesystem, +then FALSE is returned. + +Examples of usage: + +1. If a directory matches pattern, check that it contains a ".git" directory. + This allows you to exclude git repositories, with a double check that it is + a git repository by checking for the .git subdirectory. + + prune@name(*linux*) && type(d) && eval(.git, "type(d)") + + This action will match on any directory named *linux*, and exclude it if + it contains a .git subdirectory. + + +2. If a file matches a pattern, check that the parent directory matches + another pattern. This allows you to delete files if and only if they + are in a particular directory. + + prune@name(*.[ch]) && eval(.., "name(*linux*)") + + This action will delete *.[ch] files, but, only if they are in a directory + matching *linux*. + +4.37 false +---------- + +Always returns FALSE. + +4.38 true +--------- + +Always returns TRUE. + +5. Actions +========== + +An action is something which is done (or applied) to a file if the expression +(made up of the above test operators) returns TRUE. + +Different actions are applied in separate phases or gated, rather than being +applied all at once. This is to ensure that you know what the overall +state of the filesystem is when an action is applied. Or to put it another +way, if you have an action that depends on another action having already been +processed (for the entire filesystem), you'll want to know that is how +they will be applied. + +5.1 Actions applied at source filesystem reading (stage 1) +---------------------------------------------------------- + +5.1.1 exclude() +--------------- + +This action excludes all files and directories where the expression +returns TRUE. + +Obviously this action allows much greater control over which files are +excluded than the current name/pathname matching. + +Examples: + +1. Exclude any files/directories belonging to user phillip + +exclude@user(phillip) + +2. Exclude any regular files larger than 1M + +exclude@filesize(>1M) + +3. Only archive files/directories to a depth of 3 + +exclude@depth(>3) + +4. As above but also exclude directories at the depth of 3 + (which will be empty due to the above exclusion) + +exclude@depth(>3) || (depth(3) && type(d)) + +Which obviously reduces to + +exclude@depth(3) && type(d) + +Note: the following tests do not work in stage 1, and so they can't be +used in the exclude() action (see prune() action for explanation and +alternative). + + dircount() + dircount_range() + exists() + absolute() + readlink() + eval() + +5.2 Actions applied at directory scanning (stage 2) +--------------------------------------------------- + +5.2.1 fragment(name) +-------------------- + +Place all files matching the expression into a specialised fragment +named . This can increase compression and/or improve +I/O by placing similar fragments together. + +Examples: + +1. fragment(cfiles)@name(*.[ch]) + +Place all C files into special fragments reserved for them. + +2. fragment(phillip)@user(phillip) + +Place all files owned by user Phillip into special fragments. + +5.2.2 fragments() +----------------- + +Tell Mksquashfs to use fragment packing for the files matching the +expression. + +For obvious reasons this should be used in conjunction with the global +Mksquashfs option -no-fragments. By default all files are packed into +fragments if they're less than the block size. + +5.2.3 no-fragments() +-------------------- + +Tell Mksquashfs to not pack the files matching the expression into +fragments. + +This can be used where you want to optimise I/O latency by not packing +certain files into fragments. + +5.2.4 tailend() +--------------- + +Tell Mksquashfs to use tail-end packing for the files matching the +expression. Normally Mksquashfs does not pack tail-ends into fragments, +as it may affect I/O performance because it may produce more disk head +seeking. + +But tail-end packing can increase compression. Additionally with modern +solid state media, seeking is not such a major issue anymore. + +5.2.5. no-tailend() +------------------- + +Tell Mksquashfs not to use tail-end packing for the files matching the +exppression. + +For obvious reasons this should be used in conjuction with the global +Mksquashfs option -always-use-fragments. By default tail-ends are not +packed into fragments. + +5.2.6 compressed() +------------------ + +Tell Mksquashfs to compress the fies matching the expression. + +For obvious reasons this should be used in conjunction with the global +Mksquashfs options -noD and -noF. File are by default compressed. + +5.2.7 uncompressed() +-------------------- + +Tell Mksquashfs to not compress the files matching the expression. + +This action obviously can be used to avoid compressing already compressed +files (XZ, GZIP etc.). + +5.2.8 uid(uid or user) +---------------------- + +Set the ownership of the files matching the expression to uid (if arg1 +is a number) or user (if arg1 is a string). + +5.2.9 gid(gid or group) +----------------------- + +Set the group of the files matching the expression to gid (if arg1 +is a number) or group (if arg1 is a string). + +5.2.10 guid(uid/user, gid/group) +-------------------------------- + +Set the uid/user and gid/group of the files matching the expression. + +5.2.11 chmod(mode) +------------------ + +Mode can be octal, or symbolic. + +If Mode is Octal, the permission bits are set to the octal value. + +If Mode is Symbolic, permissions can be Set, Added or Removed. + +The symbolic mode is of the format [ugoa]*[[+-=]PERMS]+ + PERMS = [rwxXst]+ or [ugo] + and the above sequence can be repeated separated with commas. + +A combination of the letters ugoa, specify which permission bits will +be affected, u means user, g means group, o means other, and a +means all or ugo. + +The next letter is +, - or =. The letter + means add to the existing +permission bits, - means remove the bits from the existing permission +bits, and = means set the permission bits. + +The permission bits (PERMS) are a combination of [rwxXst] which +sets/adds/removes those bits for the specified ugoa combination. They +can alternatively be u, g or o, which takes the permission bits from the +user, group or other of the file respectively. + +Examples: + +1. chmod(u+r) + +Adds the read permission to user. + +2. chmod(ug+rw) + +Adds the read and write permissions to both user and group. + +3. chmod(u=rw,go=r) + +Sets the permissions to rw-r--r--, which is eqivalent to + +4. chmod(644) + +5. cgmod(ug=o) + +Sets the user and group permissions to the permissions for other. + +5.3 Actions applied at second directory scan (stage 3) +------------------------------------------------------ + +5.3.1 prune() + +The prune() action deletes the file or directory (and everything +underneath it) that matches the expression. In that respect it is +identical to the exclude() action, except that it takes place in the +third stage, rather than the first stage. There are a number of +reasons to have a prune() action in addition to an exclude() +action. + +1. In the first stage Mksquashfs is building an in-memory representation + of the filesystem to be compressed. At that point some of the tests + don't work because they rely on an in-memory representation having been + built. + + So the following tests don't work in stage 1, and so they can't be + used in the exclude() action. + + dircount() + dircount_range() + exists() + absolute() + readlink() + eval() + + If you want to use these tests, you have to use the prune() action. + +2. Many exclusion/pruning operations may only be easily applied after + transformation actions have been applied in stages 1 & 2. + + For example, you may change the ownership and permissions of + matching files in stage 2, and then want to delete files based on + some criteria which relies on this having taken place. + +5.4. Actions applied at third directory scan (stage 4) +------------------------------------------------------ + +5.4.1 empty(reason) + +The empty() action deletes any directory which matches the expression, +and which is also empty for . is one of "excluded", +"source" and "all". If no argument is given, empty() defaults to "all". + +The reason "excluded" means the directory has become empty due to +the exclude() or prune() actions or by exclusion on the command line. +The reason "source" means the directory was empty in the source filesystem. +The reason "all" means it is empty for either one of the above two reasons. + +This action is often useful when exclusion has produced an empty +directory, or a hierarchy of directories which are empty but for a +sub-directory which is empty but for a sub-directory until an +empty directory is reached. + +Example + +1. Exclude any file which isn't a directory, and then clean-up + any directories which are empty as a result. + + exclude@!type(d) + empty(excluded)@true + +This will produce an empty filesystem, unless there were some +directories that were originally empty. + +Changing the empty action to + + exclude@!type(d) + empty@true + +Will produce an empty filesystem. + +5.5 Actions performed at filesystem creation (stage 6) +------------------------------------------------------ + +5.5.1 xattrs-exclude(regex) + +The xattrs-exclude action excludes any xattr names matching . is +a POSIX regular expression, e.g. xattrs-exclude("^user.") excludes xattrs from +the user namespace. + +5.5.2 xattrs-include(regex) + +The xattrs-include action includes any xattr names matching . is +a POSIX regular expression, e.g. -xattrs-include("^user.") includes xattrs from +the user namespace. + +5.5.3 xattrs-add(name=val) + +The xattrs-add action adds the xattr with contents . If an user +xattr it can be added to regular files and directories (see man 7 xattr). +Otherwise it can be added to all files. + +The extended attribute value by default will be treated as binary (i.e. an +uninterpreted byte sequence), but it can be prefixed with 0s, where it will be +treated as base64 encoded, or prefixed with 0x, where it will be treated as +hexidecimal. + +Obviously using base64 or hexidecimal allows values to be used that cannot be +entered on the command line such as non-printable characters etc. But it +renders the string non-human readable. To keep readability and to allow +non-printable characters to be entered, the 0t prefix is supported. This +encoding is similar to binary encoding, except backslashes are specially +treated, and a backslash followed by three octal digits can be used to encode +any ASCII character, which obviously can be used to encode non-printable values. + +The following four actions are equivalent + +-xattrs-add("user.comment=hello world") +-xattrs-add("user.comment=0saGVsbG8gd29ybGQ=") +-xattrs-add("user.comment=0x68656c6c6f20776f726c64") +-xattrs-add("user.comment=0thello world") + +Obviously in the above example there are no non-printable characters and so +the 0t prefixed string is identical to the first line. The following three +actions are identical, but where the space has been replaced by the +non-printable NUL '\0' (null character). + +-xattrs-add("user.comment=0thello\000world") +-xattrs-add("user.comment=0saGVsbG8Ad29ybGQ=") +-xattrs-add("user.comment=0x68656c6c6f00776f726c64") diff --git a/CHANGES b/CHANGES new file mode 100644 index 0000000..d01415e --- /dev/null +++ b/CHANGES @@ -0,0 +1,914 @@ + SQUASHFS CHANGE LOG + +4.6.1 25 MAR 2023 Bug fix release to fix race condition and XATTRs + code + + 1. Race condition which can cause corruption of the "fragment table" + fixed. This is a regression introduced in August 2022, and it has + been seen when tailend packing is used (-tailends option). + 2. Fix build failure when the tools are being built without extended + attribute (XATTRs) support. + 3. Fix XATTR error message when an unrecognised prefix is found + (Christian Hesse). + 4. Fix incorrect free of pointer when an unrecognised XATTR prefix is + found. + + +4.6 17 MAR 2023 Major improvements in extended attribute handling, + pseudo file handling, and miscellaneous new options and + improvements + + 1. Extended attribute handling improved in Mksquashfs and Sqfstar + + 1.1.New -xattrs-exclude option to exclude extended attributes + from files using a regular expression. + 1.2 New -xattrs-include option to include extended attributes + from files using a regular expression. + 1.3 New -xattrs-add option to add extended attributes to files. + 1.4 New Pseudo file xattr definition to add extended attributes + to files. + 1.5 New xattrs-add Action to add extended attributes to files + (Mksquashfs only). + + 2. Extended attribute handling improved in Unsquashfs + + 2.1 New -xattrs-exclude option to exclude extended attributes + from files using a regular expression. + 2.2 New -xattrs-include option to include extended attributes + from files using a regular expression. + 2.3 Extended attributes are now supported in Pseudo file output. + + 3. Other major improvements + + 3.1 Unsquashfs can now output Pseudo files to standard out. + 3.2 Mksquashfs can now input Pseudo files from standard in. + 3.3 Squashfs filesystems can now be converted (different block + size compression etc) without unpacking to an intermediate + filesystem or mounting, by piping the output of Unsquashfs + to Mksquashfs. + 3.4 Pseudo files are now supported by Sqfstar. + 3.5 "Non-anchored" excludes are now supported by Unsquashfs. + + 4. Mksquashfs minor improvements + + 4.1 A new -max-depth option has been added, which limits + the depth Mksquashfs descends when creating the filesystem. + 4.2 A new -mem-percent option which allows memory for caches to + be specified as a percentage of physical RAM, rather than + requiring an absolute value. + 4.3 A new -percentage option added which rather than generating + the full progress-bar instead outputs a percentage. This + can be used with dialog --gauge etc. + 4.4 -mkfs-time, -all-time and -root-time options now take + a human date string, in addition to the seconds since + the epoch of 1970 00:00 UTC. For example "now", + "last week", "Wed Mar 8 05:55:01 GMT 2023" are supported. + 4.5 -root-uid, -root-gid, -force-uid and -force-gid options now + take a user/group name in addition to the integer uid/gid. + 4.6 A new -mem-default option which displays default memory + usage for caches in Mbytes. + 4.7 A new -no-compression option which produces no compression, + and it is a short-cut for -noI, -noD, -noF and -noX. + 4.8 A new -pseudo-override option which makes pseudo file uids + and gids override -all-root, -force-uid and -force-gid + options. Normally these options take precedence. + + 5. Unsquashfs minor improvements + + 5.1 New -all-time option which sets all file timestamps to +