archived-doc-es/reference/filesystem/functions/dirname.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 784c7b502d772819b579525470f113b31dd6b166 Maintainer: seros Status: ready -->
<!-- Reviewed: no Maintainer: seros -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.dirname">
 <refnamediv>
  <refname>dirname</refname>
  <refpurpose>Devuelve la ruta de un directorio padre</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>
   Dada una cadena que contiene la ruta a un fichero o directorio, esta función
   devolverá la ruta del directorio padre que está a
   <parameter>levels</parameter> niveles del directorio actual.
  </para>
 </refsect1>
 
 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>path</parameter></term>
     <listitem>
      <para>
       Una ruta.
      </para>
      <para>
       En Windows, la barra (<literal>/</literal>) y la barra invertida
       (<literal>\</literal>) se usan como carácter separador de directorio. En
       otros entornos se usa la barra hacia delante (<literal>/</literal>).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>levels</parameter></term>
     <listitem>
      <para>
       El número de directorios padre a subir.
      </para>
      <para>
       Debe ser un número entero mayor que 0.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve la ruta de un directorio padre. Si no hay barras en
   <parameter>path</parameter>, será devuelto un punto ('<literal>.</literal>'),
   indicando el directorio actual. De otro modo, la cadena devuelta es
   <parameter>path</parameter> con cualquier
   <literal>/componente</literal> final eliminado.
  </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>
        Añadido el parámetro opcional <parameter>levels</parameter>.
       </entry>
      </row>
      <row>
       <entry>5.0.0</entry>
       <entry>
        <function>dirname</function> ahora es segura al trabajar con datos binarios
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>
 
 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Ejemplo de <function>dirname</function></title>
    <programlisting role="php">
<![CDATA[
<?php
echo dirname("/etc/passwd") . PHP_EOL;
echo dirname("/etc/") . PHP_EOL;
echo dirname(".") . PHP_EOL;
echo dirname("/usr/local/lib", 2);
]]>
    </programlisting>
    &example.outputs.similar;
    <screen>
<![CDATA[
/etc
/ (o \ en Windows)
.
/usr
]]>
    </screen>
   </example>
  </para>
 </refsect1>
 
 <refsect1 role="notes">
  &reftitle.notes;
  <note>
   <para>
    <function>dirname</function> opera de forma ingénua con la cadena de entrada,
    y no es consciente del sistema de ficheros o los componentes de la ruta
    como "<literal>..</literal>".
   </para>
  </note>
  <note>
   <para>
    <function>dirname</function> usa la configuración de idioma local, para poder ver 
    de forma correcta el nombre de directorio con caracteres multibyte en la ruta, se definir la misma configuración local 
    usando la función <function>setlocale</function>.
   </para>
  </note> 
  <note>
   <para>
    A partir de PHP 4.3.0, a menudo querrá obtener una barra o un punto de
    <function>dirname</function> es situaciones donde la funcionalidad
    anterior le habría dado una cadena vacía.
   </para>
  </note>
  <para>
   Revise el siguiente cambio de ejemplo:
   <informalexample>
    <programlisting role="php">
<![CDATA[
<?php

//antes de PHP 4.3.0
dirname('c:/'); // devolvía '.'

//después de PHP 4.3.0
dirname('c:/x'); // devuelve 'c:\'
dirname('c:/Temp/x'); // devuelve 'c:/Temp'
dirname('/x'); // devuelve '\'

?>
]]>
    </programlisting>
   </informalexample>
  </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
-->