summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-10-06 12:55:17 +0200
committerDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>2019-10-06 13:26:17 +0200
commit19b7609586aac382f21bdc5c7369c56417775d6d (patch)
treefb466c28735f16b22c8f15662af16551a480df25
parentbe78958a2f132a5907b0f5beafe7c33a67125eb8 (diff)
Update tar2sqfs and sqfs2tar man page
- Add recent changes - Fix spelling and similar mistakes - Remove outdated/contradictory stuff - Consistent spelling of SquashFS - Simplify some formulations Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>
-rw-r--r--doc/sqfs2tar.142
-rw-r--r--doc/tar2sqfs.142
2 files changed, 45 insertions, 39 deletions
diff --git a/doc/sqfs2tar.1 b/doc/sqfs2tar.1
index a71f603..7d91396 100644
--- a/doc/sqfs2tar.1
+++ b/doc/sqfs2tar.1
@@ -1,22 +1,20 @@
.TH SQFS2TAR "1" "June 2019" "sqfs2tar" "User Commands"
.SH NAME
-sqfs2tar \- turn a squashfs image into a tar archive
+sqfs2tar \- turn a SquashFS image into a tar archive
.SH SYNOPSIS
.B sqfs2tar
[\fI\,OPTIONS\/\fR...] \fI\,<sqfsfile>\/\fR
.SH DESCRIPTION
-Read a squashfs archive and turn it into a tar archive, written to stdout.
-
-The idea is to quickly and painlessly turn a squashfs filesystem image into
-a tar archive that can then be examined and processed by any tool that can
-work on tar archives.
+Quickly and painlessly turn a SquashFS filesystem image into a tar archive
+that can then be examined and processed by any tool that can work on tar
+archives. The resulting archive is written to stdout.
.PP
Possible options:
.TP
\fB\-\-subdir\fR, \fB\-d\fR <dir>
Unpack the given sub directory instead of the filesystem root. Can be specified
more than once to select multiple directories. If only one is specified, it
-becomes the new root of node of the archive file system tree.
+becomes the new root of the archive filesystem tree.
.TP
\fB\-\-keep\-as\-dir\fR, \fB\-k\fR
If \fB\-\-subdir\fR is used only once, don't make the subdir the archive root,
@@ -24,11 +22,11 @@ instead keep it as prefix for all unpacked files. Using \fB\-\-subdir\fR more
than once implies \fB\-\-keep\-as\-dir\fR.
.TP
\fB\-\-no\-xattr\fR, \fB\-X\fR
-Discard extended attributes from the squashfs image. The default behavior is
-to copy all xattrs attached to squashfs inodes into the resulting tar archive.
+Discard extended attributes from the SquashFS image. The default behavior is
+to copy all xattrs attached to SquashFS inodes into the resulting tar archive.
.TP
\fB\-\-no\-skip\fR, \fB\-s\fR
-Abort if file cannot be stored in a tar record instead of skipping it.
+Abort if a file cannot be stored in a tar record instead of skipping it.
.TP
\fB\-\-help\fR, \fB\-h\fR
Print help text and exit.
@@ -36,27 +34,31 @@ Print help text and exit.
\fB\-\-version\fR, \fB\-V\fR
Print version information and exit.
.SH COMPATIBILITY
-To be compatible with as many tools as possible, the output format is pre-POSIX
-ustar archive using GNU extensions where necessary. This seems to be more
-widely supported by many tar programs (besides GNU tar), even more than the
-newer POSIX format and PAX extensions.
-
-It is not possible to store socket files in a tar or pax archive. Also, in the
-current implementation, all extended attribuates are lost.
+The output format is pre-POSIX ustar using GNU extensions where necessary.
+Experimentation determined that this is most widely supported by activeley
+used tar implementations (besides GNU tar), even more than the newer POSIX
+format with PAX extensions.
If any file or directory is encountered that cannot be converted, it is
skipped and a warning is written to stderr. Unless the \fB\-\-no\-skip\fR
option is set, which aborts processing if a file cannot be converted.
+
+This is mainly affects socket files which are supported by SquashFS but not by
+POSIX tar, GNU tar or PAX.
+
+Since the tar format contains a sequence of files with absolute names, it has
+no direct concept of a tree or an unnamed root node. Consequently, meta data
+from the SquashFS root inode is lost.
.SH EXAMPLES
-Turn a squashfs image into a tar archive:
+Turn a SquashFS image into a tar archive:
.IP
sqfs2tar rootfs.sqfs > rootfs.tar
.TP
-Turn a squashfs image into a gzip'ed tar archive:
+Turn a SquashFS image into a gzip'ed tar archive:
.IP
sqfs2tar rootfs.sqfs | gzip > rootfs.tar.gz
.TP
-Turn a squashfs image into an LZMA2 compressed tar archive:
+Turn a SquashFS image into an LZMA2 compressed tar archive:
.IP
sqfs2tar rootfs.sqfs | xz > rootfs.tar.xz
.SH SEE ALSO
diff --git a/doc/tar2sqfs.1 b/doc/tar2sqfs.1
index 346d7e7..c2c7f72 100644
--- a/doc/tar2sqfs.1
+++ b/doc/tar2sqfs.1
@@ -1,16 +1,16 @@
.TH TAR2SQFS "1" "June 2019" "tar2sqfs" "User Commands"
.SH NAME
-tar2sqfs \- create a squashfs image from a tar archive
+tar2sqfs \- create a SquashFS image from a tar archive
.SH SYNOPSIS
.B tar2sqfs
[\fI\,OPTIONS\/\fR...] \fI\,<sqfsfile>\/\fR
.SH DESCRIPTION
-Read an uncompressed tar archive from stdin and turn it into a squashfs
+Read an uncompressed tar archive from stdin and turn it into a SquashFS
filesystem image.
-The idea is to quickly and painlessly turn a tar ball into a squashfs
+The idea is to quickly and painlessly turn a tar ball into a SquashFS
filesystem image, so existing tools that work with tar can be used for
-squashfs.
+SquashFS.
.PP
Possible options:
.TP
@@ -34,18 +34,13 @@ starts waiting for the block processors to catch up. Higher values result
in higher memory consumption. Defaults to 10 times the number of workers.
.TP
\fB\-\-block\-size\fR, \fB\-b\fR <size>
-Block size to use for Squashfs image.
+Block size to use for SquashFS image.
Defaults to 131072.
.TP
\fB\-\-dev\-block\-size\fR, \fB\-B\fR <size>
Device block size to padd the image to.
Defaults to 4096.
.TP
-\fB\-\-keep\-time\fR, \fB\-k\fR
-Keep the same time stamps stored in the tar archive for the SquashFS instead of
-setting defaults on all files. The root inode and the modification time on the
-SquashFS image itself will still be set to defaults.
-.TP
\fB\-\-defaults\fR, \fB\-d\fR <options>
A comma seperated list of default values for
implicitly created directories.
@@ -66,6 +61,16 @@ mtime=<value>;\fB$SOURCE\_DATE\_EPOCH\fR if set, 0 otherwise
.TE
.TP
.TP
+\fB\-\-no\-keep\-time\fR, \fB\-k\fR
+Replace the time stamps from the tar archive with default time stamps for all
+entries.
+
+The default behavior if not specified, is to preserve the time stamps from the
+archive to the extent possible (SquashFS has second resolution and 32 bit time
+stamps; tar can use extensions to specify much larger timestamps with arbitrary
+precision). The root inode and the modification time on the SquashFS image
+itself will always still be set to defaults.
+.TP
\fB\-\-no\-xattr\fR, \fB\-x\fR
Do not copy extended attributes from archive. Default behaviour is to copy all
extended attributes and skip the ones that cannot be encoded in SquashFS.
@@ -88,15 +93,14 @@ Print help text and exit.
\fB\-\-version\fR, \fB\-V\fR
Print version information and exit.
.SH COMPATIBILITY
-The tool is designed to support a broad variety of commonly used tar archives.
-Currently the tool can process v7 format, pre-POSIX ustar, POSIX tar and GNU
-tar archives. PAX extension headers are supported.
+Currently the program can process v7 format, pre-POSIX ustar, POSIX tar and GNU
+tar archives. PAX extension headers are also supported.
-The support for GNU tar is limited to commonly used header formats (i.e. some
-older, legacy headers are not supported) and extensions like sparse files.
+The support for GNU tar is limited to commonly used subset (i.e. some legacy
+extensions that GNU tar itself no longer generates are not supported; neither
+are mutli volume archives).
Hard links are currently not supported and silently converted to symlinks.
-Furthermore, none of the various xattr extensions are currently implemented.
Extended attributes are supported through the SCHILY.xattr PAX extension
(favoured by GNU tar and star) or through the LIBARCHIVE.xattr PAX extension.
@@ -118,15 +122,15 @@ are set. Explicit command line switches are always preferred over the
environment variables.
.SH EXAMPLES
.TP
-Turn an uncompressed tar archive into a squashfs image:
+Turn an uncompressed tar archive into a SquashFS image:
.IP
tar2sqfs rootfs.sqfs < rootfs.tar
.TP
-Turn a gzip'ed tar archive into a squashfs image:
+Turn a gzip'ed tar archive into a SquashFS image:
.IP
zcat rootfs.tar.gz | tar2sqfs rootfs.sqfs
.TP
-Turn an LZMA2 compressed tar archive into a squashfs image:
+Turn an LZMA2 compressed tar archive into a SquashFS image:
.IP
xzcat rootfs.tar.xz | tar2sqfs rootfs.sqfs
.SH SEE ALSO