diff options
Diffstat (limited to 'manpages/unsquashfs.1')
| -rw-r--r-- | manpages/unsquashfs.1 | 279 |
1 files changed, 279 insertions, 0 deletions
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 |