reference/filesystem/functions/dirname.xml
21cd3a942724400765125b657d24f8c8c4d623e9
...
...
@@ -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
39
+
the function is undefined.
40
+
</para>
41
+
</caution>
21
42
</refsect1>
22
43

23
44
<refsect1 role="parameters">
...
...
@@ -61,36 +82,25 @@
61
82
<parameter>path</parameter> with any trailing
62
83
<literal>/component</literal> removed.
63
84
</para>
64
-
</refsect1>
65
85

66
-
<refsect1 role="changelog">
67
-
&reftitle.changelog;
68
-
<para>
69
-
<informaltable>
70
-
<tgroup cols="2">
71
-
<thead>
72
-
<row>
73
-
<entry>&Version;</entry>
74
-
<entry>&Description;</entry>
75
-
</row>
76
-
</thead>
77
-
<tbody>
78
-
<row>
79
-
<entry>7.0.0</entry>
80
-
<entry>
81
-
Added the optional <parameter>levels</parameter> parameter.
82
-
</entry>
83
-
</row>
84
-
<row>
85
-
<entry>5.0.0</entry>
86
-
<entry>
87
-
<function>dirname</function> is now binary safe
88
-
</entry>
89
-
</row>
90
-
</tbody>
91
-
</tgroup>
92
-
</informaltable>
93
-
</para>
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>
94
104
</refsect1>
95
105

96
106
<refsect1 role="examples">
...
...
@@ -104,6 +114,7 @@
104
114
echo dirname("/etc/passwd") . PHP_EOL;
105
115
echo dirname("/etc/") . PHP_EOL;
106
116
echo dirname(".") . PHP_EOL;
117
+
echo dirname("C:\\") . PHP_EOL;
107
118
echo dirname("/usr/local/lib", 2);
108
119
]]>
109
120
</programlisting>
...
...
@@ -113,6 +124,7 @@ echo dirname("/usr/local/lib", 2);
113
124
/etc
114
125
/ (or \ on Windows)
115
126
.
127
+
C:\
116
128
/usr
117
129
]]>
118
130
</screen>
...
...
@@ -120,51 +132,6 @@ echo dirname("/usr/local/lib", 2);
120
132
</para>
121
133
</refsect1>
122
134

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
135
<refsect1 role="seealso">
169
136
&reftitle.seealso;
170
137
<para>
171
138



Translation status