-.TH WIMLIB-IMAGEX "1" "June 2016" "wimlib 1.9.2" "User Commands"
+.TH WIMLIB-IMAGEX "1" "August 2016" "wimlib 1.10.0" "User Commands"
.SH NAME
wimlib-imagex-capture, wimlib-imagex-append \- Create or append a WIM image
.SH SYNOPSIS
Last modification times (mtime) and last access times (atime) with 100
nanosecond granularity
.IP \[bu]
-With \fB--unix-data\fR: UNIX owners, groups, and modes
+With \fB--unix-data\fR: standard UNIX file permissions (owner, group, and mode)
.IP \[bu]
-With \fB--unix-data\fR: device nodes, FIFOs, and UNIX domain sockets
+With \fB--unix-data\fR: device nodes, named pipes, and sockets
+.IP \[bu]
+With \fB--unix-data\fR: extended attributes (Linux only)
.PP
-There is no support for storing extended attributes (e.g. SELinux security
-labels and POSIX ACLs), last status change times (ctimes), or hard link
+There is no support for storing last status change times (ctimes), or hard link
information for symbolic link files (each symbolic link will be stored as an
independent file). In addition, filenames and symbolic link targets on UNIX
filesystems which are not valid UTF-8 with the addition of surrogate codepoints
All data streams of all unencrypted files, including the unnamed data stream as
well as all named data streams.
.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points.
+Reparse points. See \fBREPARSE POINTS AND SYMLINKS\fR for details.
.IP \[bu]
File and directory creation, access, and modification timestamps, using the
native NTFS resolution of 100 nanoseconds.
The sparse attribute on sparse files will be saved, but the data stored will be
the full data of the file rather than the "sparse" data. (The data is, however,
subject to the WIM format's compression.)
+.IP \[bu]
+Some types of reparse points are transparently dereferenced by Windows but not
+by NTFS-3G. See \fBREPARSE POINTS AND SYMLINKS\fR.
.SH DIRECTORY CAPTURE (WINDOWS)
On Windows, \fBwimlib-imagex capture\fR and \fBwimlib-imagex append\fR
natively support Windows-specific and NTFS-specific data. They therefore act
.IP \[bu] 4
All data streams of all files.
.IP \[bu]
-Reparse points, including symbolic links, junction points, and other reparse
-points, if supported by the source filesystem. (Note: see \fB--rpfix\fR and
-\fB--norpfix\fR for documentation on exactly how absolute symbolic links and
-junctions are captured.)
+Reparse points, if supported by the source filesystem. See \fBREPARSE POINTS
+AND SYMLINKS\fR for details.
.IP \[bu]
File and directory creation, access, and modification timestamps. These are
stored with Windows NT's native timestamp resolution of 100 nanoseconds.
Pedantic note: since Windows is not fully compatible with its own filesystem
(NTFS), on Windows wimlib cannot archive certain files that may exist on a valid
NTFS filesystem but are inaccessible to the Windows API, for example two files
-with names differing only in case in the same directory, or a file whose name
-contains certain characters considered invalid by Windows. If you run into
+with names differing only in case in the same directory (unless
+ObCaseInsensitive has been set to 0 in the Windows registry), or a file whose
+name contains certain characters considered invalid by Windows. If you run into
problems archiving such files consider using the \fBNTFS VOLUME CAPTURE
(UNIX)\fR mode from Linux.
+.SH REPARSE POINTS AND SYMLINKS
+A "symbolic link" (or "symlink") is a special file which "points to" some other
+file or directory. On Windows, a "reparse point" is a generalization of a
+symlink which allows access to a file or directory to be redirected in a more
+complex way. Windows uses reparse points to support symlinks, and sometimes
+uses them for various other features as well. Normally, applications can choose
+whether they want to "dereference" reparse points and symlinks or not.
+.PP
+The default behavior of \fBwimcapture\fR is that reparse points and symlinks are
+\fInot\fR dereferenced, meaning that the reparse points or symlinks themselves
+are stored in the archive rather than the files or data they point to. There is
+a \fB--dereference\fR option, but it is currently only supported by the UNIX
+version of \fBwimcapture\fR on UNIX filesystems (it's not yet implemented for
+Windows filesystems).
+.PP
+Windows also treats certain types of reparse points specially. For example,
+Windows applications reading from deduplicated, WIM-backed, or system-compressed
+files always see the dereferenced data, even if they ask not to. Therefore,
+\fBwimcapture\fR on Windows will store these files dereferenced, not as reparse
+points. But \fBwimcapture\fR on UNIX in NTFS-3G mode cannot dereference these
+files and will store them as reparse points instead. This difference can be
+significant in certain situations, e.g. when capturing deduplicated files which,
+to be readable after extraction, require that the chunk store also be present.
.SH OPTIONS
.TP 6
\fB--boot\fR
that may be present on the filesystem.
.TP
\fB--unix-data\fR
-(UNIX-like systems only) Store the UNIX owner, group, mode, and device ID (major
-and minor number) of each captured file. Since wimlib v1.7.0, you can backup
-and restore not only the standard UNIX file permission information, but also
-character device nodes, block device nodes, named pipes (FIFOs), and UNIX domain
-sockets.
+(UNIX-like systems only) Store UNIX-specific metadata and special files. This
+includes: standard UNIX file permissions (owner, group, and mode); device nodes,
+named pipes, and sockets; and extended attributes (Linux only). This
+information can later be restored by \fBwimlib-imagex apply\fR with the
+\fB--unix-data\fR option.
.IP
-wimlib stores UNIX data by adding a special tagged metadata item to each
-directory entry of each file that contains this information. This extra
-information is ignored by the Microsoft implementation. Note: UNIX data stored
-by wimlib before v1.7.0 used a different format that is no longer supported. If
-you have old WIM files with UNIX data, apply them with v1.6.2 and recapture them
-with v1.7.0 or later.
+UNIX-specific information is ignored by Microsoft's WIM software and by the
+Windows version of wimlib.
.TP
\fB--no-acls\fR
Do not capture files' security descriptors.
git://wimlib.net / wimlib / blobdiff