diff options
Diffstat (limited to 'manpages')
-rw-r--r-- | manpages/.gitattributes | 1 | ||||
-rw-r--r-- | manpages/README | 13 | ||||
-rw-r--r-- | manpages/mksquashfs.1 | 554 | ||||
-rw-r--r-- | manpages/sqfscat.1 | 103 | ||||
-rw-r--r-- | manpages/sqfstar.1 | 400 | ||||
-rw-r--r-- | manpages/unsquashfs.1 | 279 |
6 files changed, 1350 insertions, 0 deletions
diff --git a/manpages/.gitattributes b/manpages/.gitattributes new file mode 100644 index 0000000..9a546c2 --- /dev/null +++ b/manpages/.gitattributes @@ -0,0 +1 @@ +README !export-ignore diff --git a/manpages/README b/manpages/README new file mode 100644 index 0000000..a80b917 --- /dev/null +++ b/manpages/README @@ -0,0 +1,13 @@ +These pre-generated manpages are built using the Squashfs-tools Makefile +defaults with the gzip, lzo, lz4, xz, and zstd compression algorithms +selected. + +The manpages are intended to be used by the installer if help2man isn't +available on the system. + +But, they can obviously also be viewed by anyone who doesn't want to build +or install Squashfs-tools, by running man -l, i.e. + +% man -l mksquashfs.1 + +Will display the manpage for Mksquashfs. diff --git a/manpages/mksquashfs.1 b/manpages/mksquashfs.1 new file mode 100644 index 0000000..47377f4 --- /dev/null +++ b/manpages/mksquashfs.1 @@ -0,0 +1,554 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH MKSQUASHFS "1" "March 2023" "mksquashfs version 4.6.1" "User Commands" +.SH NAME +mksquashfs - tool to create and append to squashfs filesystems +.SH SYNOPSIS +.B mksquashfs +\fI\,source1 source2 \/\fR... \fI\,FILESYSTEM \/\fR[\fI\,OPTIONS\/\fR] [\fI\,-e list of exclude dirs/files\/\fR] +.SH DESCRIPTION +Squashfs is a highly compressed read-only filesystem for Linux. +It uses either gzip/xz/lzo/lz4/zstd compression to compress both files, inodes +and directories. Inodes in the system are very small and all blocks are +packed to minimise data overhead. Block sizes greater than 4K are supported +up to a maximum of 1Mbytes (default block size 128K). + +Squashfs is intended for general read-only filesystem use, for archival +use (i.e. in cases where a .tar.gz file may be used), and in constrained +block device/memory systems (e.g. embedded systems) where low overhead is +needed. +.SH OPTIONS +.SS "Filesystem compression options:" +.TP +\fB\-b\fR BLOCK_SIZE +set data block to BLOCK_SIZE. Default 128 Kbytes. Optionally a suffix of K or M can be given to specify Kbytes or Mbytes respectively. +.TP +\fB\-comp\fR COMP +select COMP compression. Compressors available: gzip (default), lzo, lz4, xz, zstd. +.TP +\fB\-noI\fR +do not compress inode table. +.TP +\fB\-noId\fR +do not compress the uid/gid table (implied by \fB\-noI\fR). +.TP +\fB\-noD\fR +do not compress data blocks. +.TP +\fB\-noF\fR +do not compress fragment blocks. +.TP +\fB\-noX\fR +do not compress extended attributes. +.TP +\fB\-no\-compression\fR +do not compress any of the data or metadata. This is equivalent to specifying \fB\-noI\fR \fB\-noD\fR \fB\-noF\fR and \fB\-noX\fR. +.SS "Filesystem build options:" +.TP +\fB\-tar\fR +read uncompressed tar file from standard in (stdin). +.TP +\fB\-no\-strip\fR +act like tar, and do not strip leading directories from source files. +.TP +\fB\-tarstyle\fR +alternative name for \fB\-no\-strip\fR. +.TP +\fB\-cpiostyle\fR +act like cpio, and read file pathnames from standard in (stdin). +.TP +\fB\-cpiostyle0\fR +like \fB\-cpiostyle\fR, but filenames are null terminated. Can be used with find \fB\-print0\fR action. +.TP +\fB\-reproducible\fR +build filesystems that are reproducible (default). +.TP +\fB\-not\-reproducible\fR +build filesystems that are not reproducible. +.TP +\fB\-mkfs\-time\fR TIME +set filesystem creation timestamp to TIME. TIME can be an unsigned 32\-bit int indicating seconds since the epoch (1970\-01\-01) or a string value which is passed to the "date" command to parse. Any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". +.TP +\fB\-all\-time\fR TIME +set all file timestamps to TIME. TIME can be an unsigned 32\-bit int indicating seconds since the epoch (1970\-01\-01) or a string value which is passed to the "date" command to parse. Any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". +.TP +\fB\-root\-time\fR TIME +set root directory time to TIME. TIME can be an unsigned 32\-bit int indicating seconds since the epoch (1970\-01\-01) or a string value which is passed to the "date" command to parse. Any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". +.TP +\fB\-root\-mode\fR MODE +set root directory permissions to octal MODE. +.TP +\fB\-root\-uid\fR VALUE +set root directory owner to specified VALUE, VALUE can be either an integer uid or user name. +.TP +\fB\-root\-gid\fR VALUE +set root directory group to specified VALUE, VALUE can be either an integer gid or group name. +.TP +\fB\-all\-root\fR +make all files owned by root. +.TP +\fB\-force\-uid\fR VALUE +set all file uids to specified VALUE, VALUE can be either an integer uid or user name. +.TP +\fB\-force\-gid\fR VALUE +set all file gids to specified VALUE, VALUE can be either an integer gid or group name. +.TP +\fB\-pseudo\-override\fR +make pseudo file uids and gids override \fB\-all\-root\fR, \fB\-force\-uid\fR and \fB\-force\-gid\fR options. +.TP +\fB\-no\-exports\fR +do not make filesystem exportable via NFS (\fB\-tar\fR default). +.TP +\fB\-exports\fR +make filesystem exportable via NFS (default). +.TP +\fB\-no\-sparse\fR +do not detect sparse files. +.TP +\fB\-no\-tailends\fR +do not pack tail ends into fragments (default). +.TP +\fB\-tailends\fR +pack tail ends into fragments. +.TP +\fB\-no\-fragments\fR +do not use fragments. +.TP +\fB\-no\-duplicates\fR +do not perform duplicate checking. +.TP +\fB\-no\-hardlinks\fR +do not hardlink files, instead store duplicates. +.TP +\fB\-keep\-as\-directory\fR +if one source directory is specified, create a root directory containing that directory, rather than the contents of the directory. +.SS "Filesystem filter options:" +.TP +\fB\-p\fR PSEUDO\-DEFINITION +add pseudo file definition. The definition should be quoted. +.TP +\fB\-pf\fR PSEUDO\-FILE +add list of pseudo file definitions from PSEUDO\-FILE, use \- for stdin. Pseudo file definitions should not be quoted. +.TP +\fB\-sort\fR SORT_FILE +sort files according to priorities in SORT_FILE. One file or dir with priority per line. Priority \fB\-32768\fR to 32767, default priority 0. +.TP +\fB\-ef\fR EXCLUDE_FILE +list of exclude dirs/files. One per line. +.TP +\fB\-wildcards\fR +allow extended shell wildcards (globbing) to be used in exclude dirs/files. +.TP +\fB\-regex\fR +allow POSIX regular expressions to be used in exclude dirs/files. +.TP +\fB\-max\-depth\fR LEVELS +descend at most LEVELS of directories when scanning filesystem. +.TP +\fB\-one\-file\-system\fR +do not cross filesystem boundaries. If a directory crosses the boundary, create an empty directory for each mount point. If a file crosses the boundary ignore it. +.TP +\fB\-one\-file\-system\-x\fR +do not cross filesystem boundaries. Like \fB\-one\-file\-system\fR option except directories are also ignored if they cross the boundary. +.SS "Filesystem extended attribute (xattrs) options:" +.TP +\fB\-no\-xattrs\fR +do not store extended attributes. +.TP +\fB\-xattrs\fR +store extended attributes (default). +.TP +\fB\-xattrs\-exclude\fR REGEX +exclude any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. \fB\-xattrs\-exclude\fR '^user.' excludes xattrs from the user namespace. +.TP +\fB\-xattrs\-include\fR REGEX +include any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. \fB\-xattrs\-include\fR '^user.' includes xattrs from the user namespace. +.TP +\fB\-xattrs\-add\fR NAME=VAL +add the xattr NAME with VAL to files. If an user xattr it will be added to regular files and directories (see man 7 xattr). Otherwise it will be added to all files. VAL 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 val will be treated as hexidecimal. Additionally it can be prefixed with 0t where this encoding is similar to binary encoding, except backslashes are specially treated, and a backslash followed by 3 octal digits can be used to encode any ASCII character, which obviously can be used to encode control codes. The option can be repeated multiple times to add multiple xattrs. +.SS "Mksquashfs runtime options:" +.TP +\fB\-version\fR +print version, licence and copyright message. +.TP +\fB\-exit\-on\-error\fR +treat normally ignored errors as fatal. +.TP +\fB\-quiet\fR +no verbose output. +.TP +\fB\-info\fR +print files written to filesystem. +.TP +\fB\-no\-progress\fR +do not display the progress bar. +.TP +\fB\-progress\fR +display progress bar when using the \fB\-info\fR option. +.TP +\fB\-percentage\fR +display a percentage rather than the full progress bar. Can be used with dialog \fB\-\-gauge\fR etc. +.TP +\fB\-throttle\fR PERCENTAGE +throttle the I/O input rate by the given percentage. This can be used to reduce the I/O and CPU consumption of Mksquashfs. +.TP +\fB\-limit\fR PERCENTAGE +limit the I/O input rate to the given percentage. This can be used to reduce the I/O and CPU consumption of Mksquashfs (alternative to \fB\-throttle\fR). +.TP +\fB\-processors\fR NUMBER +use NUMBER processors. By default will use number of processors available. +.TP +\fB\-mem\fR SIZE +use SIZE physical memory for caches. Use K, M or G to specify Kbytes, Mbytes or Gbytes respectively. +.TP +\fB\-mem\-percent\fR PERCENT +use PERCENT physical memory for caches. Default 25%. +.TP +\fB\-mem\-default\fR +print default memory usage in Mbytes. +.SS "Filesystem append options:" +.TP +\fB\-noappend\fR +do not append to existing filesystem. +.TP +\fB\-root\-becomes\fR NAME +when appending source files/directories, make the original root become a subdirectory in the new root called NAME, rather than adding the new source items to the original root. +.TP +\fB\-no\-recovery\fR +do not generate a recovery file. +.TP +\fB\-recovery\-path\fR NAME +use NAME as the directory to store the recovery file. +.TP +\fB\-recover\fR NAME +recover filesystem data using recovery file NAME. +.SS "Filesystem actions options:" +.TP +\fB\-action\fR ACTION@EXPRESSION +evaluate EXPRESSION on every file, and execute ACTION if it returns TRUE. +.TP +\fB\-log\-action\fR ACTION@EXPRESSION +as above, but log expression evaluation results and actions performed. +.TP +\fB\-true\-action\fR ACTION@EXPRESSION +as above, but only log expressions which return TRUE. +.TP +\fB\-false\-action\fR ACTION@EXPRESSION +as above, but only log expressions which return FALSE. +.TP +\fB\-action\-file\fR FILE +as action, but read actions from FILE. +.TP +\fB\-log\-action\-file\fR FILE +as \fB\-log\-action\fR, but read actions from FILE. +.TP +\fB\-true\-action\-file\fR FILE +as \fB\-true\-action\fR, but read actions from FILE. +.TP +\fB\-false\-action\-file\fR FILE +as \fB\-false\-action\fR, but read actions from FILE. +.SS "Tar file only options:" +.TP +\fB\-default\-mode\fR MODE +tar files often do not store permissions for intermediate directories. This option sets the default directory permissions to octal MODE, rather than 0755. This also sets the root inode mode. +.TP +\fB\-default\-uid\fR UID +tar files often do not store uids for intermediate directories. This option sets the default directory owner to UID, rather than the user running Mksquashfs. This also sets the root inode uid. +.TP +\fB\-default\-gid\fR GID +tar files often do not store gids for intermediate directories. This option sets the default directory group to GID, rather than the group of the user running Mksquashfs. This also sets the root inode gid. +.TP +\fB\-ignore\-zeros\fR +allow tar files to be concatenated together and fed to Mksquashfs. Normally a tarfile has two consecutive 512 byte blocks filled with zeros which means EOF and Mksquashfs will stop reading after the first tar file on encountering them. This option makes Mksquashfs ignore the zero filled blocks. +.SS "Expert options (these may make the filesystem unmountable):" +.TP +\fB\-nopad\fR +do not pad filesystem to a multiple of 4K. +.TP +\fB\-offset\fR OFFSET +skip OFFSET bytes at the beginning of FILESYSTEM. Optionally a suffix of K, M or G can be given to specify Kbytes, Mbytes or Gbytes respectively. Default 0 bytes. +.TP +\fB\-o\fR OFFSET +synonym for \fB\-offset\fR. +.SS "Miscellaneous options:" +.TP +\fB\-fstime\fR TIME +alternative name for \fB\-mkfs\-time\fR. +.TP +\fB\-always\-use\-fragments\fR +alternative name for \fB\-tailends\fR. +.TP +\fB\-root\-owned\fR +alternative name for \fB\-all\-root\fR. +.TP +\fB\-noInodeCompression\fR +alternative name for \fB\-noI\fR. +.TP +\fB\-noIdTableCompression\fR +alternative name for \fB\-noId\fR. +.TP +\fB\-noDataCompression\fR +alternative name for \fB\-noD\fR. +.TP +\fB\-noFragmentCompression\fR +alternative name for \fB\-noF\fR. +.TP +\fB\-noXattrCompression\fR +alternative name for \fB\-noX\fR. +.TP +\fB\-help\fR +output this options text to stdout. +.TP +\fB\-h\fR +output this options text to stdout. +.TP +\fB\-Xhelp\fR +print compressor options for selected compressor. +.SH "PSEUDO FILE DEFINITION FORMAT" +.TP +\fB\-p\fR "filename d mode uid gid" +create a directory. +.TP +\fB\-p\fR "filename m mode uid gid" +modify filename. +.TP +\fB\-p\fR "filename b mode uid gid major minor" +create a block device. +.TP +\fB\-p\fR "filename c mode uid gid major minor" +create a character device. +.TP +\fB\-p\fR "filename f mode uid gid command" +create file from stdout of command. +.TP +\fB\-p\fR "filename s mode uid gid symlink" +create a symbolic link. +.TP +\fB\-p\fR "filename i mode uid gid [s|f]" +create a socket (s) or FIFO (f). +.TP +\fB\-p\fR "filename x name=val" +create an extended attribute. +.TP +\fB\-p\fR "filename l linkname" +create a hard\-link to linkname. +.TP +\fB\-p\fR "filename L pseudo_filename" +same, but link to pseudo file. +.TP +\fB\-p\fR "filename D time mode uid gid" +create a directory with timestamp time. +.TP +\fB\-p\fR "filename M time mode uid gid" +modify a file with timestamp time. +.TP +\fB\-p\fR "filename B time mode uid gid major minor" +create block device with timestamp time. +.TP +\fB\-p\fR "filename C time mode uid gid major minor" +create char device with timestamp time. +.TP +\fB\-p\fR "filename F time mode uid gid command" +create file with timestamp time. +.TP +\fB\-p\fR "filename S time mode uid gid symlink" +create symlink with timestamp time. +.TP +\fB\-p\fR "filename I time mode uid gid [s|f]" +create socket/fifo with timestamp time. +.SH "COMPRESSORS AVAILABLE AND COMPRESSOR SPECIFIC OPTIONS" +.SS "gzip (default):" +.TP +\fB\-Xcompression\-level\fR COMPRESSION\-LEVEL +COMPRESSION\-LEVEL should be 1 .. 9 (default 9). +.TP +\fB\-Xwindow\-size\fR WINDOW\-SIZE +WINDOW\-SIZE should be 8 .. 15 (default 15). +.TP +\fB\-Xstrategy\fR strategy1,strategy2,...,strategyN +Compress using strategy1,strategy2,...,strategyN in turn and choose the best compression. Available strategies: default, filtered, huffman_only, run_length_encoded and fixed. +.SS "lzo:" +.TP +\fB\-Xalgorithm\fR ALGORITHM +Where ALGORITHM is one of: lzo1x_1, lzo1x_1_11, lzo1x_1_12, lzo1x_1_15, lzo1x_999 (default). +.TP +\fB\-Xcompression\-level\fR COMPRESSION\-LEVEL +COMPRESSION\-LEVEL should be 1 .. 9 (default 8) Only applies to lzo1x_999 algorithm. +.SS "lz4:" +.TP +\fB\-Xhc\fR +Compress using LZ4 High Compression. +.SS "xz:" +.TP +\fB\-Xbcj\fR filter1,filter2,...,filterN +Compress using filter1,filter2,...,filterN in turn (in addition to no filter), and choose the best compression. Available filters: x86, arm, armthumb, powerpc, sparc, ia64. +.TP +\fB\-Xdict\-size\fR DICT\-SIZE +Use DICT\-SIZE as the XZ dictionary size. The dictionary size can be specified as a percentage of the block size, or as an absolute value. The dictionary size must be less than or equal to the block size and 8192 bytes or larger. It must also be storable in the xz header as either 2^n or as 2^n+2^(n+1). Example dict\-sizes are 75%, 50%, 37.5%, 25%, or 32K, 16K, 8K etc. +.SS "zstd:" +.TP +\fB\-Xcompression\-level\fR COMPRESSION\-LEVEL +COMPRESSION\-LEVEL should be 1 .. 22 (default 15). +.SH ENVIRONMENT +.TP +SOURCE_DATE_EPOCH +If set, this is used as the filesystem creation timestamp. Also any file timestamps which are after SOURCE_DATE_EPOCH will be clamped to SOURCE_DATE_EPOCH. See https://reproducible\-builds.org/docs/source\-date\-epoch/ for more information. +.SH EXAMPLES +.TP +mksquashfs DIRECTORY IMAGE.SQFS +Create a Squashfs filesystem from the contents of DIRECTORY, writing the output +to IMAGE.SQSH. Mksquashfs will use the default compressor (normally gzip), and +block size of 128 Kbytes. +.TP +mksquashfs DIRECTORY FILE1 FILE2 IMAGE.SQFS +Create a Squashfs filesystem containing DIRECTORY and FILE1 and FILE2. If +multiple sources are specified on the command line they will be combined into +a single directory. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -b 1M -comp zstd +Use a block size of 1 Mbyte and Zstandard compression to create the filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -e file1 file2 +Exclude file1 and file2 from DIRECTORY when creating filesystem. No wildcard +matching of files. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "*.gz" +Exclude anything in DIRECTORY which matches the wildcard pattern "*.gz". +.TP +mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "... *.gz" +Exclude files which match the wildcard pattern "*.gz" anywhere within DIRECTORY +and its sub-directories. The initial "..." indicates the wildcard pattern is +"non-anchored" and will match anywhere. +.PP +Note: when passing wildcarded names to Mksquashfs, they should be quoted (as in +the above examples), to ensure that they are not processed by the shell. + +.SS Using pseudo file definitions +.TP +mksquashfs DIRECTORY IMAGE.SQFS -p "build_dir d 0644 0 0" +Create a directory called "build_dir" in the output filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -p "version.txt l /tmp/build/version" +Create a reference called "version.txt" to a file outside DIRECTORY, which acts +as if the file "/tmp/build/version" was copied or hard-linked into DIRECTORY +before calling Mksquashfs. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -p "date.txt f 0644 0 0 date" +Create a file called "date.txt" which holds the output (stdout) from running +the "date" command. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -p "\\"hello world\\" f 0644 0 0 date" +As above, but, showing that filenames can have spaces, if they are quoted. +The quotes need to be blackslashed to protect them from the shell. +.TP +mksquashfs - IMAGE.SQFS -p "input f 0644 root root dd if=/dev/sda1 bs=1024" -p "/ d 0644 0 0" +Create a file containing the contents of partition /dev/sda1". Ordinarily +Mksquashfs given a device, fifo, or named socket will place that special file +within the Squashfs filesystem, the above allows input from these special files +to be captured and placed in the Squashfs filesystem. Note there are no other +sources than the pseudo file, and so the command line source is "-". If there +are no other sources than pseudo files, the root (/) directory must be defined +too, as seen in this example. +.TP +unsquashfs -pf - IMAGE.SQFS | mksquashfs - NEW.SQFS -pf - +Transcode IMAGE.SQFS to NEW.SQFS by piping the pseudo file output from +Unsquashfs to Mksquashfs using stdout and stdin. This can convert from +earlier Squashfs filesystems or change compression algorithm, block size etc. +without needing to unpack into an intermediate directory or file. +.PP +Note: pseudo file definitions should be quoted (as in the above examples), to +ensure that they are passed to Mksquashfs as a single argument, and to ensure +that they are not processed by the shell. + +.SS Using extended attribute options +.TP +mksquashfs DIRECTORY IMAGE.SQFS -no-xattrs +Do not store any extended attributes in the Squashfs filesystem. Any extended +attributes in the source files will be ignored. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -xattrs-include "^user." +Filter the extended attributes in the source files, and only store extended +attributes in the user namespace in the Squashfs filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -xattrs-exclude "^user." +Filter the extended attributes in the source files, and don't store any +extended attributes in the user namespace in the Squashfs filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.comment=hello world" +Add the extended attribute called "user.comment" with the content "hello world" +to all files and directories in the Squashfs filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.comment=0thello world\\012" +Add the extended attribute called "user.comment" to all files and directories, +but in this case the contents of the extended attribute will be "hello world" +with a trailing newline character (012 octal). +.TP +mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.comment=0saGVsbG8gd29ybGQ=" +Add the extended attribute called "user.comment" to all files and directories, +where the value is given in base64 encoding, representing "hello world". +.TP +mksquashfs DIRECTORY IMAGE.SQFS -action "-xattrs-include(^user.) @ type(f)" +Filter the extended attributes but only in regular files (type f), and only +store extended attributes in the user namespace. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -p "hello_world x user.comment=0tsalve mundi\\012" +Add the extended attribute called "user.comment" to the file called +"hello_world", with the contents of the extended attribute being "salve mundi" +with a trailing newline character (012 octal). + +.SS Using Actions to not compress, change attributes etc. +.TP +mksquashfs DIRECTORY IMAGE.SQSH -action "uncompressed @ (name(*.jpg) || name(*.mpg) ) || (name(*.img) && filesize(+1G))" +Specify that any files matching the wildcards "*.jpg" and "*.mpg" should not be +compressed. Additionally, it also specifies any files matching the wildcard +"*.img" and are larger than 1 Gigabyte should be uncompressed too. This shows +test operators can be combined with logical expressions. +.TP +mksquashfs DIRECTORY IMAGE.SQSH -action "chmod(o+r)@! perm(o+r)" +If any files within DIRECTORY are not readable by "others", then make them +readable by others in the Squashfs filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQSH -action "uid(phillip)@! perm(o+r)" +As previous, match on any files which are not readable by "others", but, in +this case change the owner of the file to "phillip" in the Squashfs filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQSH -action "prune @ type(l) && ! exists" +Delete any symbolic link within DIRECTORY which points outside of DIRECTORY, +i.e. will be unresolvable in the Squashfs filesystem. +.TP +mksquashfs DIRECTORY IMAGE.SQSH -action "exclude @ depth(3)" +Create a Squashfs filesystem containing the two top most levels (contents of +DIRECTORY and immediate sub-directories), and exclude anything at level 3 or +below. +.TP +mksquashfs DIRECTORY IMAGE.SQFS -action "-xattrs-include(^user.) @ type(f)" +Filter the extended attributes but only in regular files (type f), and only +store extended attributes in the user namespace. +.PP +Note: actions should be quoted (as in the above examples), to ensure that they +are passed to Mksquashfs as a single argument, and to ensure that they are not +processed by the shell. +.SH AUTHOR +Written by Phillip Lougher <phillip@squashfs.org.uk> +.SH COPYRIGHT +Copyright \(co 2023 Phillip Lougher <phillip@squashfs.org.uk> +.PP +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, +or (at your option) any later version. +.PP +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. +.SH "SEE ALSO" +unsquashfs(1), sqfstar(1), sqfscat(1) +.PP +The README for the Squashfs\-tools 4.6.1 release, describing the new features can be +read here https://github.com/plougher/squashfs\-tools/blob/master/README\-4.6.1 +.PP +The Squashfs\-tools USAGE guide can be read here +https://github.com/plougher/squashfs\-tools/blob/master/USAGE\-4.6 +.PP +The ACTIONS\-README file describing how to use the new actions feature can be +read here https://github.com/plougher/squashfs\-tools/blob/master/ACTIONS\-README diff --git a/manpages/sqfscat.1 b/manpages/sqfscat.1 new file mode 100644 index 0000000..9770739 --- /dev/null +++ b/manpages/sqfscat.1 @@ -0,0 +1,103 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH SQFSCAT "1" "March 2023" "sqfscat version 4.6.1" "User Commands" +.SH NAME +sqfscat - tool to cat files from a squashfs filesystem to stdout +.SH SYNOPSIS +.B sqfscat +[\fI\,OPTIONS\/\fR] \fI\,FILESYSTEM \/\fR[\fI\,list of files to cat to stdout\/\fR] +.SH DESCRIPTION +Squashfs is a highly compressed read-only filesystem for Linux. +It uses either gzip/xz/lzo/lz4/zstd compression to compress both files, inodes +and directories. Inodes in the system are very small and all blocks are +packed to minimise data overhead. Block sizes greater than 4K are supported +up to a maximum of 1Mbytes (default block size 128K). + +Squashfs is intended for general read-only filesystem use, for archival +use (i.e. in cases where a .tar.gz file may be used), and in constrained +block device/memory systems (e.g. embedded systems) where low overhead is +needed. +.SH OPTIONS +.TP +\fB\-v\fR, \fB\-version\fR +print version, licence and copyright information. +.TP +\fB\-p\fR NUMBER, \fB\-processors\fR NUMBER +use NUMBER processors. By default will use the number of processors available. +.TP +\fB\-o\fR BYTES, \fB\-offset\fR BYTES +skip BYTES at start of FILESYSTEM. Optionally a suffix of K, M or G can be given to specify Kbytes, Mbytes or Gbytes respectively (default 0 bytes). +.TP +\fB\-ig\fR, \fB\-ignore\-errors\fR +treat errors writing files to stdout as non\-fatal. +.TP +\fB\-st\fR, \fB\-strict\-errors\fR +treat all errors as fatal. +.TP +\fB\-no\-exit\fR, \fB\-no\-exit\-code\fR +don't set exit code (to nonzero) on non\-fatal errors. +.TP +\fB\-da\fR SIZE, \fB\-data\-queue\fR SIZE +set data queue to SIZE Mbytes. Default 256 Mbytes. +.TP +\fB\-fr\fR SIZE, \fB\-frag\-queue\fR SIZE +set fragment queue to SIZE Mbytes. Default 256 Mbytes. +.TP +\fB\-no\-wild\fR, \fB\-no\-wildcards\fR +do not use wildcard matching in filenames. +.TP +\fB\-r\fR, \fB\-regex\fR +treat filenames as POSIX regular expressions rather than use the default shell wildcard expansion (globbing). +.TP +\fB\-h\fR, \fB\-help\fR +output options text to stdout. +.SH "DECOMPRESSORS AVAILABLE" +gzip, lzo, lz4, xz, zstd +.SH "EXIT STATUS" +.TP +0 +The file or files were output to stdout OK. +.TP +1 +FATAL errors occurred, e.g. filesystem corruption, I/O errors. Sqfscat did not continue and aborted. +.TP +2 +Non\-fatal errors occurred, e.g. not a regular file, or failed to resolve pathname. Sqfscat continued and did not abort. +.PP +See \fB\-ignore\-errors\fR, \fB\-strict\-errors\fR and \fB\-no\-exit\-code\fR options for how they affect +the exit status. +.SH EXAMPLES +.TP +sqfscat IMAGE.SQFS hello +Output the contents of "hello" to stdout. +.TP +sqfscat IMAGE.SQFS hello world +Output the contents of "hello" and then "world" to stdout. +.TP +sqfscat IMAGE.SQFS "*.[ch]" +Output the contents of all the files in the root directory that match the +wildcard *.[ch], to stdout, e.g. hello.c, hello.h, world.c, world.h. +.PP +Note: when passing wildcarded names to Sqfscat, they should be quoted (as in +the above examples), to ensure that they are not processed by the shell. +.SH AUTHOR +Written by Phillip Lougher <phillip@squashfs.org.uk> +.SH COPYRIGHT +Copyright \(co 2023 Phillip Lougher <phillip@squashfs.org.uk> +.PP +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, +or (at your option) any later version. +.PP +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. +.SH "SEE ALSO" +mksquashfs(1), unsquashfs(1), sqfstar(1) +.PP +The README for the Squashfs\-tools 4.6.1 release, describing the new features can be +read here https://github.com/plougher/squashfs\-tools/blob/master/README\-4.6.1 +.PP +The Squashfs\-tools USAGE guide can be read here +https://github.com/plougher/squashfs\-tools/blob/master/USAGE\-4.6 diff --git a/manpages/sqfstar.1 b/manpages/sqfstar.1 new file mode 100644 index 0000000..7e32732 --- /dev/null +++ b/manpages/sqfstar.1 @@ -0,0 +1,400 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH SQFSTAR "1" "March 2023" "sqfstar version 4.6.1" "User Commands" +.SH NAME +sqfstar - tool to create a squashfs filesystem from a tar archive +.SH SYNOPSIS + cat xxx.tar | sqfstar [OPTIONS] FILESYSTEM [exclude files] + zcat xxx.tgz | sqfstar [OPTIONS] FILESYSTEM [exclude files] + xzcat xxx.tar.xz | sqfstar [OPTIONS] FILESYSTEM [exclude files] + zstdcat xxx.tar.zst | sqfstar [OPTIONS] FILESYSTEM [exclude files] +.SH DESCRIPTION +Squashfs is a highly compressed read-only filesystem for Linux. +It uses either gzip/xz/lzo/lz4/zstd compression to compress both files, inodes +and directories. Inodes in the system are very small and all blocks are +packed to minimise data overhead. Block sizes greater than 4K are supported +up to a maximum of 1Mbytes (default block size 128K). + +Squashfs is intended for general read-only filesystem use, for archival +use (i.e. in cases where a .tar.gz file may be used), and in constrained +block device/memory systems (e.g. embedded systems) where low overhead is +needed. +.SH OPTIONS +.SS "Filesystem compression options:" +.TP +\fB\-b\fR BLOCK_SIZE +set data block to BLOCK_SIZE. Default 128 Kbytes. Optionally a suffix of K or M can be given to specify Kbytes or Mbytes respectively. +.TP +\fB\-comp\fR COMP +select COMP compression. Compressors available: gzip (default), lzo, lz4, xz, zstd. +.TP +\fB\-noI\fR +do not compress inode table. +.TP +\fB\-noId\fR +do not compress the uid/gid table (implied by \fB\-noI\fR). +.TP +\fB\-noD\fR +do not compress data blocks. +.TP +\fB\-noF\fR +do not compress fragment blocks. +.TP +\fB\-noX\fR +do not compress extended attributes. +.TP +\fB\-no\-compression\fR +do not compress any of the data or metadata. This is equivalent to specifying \fB\-noI\fR \fB\-noD\fR \fB\-noF\fR and \fB\-noX\fR. +.SS "Filesystem build options:" +.TP +\fB\-reproducible\fR +build filesystems that are reproducible (default). +.TP +\fB\-not\-reproducible\fR +build filesystems that are not reproducible. +.TP +\fB\-mkfs\-time\fR TIME +set filesystem creation timestamp to TIME. TIME can be an unsigned 32\-bit int indicating seconds since the epoch (1970\-01\-01) or a string value which is passed to the "date" command to parse. Any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". +.TP +\fB\-all\-time\fR TIME +set all file timestamps to TIME. TIME can be an unsigned 32\-bit int indicating seconds since the epoch (1970\-01\-01) or a string value which is passed to the "date" command to parse. Any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". +.TP +\fB\-root\-time\fR TIME +set root directory time to TIME. TIME can be an unsigned 32\-bit int indicating seconds since the epoch (1970\-01\-01) or a string value which is passed to the "date" command to parse. Any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". +.TP +\fB\-root\-mode\fR MODE +set root directory permissions to octal MODE. +.TP +\fB\-root\-uid\fR VALUE +set root directory owner to specified VALUE, VALUE can be either an integer uid or user name. +.TP +\fB\-root\-gid\fR VALUE +set root directory group to specified VALUE, VALUE can be either an integer gid or group name. +.TP +\fB\-all\-root\fR +make all files owned by root. +.TP +\fB\-force\-uid\fR VALUE +set all file uids to specified VALUE, VALUE can be either an integer uid or user name. +.TP +\fB\-force\-gid\fR VALUE +set all file gids to specified VALUE, VALUE can be either an integer gid or group name. +.TP +\fB\-default\-mode\fR MODE +tar files often do not store permissions for intermediate directories. This option sets the default directory permissions to octal MODE, rather than 0755. This also sets the root inode mode. +.TP +\fB\-default\-uid\fR UID +tar files often do not store uids for intermediate directories. This option sets the default directory owner to UID, rather than the user running Sqfstar. This also sets the root inode uid. +.TP +\fB\-default\-gid\fR GID +tar files often do not store gids for intermediate directories. This option sets the default directory group to GID, rather than the group of the user running Sqfstar. This also sets the root inode gid. +.TP +\fB\-pseudo\-override\fR +make pseudo file uids and gids override \fB\-all\-root\fR, \fB\-force\-uid\fR and \fB\-force\-gid\fR options. +.TP +\fB\-exports\fR +make the filesystem exportable via NFS. +.TP +\fB\-no\-sparse\fR +do not detect sparse files. +.TP +\fB\-no\-fragments\fR +do not use fragments. +.TP +\fB\-no\-tailends\fR +do not pack tail ends into fragments. +.TP +\fB\-no\-duplicates\fR +do not perform duplicate checking. +.TP +\fB\-no\-hardlinks\fR +do not hardlink files, instead store duplicates. +.SS "Filesystem filter options:" +.TP +\fB\-p\fR PSEUDO\-DEFINITION +add pseudo file definition. The definition should be quoted. +.TP +\fB\-pf\fR PSEUDO\-FILE +add list of pseudo file definitions. Pseudo file definitions in pseudo\-files should not be quoted. +.TP +\fB\-ef\fR EXCLUDE_FILE +list of exclude dirs/files. One per line. +.TP +\fB\-regex\fR +allow POSIX regular expressions to be used in exclude dirs/files. +.TP +\fB\-ignore\-zeros\fR +allow tar files to be concatenated together and fed to Sqfstar. Normally a tarfile has two consecutive 512 byte blocks filled with zeros which means EOF and Sqfstar will stop reading after the first tar file on encountering them. This option makes Sqfstar ignore the zero filled blocks. +.SS "Filesystem extended attribute (xattrs) options:" +.TP +\fB\-no\-xattrs\fR +do not store extended attributes. +.TP +\fB\-xattrs\fR +store extended attributes (default). +.TP +\fB\-xattrs\-exclude\fR REGEX +exclude any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. \fB\-xattrs\-exclude\fR '^user.' excludes xattrs from the user namespace. +.TP +\fB\-xattrs\-include\fR REGEX +include any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. \fB\-xattrs\-include\fR '^user.' includes xattrs from the user namespace. +.TP +\fB\-xattrs\-add\fR NAME=VAL +add the xattr NAME with VAL to files. If an user xattr it will be added to regular files and directories (see man 7 xattr). Otherwise it will be added to all files. VAL 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 val will be treated as hexidecimal. Additionally it can be prefixed with 0t where this encoding is similar to binary encoding, except backslashes are specially treated, and a backslash followed by 3 octal digits can be used to encode any ASCII character, which obviously can be used to encode control codes. The option can be repeated multiple times to add multiple xattrs. +.SS "Sqfstar runtime options:" +.TP +\fB\-version\fR +print version, licence and copyright message. +.TP +\fB\-force\fR +force Sqfstar to write to block device or file. +.TP +\fB\-exit\-on\-error\fR +treat normally ignored errors as fatal. +.TP +\fB\-quiet\fR +no verbose output. +.TP +\fB\-info\fR +print files written to filesystem. +.TP +\fB\-no\-progress\fR +do not display the progress bar. +.TP +\fB\-progress\fR +display progress bar when using the \fB\-info\fR option. +.TP +\fB\-percentage\fR +display a percentage rather than the full progress bar. Can be used with dialog \fB\-\-gauge\fR etc. +.TP +\fB\-throttle\fR PERCENTAGE +throttle the I/O input rate by the given percentage. This can be used to reduce the I/O and CPU consumption of Sqfstar. +.TP +\fB\-limit\fR PERCENTAGE +limit the I/O input rate to the given percentage. This can be used to reduce the I/O and CPU consumption of Sqfstar (alternative to \fB\-throttle\fR). +.TP +\fB\-processors\fR NUMBER +use NUMBER processors. By default will use number of processors available. +.TP +\fB\-mem\fR SIZE +use SIZE physical memory for caches. Use K, M or G to specify Kbytes, Mbytes or Gbytes respectively. +.TP +\fB\-mem\-percent\fR PERCENT +use PERCENT physical memory for caches. Default 25%. +.TP +\fB\-mem\-default\fR +print default memory usage in Mbytes. +.SS "Expert options (these may make the filesystem unmountable):" +.TP +\fB\-nopad\fR +do not pad filesystem to a multiple of 4K. +.TP +\fB\-offset\fR OFFSET +skip OFFSET bytes at the beginning of FILESYSTEM. Optionally a suffix of K, M or G can be given to specify Kbytes, Mbytes or Gbytes respectively. Default 0 bytes. +.TP +\fB\-o\fR OFFSET +synonym for \fB\-offset\fR. +.SS "Miscellaneous options:" +.TP +\fB\-fstime\fR TIME +alternative name for mkfs\-time. +.TP +\fB\-root\-owned\fR +alternative name for \fB\-all\-root\fR. +.TP +\fB\-noInodeCompression\fR +alternative name for \fB\-noI\fR. +.TP +\fB\-noIdTableCompression\fR +alternative name for \fB\-noId\fR. +.TP +\fB\-noDataCompression\fR +alternative name for \fB\-noD\fR. +.TP +\fB\-noFragmentCompression\fR +alternative name for \fB\-noF\fR. +.TP +\fB\-noXattrCompression\fR +alternative name for \fB\-noX\fR. +.TP +\fB\-help\fR +output this options text to stdout. +.TP +\fB\-h\fR +output this options text to stdout. +.TP +\fB\-Xhelp\fR +print compressor options for selected compressor. +.SH "PSEUDO FILE DEFINITION FORMAT" +.TP +\fB\-p\fR "filename d mode uid gid" +create a directory. +.TP +\fB\-p\fR "filename m mode uid gid" +modify filename. +.TP +\fB\-p\fR "filename b mode uid gid major minor" +create a block device. +.TP +\fB\-p\fR "filename c mode uid gid major minor" +create a character device. +.TP +\fB\-p\fR "filename f mode uid gid command" +create file from stdout of command. +.TP +\fB\-p\fR "filename s mode uid gid symlink" +create a symbolic link. +.TP +\fB\-p\fR "filename i mode uid gid [s|f]" +create a socket (s) or FIFO (f). +.TP +\fB\-p\fR "filename x name=val" +create an extended attribute. +.TP +\fB\-p\fR "filename l linkname" +create a hard\-link to linkname. +.TP +\fB\-p\fR "filename L pseudo_filename" +same, but link to pseudo file. +.TP +\fB\-p\fR "filename D time mode uid gid" +create a directory with timestamp time. +.TP +\fB\-p\fR "filename M time mode uid gid" +modify a file with timestamp time. +.TP +\fB\-p\fR "filename B time mode uid gid major minor" +create block device with timestamp time. +.TP +\fB\-p\fR "filename C time mode uid gid major minor" +create char device with timestamp time. +.TP +\fB\-p\fR "filename F time mode uid gid command" +create file with timestamp time. +.TP +\fB\-p\fR "filename S time mode uid gid symlink" +create symlink with timestamp time. +.TP +\fB\-p\fR "filename I time mode uid gid [s|f]" +create socket/fifo with timestamp time. +.SH "COMPRESSORS AVAILABLE AND COMPRESSOR SPECIFIC OPTIONS" +.SS "gzip (default):" +.TP +\fB\-Xcompression\-level\fR COMPRESSION\-LEVEL +COMPRESSION\-LEVEL should be 1 .. 9 (default 9). +.TP +\fB\-Xwindow\-size\fR WINDOW\-SIZE +WINDOW\-SIZE should be 8 .. 15 (default 15). +.TP +\fB\-Xstrategy\fR strategy1,strategy2,...,strategyN +Compress using strategy1,strategy2,...,strategyN in turn and choose the best compression. Available strategies: default, filtered, huffman_only, run_length_encoded and fixed. +.SS "lzo:" +.TP +\fB\-Xalgorithm\fR ALGORITHM +Where ALGORITHM is one of: lzo1x_1, lzo1x_1_11, lzo1x_1_12, lzo1x_1_15, lzo1x_999 (default). +.TP +\fB\-Xcompression\-level\fR COMPRESSION\-LEVEL +COMPRESSION\-LEVEL should be 1 .. 9 (default 8) Only applies to lzo1x_999 algorithm. +.SS "lz4:" +.TP +\fB\-Xhc\fR +Compress using LZ4 High Compression. +.SS "xz:" +.TP +\fB\-Xbcj\fR filter1,filter2,...,filterN +Compress using filter1,filter2,...,filterN in turn (in addition to no filter), and choose the best compression. Available filters: x86, arm, armthumb, powerpc, sparc, ia64. +.TP +\fB\-Xdict\-size\fR DICT\-SIZE +Use DICT\-SIZE as the XZ dictionary size. The dictionary size can be specified as a percentage of the block size, or as an absolute value. The dictionary size must be less than or equal to the block size and 8192 bytes or larger. It must also be storable in the xz header as either 2^n or as 2^n+2^(n+1). Example dict\-sizes are 75%, 50%, 37.5%, 25%, or 32K, 16K, 8K etc. +.SS "zstd:" +.TP +\fB\-Xcompression\-level\fR COMPRESSION\-LEVEL +COMPRESSION\-LEVEL should be 1 .. 22 (default 15). +.SH ENVIRONMENT +.TP +SOURCE_DATE_EPOCH +If set, this is used as the filesystem creation timestamp. Also any file timestamps which are after SOURCE_DATE_EPOCH will be clamped to SOURCE_DATE_EPOCH. See https://reproducible\-builds.org/docs/source\-date\-epoch/ for more information. +.SH EXAMPLES +.TP +sqfstar IMAGE.SQFS < archive.tar +Create a Squashfs filesystem from the uncompressed tar file "archive.tar". +Sqfstar will use the default compressor (normally gzip), and block size of 128 +Kbytes. +.TP +zcat archive.tgz | sqfstar IMAGE.SQFS +Create a Squashfs filesystem from the compressed tar file "archive.tgz". Sqfstar +will use the default compressor (normally gzip), and block size of 128 Kbytes. +.TP +sqfstar -b 1M -comp zstd IMAGE.SQFS < archive.tar +Use a block size of 1 Mbyte and Zstandard compression to create the filesystem. +.TP +sqfstar -root-uid 0 -root-gid 0 IMAGE.SQFS < archive.tar +Tar files do not supply a definition for the root directory, and the default is +to make the directory owned/group owned by the user running Sqfstar. The above +command sets the ownership/group ownership to root. +.TP +sqfstar -root-mode 0755 IMAGE.SQFS < archive.tar +The default permissions for the root directory is 0777 (rwxrwxrwx). The above +command sets the permissions to 0755 (rwxr-xr-x). +.TP +sqfstar IMAGE.SQFS file1 file2 < archive.tar +Exclude file1 and file2 from the tar file when creating filesystem. +.TP +sqfstar IMAGE.SQFS "*.gz" < archive.tar +Exclude any files in the top level directory which matches the wildcard pattern +"*.gz". +.TP +sqfstar IMAGE.SQFS "... *.gz" < archive.tar +Exclude any file which matches the wildcard pattern "*.gz" anywhere within the +tar file. The initial "..." indicates the wildcard pattern is "non-anchored" +and will match anywhere. +.PP +Note: when passing wildcarded names to Sqfstar, they should be quoted (as in +the above examples), to ensure that they are not processed by the shell. + +.SS Using pseudo file definitions +.TP +sqfstar -p "build_dir d 0644 0 0" IMAGE.SQFS < archive.tar +Create a directory called "build_dir" in the output filesystem. +.TP +sqfstar -p "version.txt l /tmp/build/version" IMAGE.SQFS < archive.tar +Create a reference called "version.txt" to a file not in the tar archive, +which acts as if that file was in the tar archive. +.TP +sqfstar -p "date.txt f 0644 0 0 date" IMAGE.SQFS < archive.tar +Create a file called "date.txt" which holds the output (stdout) from running +the "date" command. +.TP +sqfstar -p "\\"hello world\\" f 0644 0 0 date" IMAGE.SQFS < archive.tar +As above, but, showing that filenames can have spaces, if they are quoted. +The quotes need to be blackslashed to protect them from the shell. +.TP +sqfstar -p "input f 0644 root root dd if=/dev/sda1 bs=1024" IMAGE.SQFS < archive.tar +Create a file containing the contents of partition /dev/sda1". The above allows +input from these special files to be captured and placed in the Squashfs +filesystem. +.PP +Note: pseudo file definitions should be quoted (as in the above examples), to +ensure that they are passed to Mksquashfs as a single argument, and to ensure +that they are not processed by the shell. +.SH AUTHOR +Written by Phillip Lougher <phillip@squashfs.org.uk> +.SH COPYRIGHT +Copyright \(co 2023 Phillip Lougher <phillip@squashfs.org.uk> +.PP +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, +or (at your option) any later version. +.PP +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. +.SH "SEE ALSO" +mksquashfs(1), unsquashfs(1), sqfscat(1) +.PP +The README for the Squashfs\-tools 4.6.1 release, describing the new features can be +read here https://github.com/plougher/squashfs\-tools/blob/master/README\-4.6.1 +.PP +The Squashfs\-tools USAGE guide can be read here +https://github.com/plougher/squashfs\-tools/blob/master/USAGE\-4.6 diff --git a/manpages/unsquashfs.1 b/manpages/unsquashfs.1 new file mode 100644 index 0000000..2d45f87 --- /dev/null +++ b/manpages/unsquashfs.1 @@ -0,0 +1,279 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.48.5. +.TH UNSQUASHFS "1" "March 2023" "unsquashfs version 4.6.1" "User Commands" +.SH NAME +unsquashfs - tool to uncompress, extract and list squashfs filesystems +.SH SYNOPSIS +.B unsquashfs +[\fI\,OPTIONS\/\fR] \fI\,FILESYSTEM \/\fR[\fI\,files to extract or exclude (with -excludes) or cat (with -cat )\/\fR] +.SH DESCRIPTION +Squashfs is a highly compressed read-only filesystem for Linux. +It uses either gzip/xz/lzo/lz4/zstd compression to compress both files, inodes +and directories. Inodes in the system are very small and all blocks are +packed to minimise data overhead. Block sizes greater than 4K are supported +up to a maximum of 1Mbytes (default block size 128K). + +Squashfs is intended for general read-only filesystem use, for archival +use (i.e. in cases where a .tar.gz file may be used), and in constrained +block device/memory systems (e.g. embedded systems) where low overhead is +needed. +.SH OPTIONS +.SS "Filesystem extraction (filtering) options:" +.TP +\fB\-d\fR PATHNAME, \fB\-dest\fR PATHNAME +extract to PATHNAME, default "squashfs\-root". This option also sets the prefix used when listing the filesystem. +.TP +\fB\-max\fR LEVELS, \fB\-max\-depth\fR LEVELS +descend at most LEVELS of directories when extracting. +.TP +\fB\-excludes\fR +treat files on command line as exclude files. +.TP +\fB\-ex\fR, \fB\-exclude\-list\fR +list of files to be excluded, terminated with ; e.g. file1 file2 ;. +.TP +\fB\-extract\-file\fR FILE +list of directories or files to extract. One per line. +.TP +\fB\-exclude\-file\fR FILE +list of directories or files to exclude. One per line. +.TP +\fB\-match\fR +abort if any extract file does not match on anything, and can not be resolved. Implies \fB\-missing\-symlinks\fR and \fB\-no\-wildcards\fR. +.TP +\fB\-follow\fR, \fB\-follow\-symlinks\fR +follow symlinks in extract files, and add all files/symlinks needed to resolve extract file. Implies \fB\-no\-wildcards\fR. +.TP +\fB\-missing\fR, \fB\-missing\-symlinks\fR +Unsquashfs will abort if any symlink can't be resolved in \fB\-follow\-symlinks\fR. +.TP +\fB\-no\-wild\fR, \fB\-no\-wildcards\fR +do not use wildcard matching in extract and exclude names. +.TP +\fB\-r\fR, \fB\-regex\fR +treat extract names as POSIX regular expressions rather than use the default shell wildcard expansion (globbing). +.TP +\fB\-all\fR TIME, \fB\-all\-time\fR TIME +set all file timestamps to TIME, rather than the time stored in the filesystem inode. TIME can be an unsigned 32\-bit int indicating seconds since the epoch (1970\-01\-01) or a string value which is passed to the "date" command to parse. Any string value which the date command recognises can be used such as "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023". +.TP +\fB\-cat\fR +cat the files on the command line to stdout. +.TP +\fB\-f\fR, \fB\-force\fR +if file already exists then overwrite. +.TP +\fB\-pf\fR FILE +output a pseudo file equivalent of the input Squashfs filesystem, use \- for stdout. +.SS "Filesystem information and listing options:" +.TP +\fB\-s\fR, \fB\-stat\fR +display filesystem superblock information. +.TP +\fB\-max\fR LEVELS, \fB\-max\-depth\fR LEVELS +descend at most LEVELS of directories when listing. +.TP +\fB\-i\fR, \fB\-info\fR +print files as they are extracted. +.TP +\fB\-li\fR, \fB\-linfo\fR +print files as they are extracted with file attributes (like ls \fB\-l\fR output). +.TP +\fB\-l\fR, \fB\-ls\fR +list filesystem, but do not extract files. +.TP +\fB\-ll\fR, \fB\-lls\fR +list filesystem with file attributes (like ls \fB\-l\fR output), but do not extract files. +.TP +\fB\-lln\fR, \fB\-llnumeric\fR +same as \fB\-lls\fR but with numeric uids and gids. +.TP +\fB\-lc\fR +list filesystem concisely, displaying only files and empty directories. Do not extract files. +.TP +\fB\-llc\fR +list filesystem concisely with file attributes, displaying only files and empty directories. Do not extract files. +.TP +\fB\-full\fR, \fB\-full\-precision\fR +use full precision when displaying times including seconds. Use with \fB\-linfo\fR, \fB\-lls\fR, \fB\-lln\fR and \fB\-llc\fR. +.TP +\fB\-UTC\fR +use UTC rather than local time zone when displaying time. +.TP +\fB\-mkfs\-time\fR +display filesystem superblock time, which is an unsigned 32\-bit int representing the time in seconds since the epoch (1970\-01\-01). +.SS "Filesystem extended attribute (xattrs) options:" +.TP +\fB\-no\fR, \fB\-no\-xattrs\fR +do not extract xattrs in file system. +.TP +\fB\-x\fR, \fB\-xattrs\fR +extract xattrs in file system (default). +.TP +\fB\-xattrs\-exclude\fR REGEX +exclude any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. \fB\-xattrs\-exclude\fR '^user.' excludes xattrs from the user namespace. +.TP +\fB\-xattrs\-include\fR REGEX +include any xattr names matching REGEX. REGEX is a POSIX regular expression, e.g. \fB\-xattrs\-include\fR '^user.' includes xattrs from the user namespace. +.SS "Unsquashfs runtime options:" +.TP +\fB\-v\fR, \fB\-version\fR +print version, licence and copyright information. +.TP +\fB\-p\fR NUMBER, \fB\-processors\fR NUMBER +use NUMBER processors. By default will use the number of processors available. +.TP +\fB\-q\fR, \fB\-quiet\fR +no verbose output. +.TP +\fB\-n\fR, \fB\-no\-progress\fR +do not display the progress bar. +.TP +\fB\-percentage\fR +display a percentage rather than the full progress bar. Can be used with dialog \fB\-\-gauge\fR etc. +.TP +\fB\-ig\fR, \fB\-ignore\-errors\fR +treat errors writing files to output as non\-fatal. +.TP +\fB\-st\fR, \fB\-strict\-errors\fR +treat all errors as fatal. +.TP +\fB\-no\-exit\fR, \fB\-no\-exit\-code\fR +do not set exit code (to nonzero) on non\-fatal errors. +.TP +\fB\-da\fR SIZE, \fB\-data\-queue\fR SIZE +set data queue to SIZE Mbytes. Default 256 Mbytes. +.TP +\fB\-fr\fR SIZE, \fB\-frag\-queue\fR SIZE +set fragment queue to SIZE Mbytes. Default 256 Mbytes. +.SS "Miscellaneous options:" +.TP +\fB\-h\fR, \fB\-help\fR +output this options text to stdout. +.TP +\fB\-o\fR BYTES, \fB\-offset\fR BYTES +skip BYTES at start of FILESYSTEM. Optionally a suffix of K, M or G can be given to specify Kbytes, Mbytes or Gbytes respectively (default 0 bytes). +.TP +\fB\-fstime\fR +synonym for \fB\-mkfs\-time\fR. +.TP +\fB\-e\fR, \fB\-ef\fR EXTRACT FILE +synonym for \fB\-extract\-file\fR. +.TP +\fB\-exc\fR, \fB\-excf\fR EXCLUDE FILE +synonym for \fB\-exclude\-file\fR. +.TP +\fB\-L\fR +synonym for \fB\-follow\-symlinks\fR. +.TP +\fB\-pseudo\-file\fR FILE +alternative name for \fB\-pf\fR. +.SH "DECOMPRESSORS AVAILABLE" +gzip, lzo, lz4, xz, zstd +.SH "EXIT STATUS" +.TP +0 +The filesystem listed or extracted OK. +.TP +1 +FATAL errors occurred, e.g. filesystem corruption, I/O errors. Unsquashfs did not continue and aborted. +.TP +2 +Non\-fatal errors occurred, e.g. no support for XATTRs, Symbolic links in output filesystem or couldn't write permissions to output filesystem. Unsquashfs continued and did not abort. +.PP +See \fB\-ignore\-errors\fR, \fB\-strict\-errors\fR and \fB\-no\-exit\-code\fR options for how they affect +the exit status. +.SH EXAMPLES +.TP +unsquashfs IMAGE.SQFS +Extract IMAGE.SQFS to "squashfs-root" in the current working directory. +.TP +unsquashfs -d output IMAGE.SQFS +Extract IMAGE.SQFS to "output" in the current working directory. +.TP +unsquashfs -d . IMAGE.SQFS +Extract IMAGE.SQFS to current working directory. +.TP +unsquashfs -linfo IMAGE.SQFS +Output a listing of IMAGE.SQFS with file attributes to stdout, while extracting +the filesystem to "squashfs-root". +.TP +unsquashfs -lls IMAGE.SQFS +Output a listing of IMAGE.SQFS with file attributes to stdout, but do not +extract the filesystem. The listing will be prefixed with "squashfs-root". +.TP +unsquashfs -d "" -lls IMAGE.SQFS +Output a listing of IMAGE.SQFS with file attributes to stdout, but do not +extract the filesystem. The listing will not be prefixed with "squashfs-root". +.TP +unsquashfs IMAGE.SQFS fs/squashfs +Extract only the "fs/squashfs" directory. +.TP +unsquashfs IMAGE.SQFS "[Tt]est/example*" +Extract all files beginning with "example" inside top level directories +called "Test" or "test". +.TP +unsquashfs -excludes IMAGE.SQFS "test/*data*.gz" +This will extract everything except for files that match *data*.gz in the +test directory. The -excludes option tells Unsquashfs to exclude the files +on the command line rather than extract them. +.TP +unsquashfs -excludes IMAGE.SQFS "... *.gz" +This will extract everything except for files that match *.gz anywhere +in the image. The "..." means this is a non-anchored exclude which +matches anywhere. +.TP +unsquashfs -ex "test/*data*.gz" \; IMAGE.SQFS test +This uses both extract and exclude options, to tell Unsquashfs to only +extract the "test" directory, and to exclude any files within it that +match *data*.gz. +.TP +unsquashfs -ex "... *.gz" IMAGE.SQFS test +This uses both extract and exclude options, to tell Unsquashfs to only +extract the "test" directory, and to exclude files which match "*.gz" +anywhere within "test" directory or sub-directories. +.TP +unsquashfs -dest output -max-depth 2 IMAGE.SQFS +Extract only the top two levels of IMAGE.SQFS to "output" directory. +.TP +unsquashfs -max-depth 2 IMAGE.SQFS "test/*.gz" +Only extract the gzipped files in the test directory. +.TP +unsquashfs -llc -max-depth 2 IMAGE.SQFS "test/*.gz" +Output a listing of the gzipped files in the test directory to stdout, +but do not extract them. +.TP +unsquashfs -no-xattrs IMAGE.SQFS +Do not extract any extended attributes. Any extended attributes in the +filesystem will be ignored. +.TP +unsquashfs -xattrs-include "^user." IMAGE.SQFS +Filter the extended attributes and only extract extended attributes in the +user namespace from the Squashfs filesystem. +.TP +unsquashfs -xattrs-exclude "^user." IMAGE.SQFS +Filter the extended attributes and do not extract any extended attributes in +the user namespace from the Squashfs filesystem. +.PP +Note: when passing wildcarded names to Unsquashfs, they should be quoted (as in +the above examples), to ensure that they are not processed by the shell. +.SH AUTHOR +Written by Phillip Lougher <phillip@squashfs.org.uk> +.SH COPYRIGHT +Copyright \(co 2023 Phillip Lougher <phillip@squashfs.org.uk> +.PP +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, +or (at your option) any later version. +.PP +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. +.SH "SEE ALSO" +mksquashfs(1), sqfstar(1), sqfscat(1) +.PP +The README for the Squashfs\-tools 4.6.1 release, describing the new features can be +read here https://github.com/plougher/squashfs\-tools/blob/master/README\-4.6.1 +.PP +The Squashfs\-tools USAGE guide can be read here +https://github.com/plougher/squashfs\-tools/blob/master/USAGE\-4.6 |