<?xml version="1.0" encoding="utf-8"?>

<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.dirname">

<refnamediv>

<refname>dirname</refname>

<refpurpose>Возвращает путь к родительскому каталогу</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>

Функция получит строку, которая содержит путь к файлу или каталогу,

и вернёт путь к родительскому каталогу на столько уровней выше текущего

каталога, сколько указали в параметре <parameter>levels</parameter>.

</para>

<note>

<para>

Функция <function>dirname</function> наивно работает со входной

строкой и не знает действительную файловую систему

или компоненты пути наподобие «<literal>..</literal>».

</para>

</note>

<caution>

<para>

В ОС Windows функция <function>dirname</function> принимает установленную кодовую страницу.

Поэтому, чтобы функция видела правильное имя каталога, путь которого содержит

многобайтовые символы, требуется устанавливать кодовую страницу, которая соответствует

кодировке этих символов.

Функция <function>dirname</function> поведёт себя непредсказуемо, если имя

пути <parameter>path</parameter> содержит неправильные для текущей

кодовой страницы символы.

</para>

<para>

В других системах функция <function>dirname</function> предполагает,

что путь <parameter>path</parameter> закодировали в ASCII-совместимой кодировке,

иначе функция ведёт себя непредсказуемо.

</para>

</caution>

</refsect1>

<refsect1 role="parameters">

&reftitle.parameters;

<para>

<variablelist>

<varlistentry>

<term><parameter>path</parameter></term>

<listitem>

<para>

Путь.

</para>

<para>

На платформах Windows как разделитель имён каталогов работает

и прямой <literal>/</literal>, и обратный <literal>\</literal> слеш.

В других окружениях — прямой слеш <literal>/</literal>.

</para>

</listitem>

</varlistentry>

<varlistentry>

<term><parameter>levels</parameter></term>

<listitem>

<para>

На сколько уровней вложенности вверх требуется пройти.

</para>

<para>

Значение должно быть целым числом больше 0.

</para>

</listitem>

</varlistentry>

</variablelist>

</para>

</refsect1>

<refsect1 role="returnvalues">

&reftitle.returnvalues;

<para>

Функция возвращает путь к родительской директории. Функция возвращает

точку «<literal>.</literal>», которая указывает на текущую директорию,

если путь <parameter>path</parameter> не содержит слешей,

иначе возвращает путь <parameter>path</parameter>

без последнего компонента <literal>/component</literal>.

</para>

<caution>

<para>

При работе с функцией в цикле соблюдают осторожность,

поскольку при достижении каталога верхнего уровня функция войдет в бесконечный цикл.

<informalexample>

<programlisting role="php">

</programlisting>

</informalexample>

</para>

</caution>

</refsect1>

<refsect1 role="examples">

&reftitle.examples;

<para>

<example>

<title>Пример использования функции <function>dirname</function></title>

<programlisting role="php">

</programlisting>

&example.outputs.similar;

<screen>

</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>