現在の位置: ホーム> 最新記事一覧> diskfreespace（）関数の戻り値は正確に何を表していますか？意味と単位の完全な分析

diskfreespace（）関数の戻り値は正確に何を表していますか？意味と単位の完全な分析

gitbox 2025-09-19

： diskfreespace（） （エイリアスdisk_free_space（） ）は、指定されたファイルシステム/パーティションで現在のPHPプロセスで利用可能なバイト数を返します。戻り値の単位はバイトです。通常、ディスク上の絶対的な総自由バイトではなく、「実行プロセスが利用可能」のスペースを表すことに注意してください（UNIXでは、予約ブロックと許可の影響を受けます。また、32ビットPHPで整数オーバーフローの問題に遭遇する可能性があります）。

重要な詳細を以下に説明し、一般的な用途を示します。

1.基本的な使用法と返品値のタイプ

<span><span><span class="hljs-variable">$free</span></span><span> = </span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-string">'/'</span></span><span>); </span><span><span class="hljs-comment">// または disk_free_space('/path/to/dir');</span></span><span>
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$free</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"取得に失敗しました"</span></span><span>;
} </span><span><span class="hljs-keyword">else</span></span><span> {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"利用可能なバイトの数： <span class="hljs-subst">$free</span></span></span><span>\n";
}
</span></span>

  • 戻り値ユニット：バイト。

  • 可能なリターンタイプ：通常、最新のPHP（64ビット）の整数（INT、64ビット）は、一部の環境または古いPHP/32ビット環境で浮動小数点数またはオーバーフローである場合があります。関数は障害時にfalseを返し、警告を発します。

  • パラメーター：ファイルパスまたはマウントポイント（たとえば、 C：\ 、 /var 、 /mnt /share ）に渡され、HTTP /ftpおよびその他のURL（ローカルまたはマウントされたパスが必要）で直接通過できません。

2。「利用可能な」は常に「絶対にアイドル状態」に等しいとは限りません。

DiskFreespace（）の結果は、通常、UNIXのSTATVFSまたはWindows同等のシステムコールの「利用可能な」フィールドに相当します。これは、現在のユーザー（または実行中のプロセス）が利用できるバイト数を表します。したがって：

  • Unix/Linuxでは、ファイルシステムは通常、rootのブロックの一部（5％など）を留保します。非ルートユーザーはこの部分を見ることができず、返品値には予約済みのスペースが含まれません。

  • PHPが非主要なユーザーとして実行されている場合、返品値は、スーパーユーザーが使用できるすべての自由スペースではなく、ユーザーが書き込むことができるスペースを反映します。

  • ネットワークマウント（NFS、SMB）またはコンテナ/仮想マシン環境の場合、リターン値は、マウントオプションとコンテナ制限（クォータ、CGROUPなど）の影響も受けます。

したがって、ディスクが「本当に」無料であるかどうかを判断するには、ルートであるかどうか、およびファイルシステムの予約/クォータ設定であろうと、許可と組み合わせて値を理解する必要があります。

3。disk_total_space （）との関係

disk_total_space（）パーティションのバイト（総容量）の総数を返し、 diskfreespace（）は利用可能なバイトの数を返します。使用率は、2つを組み合わせることで計算できます。

 <span><span><span class="hljs-variable">$path</span></span><span> = </span><span><span class="hljs-string">'/'</span></span><span>;
</span><span><span class="hljs-variable">$total</span></span><span> = </span><span><span class="hljs-title function_ invoke__">disk_total_space</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);
</span><span><span class="hljs-variable">$free</span></span><span>  = </span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$total</span></span><span> &amp;&amp; </span><span><span class="hljs-variable">$free</span></span><span> !== </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-variable">$used</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> - </span><span><span class="hljs-variable">$free</span></span><span>;
    </span><span><span class="hljs-variable">$usedPercent</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> &gt; </span><span><span class="hljs-number">0</span></span><span> ? (</span><span><span class="hljs-variable">$used</span></span><span> / </span><span><span class="hljs-variable">$total</span></span><span>) * </span><span><span class="hljs-number">100</span></span><span> : </span><span><span class="hljs-number">0</span></span><span>;
    </span><span><span class="hljs-title function_ invoke__">printf</span></span><span>(</span><span><span class="hljs-string">"総容量: %s, 利用可能: %s, 使用済み: %.2f%%\n"</span></span><span>, </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$total</span></span><span>), </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$free</span></span><span>), </span><span><span class="hljs-variable">$usedPercent</span></span><span>);
}
</span></span>

