https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;h=78ff40d78ef64313b73834500c3f7775e64e534f
commit 78ff40d78ef64313b73834500c3f7775e64e534f
Author: Christian Franke <christian.fra...@t-online.de>
AuthorDate: Mon Feb 24 14:21:50 2025 +0100
Commit: Corinna Vinschen <cori...@vinschen.de>
CommitDate: Mon Feb 24 18:12:00 2025 +0100
Cygwin: FAQ: Add section about sparse files
Signed-off-by: Christian Franke <christian.fra...@t-online.de>
Diff:
---
winsup/doc/faq-using.xml | 63 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 63 insertions(+)
diff --git a/winsup/doc/faq-using.xml b/winsup/doc/faq-using.xml
index 8a4eee99f017..4dc462a0aacd 100644
--- a/winsup/doc/faq-using.xml
+++ b/winsup/doc/faq-using.xml
@@ -802,6 +802,69 @@ for a detailed description of what's possible with
filenames and what is not.
</para>
</answer></qandaentry>
+<qandaentry id="faq.using.sparse-files">
+<question><para>Does Cygwin support sparse files?</para></question>
+<answer>
+
+<para>Filesystems of Unix-like operating systems traditionally provide
+automatic support for sparse files: no disk blocks are allocated for file
+regions which are not explicitly written. The Windows NTFS filesystem
+supports sparse files, but requires to enable it for individual files via
+<literal>FILE_ATTRIBUTE_SPARSE_FILE</literal>. If the mount option
+<literal>sparse</literal> is used or the mount point is on a solid state
+device, Cygwin heuristically detects skipped file regions and sets this
+attribute then. Independent of mount option or SSD, sparse files may also
+be created if an application uses the related POSIX functionality
+(<literal>FALLOC_FL_PUNCH_HOLE</literal>) as the <literal>cp</literal>
+command does if <literal>--sparse=always</literal> is specified. In some use
+cases requiring only a single sparse file, for example creating disk images
+with <literal>dd</literal> or <literal>ddrescue</literal>, it is also
+possible to preset the sparse attribute with <literal>chattr</literal>.
+</para>
+<para>Example (<literal>sparse</literal> not set, no SSD):
+</para>
+<screen>
+ $ mkdir 0
+ $ > 0/is_sparse
+ $ chattr +S 0/is_sparse
+ $ dd if=/dev/zero bs=1M count=1 of=0/is_sparse conv=sparse,notrunc
+ $ echo EOF >> 0/is_sparse
+ $ dd if=/dev/zero bs=1M count=1 of=0/maybe_sparse conv=sparse
+ $ echo EOF >> 0/maybe_sparse
+ $ dd if=/dev/zero bs=1M count=1 of=0/not_sparse
+ $ echo EOF >> 0/not_sparse
+ $ cp -a 0 1
+ $ cp -a --sparse=always 0 2
+ $ ls -hls ?/*
+ 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 0/is_sparse
+ 1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 0/maybe_sparse
+ 1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 0/not_sparse
+ 1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 1/is_sparse
+ 1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 1/maybe_sparse
+ 1.1M -rw-r--r-- 1 user group 1.1M Feb 22 12:42 1/not_sparse
+ 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 2/is_sparse
+ 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 2/maybe_sparse
+ 64K -rw-r--r-- 1 user group 1.1M Feb 22 12:42 2/not_sparse
+ $ lsattr ?/*
+ ---a-S-------- 0/is_sparse
+ ---a---------- 0/maybe_sparse
+ ---a---------- 0/not_sparse
+ ---a---------- 1/is_sparse
+ ---a---------- 1/maybe_sparse
+ ---a---------- 1/not_sparse
+ ---a-S-------- 2/is_sparse
+ ---a-S-------- 2/maybe_sparse
+ ---a-S-------- 2/not_sparse
+</screen>
+<para>With <literal>sparse</literal> mount option or a SSD, all
+<literal>?/maybe_sparse</literal> files would be sparse.
+</para>
+<para>Note that the detection of solid state devices may be false negative in
+various configurations, for example RAID volumes, USB flash drives, very old
+SATA SSDs, or SSDs behind USB docking stations.
+</para>
+</answer></qandaentry>
+
<qandaentry id="faq.using.hangs">
<question><para>When it hangs, how do I get it back?</para></question>
<answer>
