Cleanup: move man pages to the respective program source directories

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

1 files changed, 93 insertions, 0 deletions

diff --git a/bin/sqfs2tar/sqfs2tar.1 b/bin/sqfs2tar/sqfs2tar.1
new file mode 100644
index 0000000..0fc69f6
--- /dev/null
+++ b/bin/sqfs2tar/sqfs2tar.1
@@ -0,0 +1,93 @@
+.TH SQFS2TAR "1" "June 2019" "sqfs2tar" "User Commands"
+.SH NAME
+sqfs2tar \- turn a SquashFS image into a tar archive
+.SH SYNOPSIS
+.B sqfs2tar
+[\fI\,OPTIONS\/\fR...] \fI\,<sqfsfile>\/\fR
+.SH DESCRIPTION
+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\-\-root\-becomes\fR, \fB\-r\fR <dir>
+Prefix all paths in the tarball with the given directory name and add an
+entry for this directory that receives all meta data (permissions, ownership,
+extended attributes, et cetera) of the root inode.
+
+The special value \fB.\fR can be used since many tar archivers themselves pack
+the attributes of the root directory that way and naturally support this.
+
+If this option is not used, all meta data from the root inode IS LOST!
+.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 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,
+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.
+.TP
+\fB\-\-no\-hard\-links\fR, \fB\-L\fR
+Normally, sqfs2tar runs hard link detection and generates hard links for
+entries that refer to the same inode. If this flag is set, hard link
+detection is not performed and duplicate data records are generated
+instead.
+.TP
+\fB\-\-no\-skip\fR, \fB\-s\fR
+Abort if a file cannot be stored in a tar archive. For instance, the tar format
+does not support socket files, but SquashFS does. The default behaviour of
+\fBsqfs2tar\fR is to emit a warning to stderr and skip the entry. If this flag
+is set, processing is aborted and \fBsqfs2tar\fR exits with an error status.
+.TP
+\fB\-\-help\fR, \fB\-h\fR
+Print help text and exit.
+.TP
+\fB\-\-version\fR, \fB\-V\fR
+Print version information and exit.
+.SH COMPATIBILITY
+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 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, unless the \fB\-\-root\-becomes\fR option
+is used.
+.SH EXAMPLES
+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:
+.IP
+sqfs2tar rootfs.sqfs | gzip > rootfs.tar.gz
+.TP
+Turn a SquashFS image into an LZMA2 compressed tar archive:
+.IP
+sqfs2tar rootfs.sqfs | xz > rootfs.tar.xz
+.SH SEE ALSO
+rdsquashfs(1), tar2sqfs(1)
+.SH AUTHOR
+Written by David Oberhollenzer.
+.SH COPYRIGHT
+Copyright \(co 2019 David Oberhollenzer
+License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
+.br
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.