4.数値ユニットと表示方法（一般的なエラーポイント）

ディスクスペースには一般的に使用される2つのユニットがあります。

  • バイナリ（オペレーティングシステムで一般的に使用）： 1 KIB = 1024バイト、1 MIB = 1024 KIB = 10242バイト、1 GIB = 10243バイト。

  • 小数（一部のメーカーまたはハードディスク仕様）： 1 kb = 1000バイト、1 Mb = 10002バイト。

PHPはバイト数を返します。 「人間読み取り可能な」ディスプレイが必要な場合は、通常、オペレーティングシステムツール（ DF -Hなどに近いバイナリ（1024）で変換されます。通常はGIBを表示します）：

 <span><span><span class="hljs-function"><span class="hljs-keyword">function</span></span></span><span> </span><span><span class="hljs-title">formatBytes</span></span><span>(</span><span><span class="hljs-params"><span class="hljs-variable">$bytes</span></span></span><span>, </span><span><span class="hljs-variable">$precision</span></span><span> = </span><span><span class="hljs-number">2</span></span><span>) {
    </span><span><span class="hljs-keyword">if</span></span><span> (!</span><span><span class="hljs-title function_ invoke__">is_numeric</span></span><span>(</span><span><span class="hljs-variable">$bytes</span></span><span>) || </span><span><span class="hljs-variable">$bytes</span></span><span> &lt; </span><span><span class="hljs-number">0</span></span><span>) </span><span><span class="hljs-keyword">return</span></span><span> </span><span><span class="hljs-string">'0 B'</span></span><span>;
    </span><span><span class="hljs-variable">$units</span></span><span> = [</span><span><span class="hljs-string">'B'</span></span><span>,</span><span><span class="hljs-string">'KiB'</span></span><span>,</span><span><span class="hljs-string">'MiB'</span></span><span>,</span><span><span class="hljs-string">'GiB'</span></span><span>,</span><span><span class="hljs-string">'TiB'</span></span><span>,</span><span><span class="hljs-string">'PiB'</span></span><span>];
    </span><span><span class="hljs-variable">$i</span></span><span> = </span><span><span class="hljs-number">0</span></span><span>;
    </span><span><span class="hljs-keyword">while</span></span><span> (</span><span><span class="hljs-variable">$bytes</span></span><span> &gt;= </span><span><span class="hljs-number">1024</span></span><span> &amp;&amp; </span><span><span class="hljs-variable">$i</span></span><span> &lt; </span><span><span class="hljs-title function_ invoke__">count</span></span><span>(</span><span><span class="hljs-variable">$units</span></span><span>)-</span><span><span class="hljs-number">1</span></span><span>) {
        </span><span><span class="hljs-variable">$bytes</span></span><span> /= </span><span><span class="hljs-number">1024</span></span><span>;
        </span><span><span class="hljs-variable">$i</span></span><span>++;
    }
    </span><span><span class="hljs-keyword">return</span></span><span> </span><span><span class="hljs-title function_ invoke__">round</span></span><span>(</span><span><span class="hljs-variable">$bytes</span></span><span>, </span><span><span class="hljs-variable">$precision</span></span><span>) . </span><span><span class="hljs-string">' '</span></span><span> . </span><span><span class="hljs-variable">$units</span></span><span>[</span><span><span class="hljs-variable">$i</span></span><span>];
}
</span></span>

例： 1073741824バイト= 1073741824 /1024^3 = 1 GIB （つまり、1GIB）。

