mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-24 12:58:56 +00:00
88c1f8d6c9
For basename(), we declare the behavior regarding invalid characters in
the path as being undefined, since that depends on the availability of
mblen, and also on the position of the invalid characters prior to PHP
8.0.0[1].
dirname() is actually not local-aware, but relies on an ASCII
compatible character encoding regarding the directory separator. On
Windows, it is however, dependent on the currently set codepage
(although a fallback is still in place to use the Windows ANSI codepage
of the operating system[2], if the string is not valid for the current
codepage).
Again, we declared failure to comply to these assumptions as resulting
in undefined behavior. Users should make sure to pass valid strings.
[1] <http://git.php.net/?p=php-src.git;a=commitdiff;h=90705d44e3da1d0aa7b8b4fd921ec597391eccb2>
[2] <5e01542526/win32/codepage.h (L95-L106)>
172 lines
4.5 KiB
XML
172 lines
4.5 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.dirname">
|
|
<refnamediv>
|
|
<refname>dirname</refname>
|
|
<refpurpose>Returns a parent directory's path</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>string</type><methodname>dirname</methodname>
|
|
<methodparam><type>string</type><parameter>path</parameter></methodparam>
|
|
<methodparam choice="opt"><type>int</type><parameter>levels</parameter><initializer>1</initializer></methodparam>
|
|
</methodsynopsis>
|
|
<para>
|
|
Given a string containing the path of a file or directory, this function
|
|
will return the parent directory's path that is
|
|
<parameter>levels</parameter> up from the current directory.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
<function>dirname</function> operates naively on the input string,
|
|
and is not aware of the actual filesystem, or path components such
|
|
as "<literal>..</literal>".
|
|
</para>
|
|
</note>
|
|
<caution>
|
|
<para>
|
|
On Windows, <function>dirname</function> assumes the currently set codepage, so for it to see the
|
|
correct directory name with multibyte character paths, the matching codepage must
|
|
be set.
|
|
If <parameter>path</parameter> contains characters which are invalid for the
|
|
current codepage, the behavior of <function>basename</function> is undefined.
|
|
</para>
|
|
<para>
|
|
On other systems, <function>dirname</function> assumes <parameter>path</parameter>
|
|
to be encoded in an ASCII compatible encoding. Otherwise the behavior of the
|
|
the function is undefined.
|
|
</para>
|
|
</caution>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><parameter>path</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
A path.
|
|
</para>
|
|
<para>
|
|
On Windows, both slash (<literal>/</literal>) and backslash
|
|
(<literal>\</literal>) are used as directory separator character. In
|
|
other environments, it is the forward slash (<literal>/</literal>).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><parameter>levels</parameter></term>
|
|
<listitem>
|
|
<para>
|
|
The number of parent directories to go up.
|
|
</para>
|
|
<para>
|
|
This must be an integer greater than 0.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns the path of a parent directory. If there are no slashes in
|
|
<parameter>path</parameter>, a dot ('<literal>.</literal>') is returned,
|
|
indicating the current directory. Otherwise, the returned string is
|
|
<parameter>path</parameter> with any trailing
|
|
<literal>/component</literal> removed.
|
|
</para>
|
|
</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.0</entry>
|
|
<entry>
|
|
Added the optional <parameter>levels</parameter> parameter.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title><function>dirname</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
echo dirname("/etc/passwd") . PHP_EOL;
|
|
echo dirname("/etc/") . PHP_EOL;
|
|
echo dirname(".") . PHP_EOL;
|
|
echo dirname("C:\\") . PHP_EOL;
|
|
echo dirname("/usr/local/lib", 2);
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs.similar;
|
|
<screen>
|
|
<![CDATA[
|
|
/etc
|
|
/ (or \ on Windows)
|
|
.
|
|
C:\
|
|
/usr
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member><function>basename</function></member>
|
|
<member><function>pathinfo</function></member>
|
|
<member><function>realpath</function></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
|
|
-->
|