-
Notifications
You must be signed in to change notification settings - Fork 56
/
fopen.xml
393 lines (383 loc) · 16.6 KB
/
fopen.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: ea62fb83196997032641b50fe44420305466195e Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,mumumu -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fopen">
<refnamediv>
<refname>fopen</refname>
<refpurpose>ファイルまたは URL をオープンする</refpurpose>
</refnamediv>
<refsect1 role="description">
&reftitle.description;
<methodsynopsis>
<type class="union"><type>resource</type><type>false</type></type><methodname>fopen</methodname>
<methodparam><type>string</type><parameter>filename</parameter></methodparam>
<methodparam><type>string</type><parameter>mode</parameter></methodparam>
<methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>&false;</initializer></methodparam>
<methodparam choice="opt"><type class="union"><type>resource</type><type>null</type></type><parameter>context</parameter><initializer>&null;</initializer></methodparam>
</methodsynopsis>
<para>
<function>fopen</function> は、<parameter>filename</parameter>
で指定されたリソースをストリームに結び付けます。
</para>
</refsect1>
<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>filename</parameter></term>
<listitem>
<para>
<parameter>filename</parameter> が "スキーム://..." の形式である場合、
それは URL とみなされ、PHP はそのプロトコルのハンドラ
(ラッパーともいいます) を探します。
もしもそのプロトコルに対するラッパーが登録されていない場合、
PHP はスクリプトに潜在的な問題があることを示す NOTICE を発行したうえで、
<parameter>filename</parameter> を通常のファイルとみなしてオープンすることを試みます。
</para>
<para>
PHP は、<parameter>filename</parameter> がローカルのファイルを示しているとみなすと、
そのファイルへのストリームをオープンします。
そのファイルはPHPからアクセスできるものでなければなりません。
ファイルのパーミッションが (パラメータで指定された)
アクセスを許可されているかどうか確認する必要があります。
<link linkend="ini.open-basedir">open_basedir</link>
を有効にしている場合は、更なるアクセス制限が加えられることがあります。
</para>
<para>
<parameter>filename</parameter> が登録されているプロトコルを示していると
PHP が判断し、かつそのプロトコルがネットワーク URL として登録されていれば、
PHP は <link linkend="ini.allow-url-fopen">allow_url_fopen</link>
が有効となっているかどうかチェックします。
もしこれがオフになっていると、PHP は warning を発行し fopen は失敗します。
</para>
<note>
<para>
サポートされているプロトコルのリストは <xref linkend="wrappers"/> にあります。
いくつかのプロトコル (<literal>wrappers</literal>にも関連する) は
<literal>context</literal> かつ/または &php.ini; のオプションをサポートします。
使用するプロトコルについてセットされるオプションのリストについては、
それぞれのページを見てください (例えば、 &php.ini; 上の
<literal>user_agent</literal> の値は
<literal>http</literal> ラッパーが使用します)。
</para>
</note>
<para>
Windows 環境では、ファイルパスで用いる全てのバックスラッシュを
エスケープするかフォワードスラッシュを使用することに注意してください。
<informalexample>
<programlisting role="php">
<![CDATA[
<?php
$handle = fopen("c:\\folder\\resource.txt", "r");
?>
]]>
</programlisting>
</informalexample>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>mode</parameter></term>
<listitem>
<para>
パラメータ <parameter>mode</parameter> は、
そのストリームに要するアクセス形式を指定します。
この指定は、下表のうちのどれかとなります。
<table>
<title>
<function>fopen</function> で使用可能な
<parameter>mode</parameter> のリスト
</title>
<tgroup cols="2">
<thead>
<row>
<entry><parameter>mode</parameter></entry>
<entry>説明</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>'r'</literal></entry>
<entry>
読み込みのみでオープンします。ファイルポインタをファイルの先頭に置きます。
</entry>
</row>
<row>
<entry><literal>'r+'</literal></entry>
<entry>
読み込み/書き出し用にオープンします。
ファイルポインタをファイルの先頭に置きます。
</entry>
</row>
<row>
<entry><literal>'w'</literal></entry>
<entry>
書き出しのみでオープンします。ファイルポインタをファイルの先頭に置き、
ファイルサイズをゼロにします。ファイルが存在しない場合には、
作成を試みます。
</entry>
</row>
<row>
<entry><literal>'w+'</literal></entry>
<entry>
読み込み/書き出し用でオープンします。
それ以外の振る舞いは、<literal>'w'</literal> と同じです。
</entry>
</row>
<row>
<entry><literal>'a'</literal></entry>
<entry>
書き出し用のみでオープンします。ファイルポインタをファイルの終端に置きます。
ファイルが存在しない場合には、作成を試みます。
このモードは、<function>fseek</function> では何の効果もありません。
書き込みは、常に追記となります。
</entry>
</row>
<row>
<entry><literal>'a+'</literal></entry>
<entry>
読み込み/書き出し用でオープンします。
ファイルポインタをファイルの終端に置きます。
ファイルが存在しない場合には、作成を試みます。
このモードは、<function>fseek</function> では読み込み位置のみに影響します。
書き込みは、常に追記となります。
</entry>
</row>
<row>
<entry><literal>'x'</literal></entry>
<entry>
書き込みのみでオープンします。ファイルポインタをファイルの先頭に置きます。
ファイルが既に存在する場合には <function>fopen</function> は失敗し、
<constant>E_WARNING</constant> レベルのエラーを発行します。
ファイルが存在しない場合には新規作成を試みます。
これは <literal>open(2)</literal> システムコールにおける
<literal>O_EXCL|O_CREAT</literal> フラグの指定と等価です。
このオプションはPHP4.3.2以降でサポートされ、また、
ローカルファイルに対してのみ有効です。
</entry>
</row>
<row>
<entry><literal>'x+'</literal></entry>
<entry>
読み込み/書き出し用でオープンします。
それ以外の振る舞いは <literal>'x'</literal> と同じです。
</entry>
</row>
<row>
<entry><literal>'c'</literal></entry>
<entry>
書き込みのみでオープンします。ファイルが存在しない場合には新規作成を試みます。
ファイルが既に存在する場合でもそれを (<literal>'w'</literal> のように) 切り詰めたりせず、
また (<literal>'x'</literal> のように) 関数のコールが失敗することもありません。
ファイルポインタをファイルの先頭に置きます。これは、アドバイザリ・ロック
(<function>flock</function> を参照ください) を確保してからファイルを変更したい場合に便利です。
<literal>'w'</literal> を使うと、ロックを取得する前にファイルを切り詰めてしまいます
(もしファイルを切り詰めたいのなら、ロックを要求した後で
<function>ftruncate</function> を使うこともできます)。
</entry>
</row>
<row>
<entry><literal>'c+'</literal></entry>
<entry>
読み込み/書き出し用でオープンします。
それ以外の振る舞いは <literal>'c'</literal> と同じです。
</entry>
</row>
<row>
<entry><literal>'e'</literal></entry>
<entry>
オープンされたファイル記述子に close-on-exec フラグを設定します。
POSIX.1-2008 準拠のシステムでコンパイルされた PHP でのみ利用可能です。
</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<note>
<para>
オペレーティングシステムファミリが異なると行末も異なります。
テキストファイルに書き出し、そこに改行を加えたいとき、
オペレーティングシステムにあわせた正しい改行コードを使用する必要があります。
Unix ベースのシステムでは改行に <literal>\n</literal> キャラクタを使用します。
Windows ベースのシステムでは <literal>\r\n</literal> を使用します。
マッキントッシュベースのシステム (Mac OS Classic) では <literal>\r</literal> を使用します。
</para>
<para>
間違った改行コードでファイルに書き込むと、
他のアプリケーション上でそのファイルを開いた際に変な風に見えてしまいます。
</para>
<para>
Windows上では、<literal>\n</literal>を<literal>\r\n</literal>に透過的に変換する
text-mode変換フラグ(<literal>'t'</literal>)が提供されます。
それに対し、<literal>'b'</literal>を使って強制的にバイナリモードにすることもできます。
その場合データの変換はされません。
このフラグを使用するには、<literal>'b'</literal> または <literal>'t'</literal>を
<parameter>mode</parameter>引数の最後に追加してください。
</para>
<para>
デフォルトの変換モードは <literal>'b'</literal> です。
plain-text ファイルを使用する場合には <literal>'t'</literal> モードを指定できますし、
改行に <literal>\n</literal> を使用すると、
古いバージョンのメモ帳のようなアプリケーションで読めることを期待できます。
それ以外のケースでは <literal>'b'</literal> を使うべきです。
</para>
<para>
バイナリファイルを扱っている際に
<literal>'t'</literal> フラグを指定した場合、
画像ファイルが壊れたり、<literal>\r\n</literal>
キャラクタがおかしくなる等の問題を抱えてしまうでしょう。
</para>
</note>
<note>
<para>
互換性維持のために、<literal>'t'</literal>
モードを使用または依存しているコードを書き直し、
正しい改行コードと <literal>'b'</literal> モードを代わりに使用することが、
強く推奨されます。
</para>
</note>
<note>
<simpara>
<filename>php://output</filename>,
<filename>php://input</filename>, <filename>php://stdin</filename>,
<filename>php://stdout</filename>, <filename>php://stderr</filename>,
<filename>php://fd</filename> ストリームラッパーについては、
<parameter>mode</parameter> は無視されます。
</simpara>
</note>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>use_include_path</parameter></term>
<listitem>
<para>
オプションの3番目の引数<parameter>use_include_path</parameter>に'1'又は
&true; を設定することにより、<link linkend="ini.include-path">include_path</link>
のファイルの検索も行うこともできます。
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>context</parameter></term>
<listitem>
¬e.context-support;
</listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>
<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
成功した場合にファイルポインタリソース、
&return.falseforfailure;
</para>
</refsect1>
<refsect1 role="errors">
&reftitle.errors;
&fs.emits.warning.on.failure;
</refsect1>
<refsect1 role="changelog">
&reftitle.changelog;
<para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>&Version;</entry>
<entry>&Description;</entry>
</row>
</thead>
<tbody>
<row>
<entry>7.0.16, 7.1.2</entry>
<entry>
<literal>'e'</literal> が追加されました。
</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</para>
</refsect1>
<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>fopen</function> の例</title>
<programlisting role="php">
<![CDATA[
<?php
$handle = fopen("/home/rasmus/file.txt", "r");
$handle = fopen("/home/rasmus/file.gif", "wb");
$handle = fopen("http://www.example.com/", "r");
$handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
?>
]]>
</programlisting>
</example>
</para>
</refsect1>
<refsect1 role="notes">
&reftitle.notes;
&warn.ssl-non-standard;
<note>
<para>
ファイルの読みこみ・書きこみ時に問題が発生し、
サーバーモジュール版のPHPを使用している場合、
使用するファイル・ディレクトリがサーバープロセスからアクセス可能かどうかを確認してください。
</para>
</note>
<note>
<para>
この関数は、<parameter>filename</parameter> がディレクトリの場合でも成功することがあります。
<parameter>filename</parameter> がファイルなのかディレクトリなのかがはっきりしない場合は、
まず <function>is_dir</function> を使ってから <function>fopen</function> を呼ぶようにしましょう。
</para>
</note>
</refsect1>
<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><xref linkend="wrappers"/></member>
<member><function>fclose</function></member>
<member><function>fgets</function></member>
<member><function>fread</function></member>
<member><function>fwrite</function></member>
<member><function>fsockopen</function></member>
<member><function>file</function></member>
<member><function>file_exists</function></member>
<member><function>is_readable</function></member>
<member><function>stream_set_timeout</function></member>
<member><function>popen</function></member>
<member><function>stream_context_create</function></member>
<member><function>umask</function></member>
<member><classname>SplFileObject</classname></member>
</simplelist>
</para>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->