fatfs/doc/ja/expand.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html lang="ja">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <link rel="up" title="FatFs" href="../00index_j.html">
   7 <link rel="alternate" hreflang="ja" title="English" href="../en/expand.html">
   8 <link rel="stylesheet" href="../css_j.css" type="text/css" media="screen" title="ELM Default">
   9 <title>FatFs - f_expand</title>
  10 </head>
  11
  12 <body>
  13
  14 <div class="para func">
  15 <h2>f_expand</h2>
  16 <p>ファイルに連続したデータ領域を割り当てます。</p>
  17
  18 <pre>
  19 FRESULT f_expand (
  20   FIL*    <span class="arg">fp</span>,  <span class="c">/* [IN] ファイル オブジェクト構造体へのポインタ */</span>
  21   FSIZE_t <span class="arg">fsz</span>, <span class="c">/* [IN] 割り当てサイズ */</span>
  22   BYTE    <span class="arg">opt</span>  <span class="c">/* [IN] 動作オプション */</span>
  23 );
  24 </pre>
  25 </div>
  26
  27 <div class="para arg">
  28 <h4>Parameters</h4>
  29 <dl class="par">
  30 <dt>fp</dt>
  31 <dd>対象となるファイル オブジェクト構造体へのポインタを指定します。</dd>
  32 <dt>fsz</dt>
  33 <dd>ファイルに割り当てるバイト単位のサイズ。データ型<tt>FSIZE_t</tt>は、<tt>DWORD</tt>(32-bit)または<tt>QWORD</tt>(64-bit)のエリアスで、exFATサポートの有無により切り替わります。</dd>
  34 <dt>opt</dt>
  35 <dd>実際に割り当てを行うかどうか指定するフラグ。</dd>
  36 </dl>
  37 </div>
  38
  39
  40 <div class="para ret">
  41 <h4>Return Values</h4>
  42 <p>
  43 <a href="rc.html#ok">FR_OK</a>,
  44 <a href="rc.html#de">FR_DISK_ERR</a>,
  45 <a href="rc.html#ie">FR_INT_ERR</a>,
  46 <a href="rc.html#io">FR_INVALID_OBJECT</a>,
  47 <a href="rc.html#dn">FR_DENIED</a>,
  48 <a href="rc.html#tm">FR_TIMEOUT</a>
  49 </p>
  50 </div>
  51
  52
  53 <div class="para desc">
  54 <h4>解説</h4>
  55 <p><tt class="arg">opt</tt>に1を指定すると、ファイルに連続したデータ領域を割り当てます。<tt>f_lseek</tt>によるサイズ拡張とは異なり、対象ファイルのサイズは0(つまりデータ領域未割り当て)でなければなりません。また、リード/ライト ポインタは、ファイル先頭に留まります。この関数により割り当てられたファイルの内容は未定義なので、それに対して何の前提も持つべきではありません。この関数は、次の理由により<tt>FR_DENIED</tt>で失敗することがあります。</p>
  56 <ul>
  57 <li>ボリューム上に連続した空き領域が見つからなかった。</li>
  58 <li>ファイルのサイズが0ではなかった。</li>
  59 <li>ファイルが非書き込みモードで開かれている。</li>
  60 <li>指定されたファイル サイズが無効。(FATボリューム上で &gt;=4GiB)</li>
  61 </ul>
  62 <p><tt class="arg">opt</tt>に0を指定したときは、連続したデータ領域を探すのみで、その時点ではファイルへの割り当てを行わず、代わりにそれを検索開始ポイントとしてファイル システム オブジェクトにセットします。これにより、そのボリューム上で別の操作(FAT変更を伴う)が行われない限り、書き込まれるファイルは少なくともそのサイズまでは連続性が保証され、遅延無く書き込めることになります。</p>
  63 <p>時間的制約のあるファイル読み書き操作において、連続データ領域を割り当てられたファイルは有利となります。これは、分割されたファイルによりもたらされる無用なランダム アクセスが減ることにより、ファイル システムやストレージ デバイスの処理のオーバーヘッドが削減されるからです。特にexFATボリューム上の連続ファイルでは一切のFATアクセスが発生せず、効率的なシーケンシャル アクセスが行えます。</p>
  64 <p>連続ファイルに対して低レベルI/Oを使用したさらに効率的な直接アクセスも容易に行えますが、これは将来の互換性の点で推奨はされません。</p>
  65 </div>
  66
  67 <div class="para comp">
  68 <h4>対応情報</h4>
  69 <p><tt>_USE_EXPAND == 1</tt>で、かつ<tt>_FS_READONLY == 0</tt>のとき使用可能です。</p>
  70 </div>
  71
  72
  73 <div class="para use">
  74 <h4>使用例</h4>
  75 <pre>
  76     <span class="c">/* 連続ファイルの作成 */</span>
  77
  78     <span class="c">/* 新しいファイルの作成 */</span>
  79     res = f_open(fp = malloc(sizeof (FIL)), "file.dat", FA_WRITE|FA_CREATE_ALWAYS);
  80     if (res) { <span class="c">/* ファイルが開かれたかチェック */</span>
  81         free(fp);
  82         ...
  83     }
  84
  85     <span class="c">/* 100 MiB の連続領域を割り当てる */</span>
  86     res = f_expand(fp, 104857600, 1);
  87     if (res) { <span class="c">/* 割り当てられたかチェック */</span>
  88         ...
  89         free(fp);
  90         ...
  91     }
  92     <span class="c">/* 連続ファイル作成成功 fp でアクセス可能 */</span>
  93
  94 </pre>
  95 <pre>
  96     <span class="c">/* ファイル システムを介さず直接アクセスする例 */</span>
  97
  98     <span class="c">/* ファイル データの物理的位置を取得 */</span>
  99     drv = fp-&gt;obj.fs-&gt;drv;
 100     sect = fp-&gt;obj.fs-&gt;database + fp-&gt;obj.fs-&gt;csize * (fp-&gt;obj.sclust - 2);
 101
 102     <span class="c">/* ファイル先頭から2048セクタを書き込み */</span>
 103     res = disk_write(drv, buffer, sect, 2048);
 104
 105 </pre>
 106 </div>
 107
 108
 109 <div class="para ref">
 110 <h4>参照</h4>
 111 <p><tt><a href="open.html">f_open</a>, <a href="lseek.html">f_lseek</a>, <a href="sfile.html">FIL</a></tt></p>
 112 </div>
 113
 114 <p class="foot"><a href="../00index_j.html">戻る</a></p>
 115 </body>
 116 </html>