archived-doc-it/reference/filesystem/functions/fopen.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: e41806c30bf6975e452c0d4ce35ab0984c2fa68c Maintainer: pastore Status: ready -->
<!-- CREDITS: cortesi,fernando -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fopen">
 <refnamediv>
  <refname>fopen</refname>
  <refpurpose>Apre un file o un URL</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>resource</type><methodname>fopen</methodname>
   <methodparam><type>string</type><parameter>filename</parameter></methodparam>
   <methodparam><type>string</type><parameter>mode</parameter></methodparam>
   <methodparam choice="opt"><type>bool</type><parameter>use_include_path</parameter><initializer>&false;</initializer></methodparam>
   <methodparam choice="opt"><type>resource</type><parameter>context</parameter></methodparam>
  </methodsynopsis>
  <para>
    La funzione <function>fopen</function> apre un collegamento tra una risorsa, indicata
    dal parametro <parameter>filename</parameter>, ed un flusso.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>filename</parameter></term>
     <listitem>
      <para>
       Se il parametro <parameter>filename</parameter> è nella forma "scheme://...",
       si assume che sia un URL e PHP cercherà il modulo di gestione del protocollo
       (detto anche wrapper) per quello schema. Se non vi sono wrapper
       registrati per il protocollo richiesto, PHP genererà un messaggio per aiutare a trovare
       potenziali problemi nello script e quindi procede considerando
       <parameter>filename</parameter> come un file normale.
      </para>
      <para>
       Se PHP ha stabilito che <parameter>filename</parameter> indica
       un file locale, tenterà di aprire detto file come stream.
       Il file in oggetto dovrà esere accessibile a PHP, occorre, pertanto, assicurarsi che
       i permessi di accesso del file lo consentano.
       Se si è attivato
       <link linkend="ini.open-basedir">open_basedir</link> potrebbero
       essere applicate ulteriori restrizioni.
      </para>
      <para>
       Se PHP ha stabilito che <parameter>filename</parameter> indica
       un protocollo registrato, e che tale protocollo è registrato come un
       URL di rete, PHP verificherà che
       <link linkend="ini.allow-url-fopen">allow_url_fopen</link> sia
       abilitato. Se fosse disabilitato, PHP genererà un avviso e
       la chiamata ad fopen fallirà.
      </para>
      <note>
       <para>
        L'elenco dei protocolli supportati si trova in <xref
        linkend="wrappers"/>. Alcuni protocolli (indicati anche come
        <literal>wrappers</literal>) supportano il <literal>context</literal>
        e/o le opzioni del &php.ini;. Fare riferimento alla pagina specifica
        del protocollo in uso per avere l'elenco delle opzioni che possono essere utilizzate. (Ad esempio
        il valore di <literal>user_agent</literal> del &php.ini; è utilizzato dal
        wrapper <literal>http</literal>).
       </para>
      </note>
      <para>
       Sulla piattaforma Windows, fare attenzione effettuando l'escape dei backslash
       usati nel percorso del file, o utilizzare gli slash.
       <informalexample>
        <programlisting role="php">
