From b327996a46e30da1c71b101115fb586fc51d053e Mon Sep 17 00:00:00 2001
From: Davide Pastore <pasdavide@gmail.com>
Date: Fri, 7 Feb 2025 17:44:58 +0000
Subject: [PATCH] Update fwrite.xml

---
 reference/filesystem/functions/fwrite.xml | 269 ++++++++++++++++------
 1 file changed, 195 insertions(+), 74 deletions(-)

diff --git a/reference/filesystem/functions/fwrite.xml b/reference/filesystem/functions/fwrite.xml
index d8bdb5eb9..ebfdb16e9 100644
--- a/reference/filesystem/functions/fwrite.xml
+++ b/reference/filesystem/functions/fwrite.xml
@@ -1,94 +1,215 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!-- splitted from ./it/functions/filesystem.xml, last change in rev 1.15 -->
-<!-- EN-Revision: n/a Maintainer: fernando Status: working -->
-<!-- CREDITS: cortesi -->  
-<refentry xml:id="function.fwrite" xmlns="http://docbook.org/ns/docbook">
-   <refnamediv>
-    <refname>fwrite</refname>
-    <refpurpose>Scrive un file salvaguardando la corrispondenza binaria</refpurpose>
-   </refnamediv>
-   <refsect1>
-    <title>Descrizione</title>
-     <methodsynopsis>
-      <type>int</type><methodname>fwrite</methodname>
-      <methodparam><type>resource</type><parameter>handle</parameter></methodparam>
-      <methodparam><type>string</type><parameter>string</parameter></methodparam>
-      <methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
-     </methodsynopsis>
-    <simpara>
-     <function>fwrite</function> scrive il contenuto di
-     <parameter>string</parameter> nel flusso del file puntato da
-     <parameter>handle</parameter>. Se l'argomento <parameter>length</parameter>
-     è specificato la scrittura si arresterà dopo aver scritto
-     <parameter>length</parameter> byte o alla fine di 
-     <parameter>string</parameter> se si verificasse 
-     prima.
-    </simpara>
-    <simpara>
-     <function>fwrite</function> returns the number of bytes
-     written, or &false; on error.
-    </simpara>
-    <simpara>
-     Nota che se il parametro <parameter>length</parameter> viene specificato,
-     allora l'opzione di configurazione <link
-     linkend="ini.magic-quotes-runtime">magic_quotes_runtime</link>
-     verrà ignorata e nessuno slash verrà 
-     skippato da <parameter>string</parameter>.
-    </simpara>
-    <note>
-     <para>
-      Su sistemi che differenzino fra file binari e di testo 
-      (come Windows) il file deve essere aperto includendo 'b' nel paramentro mode di
-      <function>fopen</function>.
-     </para>
-    </note>
-    <para>
-     <example>
-      <title>Un semplice esempio di fwrite</title>
-      <programlisting role="php">
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: bb6247b68128cab1b166b49a3a73a87f40333267 Maintainer: pastore Status: working -->
+<!-- CREDITS: cortesi,fernando -->
+<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.fwrite">
+ <refnamediv>
+  <refname>fwrite</refname>
+  <refpurpose>Scrittura su file binary-safe</refpurpose>
+ </refnamediv>
+ 
+ <refsect1 role="description">
+  &reftitle.description;
+  <methodsynopsis>
+   <type class="union"><type>int</type><type>false</type></type><methodname>fwrite</methodname>
+   <methodparam><type>resource</type><parameter>stream</parameter></methodparam>
+   <methodparam><type>string</type><parameter>data</parameter></methodparam>
+   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
+  </methodsynopsis>
+  <simpara>
+   <function>fwrite</function> scrive il contenuto di
+   <parameter>data</parameter> nello stream del file puntato da
+   <parameter>stream</parameter>.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>stream</parameter></term>
+     <listitem>
+      &fs.file.pointer;
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>data</parameter></term>
+     <listitem>
+      <para>
+       La stringa che deve essere scritta.
+      </para>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>length</parameter></term>
+     <listitem>
+      <para>
+       Se l'argomento <parameter>length</parameter> è un &integer;, la scrittura si arresterà
+       dopo aver scritto <parameter>length</parameter> byte o alla
+       fine di <parameter>data</parameter> a seconda di quale dei due eventi si verifica prima.
+      </para>
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   <function>fwrite</function> restituisce il numero di byte
+   scritti, &return.falseforfailure;.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <para>
+   <function>fwrite</function> genera un <constant>E_WARNING</constant> in caso di errore.
+  </para>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.0.0</entry>
+      <entry>
+       Ora <parameter>length</parameter> è nullable.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <para>
+   <example>
+    <title>Un esempio semplice di <function>fwrite</function></title>
+    <programlisting role="php">
 <![CDATA[
 <?php
 $filename = 'test.txt';
-$somecontent = "Aggiunge questa riga al file\n";
+$somecontent = "Aggiungi questo al file\n";
 
-// Verifica che il file esista e sia riscrivibile
+// Assicuriamoci prima che il file esista e sia scrivibile.
 if (is_writable($filename)) {
 
-    // In questo esempio apriamo $filename in append mode.
-    // Il puntatore del file è posizionato in fondo al file
-    // è qui che verrà posizionato $somecontent quando eseguiremo fwrite().
-    if (!$handle = fopen($filename, 'a')) {
-         echo "Non si riesce ad aprire il file ($filename)";
+    // Nel nostro esempio stiamo aprendo $filename in modalità append.
+    // Il puntatore del file si trova in fondo al file, quindi
+    // è lì che $somecontent verrà scritto quando lo scriviamo con fwrite().
+    if (!$fp = fopen($filename, 'a')) {
+         echo "Impossibile aprire il file ($filename)";
          exit;
     }
 
-    // Scrive $somecontent nel file aperto.
-    if (fwrite($handle, $somecontent) === FALSE) {
-        echo "Non si riesce a scrivere nel file ($filename)";
+    // Scriviamo $somecontent nel nostro file aperto.
+    if (fwrite($fp, $somecontent) === FALSE) {
+        echo "Impossibile scrivere nel file ($filename)";
         exit;
     }
 
-    echo "Riuscito, scritto ($somecontent) nel file ($filename)";
+    echo "Successo, scritto ($somecontent) nel file ($filename)";
 
-    fclose($handle);
+    fclose($fp);
 
 } else {
-    echo "Il file $filename non è accessibile";
+    echo "Il file $filename non è scrivibile";
+}
+?>
+]]>
+    </programlisting>
+   </example>
+  </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <para>
+    Scrivere su uno stream di rete potrebbe terminare prima che l'intera stringa sia scritta.
+    Il valore restituito da <function>fwrite</function> potrebbe essere verificato:
+    <programlisting role="php">
+     <![CDATA[
+<?php
+function fwrite_stream($fp, $string) {
+    for ($written = 0; $written < strlen($string); $written += $fwrite) {
+        $fwrite = fwrite($fp, substr($string, $written));
+        if ($fwrite === false) {
+            return $written;
+        }
+    }
+    return $written;
 }
 ?>
 ]]>
-      </programlisting>
-     </example>
-    </para>
-    <simpara>
-     Vedere anche <function>fread</function>, 
-     <function>fopen</function>,
-     <function>fsockopen</function>, 
-     <function>popen</function> e
-     <function>file_put_contents</function>.
-    </simpara>
-   </refsect1>
-  </refentry>
+    </programlisting>
+   </para>
+  </note>
+
+  <note>
+   <para>
+    Su sistemi che differenziano tra file binari e di testo
+    (ad esempio Windows), il file deve essere aperto con 'b' incluso nel
+    parametro di modalità di <function>fopen</function>.
+   </para>
+  </note>
+  <note>
+   <para>
+    Se <parameter>stream</parameter> è stato aperto in modalità append tramite <function>fopen</function>,
+    le scritture con <function>fwrite</function> sono atomiche (a meno che la dimensione di
+    <parameter>data</parameter> non superi la dimensione del blocco del filesystem, su alcune
+    piattaforme, e purché il file sia su un filesystem locale). Cioè,
+    non c'è bisogno di usare <function>flock</function> prima di chiamare
+    <function>fwrite</function>; tutti i dati saranno scritti senza
+    interruzione.
+   </para>
+  </note>
+  <note>
+   <para>
+    Se si scrive due volte sul puntatore del file, i dati verranno aggiunti
+    alla fine del contenuto del file:
+    <programlisting role="php">
+     <![CDATA[
+<?php
+$fp = fopen('data.txt', 'w');
+fwrite($fp, '1');
+fwrite($fp, '23');
+fclose($fp);
+
+// il contenuto di 'data.txt' è ora 123 e non 23!
+?>
+]]>
+    </programlisting>
+   </para>
+  </note>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>fread</function></member>
+    <member><function>fopen</function></member>
+    <member><function>fsockopen</function></member>
+    <member><function>popen</function></member>
+    <member><function>file_get_contents</function></member>
+    <member><function>pack</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
+
+</refentry>
 
 <!-- Keep this comment at the end of the file
 Local variables:
@@ -109,4 +230,4 @@ End:
 vim600: syn=xml fen fdm=syntax fdl=2 si
 vim: et tw=78 syn=sgml
 vi: ts=1 sw=1
--->
+-->
\ No newline at end of file