ftell()

Cos'è la funzione ftell()?

La funzione ftell() è una funzione PHP integrata che restituisce la posizione corrente del puntatore del file — l'offset in byte, contato dall'inizio del file, dove avverrà la prossima lettura o scrittura. Ogni handle di file aperto mantiene un cursore interno; fread(), fwrite() e fgets() lo avanzano, mentre fseek() e rewind() lo spostano esplicitamente. ftell() si limita a riportare la posizione attuale del cursore senza modificarla.

Conoscere l'offset è utile quando si vuole registrare la posizione nel file (per riprenderla in seguito con fseek()), misurare quanti byte sono stati consumati finora, oppure rilevare la fine di un record in un file a larghezza fissa o binario.

Questa pagina illustra la sintassi, un esempio eseguibile, il valore restituito da ftell(), gli errori comuni (modalità append, stream) e il suo rapporto con le altre funzioni per il puntatore del file.

Sintassi

ftell(resource $stream): int|false

$stream deve essere un puntatore al file restituito da fopen() (o da una funzione come fsockopen()). La funzione restituisce la posizione come offset intero in byte, oppure false in caso di errore — ad esempio se lo stream non è seekable. Poiché 0 (l'inizio del file) è un risultato valido ma "falsy", verificare sempre il valore restituito con ===:

$pos = ftell($file);
if ($pos === false) {
    // could not determine the position
}

Come usare la funzione ftell()

Il flusso tipico è il seguente:

1. Aprire il file con fopen() nella modalità desiderata.
2. Leggere da o scrivere nel file in modo che il puntatore si sposti.
3. Chiamare ftell() con il puntatore al file per leggerne la posizione.
4. Utilizzare quell'offset — ad esempio, memorizzarlo o passarlo a fseek().
5. Chiudere il file con fclose().

L'esempio seguente è completamente autonomo: scrive prima un file temporaneo, quindi è possibile eseguirlo così com'è senza preparare alcun dato.

<?php

// Create a temporary file with known contents.
$filename = tempnam(sys_get_temp_dir(), 'demo');
file_put_contents($filename, 'Hello, World! This is a test.');

$file = fopen($filename, 'r');

echo "Start position: " . ftell($file) . "\n";   // 0

fread($file, 5);                                  // read "Hello"
echo "After reading 5 bytes: " . ftell($file) . "\n";  // 5

fread($file, 5);                                  // read ", Wor"
echo "After reading 5 more: " . ftell($file) . "\n";   // 10

rewind($file);                                    // jump back to the start
echo "After rewind: " . ftell($file) . "\n";      // 0

fseek($file, 7);                                  // jump to byte 7
echo "After fseek to 7: " . ftell($file) . "\n";  // 7
echo "Next 5 bytes: " . fread($file, 5) . "\n";   // "World"

fclose($file);
unlink($filename);

Output:

Start position: 0
After reading 5 bytes: 5
After reading 5 more: 10
After rewind: 0
After fseek to 7: 7
Next 5 bytes: World

Ogni fread() avanza il puntatore del numero di byte effettivamente letti, quindi ftell() cresce da 0 a 5 fino a 10. rewind() lo riporta a 0, e fseek($file, 7) lo sposta direttamente al byte 7, dove inizia la parola World.

Modalità Append: un errore comune

Quando un file viene aperto in modalità append ('a' o 'a+'), ogni scrittura avviene alla fine del file indipendentemente dalla posizione del puntatore. ftell() può restituire 0 subito dopo l'apertura anche se le scritture finiscono in fondo — il suo valore restituito non descrive in modo affidabile dove andrà la prossima scrittura in modalità append. Se si necessita di posizioni precise, aprire il file con 'r+', 'w+' o 'c+' e spostare il puntatore esplicitamente.

Analogamente, gli stream non seekable (come alcuni stream di rete o pipe) non possono riportare una posizione significativa e ftell() restituisce false per essi.

Funzioni correlate

ftell() raramente lavora da sola. Fa parte di una piccola famiglia di funzioni per il puntatore del file:

• fopen() — apre un file e restituisce il puntatore che ftell() legge.
• fread() — legge i byte e avanza il puntatore.
• fwrite() — scrive i byte e avanza il puntatore.
• fseek() — sposta il puntatore a una posizione assoluta o relativa; usarla insieme a ftell() per salvare e ripristinare gli offset.
• rewind() — riporta il puntatore all'inizio (equivalente a fseek($file, 0)).
• fclose() — chiude il file al termine delle operazioni.

Per una panoramica più ampia, vedere PHP File Handling.

Conclusione

La funzione ftell() riporta l'offset in byte corrente di un puntatore al file senza spostarlo, rendendola il compagno naturale di fseek() e rewind() per navigare nei file. Ricordare di confrontare il risultato con === false (poiché 0 è un offset valido) e tenere presente che la modalità append e gli stream non seekable non restituiscono posizioni affidabili.

Esercitazione