manual/LDP_man-pages/draft/man2/sync_file_range.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright (c) 2006 Andrew Morton <akpm@osdl.org>
   4 .\" and Copyright 2006 Michael Kerrisk <mtk.manpages@gmail.com>
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .\" 2006-07-05 Initial creation, Michael Kerrisk based on
  27 .\"     Andrew Morton's comments in fs/sync.c
  28 .\"
  29 .\" Japanese Version Copyright (c) 2007 Akihiro MOTOKI
  30 .\"         all rights reserved.
  31 .\" Translated 2007-01-09, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.43
  32 .\" Updated 2008-08-06, Akihiro MOTOKI, LDP v3.05
  33 .\" Updated 2010-04-23, Akihiro MOTOKI, LDP v3.24
  34 .\"
  35 .TH SYNC_FILE_RANGE 2 2010-01-17 "Linux" "Linux Programmer's Manual"
  36 .\"O .SH NAME
  37 .SH 名前
  38 .\"O sync_file_range \- sync a file segment with disk
  39 sync_file_range \- ファイルセグメントをディスクと同期する
  40 .\"O .SH SYNOPSIS
  41 .SH 書式
  42 .nf
  43 .\"O .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  44 .BR "#define _GNU_SOURCE" "         /* feature_test_macros(7) 参照 */"
  45 .B #include <fcntl.h>
  46
  47 .BI "int sync_file_range(int " fd ", off64_t " offset ", off64_t " nbytes ,
  48 .BI "                    unsigned int " flags );
  49 .fi
  50 .\"O .SH DESCRIPTION
  51 .SH 説明
  52 .\"O .BR sync_file_range ()
  53 .\"O permits fine control when synchronizing the open file referred to by the
  54 .\"O file descriptor
  55 .\"O .I fd
  56 .\"O with disk.
  57 .BR sync_file_range ()
  58 を使うと、ファイルディスクリプタ
  59 .I fd
  60 で参照されるオープンされたファイルのディスクとの同期に関して、
  61 きめ細かな制御が可能となる。
  62
  63 .\"O .I offset
  64 .\"O is the starting byte of the file range to be synchronized.
  65 .\"O .I nbytes
  66 .\"O specifies the length of the range to be synchronized, in bytes; if
  67 .\"O .I nbytes
  68 .\"O is zero, then all bytes from
  69 .\"O .I offset
  70 .\"O through to the end of file are synchronized.
  71 .\"O Synchronization is in units of the system page size:
  72 .\"O .I offset
  73 .\"O is rounded down to a page boundary;
  74 .\"O .I (offset+nbytes-1)
  75 .\"O is rounded up to a page boundary.
  76 .I offset
  77 は、同期を行うファイルの領域の開始バイトである。
  78 .I nbytes
  79 には同期を行う領域の長さをバイト単位で指定する。
  80 .I nbytes
  81 が 0 の場合は、
  82 .I offset
  83 からファイル末尾までの全バイトを同期する。
  84 同期はシステムのページサイズの単位で行われる。
  85 .I offset
  86 はページ境界にあわせて切り下げられ、
  87 .I (offset+nbytes-1)
  88 はページ境界にあわせて切り上げられる。
  89
  90 .\"O The
  91 .\"O .I flags
  92 .\"O bit-mask argument can include any of the following values:
  93 ビットマスク引き数
  94 .I flags
  95 には以下の値を指定することができる:
  96 .TP
  97 .B SYNC_FILE_RANGE_WAIT_BEFORE
  98 .\"O Wait upon write-out of all pages in the specified range
  99 .\"O that have already been submitted to the device driver for write-out
 100 .\"O before performing any write.
 101 何らかの書き込みを行う前に、指定された領域のページで
 102 書き出しを行うようにデバイスドライバにすでに要求が発行されている
 103 ページの書き出しが全て完了するのを待つ。
 104 .TP
 105 .B SYNC_FILE_RANGE_WRITE
 106 .\"O Initiate write-out of all dirty pages in the specified
 107 .\"O range which are not presently submitted write-out.
 108 .\"O Note that even this may block if you attempt to
 109 .\"O write more than request queue size.
 110 指定された領域のページで、書き出し要求が発行されていない
 111 全ての dirty (キャッシュだけが変更されている) ページの
 112 書き出しを開始する。
 113 リクエストキューの大きさより多く書き込もうとした場合には、
 114 この処理は停止 (block) する可能性がある点に注意すること。
 115 .TP
 116 .B SYNC_FILE_RANGE_WAIT_AFTER
 117 .\"O Wait upon write-out of all pages in the range
 118 .\"O after performing any write.
 119 何らかの書き込み後に、指定された領域の全てのページの
 120 書き出しが行われるのを待つ。
 121 .PP
 122 .\"O Specifying
 123 .\"O .I flags
 124 .\"O as 0 is permitted, as a no-op.
 125 .I flags
 126 に 0 を指定した場合、何もしないことを表す。
 127 .\"O .SS Warning
 128 .SS 警告
 129 .\"O This system call is extremely dangerous and should not be used in portable
 130 .\"O programs.
 131 このシステムコールは非常に危険であり、
 132 移植性が必要なプログラムで使用すべきではない。
 133 .\"O None of these operations writes out the file's metadata.
 134 .\"O Therefore, unless the application is strictly performing overwrites of
 135 .\"O already-instantiated disk blocks, there are no guarantees that the data will
 136 .\"O be available after a crash.
 137 これらの操作ではどれもファイルのメタデータの書き出しを行わない。
 138 したがって、アプリケーションにより作成済みのディスクブロックの
 139 上書きの実行が確実に行われない限り、クラッシュの後でもデータが
 140 利用できる保証はない。
 141 .\"O There is no user interface to know if a write is purely an overwrite.
 142 .\"O On filesystem using copy-on-write semantics (e.g.,
 143 .\"O .IR btrfs )
 144 .\"O an overwrite of existing allocated blocks is impossible.
 145 .\"O When writing into preallocated space,
 146 .\"O many filesystems also require calls into the block
 147 .\"O allocator, which this system call does not sync out to disk.
 148 .\"O This system call does not flush disk write caches and thus does not provide
 149 .\"O any data integrity on systems with volatile disk write caches.
 150 書き込みが上書きだけであるかを知るためのユーザインタフェースは存在しない。
 151 .RI ( btrfs
 152 などの) copy-on-write 動作を使ったファイルシステムでは、
 153 既存の割り当て済みのブロックに対する上書き自体ができない。
 154 前もって割り当てられた領域に書き込みを行う場合、
 155 多くのファイルシステムでは block allocator への書き込みも必要となるが、
 156 このシステムコールは block allocator のディスクへの同期を行わない。
 157 このシステムコールはディスク書き込みキャッシュのフラッシュを
 158 行わないので、揮発性のディスク書き込みキャッシュを使ったシステムでは
 159 このシステムコールではデータの一貫性を確保できないことになる。
 160 .\"O .SS Some details
 161 .SS 詳細
 162 .\"O .B SYNC_FILE_RANGE_WAIT_BEFORE
 163 .\"O and
 164 .\"O .B SYNC_FILE_RANGE_WAIT_AFTER
 165 .\"O will detect any
 166 .\"O I/O errors or
 167 .\"O .B ENOSPC
 168 .\"O conditions and will return these to the caller.
 169 .B SYNC_FILE_RANGE_WAIT_BEFORE
 170 と
 171 .B SYNC_FILE_RANGE_WAIT_AFTER
 172 は I/O エラーや
 173 .B ENOSPC
 174 状態を検出し、呼び出し元にこれらの情報を返す。
 175
 176 .\"O Useful combinations of the
 177 .\"O .I flags
 178 .\"O bits are:
 179 .I flags
 180 の役に立つビットの組み合わせを以下に示す:
 181 .TP
 182 .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
 183 .\"O Ensures that all pages
 184 .\"O in the specified range which were dirty when
 185 .\"O .BR sync_file_range ()
 186 .\"O was called are placed
 187 .\"O under write-out.
 188 .\"O This is a start-write-for-data-integrity operation.
 189 指定された範囲内のページで、
 190 .BR sync_file_range ()
 191 が呼び出された際に dirty であった全てのページが、
 192 確実に書き出し対象となるようにする。
 193 これは、start-write-for-data-integrity 操作
 194 (データ完全性確保のための書き込み開始の操作) である。
 195 .TP
 196 .B SYNC_FILE_RANGE_WRITE
 197 .\"O Start write-out of all dirty pages in the specified range which
 198 .\"O are not presently under write-out.
 199 .\"O This is an asynchronous flush-to-disk
 200 .\"O operation.
 201 .\"O This is not suitable for data integrity operations.
 202 指定された範囲内のページで、現在書き出し中でない全ての dirty ページの
 203 書き出しを開始する。これは非同期のディスクへのフラッシュ (flush-to-disk)
 204 操作である。データ完全性確保が必要な操作としては適切ではない。
 205 .TP
 206 .BR SYNC_FILE_RANGE_WAIT_BEFORE " (or " SYNC_FILE_RANGE_WAIT_AFTER )
 207 .\"O Wait for
 208 .\"O completion of write-out of all pages in the specified range.
 209 .\"O This can be used after an earlier
 210 .\"O .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
 211 .\"O operation to wait for completion of that operation, and obtain its result.
 212 指定された範囲内の全てのページの書き出しの完了を待つ。
 213 このフラグは、前に行われた操作
 214 .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE
 215 の後に使用でき、この操作の完了を待ち、結果を取得することができる。
 216 .TP
 217 .B SYNC_FILE_RANGE_WAIT_BEFORE | SYNC_FILE_RANGE_WRITE | \
 218 SYNC_FILE_RANGE_WAIT_AFTER
 219 .\"O This is a write-for-data-integrity operation
 220 .\"O that will ensure that all pages in the specified range which were dirty when
 221 .\"O .BR sync_file_range ()
 222 .\"O was called are committed to disk.
 223 これは write-for-data-integrity 操作
 224 (データ完全性確保のための書き込み) であり、指定された範囲内の、
 225 .BR sync_file_range ()
 226 が呼ばれた時点で dirty な全てのページが
 227 ディスクに格納されることが保証される。
 228 .\"O .SH RETURN VALUE
 229 .SH 返り値
 230 .\"O On success,
 231 .\"O .BR sync_file_range ()
 232 .\"O returns 0; on failure \-1 is returned and
 233 .\"O .I errno
 234 .\"O is set to indicate the error.
 235 成功の場合、
 236 .BR sync_file_range ()
 237 は 0 を返す。失敗の場合、\-1 を返し、
 238 .I error
 239 にエラーを示す値を設定する。
 240 .\"O .SH ERRORS
 241 .SH エラー
 242 .TP
 243 .B EBADF
 244 .\"O .I fd
 245 .\"O is not a valid file descriptor.
 246 .I fd
 247 が有効なファイルディスクリプタではない。
 248 .TP
 249 .B EINVAL
 250 .\"O .I flags
 251 .\"O specifies an invalid bit; or
 252 .\"O .I offset
 253 .\"O or
 254 .\"O .I nbytes
 255 .\"O is invalid.
 256 .I flags
 257 に不正なビットが指定されている。または
 258 .I offset
 259 か
 260 .I nbytes
 261 が不正である。
 262 .TP
 263 .B EIO
 264 .\"O I/O error.
 265 I/O エラー。
 266 .TP
 267 .B ENOMEM
 268 .\"O Out of memory.
 269 メモリ不足である。
 270 .TP
 271 .B ENOSPC
 272 .\"O Out of disk space.
 273 ディスク領域不足である。
 274 .TP
 275 .B ESPIPE
 276 .\"O .I fd
 277 .\"O refers to something other than a regular file, a block device,
 278 .\"O a directory, or a symbolic link.
 279 .I fd
 280 が、通常のファイル、ブロックデバイス、ディレクトリ、シンボリックリンク
 281 以外のものを指している。
 282 .\" FIXME . (bug?) Actually, how can 'fd' refer to a symbolic link (S_ISLNK)?
 283 .\" (In userspace at least) it isn't possible to obtain a file descriptor
 284 .\" for a symbolic link.
 285 .SH バージョン
 286 .\"O .BR sync_file_range ()
 287 .\"O appeared on Linux in kernel 2.6.17.
 288 .BR sync_file_range ()
 289 はカーネル 2.6.17 で Linux に登場した。
 290 .\"O .SH "CONFORMING TO"
 291 .SH 準拠
 292 .\"O This system call is Linux-specific, and should be avoided
 293 .\"O in portable programs.
 294 このシステムコールは Linux 独自であり、
 295 移植性が必要なプログラムでは使用を避けるべきである。
 296 .\"O .SH VERSIONS
 297 .\"O .SH "SEE ALSO"
 298 .SH 関連項目
 299 .BR fdatasync (2),
 300 .BR fsync (2),
 301 .BR msync (2),
 302 .BR sync (2)