reference/filesystem/functions/dirname.xml
67ca0d930c95a85ea49aff456409409f6ae06c1b
67ca0d930c95a85ea49aff456409409f6ae06c1b
...
...
@@ -18,6 +18,27 @@
18
18
will return the parent directory's path that is
19
19
<parameter>levels</parameter> up from the current directory.
20
20
</para>
21
+
<note>
22
+
<para>
23
+
<function>dirname</function> operates naively on the input string,
24
+
and is not aware of the actual filesystem, or path components such
25
+
as "<literal>..</literal>".
26
+
</para>
27
+
</note>
28
+
<caution>
29
+
<para>
30
+
On Windows, <function>dirname</function> assumes the currently set codepage, so for it to see the
31
+
correct directory name with multibyte character paths, the matching codepage must
32
+
be set.
33
+
If <parameter>path</parameter> contains characters which are invalid for the
34
+
current codepage, the behavior of <function>dirname</function> is undefined.
35
+
</para>
36
+
<para>
37
+
On other systems, <function>dirname</function> assumes <parameter>path</parameter>
38
+
to be encoded in an ASCII compatible encoding. Otherwise the behavior of the
39
+
the function is undefined.
40
+
</para>
41
+
</caution>
21
42
</refsect1>
22
43
23
44
<refsect1 role="parameters">
...
...
@@ -61,6 +82,25 @@
61
82
<parameter>path</parameter> with any trailing
62
83
<literal>/component</literal> removed.
63
84
</para>
85
+
86
+
<caution>
87
+
<para>
88
+
Be careful when using this function in a loop that can reach the
89
+
top-level directory as this can result in an infinite loop.
90
+
<informalexample>
91
+
<programlisting role="php">
92
+
<![CDATA[
93
+
<?php
94
+
dirname('.'); // Will return '.'.
95
+
dirname('/'); // Will return `\` on Windows and '/' on *nix systems.
96
+
dirname('\\'); // Will return `\` on Windows and '.' on *nix systems.
97
+
dirname('C:\\'); // Will return 'C:\' on Windows and '.' on *nix systems.
98
+
?>
99
+
]]>
100
+
</programlisting>
101
+
</informalexample>
102
+
</para>
103
+
</caution>
64
104
</refsect1>
65
105
66
106
<refsect1 role="changelog">
...
...
@@ -81,12 +121,6 @@
81
121
Added the optional <parameter>levels</parameter> parameter.
82
122
</entry>
83
123
</row>
84
-
<row>
85
-
<entry>5.0.0</entry>
86
-
<entry>
87
-
<function>dirname</function> is now binary safe
88
-
</entry>
89
-
</row>
90
124
</tbody>
91
125
</tgroup>
92
126
</informaltable>
...
...
@@ -104,6 +138,7 @@
104
138
echo dirname("/etc/passwd") . PHP_EOL;
105
139
echo dirname("/etc/") . PHP_EOL;
106
140
echo dirname(".") . PHP_EOL;
141
+
echo dirname("C:\\") . PHP_EOL;
107
142
echo dirname("/usr/local/lib", 2);
108
143
]]>
109
144
</programlisting>
...
...
@@ -113,6 +148,7 @@ echo dirname("/usr/local/lib", 2);
113
148
/etc
114
149
/ (or \ on Windows)
115
150
.
151
+
C:\
116
152
/usr
117
153
]]>
118
154
</screen>
...
...
@@ -120,51 +156,6 @@ echo dirname("/usr/local/lib", 2);
120
156
</para>
121
157
</refsect1>
122
158
123
-
<refsect1 role="notes">
124
-
&reftitle.notes;
125
-
<note>
126
-
<para>
127
-
<function>dirname</function> operates naively on the input string,
128
-
and is not aware of the actual filesystem, or path components such
129
-
as "<literal>..</literal>".
130
-
</para>
131
-
</note>
132
-
<note>
133
-
<para>
134
-
<function>dirname</function> is locale aware, so for it to see the
135
-
correct directory name with multibyte character paths, the matching locale must
136
-
be set using the <function>setlocale</function> function.
137
-
</para>
138
-
</note>
139
-
<note>
140
-
<para>
141
-
Since PHP 4.3.0, you will often get a slash or a dot back from
142
-
<function>dirname</function> in situations where the older
143
-
functionality would have given you the empty string.
144
-
</para>
145
-
</note>
146
-
<para>
147
-
Check the following change example:
148
-
<informalexample>
149
-
<programlisting role="php">
150
-
<![CDATA[
151
-
<?php
152
-
153
-
//before PHP 4.3.0
154
-
dirname('c:/'); // returned '.'
155
-
156
-
//after PHP 4.3.0
157
-
dirname('c:/x'); // returns 'c:\'
158
-
dirname('c:/Temp/x'); // returns 'c:/Temp'
159
-
dirname('/x'); // returns '\'
160
-
161
-
?>
162
-
]]>
163
-
</programlisting>
164
-
</informalexample>
165
-
</para>
166
-
</refsect1>
167
-
168
159
<refsect1 role="seealso">
169
160
&reftitle.seealso;
170
161
<para>
171
162