<![CDATA[
<?php
$handle = fopen("c:\\folder\\resource.txt", "r");
?>
]]>
        </programlisting>
       </informalexample>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>mode</parameter></term>
     <listitem>
      <para>
       Il parametro <parameter>mode</parameter> indica il tipo di accesso
       richiesto per il flusso. Esso può essere uno dei seguenti:
       <table>
        <title>
         Elenco dei possibili valori usati da <function>fopen</function>
         per il parametro <parameter>mode</parameter>
        </title>
        <tgroup cols="2">
         <thead>
          <row>
           <entry><parameter>mode</parameter></entry>
           <entry>Descrizione</entry>
          </row>
         </thead>
         <tbody>
          <row>
           <entry><literal>'r'</literal></entry>
           <entry>
            Apre in sola lettura; posiziona il puntatore
            all'inizio del file.
           </entry>
          </row>
          <row>
           <entry><literal>'r+'</literal></entry>
           <entry>
            Apre in lettura e scrittura; posiziona il puntatore
            all'inizio del file.
           </entry>
          </row>
          <row>
           <entry><literal>'w'</literal></entry>
           <entry>
            Apre il file in sola scrittura; posiziona il puntatore
            all'inizio del file e tronca il file alla lunghezza zero.
            Se il file non esiste, tenta di crearlo.
           </entry>
          </row>
          <row>
           <entry><literal>'w+'</literal></entry>
           <entry>
            Apre in lettura e scrittura; posiziona il puntatore
            all'inizio del file e tronca il file alla lunghezza
            zero. Se il file non esiste, tenta di crearlo.
           </entry>
          </row>
          <row>
           <entry><literal>'a'</literal></entry>
           <entry>
            Apre in sola scrittura; posiziona il puntatore alla fine
            del file. Se il file non esiste, tenta di crearlo.
            In questa modalità, <function>fseek</function> non ha effetto, le scritture vengono sempre aggiunte alla fine.
           </entry>
          </row>
          <row>
           <entry><literal>'a+'</literal></entry>
           <entry>
            Apre in lettura e scrittura; posiziona il puntatore
            alla fine del file. Se il file non esiste, tenta
            di crearlo. In questa modalità <function>fseek</function> influisce solo
            sulla posizione di lettura, le scritture vengono sempre aggiunte alla fine.
           </entry>
          </row>
          <row>
           <entry><literal>'x'</literal></entry>
           <entry>
            Crea ed apre il file in sola scrittura; posiziona il puntatore
            all'inizio del file. Se il file esiste già, la chiamata
            a <function>fopen</function> fallirà restituendo &false; e
            verrà generato un errore di livello <constant>E_WARNING</constant>. Se
            il file non esiste, si tenterà di crearlo. Questo equivale
            a specificare i flag <literal>O_EXCL|O_CREAT</literal> nella
            sottostante chiamata di sistema a <literal>open(2)</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'x+'</literal></entry>
           <entry>
            Crea ed apre il file in lettura e scrittura; per il resto ha lo
            stesso comportamento di <literal>'x'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'c'</literal></entry>
           <entry>
            Apre il file in sola scrittura. Se il file non esiste, viene
            creato. Se esiste, non viene né troncato (al contrario di
            <literal>'w'</literal>), né la chiamata a questa funzione fallisce (come
            nel caso di <literal>'x'</literal>). Il puntatore del file è
            posizionato all'inizio del file. Questo può essere utile se si
            desidera ottenere un advisory lock (vedere <function>flock</function>)
            prima di tentare di modificare il file, poiché l'utilizzo di
            <literal>'w'</literal> potrebbe troncare il file prima che il lock
            venga ottenuto (se si desidera troncare,
            può essere usata <function>ftruncate</function>dopo che il lock viene
            richiesto).
           </entry>
          </row>
          <row>
           <entry><literal>'c+'</literal></entry>
           <entry>
            Apre il file in lettura e scrittura; per il resto ha lo stesso
            comportamento di <literal>'c'</literal>.
           </entry>
          </row>
          <row>
           <entry><literal>'e'</literal></entry>
           <entry>
            Imposta il flag close-on-exec sul descrittore del file aperto. Disponibile
            solo per PHP compilato su sistemi conformi a POSIX.1-2008.
           </entry>
          </row>
         </tbody>
        </tgroup>
       </table>
      </para>
      <note>
       <para>
        Differenti famiglie di file system hanno differenti convenzioni di terminatori
        di riga. Quando si scrive un file di testo e si desidera inserire una interruzione
        di linea, occorre utilizzare il terminatore appropriato per il
        sistema operativo utilizzato. I sistemi basati su Unix utilizzano <literal>\n</literal> come
        terminatore di riga, i sistemi basati su Windows utilizzano <literal>\r\n</literal>
        mentre i sistemi Macintosh (Mac OS Classic) utilizzano
        <literal>\r</literal>.
       </para>
       <para>
        Se si utilizza un errato terminatore di riga quando si scrivono i file, si
        può verificare che altre applicazioni che aprono questi file abbiano "comportamenti
        bizzarri".
       </para>
       <para>
        Windows offre un flag di traduzione della modalità testo (<literal>'t'</literal>)
        che in modo trasparente converte <literal>\n</literal>  in
        <literal>\r\n</literal> mentre si lavora sul file. In contrasto, si
        può anche usare il flag <literal>'b'</literal> per forzare una modalità binaria, nella quale non
        si ha la conversione dei dati. Per usare questi flag, <literal>'b'</literal>
        oppure <literal>'t'</literal>, devono essere posizionati
        come ultimo carattere del parametro <parameter>mode</parameter>.
       </para>
       <para>
        La modalità di conversione di default è <literal>'b'</literal>.
        Si può usare la modalità
        <literal>'t'</literal> se si lavora con dei file di testo e si utilizza 
        <literal>\n</literal> per indicare il fine linea negli script, ma
        ci si aspetta che applicazioni, tipo vecchie versioni di notepad, leggano i file prodotti. In
        tutti gli altri casi si dovrebbe utilizzare <literal>'b'</literal>.
       </para>
       <para>
        Se non si specifica il flag 'b' quando si lavora con file binari, si
        possono avere situazioni anomale nei dati, tipo immagini corrotte,
        e situazioni anomale con i caratteri <literal>\r\n</literal>.
       </para>
      </note>
      <note>
       <para>
        Per la portabilità, è fortemente raccomandato di
        riscrivere il codice che utilizza o che si avvale del mode
        <literal>'t'</literal>, così da utilizzare il corretto terminatore di linea invece del
        <literal>'b'</literal> mode.
       </para>
      </note>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>use_include_path</parameter></term>
     <listitem>
      <para>
       Il terzo parametro opzionale <parameter>use_include_path</parameter>
       può essere impostato a '1' oppure a &true; se si desidera cercare il file anche
       in <link linkend="ini.include-path">include_path</link>.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>context</parameter></term>
     <listitem>
      &note.context-support;
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Restituisce una risorsa puntatore a file in caso di successo,
   &return.falseforfailure;
  </para>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &fs.emits.warning.on.failure;
 </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.16, 7.1.2</entry>
       <entry>
        È stata aggiunta l'opzione <literal>'e'</literal>.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Esempi di <function>fopen</function></title>
    <programlisting role="php">
