Adding upstream version 1:4.6.1.upstream/1%4.6.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 498 insertions, 0 deletions

diff --git a/USAGE-UNSQUASHFS-4.6 b/USAGE-UNSQUASHFS-4.6
new file mode 100644
index 0000000..0f7dc0e
--- /dev/null
+++ b/USAGE-UNSQUASHFS-4.6
@@ -0,0 +1,498 @@
+	UNSQUASHFS - a tool to extract and list Squashfs filesystems
+
+Unsquashfs allows you to decompress and extract a Squashfs filesystem without
+mounting it.  It can extract the entire filesystem, or a specific
+file or directory.
+
+Unsquashfs can decompress all official Squashfs filesystem versions.
+
+The Unsquashfs usage info is:
+
+SYNTAX: unsquashfs [OPTIONS] FILESYSTEM [files to extract or exclude (with -excludes) or cat (with -cat )]
+
+Filesystem extraction (filtering) options:
+	-d[est] <pathname>	extract to <pathname>, default "squashfs-root".
+				This option also sets the prefix used when
+				listing the filesystem
+	-max[-depth] <levels>	descend at most <levels> of directories when
+				extracting
+	-excludes		treat files on command line as exclude files
+	-ex[clude-list]		list of files to be excluded, terminated
+				with ; e.g. file1 file2 ;
+	-extract-file <file>	list of directories or files to extract.
+				One per line
+	-exclude-file <file>	list of directories or files to exclude.
+				One per line
+	-match			abort if any extract file does not match on
+				anything, and can not be resolved.  Implies
+				-missing-symlinks and -no-wildcards
+	-follow[-symlinks]	follow symlinks in extract files, and add all
+				files/symlinks needed to resolve extract file.
+				Implies -no-wildcards
+	-missing[-symlinks]	Unsquashfs will abort if any symlink can't be
+				resolved in -follow-symlinks
+	-no-wild[cards]		do not use wildcard matching in extract and
+				exclude names
+	-r[egex]		treat extract names as POSIX regular expressions
+				rather than use the default shell wildcard
+				expansion (globbing)
+	-all[-time] <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"
+	-cat			cat the files on the command line to stdout
+	-f[orce]		if file already exists then overwrite
+	-pf <file>		output a pseudo file equivalent of the input
+				Squashfs filesystem, use - for stdout
+
+Filesystem information and listing options:
+	-s[tat]			display filesystem superblock information
+	-max[-depth] <levels>	descend at most <levels> of directories when
+				listing
+	-i[nfo]			print files as they are extracted
+	-li[nfo]		print files as they are extracted with file
+				attributes (like ls -l output)
+	-l[s]			list filesystem, but do not extract files
+	-ll[s]			list filesystem with file attributes (like
+				ls -l output), but do not extract files
+	-lln[umeric]		same as -lls but with numeric uids and gids
+	-lc			list filesystem concisely, displaying only files
+				and empty directories.  Do not extract files
+	-llc			list filesystem concisely with file attributes,
+				displaying only files and empty directories.
+				Do not extract files
+	-full[-precision]	use full precision when displaying times
+				including seconds.  Use with -linfo, -lls, -lln
+				and -llc
+	-UTC			use UTC rather than local time zone when
+				displaying time
+	-mkfs-time		display filesystem superblock time, which is an
+				unsigned 32-bit int representing the time in
+				seconds since the epoch (1970-01-01)
+
+Filesystem extended attribute (xattrs) options:
+	-no[-xattrs]		do not extract xattrs in file system
+	-x[attrs]		extract xattrs in file system (default)
+	-xattrs-exclude <regex>	exclude any xattr names matching <regex>.
+				<regex> is a POSIX regular expression, e.g.
+				-xattrs-exclude '^user.' excludes xattrs from
+				the user namespace
+	-xattrs-include <regex>	include any xattr names matching <regex>.
+				<regex> is a POSIX regular expression, e.g.
+				-xattrs-include '^user.' includes xattrs from
+				the user namespace
+
+Unsquashfs runtime options:
+	-v[ersion]		print version, licence and copyright information
+	-p[rocessors] <number>	use <number> processors.  By default will use
+				the number of processors available
+	-q[uiet]		no verbose output
+	-n[o-progress]		do not display the progress bar
+	-percentage		display a percentage rather than the full
+				progress bar.  Can be used with dialog --gauge
+				etc.
+	-ig[nore-errors]	treat errors writing files to output as
+				non-fatal
+	-st[rict-errors]	treat all errors as fatal
+	-no-exit[-code]		do not set exit code (to nonzero) on non-fatal
+				errors
+	-da[ta-queue] <size>	set data queue to <size> Mbytes.  Default 256
+				Mbytes
+	-fr[ag-queue] <size>	set fragment queue to <size> Mbytes.  Default
+				256 Mbytes
+
+Miscellaneous options:
+	-h[elp]			output this options text to stdout
+	-o[ffset] <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).
+	-fstime			synonym for -mkfs-time
+	-e[f] <extract file>	synonym for -extract-file
+	-exc[f] <exclude file>	synonym for -exclude-file
+	-L			synonym for -follow-symlinks
+	-pseudo-file <file>	alternative name for -pf
+
+
+By default Unsquashfs will extract all the files in the Squashfs filesystem
+into the directory "squashfs-root", placed in the current working directory.
+The location and name of the directory can be changed with the -dest option.
+
+Unsquashfs can also extract only part of the filesystem, with both extract
+filenames and exclude filenames supported.  These can be combined to specify
+a set of directories to be extracted, and then a set of files or directories
+to be excluded within them.
+
+Section 2 describes using extract files with Unsquashfs, and Section 3 describes
+using exclude files with Unsquashfs. 
+
+1. FREQUENTLY USED UNSQUASHFS OPTIONS
+-------------------------------------
+
+The "-dest" option specifies the directory that is used to decompress
+the filesystem data.  If this option is not given then the filesystem is
+decompressed to the directory "squashfs-root" in the current working directory.
+The filename "." can used to specify the current directory.
+
+The "-ls" option can be used to list the contents of a filesystem without
+decompressing the filesystem data itself.  The "-lls" option is similar
+but it also displays file attributes (ls -l style output).  The "-lln"
+option is the same but displays uids and gids numerically.
+
+The "-lc" option is similar to the -ls option except it only displays files
+and empty directories.  The -llc option displays file attributes.
+
+The "-info" option forces Unsquashfs to print each file as it is decompressed.
+The -"linfo" is similar but it also displays file attributes.
+
+The "max-depth" option limits extraction and listing of the filesystem to
+at most <level> directories.
+
+The "-force" option forces Unsquashfs to output to the destination
+directory even if files or directories already exist.  This allows you
+to update an existing directory tree, or to Unsquashfs to a partially
+filled directory.  Without the "-force" option, Unsquashfs will
+refuse to overwrite any existing files, or to create any directories if they
+already exist.  This is done to protect data in case of mistakes, and
+so the "-force" option should be used with caution.
+
+The "-stat" option displays filesystem superblock information.  This is
+useful to discover the filesystem version, byte ordering, whether it has a NFS
+export table, and what options were used to compress the filesystem, etc.
+
+The -mkfs-time option displays the make filesystem time contained
+in the super-block.  This is displayed as the number of seconds since
+the epoch of 1970-01-01 00:00:00 UTC.
+
+The -UTC option makes Unsquashfs display all times in the UTC time zone
+rather than using the default local time zone.
+
+2. USING "EXTRACT" FILES
+------------------------
+
+To extract a subset of the filesystem, the filenames or directory
+trees that are to be extracted can be specified on the command line.  The
+files/directories should be specified using the full path to the
+files/directories as they appear within the Squashfs filesystem.  The
+files/directories will also be extracted to those positions within the
+specified destination directory.
+
+The extract files can also be given in a file using the "-e[f]" option.
+
+Similarly to Mksquashfs, wildcard matching is performed on the extract
+files.  Wildcard matching is enabled by default.
+
+Examples:
+
+  1. unsquashfs image.sqsh 'test/*.gz'
+
+     Extract all files matching "*.gz" in the top level directory "test".
+
+  2. unsquashfs image.sqsh '[Tt]est/example*'
+
+     Extract all files beginning with "example" inside top level directories
+     called "Test" or "test".
+
+  Using extended wildcards, negative matching is also possible.
+
+  3. unsquashfs image.sqsh 'test/!(*data*).gz'
+
+     Extract all files matching "*.gz" in top level directory "test",
+     except those with "data" in the name.
+
+
+3. USING "EXCLUDE" FILES IN ADDITION TO "EXTRACT" FILES
+-------------------------------------------------------
+
+Unsquashfs allows exclude files to be specified, either on their own, or in
+addition to extract files.
+
+An exclude file is, obviously, the opposite of an extract file.  Whereas an
+extract file limits the output of Unsquashfs to the files/directories matched by
+the extract file(s), exclude file(s) output the entire filesystem, with the
+sub-set of files matched by the exclude file(s) excluded.
+
+Often you want to output the filesystem where you're only interested in some
+files, which is where extract files are useful.  But equally, you often want to
+output the entire filesystem, but, with some unwanted files removed.  An example
+of this, perhaps, is where you've inadvertantly, archived binaries (.o files
+etc.) and you're only interested in extracting the source code.
+
+In the above example, trying to remove the binaries (.o etc) when you've only
+got "extract" files capability becomes extremely messy.  It is a lot easier to
+do that with "exclude" files.
+
+Unsquashfs supports two ways of specifying exclude files, and it supports
+"anchored" and "non-anchored" excludes.  The two ways of specifying exclude
+files is described first.
+
+The most straightforward way is to tell Unsquashfs to treat extract files as
+exclude files.  That is extract files are specified on the command line as a
+list of files after the options and filesystem image.  Giving the -excludes
+option tells Unsquashfs to treat them as exclude files.
+
+To make this clearer,
+
+% unsquashfs img file1 file2 file3
+
+Tells Unsquashfs to extract file1, file2 and file3.  But,
+
+% unsquashfs -excludes img file1 file2 file3
+
+Tells Unsquashfs to exclude file1, file2, and file3.
+
+The perhaps obvious problem with this, is it allows you to choose between
+"extract" files or "exclude" files.  But, it doesn't allow you to have both
+"extract" files and "exclude" files on the command line.
+
+To get around this problem Unsquashfs supports another way of specifying exclude
+files.  That is to use the option -exclude-list.  This option allows a list of
+exclude files to specified, terminated by a ";".  The necessity of using ";" to
+terminate the list is because this is a normal option, without it, any further
+entries on the command line would be interpreted as being part of the list.
+
+For example, the following are equivalent:
+
+% unsquashfs -excludes img file1 file2 file3
+
+% unsquashfs -exclude-list file1 file2 file3 \; img
+
+Note the black-slashing of ";" to prevent it from being interpreted by the shell
+as a special character.
+
+Obviously, where the -exclude-list option comes into its own is when it is mixed
+with extract files, for example:
+
+% unsquashfs -exclude-list dir1/file1 dir2/file2 \; img dir1 dir2
+
+This tells Unsquashfs to extract directories "dir1" and "dir2", and then to
+exclude the files "dir1/file1" and "dir2/file2".
+
+From this it should be clear that the precedence is extract files and then
+exclude files, because it doesn't make any sense otherwise.  Extract files
+define the set of directories/files to be extracted, and exclude files remove
+directories/files from that sub-set.
+
+Now the concepts of "anchored" and "non-anchored" exclude files can be
+explained.  An anchored exclude is one which matches from the root of the
+directory and nowhere else, a non-anchored exclude matches anywhere.  For
+example given the directory hierarchy "a/b/c/a/b", the anchored exclude
+"a/b" will match "a/b" at the root of the directory hierarchy, but
+it will not match the "/a/b" sub-directory within directory "c", whereas a
+non-anchored exclude would.
+
+A couple of examples should make this clearer.
+
+Anchored excludes
+
+  1. unsquashfs -excludes image.sqsh 'test/*.gz'
+
+     Exclude all files matching "*.gz" in the top level directory "test".
+
+  2. unsquashfs -excludes image.sqsh '*/[Tt]est/example*'
+
+     Exclude all files beginning with "example" inside directories called
+     "Test" or "test", that occur inside any top level directory.
+
+  Using extended wildcards, negative matching is also possible.
+
+  3. unsquashfs -excludes image.sqsh 'test/!(*data*).gz'
+
+     Exclude all files matching "*.gz" in top level directory "test",
+     except those with "data" in the name.
+
+Non-anchored excludes
+
+  By default excludes match from the top level directory, but it is
+  often useful to exclude a file matching anywhere in the Squashfs filesystem.
+  For this non-anchored excludes can be used, specified by pre-fixing the
+  exclude with "...".
+
+  Examples:
+
+  1. unsquashfs -excludes image.sqsh '... *.gz'
+
+     Exclude files matching "*.gz" anywhere in the Squashfs filesystem.
+     For example this will match "example.gz", "test/example.gz", and
+     "test/test/example.gz".
+
+  2. unsquashfs -excludes image.sqsh '... [Tt]est/*.gz'
+
+     Exclude files matching "*.gz" inside directories called "Test" or
+     "test" that occur anywhere in the Squashfs filesystem.
+
+  Again, using extended wildcards, negative matching is also possible.
+
+  3. unsquashfs -excludes image.sqsh '... !(*data*).gz'
+
+     Exclude all files matching "*.gz" anywhere in the Squashfs filesystem,
+     except those with "data" in the name.
+
+
+4. FOLLOWING SYMBOLIC LINKS IN EXTRACT FILES
+--------------------------------------------
+
+Unsquashfs walks the extract file paths as it recursively descends
+the Squashfs filesystem from top to bottom.  During that recursive
+extraction symbolic links are obviously not followed (see below).
+
+The consequence of this is if an extract file ends in a symbolic link
+(leaf component) it is extracted and left as a dangling symlink,
+unless the real file it links to has also specified as an extract file.
+
+Additionally, if the extract file pathname traverses symbolic links
+while walking the pathname (i.e. the extract file pathname has
+embedded symbolic links), the extraction will stop at that point.
+
+One way of solving this problem is by following (or dereferencing) the
+symbolic link(s), and replacing them with what they actually link to,
+in a similar way to "cp -L".  But this is dangerous, and can cause
+Unsquashfs to produce output which does not match the input Squashfs
+filesystem, which is something Unsquashfs should never do.
+
+The reason for this is whereas "cp -L" is derefencing the *input*,
+Unsquashfs is dereferencing the *output*.  If a filesystem has a real
+filename, say
+
+	a/b/c/hello_world
+
+and two symlinks
+
+	a/symlink1 ---> b/c/hello_world
+	a/symlink2 ---> b/c
+
+There are multiple different ways (or paths) to the *single* hello_world file.
+
+	a/b/c/hello_world
+	a/symlink1
+	a/symlink2/hello_world
+
+If Unsquashfs was given all three paths as extract files, and Unsquashfs
+dereferenced them on output, you will get *three* copies of the hello_world
+file, and two copies of directory "c".
+
+Superficially the output may look the same, but, it may not work the same,
+and obviously edits to the one hello_world file will not get reflected in
+the other copies.  Any option that can be accidently or maliciously used
+to produce such an output is too dangerous to be added.
+
+Unsquashfs solves the problem in an equivalent way, but which does not alter
+the output, and so it is a completely safe option.
+
+If the -follow-symlinks option is specified, Unsquashfs will canonicalise
+the extract files to produce the canonical pathname (that is the
+"real" pathname without any symbolic links).  It will then add all
+the symbolic links necessary to ensure that the extract file can be
+resolved.
+
+The -missing-symlinks option is similar to -follow-symlinks except it
+will cause Unsquashfs to abort if any symbolic link cannot be resolved.
+
+Note: as a side effect of the canonicalisation, with the above options
+enabled extract filenames can also now have ".", ".." elements within
+the pathnames.
+
+5. DEALING WITH ERRORS
+----------------------
+
+Unsquashfs splits errors into two categories: fatal errors and non-fatal
+errors.
+
+Fatal errors are those which cause Unsquashfs to abort instantly.
+These are generally due to failure to read the filesystem (corruption),
+and/or failure to write files to the output filesystem, due to I/O error
+or out of space.  Generally anything which is unexpected is a fatal error.
+
+Non-fatal errors are generally where support is lacking in the
+output filesystem, and it can be considered to be an expected failure.
+This includes the inability to write extended attributes (xattrs) to
+a filesystem that doesn't support them, the inability to create files on
+filesystem that doesn't support them (i.e. symbolic links on VFAT), and the
+inability to execute privileged operations as a user-process.
+
+The user may well know the filesystem cannot support certain operations
+and would prefer Unsquashfs to ignore then without aborting.
+
+In the past Unsquashfs was much more tolerant of errors, now a significant
+number of errors that were non-fatal have been hardened to fatal.
+
+-ignore-errors
+
+This makes Unsquashfs behave like previous versions, and treats more
+errors as non-fatal.
+
+-strict-errors
+
+This makes Unsquashfs treat every error as fatal, and it will abort
+instantly.
+
+
+6. UNSQUASHFS PSEUDO FILE OUTPUT
+--------------------------------
+
+If the Pseudo file (-pf) option is given, Unsquashfs will output a Pseudo file
+representation of the input filesystem.  This pseudo file can be used as input
+to Mksquashfs to reproduce the Squashfs filesystem without having to unpack the
+input filesystem image.
+
+The Pseudo file output is designed to be editable, and the pseudo file entries
+can be altered (name, date, ownership etc.) or added/deleted before any new file
+system is rebuilt.
+
+The format of the pseudo file, is obviously, the same as the pseudo file
+definitions supported by Msquashfs.
+
+Regular files (with data) are supported with the "R" pseudo definition, which is
+
+filename R time mode uid gid length offset sparse
+
+<length> specifies the size of the file, and <offset> is a byte offset into the
+pseudo file where the data is stored.  This offset is taken from the start of
+the data section (see below), rather than from the start of the file (this is to
+allow the pseudo file entries to be edited without altering the data offsets).
+Data is deliberately stored out of line (i.e. unlike tar), to make the file more
+easily editable manually.
+
+<sparse> is a special boolean parameter.  It controls whether the file is
+presented to user-space as a "sparse" file when the filesystem is mounted,
+or is extracted as a "sparse" file by Unsquashfs.  This flag is important
+because Mksquashfs will always convert a file to a "sparse" file in the
+filesystem if it has block size sequences of zeros.  These zeros will not be
+stored and replaced with a hole.  But Mksquashfs is careful to preserve
+the semantics of the files it stores, if is was originally non-sparse it
+will flag that, so it doesn't appear as sparse to user-space or get
+copied as sparse by Unsquashfs.
+
+An example pseudo file output for a filesystem consisting of a directory, two
+regular files, and a symbolic link might be
+
+	/ D 1625536033 1777 0 0
+	test D 1625536969 755 1000 100
+	test/hello_world R 1625535696 644 1000 100 12 0 0
+	test/regfile R 1625536928 644 1000 100 37 12 0
+	test/symlink S 1625535712 777 1000 100 hello_world
+	#
+	# START OF DATA - DO NOT MODIFY
+	#
+	Hello World
+	This is the data contents of regfile
+
+Here you should be able to see the most important aspects of the layout, the
+pseudo file entries appear at the start of the file, and the data is stored at
+the end.  The two sections are separated by 3 special marker lines, containing
+the words "START OF DATA - DO NOT MODIFY".
+
+The following is a small example of how someone might edit and rebuild a
+Squashfs image.
+
+$ unsquashfs -pf pseudo test.sqsh
+$ sed -i "0,/# START OF DATA/s/\([^ ]* . [0-9]* [0-7]* \)[0-9]*/\11234/g" pseudo
+$ sed -i "0,/# START OF DATA/s/hello_world/hello/g" pseudo
+$ mksquashfs - test2.sqsh -pf pseudo
+
+This will change the ownership to uid 1234, and change the name of "hello_word"
+to "hello".