Descripción

flock(resource $stream, int $operation, int &$would_block = null): bool

flock() permite realizar un sistema simple de bloqueos de escritura/lectura, que puede ser utilizado en cualquier plataforma (incluyendo Unix y Windows).

El bloqueo también se libera con fclose(), o cuando stream es recogido por el recolector de basura.

PHP dispone de un sistema completo de bloqueo de ficheros. Todos los programas que accedan al fichero deben utilizar la misma metodología de bloqueo para que sea efectivo. Por omisión, esta función se bloqueará hasta que el bloqueo solicitado sea adquirido; este comportamiento puede ser controlado con la opción LOCK_NB cuya documentación se encuentra a continuación.

Parámetros

stream

Un puntero del sistema de archivos de tipo resource que es habitualmente creado utilizando la función fopen().

operation

operation puede tomar uno de los siguientes valores:

LOCK_SH para adquirir un bloqueo compartido (lectura).
LOCK_EX para adquirir un bloqueo exclusivo (escritura).
LOCK_UN para liberar un bloqueo (compartido o exclusivo).

Asimismo, es posible añadir LOCK_NB como máscara de una de las operaciones anteriores si no se desea que la función flock() se bloquee durante el bloqueo.

would_block

Este tercer argumento opcional se establece a 1 si el bloqueo debe bloquear el script (condición de error EWOULDBLOCK).

Valores devueltos

Esta función retorna true en caso de éxito o false si ocurre un error.

Ejemplos

Ejemplo #1 Ejemplo con flock()

<?php

$fp = fopen("/tmp/lock.txt", "r+");

if (flock($fp, LOCK_EX)) { // adquiere un bloqueo exclusivo
    ftruncate($fp, 0);     // borrado del contenido
    fwrite($fp, "Escribir en un fichero\n");
    fflush($fp);            // libera el contenido antes de quitar el bloqueo
    flock($fp, LOCK_UN);    // Quita el bloqueo
} else {
    echo "¡Imposible bloquear el fichero!";
}

fclose($fp);

?>

Ejemplo #2 Ejemplo con flock() utilizando la opción LOCK_NB

<?php
$fp = fopen('/tmp/lock.txt', 'r+');

/* Activación de la opción LOCK_NB durante una operación LOCK_EX */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
    echo 'Imposible obtener el bloqueo';
    exit(-1);
}

/* ... */

fclose($fp);
?>

Notas

Nota:
flock() utiliza bloqueos obligatorios bajo Windows, que también son soportados en Linux y sistemas derivados de System V mediante la llamada al sistema fcntl(): si el fichero en cuestión tiene el bit setgid activado y el bit de grupo vacío. En Linux, el sistema de ficheros deberá ser montado con la opción mand para que esto funcione.

Nota:
Al requerir un puntero de fichero, flock() puede ser necesario utilizar un bloqueo especial para proteger el acceso al fichero que se desea truncar al abrirlo en modo escritura (con "w" o "w+" como argumento de fopen()).

Nota:
Debería ser utilizado únicamente en recursos provenientes de fopen() para ficheros locales o mediante el gestor de flujos personalizado definiendo streamWrapper::stream_lock().

Advertencia

Asignar otro valor al argumento stream en este código liberará el bloqueo.

Advertencia

En ciertos sistemas operativos, flock() está implementado a nivel de proceso. Al utilizar una API multihilo, puede que no se pueda confiar en flock() para proteger ficheros contra otros scripts PHP que funcionen en paralelo en otros hilos del mismo servidor.

flock() no es soportado en sistemas de ficheros antiguos como FAT y sus derivados, y siempre devolverá false en estos entornos.

Nota:
En Windows, si el procedimiento de bloqueo abre un fichero por segunda vez, no puede acceder al fichero a través de este gestor hasta que el fichero sea desbloqueado.