<![CDATA[
<?php
$handle = fopen("/home/rasmus/file.txt", "r");
$handle = fopen("/home/rasmus/file.gif", "wb");
$handle = fopen("http://www.example.com/", "r");
$handle = fopen("ftp://user:password@example.com/somefile.txt", "w");
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &warn.ssl-non-standard;
  <note>
   <para>
    Se si dovessero manifestare dei problemi nella lettura o scrittura di file e
    si sta utilizzando la versione server di PHP, occorre verificare che
    i file e le directory utilizzate dallo script siano accessibili dal processo del
    server.
   </para>
  </note>
  <note>
   <para>
    Questa funzione può anche avere successo quando <parameter>filename</parameter> è una
    directory. Se non si è sicuri che <parameter>filename</parameter> sia
    un file o una directory, potrebbe essere necessario utilizzare la funzione
    <function>is_dir</function> prima di chiamare <function>fopen</function>.
   </para>
  </note>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><xref linkend="wrappers"/></member>
    <member><function>fclose</function></member>
    <member><function>fgets</function></member>
    <member><function>fread</function></member>
    <member><function>fwrite</function></member>
    <member><function>fsockopen</function></member>
    <member><function>file</function></member>
    <member><function>file_exists</function></member>
    <member><function>is_readable</function></member>
    <member><function>stream_set_timeout</function></member>
    <member><function>popen</function></member>
    <member><function>stream_context_create</function></member>
    <member><function>umask</function></member>
    <member><classname>SplFileObject</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
-->