diff options
| author | Christoph Hellwig <hch@lst.de> | 2010-01-17 05:44:25 +0100 |
|---|---|---|
| committer | Michael Kerrisk <mtk.manpages@gmail.com> | 2010-01-17 05:44:25 +0100 |
| commit | db3e674548bbb09e723e07c26105fcfd97699ff3 (patch) | |
| tree | 50692888ed8837e3f0a5f1b75dc7d708ed2d7ab9 | |
| parent | a0c811713df93a9265e53591105d778a632723d7 (diff) | |
| download | man-pages-db3e674548bbb09e723e07c26105fcfd97699ff3.tar.gz | |
sync_file_range.2: Add some big warnings re data integrity
This system call is by design completely unsuitable for any data
integrity operations. Make that very clear in the manpage.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
| -rw-r--r-- | man2/sync_file_range.2 | 23 |
1 files changed, 17 insertions, 6 deletions
diff --git a/man2/sync_file_range.2 b/man2/sync_file_range.2 index 9940a00d40..cb4b8e3121 100644 --- a/man2/sync_file_range.2 +++ b/man2/sync_file_range.2 @@ -26,7 +26,7 @@ .\" 2006-07-05 Initial creation, Michael Kerrisk based on .\" Andrew Morton's comments in fs/sync.c .\" -.TH SYNC_FILE_RANGE 2 2008-05-27 "Linux" "Linux Programmer's Manual" +.TH SYNC_FILE_RANGE 2 2010-01-17 "Linux" "Linux Programmer's Manual" .SH NAME sync_file_range \- sync a file segment with disk .SH SYNOPSIS @@ -80,12 +80,23 @@ after performing any write. Specifying .I flags as 0 is permitted, as a no-op. -.SS Some details -None of these operations write out the file's metadata. +.SS Warning +This system call is extremely dangerous and should not be used in portable +programs. +None of these operations writes out the file's metadata. Therefore, unless the application is strictly performing overwrites of -already-instantiated disk blocks, -there are no guarantees that the data will be available after a crash. - +already-instantiated disk blocks, there are no guarantees that the data will +be available after a crash. +There is no user interface to know if a write is purely an overwrite. +On filesystem using copy-on-write semantics (e.g., +.IR btrfs ) +an overwrite of existing allocated blocks is impossible. +When writing into preallocated space, +many filesystems also require calls into the block +allocator, which this system call does not sync out to disk. +This system call does not flush disk write caches and thus does not provide +any data integrity on systems with volatile disk write caches. +.SS Some details .B SYNC_FILE_RANGE_WAIT_BEFORE and .B SYNC_FILE_RANGE_WAIT_AFTER |