5.一般的な落とし穴と推奨されるプラクティス

  1. 32ビットオーバーフロー：32ビットのPHPでは、より多くのバイトがINT範囲から外れている可能性があり、エラーまたは浮動ポイント近似が発生します。 64ビット環境で実行するか、フロート/ストリングを使用して多数を処理してください。

  2. return値を確認​​します： falseを返す関数が失敗したら、 === falseを適用して、 if（！$ free）ではなく、エラーを判断します）（0バイトもfalse値であるため）。

  3. 権限と保持ブロック：「現在のプロセスで可視/利用可能」スペースで返されることを認識してください - Webサーバーユーザーとして実行すると、結果は利用可能なスーパーユーザーよりも低い場合があります。

  4. ネットワークファイルシステム（NFS/SMB） ：これらのマウントは、マウントオプションによって不安定または影響を受けた場合、特定のマウント構成と組み合わせてテストする必要があります。

  5. クイックモニタリング：アラームに使用される場合（ディスク使用量> 90％など）、 Disk_total_space（）とdiskfreespace（）の組み合わせを使用し、保持されたブロックやクォータに誤解されないようにしきい値を控えめに設定します。

6。完了例：利用可能なスペースを取得し、パーセンテージでアラートします

<span><span><span class="hljs-meta">&lt;?php</span></span><span>
</span><span><span class="hljs-variable">$path</span></span><span> = </span><span><span class="hljs-string">'/'</span></span><span>; </span><span><span class="hljs-comment">// 検出されるパス</span></span><span>
</span><span><span class="hljs-variable">$total</span></span><span> = @</span><span><span class="hljs-title function_ invoke__">disk_total_space</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);
</span><span><span class="hljs-variable">$free</span></span><span>  = @</span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$total</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span> || </span><span><span class="hljs-variable">$free</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"ディスク情報を取得できません（パスエラーまたは不十分な権限である場合があります）\n"</span></span><span>;
    </span><span><span class="hljs-keyword">exit</span></span><span>(</span><span><span class="hljs-number">1</span></span><span>);
}

</span><span><span class="hljs-variable">$used</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> - </span><span><span class="hljs-variable">$free</span></span><span>;
</span><span><span class="hljs-variable">$usedPercent</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> &gt; </span><span><span class="hljs-number">0</span></span><span> ? (</span><span><span class="hljs-variable">$used</span></span><span> / </span><span><span class="hljs-variable">$total</span></span><span>) * </span><span><span class="hljs-number">100</span></span><span> : </span><span><span class="hljs-number">0</span></span><span>;

</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"パス: <span class="hljs-subst">$path</span></span></span><span>\n";
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"総容量: "</span></span><span> . </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$total</span></span><span>) . </span><span><span class="hljs-string">"\n"</span></span><span>;
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"利用可能: "</span></span><span>     . </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$free</span></span><span>)  . </span><span><span class="hljs-string">"\n"</span></span><span>;
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"使用済み: "</span></span><span>     . </span><span><span class="hljs-title function_ invoke__">number_format</span></span><span>(</span><span><span class="hljs-variable">$usedPercent</span></span><span>, </span><span><span class="hljs-number">2</span></span><span>) . </span><span><span class="hljs-string">"%\n"</span></span><span>;

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$usedPercent</span></span><span> &gt;= </span><span><span class="hljs-number">90</span></span><span>) {
    </span><span><span class="hljs-comment">// アラームロジックの例</span></span><span>
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"警告：ディスクは以上に使用されています 90%！\n"</span></span><span>;
}

</span><span><span class="hljs-comment">// formatBytes 関数は上記と同じです</span></span><span>
</span></span>

7。概要（キーポイントのレビュー）

  • DiskFreespace（）はバイトを返し、ディスク上のすべてのユーザーが使用できる「絶対的なアイドル量」ではなく、このマウントポイントで現在のPHPプロセスで利用可能なスペースを表します。

  • 結果は、ファイルシステムの予約ブロック、許可、クォータ、ネットワークマウント、および動作環境（コンテナ/仮想マシン）の影響を受けます。

  • 表示するときは、オペレーティングシステムの一般的な表示方法に近い1024のカーディナリティに従って、Kib/Mib/Gibに変換します。

  • 必ず=== falseを確認してエラーを処理し、32ビット環境での大量のオーバーフローに注意してください。

関連内容