archived-doc-fr/reference/filesystem/functions/stat.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: f80105b4fc1196bd8d5fecb98d686b580b1ff65d Maintainer: yannick Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.stat" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>stat</refname>
  <refpurpose>Renvoie les informations à propos d'un fichier</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>stat</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
  </methodsynopsis>
  <para>
   Renvoie les informations à propos du fichier <parameter>filename</parameter>.
   Si <parameter>filename</parameter> est un lien symbolique, les informations
   proviennent du fichier lui-même, et non du lien symbolique.
   Avant PHP 7.4.0, sous Windows <abbrev>NTS</abbrev> compile les
   valeurs statiques <literal>size</literal>, <literal>atime</literal>,
   <literal>mtime</literal> et <literal>ctime</literal> depuis les liens
   symboliques, dans ce cas.
  </para>
  <para>
   <function>lstat</function> est identique à
   <function>stat</function> sauf que les informations seront alors basées
   sur le lien symbolique.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Le chemin vers le fichier.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <table>
    <title>Format du résultat de <function>stat</function> et
     <function>fstat</function></title>
    <tgroup cols="3">
     <thead>
      <row>
       <entry>Numéro</entry>
       <entry>Nom</entry>
       <entry>Description</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>0</entry>
       <entry>dev</entry>
       <entry>volume (***)</entry>
      </row>
      <row>
       <entry>1</entry>
       <entry>ino</entry>
       <entry>Numéro d'inode (****)</entry>
      </row>
      <row>
       <entry>2</entry>
       <entry>mode</entry>
       <entry>droit d'accès à l'inode *****</entry>
      </row>
      <row>
       <entry>3</entry>
       <entry>nlink</entry>
       <entry>nombre de liens</entry>
      </row>
      <row>
       <entry>4</entry>
       <entry>uid</entry>
       <entry>userid du propriétaire (*)</entry>
      </row>
      <row>
       <entry>5</entry>
       <entry>gid</entry>
       <entry>groupid du propriétaire (*)</entry>
      </row>
      <row>
       <entry>6</entry>
       <entry>rdev</entry>
       <entry>type du volume, si le volume est une inode</entry>
      </row>
      <row>
       <entry>7</entry>
       <entry>size</entry>
       <entry>taille en octets</entry>
      </row>
      <row>
       <entry>8</entry>
       <entry>atime</entry>
       <entry>date de dernier accès (Unix timestamp)</entry>
      </row>
      <row>
       <entry>9</entry>
       <entry>mtime</entry>
       <entry>date de dernière modification (Unix timestamp)</entry>
      </row>
      <row>
       <entry>10</entry>
       <entry>ctime</entry>
       <entry>date de dernier changement d'inode (Unix timestamp)</entry>
      </row>
      <row>
       <entry>11</entry>
       <entry>blksize</entry>
       <entry>taille de bloc (**)</entry>
      </row>
      <row>
       <entry>12</entry>
       <entry>blocks</entry>
       <entry>nombre de blocs de 512 octets alloués (**)</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </para>
  <para>
   * - Sous Windows, ceci sera toujours <literal>0</literal>.
  </para>
  <para>
   ** - uniquement sur les systèmes qui supportent le type <literal>st_blksize</literal>.
   Les autres systèmes (p. ex. Windows) retournent <literal>-1</literal>.
  </para>
  <para>
   *** - Sous Windows, à partir de PHP 7.4.0, ce sera le numéro de série du volume qui
   contient le fichier, qui sera un entier 64-bit <emphasis>non signé</emphasis>
   qui peut déborder. Auparavant, c'était la représentation numérique de la lettre
   du volume (c.-à-d. <literal>2</literal> pour <literal>C:</literal>) pour la fonction
   <function>stat</function>, et <literal>0</literal> pour la fonction
   <function>lstat</function>.
  </para>
  <para>
   **** - Sous Windows, à partir de PHP 7.4.0, c'est l'identifiant associé avec le fichier,
   qui sera un entier 64-bit <emphasis>non signé</emphasis> qui peut déborder.
   Auparavant, c'était toujours <literal>0</literal>.
  </para>
  <para>
   ***** Sous Windows, le bit de la permission d'écriture est défini en
   fonction de l'attribut lecture seule du fichier, et la même valeur est
   rapportée pour tous les utilisateurs, groupe, et propriétaire.
   L'ACL n'est pas prise en compte, contrairement à <function>is_writable</function>.
  </para>
  <para>
   La valeur de <literal>mode</literal> contient des informations lues par
   plusieurs fonctions. Écrite en octal, en commençant par la droite,
   les trois premiers chiffres sont retournés par <function>chmod</function>.
   Le chiffre suivant est ignoré par PHP. Les deux chiffres suivants indiquent
   le type de fichier :
   <table>
    <title>Les types de fichiers <literal>mode</literal></title>
    <tgroup cols="2">
     <thead>
      <row>
       <entry><literal>mode</literal> en octal</entry>
       <entry>Signification</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry><literal>0140000</literal></entry>
       <entry>socket</entry>
      </row>
      <row>
       <entry><literal>0120000</literal></entry>
       <entry>lien symbolique</entry>
      </row>
      <row>
       <entry><literal>0100000</literal></entry>
       <entry>fichier régulier</entry>
      </row>
      <row>
       <entry><literal>0060000</literal></entry>
       <entry>périphérique bloc</entry>
      </row>
      <row>
       <entry><literal>0040000</literal></entry>
       <entry>dossier</entry>
      </row>
      <row>
       <entry><literal>0020000</literal></entry>
       <entry>périphérique de caractère</entry>
      </row>
      <row>
       <entry><literal>0010000</literal></entry>
       <entry>FIFO (un tube nommé)</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
   Ainsi, par exemple, un fichier régulier pourrait être
   <literal>0100644</literal> et un dossier pourrait être
   <literal>0040755</literal>.
  </para>
  <para>
   En cas d'erreur, <function>stat</function> retourne &false;.
  </para>
  &fs.file.32bit;
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <para>
   Si une erreur survient, une alerte de type
   <constant>E_WARNING</constant> est émise.
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>7.4.0</entry>
      <entry>
       Sous Windows, le numéro du volume est maintenant le numéro de série qui contient
       le fichier, et le numéro de l'inode est l'identifiant associé avec le fichier.
      </entry>
     </row>
     <row>
      <entry>7.4.0</entry>
      <entry>
       Les valeurs statiques <literal>size</literal>, <literal>atime</literal>,
       <literal>mtime</literal> et <literal>ctime</literal> des liens symboliques
       sont toujours ceux de la cible. Ce n'était précédemment pas le cas
       pour les builds <abbrev>NTS</abbrev> sous Windows.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Exemple avec <function>stat</function></title>
    <programlisting role="php">
