From 19b7609586aac382f21bdc5c7369c56417775d6d Mon Sep 17 00:00:00 2001 From: David Oberhollenzer <david.oberhollenzer@sigma-star.at> Date: Sun, 6 Oct 2019 12:55:17 +0200 Subject: 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> --- doc/sqfs2tar.1 | 42 ++++++++++++++++++++++-------------------- doc/tar2sqfs.1 | 42 +++++++++++++++++++++++------------------- 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 -- cgit v1.2.3