Description

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

flock() permet de réaliser un système simple de verrous écriture/lecture, qui peut être utilisé sur n'importe quelle plate-forme (Unix et Windows compris).

Le verrou est également levé avec fclose(), ou quand stream est ramassé par le ramasse-miettes.

PHP dispose d'un système complet de verrouillage de fichiers. Tous les programmes qui accèdent au fichier doivent utiliser la même méthode de verrouillage pour qu'il soit efficace. Par défaut, cette fonction se bloquera tant que le verrou demandé ne sera pas acquis ; ce comportement peut être contrôlé avec l'option LOCK_NB dont se trouve la documentation ci-dessous.

Liste de paramètres

stream

Un pointeur de système de fichiers de type resource qui est habituellement créé en utilisant la fonction fopen().

operation

operation peut prendre une des valeurs suivantes :

LOCK_SH pour acquérir un verrou partagé (lecture).
LOCK_EX pour acquérir un verrou exclusif (écriture).
LOCK_UN pour libérer un verrou (partagé ou exclusif).

Il est également possible d'ajouter LOCK_NB comme masque d'une des opérations précédentes si l'on ne veut pas que la fonction flock() bloque durant le verrouillage.

would_block

Ce troisième argument optionnel est défini à 1 si le verrou doit bloquer le script (condition d'erreur EWOULDBLOCK).

Valeurs de retour

Cette fonction retourne true en cas de succès ou false si une erreur survient.

Exemples

Exemple #1 Exemple avec flock()

<?php

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

if (flock($fp, LOCK_EX)) { // acquiert un verrou exclusif
    ftruncate($fp, 0);     // effacement du contenu
    fwrite($fp, "Écrire dans un fichier\n");
    fflush($fp);            // libère le contenu avant d'enlever le verrou
    flock($fp, LOCK_UN);    // Enlève le verrou
} else {
    echo "Impossible de verrouiller le fichier !";
}

fclose($fp);

?>

Exemple #2 Exemple avec flock() en utilisant l'option LOCK_NB

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

/* Activation de l'option LOCK_NB lors d'une opération LOCK_EX */
if(!flock($fp, LOCK_EX | LOCK_NB)) {
    echo 'Impossible d\'obtenir le verrou';
    exit(-1);
}

/* ... */

fclose($fp);
?>

Notes

Note:
flock() utilise les verrous obligatoires sous Windows, qui sont aussi supportés sur Linux et les systèmes dérivés de System V au moyen de l'appel système fcntl(): si le fichier en question a le bit setgid positionné et le bit de groupe vide. Sur Linux, le système de fichiers devra être monté avec l'option mand pour que cela fonctionne.

Note:
Comme flock() requiert un pointeur de fichier, il est possible d'avoir à utiliser un verrou spécial pour protéger l'accès au fichier que l'on veut tronquer en l'ouvrant en mode d'écriture (avec "w" ou "w+" comme argument de fopen()).

Note:
Ne devrait être utilisé que sur des ressources issues de fopen() pour des fichiers locaux ou via le gestionnaire de flux personnalisé en définissant streamWrapper::stream_lock().

Avertissement

Assigner une autre valeur à l'argument stream dans ce code libérera le verrou.

Avertissement

Sur certains systèmes d'exploitation, flock() est implémenté au niveau processus. Lors de l'utilisation d'une API multithread, il y a un risque de ne pas pouvoir avoir confiance en flock() pour protéger les fichiers contre d'autres scripts PHP qui fonctionnent en parallèle sur d'autres threads du même serveur.

flock() n'est pas supporté sur les vieux systèmes de fichiers comme FAT et ses dérivés, et retourne forcément false sous ces environnements.

Note:
Sur Windows, si la procédure de verrou ouvre un fichier une deuxième fois, il ne peut pas accéder au fichier à travers ce gestionnaire jusqu'à ce que le fichier soit déverrouillé.