<![CDATA[
<?php
/* Récupération des informations */
$stat = stat('C:\php\php.exe');

/*
 * Affichage de la date et heure de l'accès à ce fichier,
 * identique à l'appel à la fonction fileatime()
 */
echo 'Date et heure d\'accès : ' . $stat['atime'];

/*
 * Affiche de la date et heure de modification du fichier,
 * identique à l'appel à la fonction filemtime()
 */
echo 'Date et heure de modification : ' . $stat['mtime'];

/* Affichage du numéro du device */
echo 'Numéro du Device : ' . $stat['dev'];
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Utilisation des informations issues de <function>stat</function>
    conjointement avec la fonction <function>touch</function></title>
    <programlisting role="php">
<![CDATA[
<?php
/* Récupération des informations issues de la fonction stat */
$stat = stat('C:\php\php.exe');

/* L'accès aux informations a-t-il échoué ? */
if (!$stat) {
    echo 'L\'appel à stat() a échoué...';
} else {
    /*
     * Nous voulons que la date et heure d'accès soit d'une
     * semaine après la date courante.
     */
    $atime = $stat['atime'] + 604800;

    /* Touchons le fichier ! */
    if(!touch('some_file.txt', time(), $atime)) {
        echo 'Échec lors de l\'appel à la fonction touch()...';
    } else {
        echo 'L\'appel à touch() a réussi...';
    }
}
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.filesystem-time-res;
  &note.clearstatcache;
  &tip.fopen-wrapper.stat;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>lstat</function></member>
    <member><function>fstat</function></member>
    <member><function>filemtime</function></member>
    <member><function>filegroup</function></member>
    <member><classname>SplFileInfo</classname></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
-->