fseek()

Cuando PHP lee o escribe un archivo, mantiene un cursor interno — el indicador de posición del archivo — que marca dónde ocurrirá la siguiente lectura o escritura. Normalmente ese cursor avanza automáticamente a medida que llamas a fread() o fwrite(). La función fseek() te permite moverlo manualmente a cualquier posición en bytes, para que puedas retroceder, avanzar o volver a leer parte de un archivo sin cerrarlo y volver a abrirlo.

Este capítulo cubre la sintaxis de fseek(), los tres modos de whence, su valor de retorno y patrones prácticos como leer un registro en un desplazamiento conocido y buscar más allá del final de un archivo.

Sintaxis

fseek(resource $stream, int $offset, int $whence = SEEK_SET): int

fseek() devuelve 0 en caso de éxito y -1 en caso de fallo. No devuelve la nueva posición — usa ftell() para eso.

Los tres modos de whence

La constante $whence decide desde dónde se cuenta el desplazamiento:

<?php
fseek($file, 10);            // 10 bytes from the start (SEEK_SET is implied)
fseek($file, 5, SEEK_CUR);   // 5 bytes forward from where we are now
fseek($file, -4, SEEK_END);  // 4 bytes before the end of the file

Un ejemplo funcional

Vamos a crear un archivo, luego saltar al byte 6 y leer desde ahí. Como escribimos y leemos en el mismo script, el ejemplo es completamente autocontenido:

<?php

$filename = 'demo.txt';

// Create a file with known contents.
file_put_contents($filename, 'Hello, World!');

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

fseek($file, 7, SEEK_SET);   // move the cursor to byte 7
$data = fread($file, 5);     // read 5 bytes: W, o, r, l, d
echo $data;                  // World

fclose($file);

La cadena 'Hello, World!' se almacena como bytes H(0) e(1) l(2) l(3) o(4) ,(5) (6) W(7) o(8) r(9) l(10) d(11) !(12). Buscar el byte 7 apunta a la W, y leer 5 bytes imprime World.

Siempre verifica el valor de retorno

Dado que fseek() devuelve 0 en caso de éxito y -1 en caso de fallo, compáralo explícitamente. Una comprobación de veracidad débil es incorrecta aquí — 0 es falsy:

<?php

$file = fopen('demo.txt', 'r');

if (fseek($file, 7) === -1) {
    echo "Seek failed";
} else {
    echo "Seek succeeded";   // Seek succeeded
}

fclose($file);

Cosas a tener en cuenta

• No todos los streams son buscables. Las tuberías, los sockets de red y el stream php://stdin no pueden ser buscados; fseek() devuelve -1 en ellos.
• Buscar más allá del final está permitido. Con un archivo abierto para escritura, puedes usar fseek() más allá del final actual y luego escribir — el hueco se rellena con bytes \0 (null), creando una región dispersa.
• Usa SEEK_CUR con precaución en modo append. Los archivos abiertos con el modo 'a' siempre escriben al final independientemente del cursor; fseek() solo afecta las lecturas en ese modo.
• fseek() limpia el indicador de fin de archivo, por lo que retroceder con seek te permite leer datos que ya pasaste sin reabrir el archivo.

Funciones relacionadas

• ftell() — reporta la posición actual del cursor (el complemento de fseek()).
• rewind() — atajo para fseek($file, 0).
• fread() / fwrite() — lee o escribe comenzando desde el cursor.
• fopen() / fclose() — abre y cierra el stream.

Consulta el capítulo Manejo de Archivos PHP para tener una visión más amplia.

Conclusión

fseek() te da acceso aleatorio a un archivo: mueve el cursor con un $offset medido desde SEEK_SET, SEEK_CUR o SEEK_END, luego lee o escribe desde el nuevo punto. Recuerda verificar el valor de retorno -1, combínalo con ftell() para saber dónde estás, y ten en cuenta que no todos los streams admiten la búsqueda.

Práctica