lchown()

La fonction PHP lchown() modifie le propriétaire du lien symbolique lui-même, sans suivre le lien vers sa cible. Cette page explique son fonctionnement, ses différences avec chown(), sa signature exacte et sa valeur de retour, les cas où vous en avez vraiment besoin, ainsi que les règles de permissions qui déterminent son succès ou son échec.

Qu'est-ce que la fonction lchown() ?

lchown() est une fonction PHP intégrée qui définit l'utilisateur (propriétaire) d'un lien symbolique. Le préfixe « l » signifie qu'elle opère sur le lien lui-même, et non sur le fichier vers lequel le lien pointe — la même convention utilisée par les appels de la bibliothèque C sous-jacente (lchown contre chown).

Cette distinction n'a d'importance que pour les liens symboliques. Un lien symbolique est un petit fichier qui stocke un chemin vers un autre fichier. La plupart des appels système de fichiers déréférencent automatiquement un lien symbolique : si vous appelez chown() sur un lien symbolique, vous modifiez le propriétaire du fichier cible. lchown() est la variante qui s'arrête au lien et modifie la propriété du lien lui-même.

lchown() est le pendant de propriété utilisateur de lchgrp(), qui modifie le groupe d'un lien symbolique.

Syntaxe

lchown(string $filename, string|int $user): bool

Valeur de retour. lchown() renvoie true en cas de succès et false en cas d'échec (et émet un avertissement, par exemple si vous ne disposez pas des permissions requises ou si le chemin n'existe pas).

Exemple de base

<?php

$link = '/path/to/link';
$user = 'myuser';

if (lchown($link, $user)) {
    echo 'Ownership of symbolic link updated successfully';
} else {
    echo 'Failed to update ownership of symbolic link';
}

Ici, le propriétaire du lien symbolique /path/to/link est défini sur myuser. Le if vérifie le résultat booléen afin que vous puissiez réagir à un échec plutôt que de l'ignorer silencieusement.

lchown() vs chown() : pourquoi cela compte

La différence est plus facile à percevoir lorsqu'un lien et sa cible appartiennent à des propriétaires différents. Supposons que report.txt soit un vrai fichier et que latest soit un lien symbolique vers ce fichier :

<?php

$target = '/var/data/report.txt';
$link   = '/var/data/latest';      // symlink -> report.txt

// Changes the OWNER OF report.txt (chown follows the link):
chown($link, 'alice');

// Changes the OWNER OF the symlink "latest" only; report.txt is untouched:
lchown($link, 'bob');

Utilisez lchown() chaque fois que vous souhaitez spécifiquement modifier les métadonnées du lien sans toucher — ni re-attribuer accidentellement — le fichier vers lequel il pointe. Utiliser chown() ici serait un bug si votre intention était de re-attribuer le lien lui-même.

Démonstration complète

Ce script crée un vrai fichier et un lien symbolique vers ce fichier, puis modifie le propriétaire du lien pour l'attribuer à l'utilisateur courant et confirme le résultat. Étant donné que le changement de propriété nécessite normalement des privilèges élevés, se ré-attribuer le lien à soi-même est le seul cas où un utilisateur ordinaire est autorisé à le faire.

<?php

$target = sys_get_temp_dir() . '/lchown_target.txt';
$link   = sys_get_temp_dir() . '/lchown_link';

file_put_contents($target, "hello\n");
@unlink($link);            // remove any leftover link from a previous run
symlink($target, $link);   // create the symbolic link

$me = posix_getpwuid(posix_geteuid())['name']; // current process user

if (lchown($link, $me)) {
    echo "Link owner set to: " . posix_getpwuid(lstat($link)['uid'])['name'] . "\n";
} else {
    echo "lchown() failed\n";
}

lstat() (plutôt que stat()) est utilisé pour lire les métadonnées propres au lien, en miroir de la façon dont lchown() les écrit.

Permissions et points d'attention

• Privilèges requis. Modifier le propriétaire d'un élément pour le confier à un autre utilisateur nécessite généralement les droits root. En tant qu'utilisateur non-root, vous pouvez généralement seulement « modifier » le propriétaire pour vous-même, ce qui est en pratique une non-opération. Attendez-vous à un retour false accompagné d'un avertissement dans les autres cas.
• Windows. lchown() est une opération de style POSIX et n'est pas disponible sous Windows. Elle est destinée aux systèmes de fichiers de type Unix.
• Le chemin doit être un lien symbolique. Pointer lchown() vers un fichier ordinaire fonctionne toujours au niveau du système d'exploitation, mais l'intérêt de la fonction concerne les liens symboliques — utilisez chown() pour les fichiers ordinaires.
• Vérifiez, ne supprimez pas. Les échecs génèrent un E_WARNING. Préférez vérifier la valeur de retour (comme ci-dessus) plutôt que de faire taire l'avertissement avec @ en espérant que tout se passe bien.

Fonctions associées

• chown() — modifier le propriétaire d'un fichier (suit les liens symboliques).
• lchgrp() — modifier le groupe d'un lien symbolique.
• chgrp() — modifier le groupe d'un fichier.
• fileowner() — lire l'identifiant utilisateur du propriétaire d'un fichier.
• symlink() — créer un lien symbolique.
• readlink() — retourner la cible vers laquelle pointe un lien symbolique.

Conclusion

lchown() modifie le propriétaire d'un lien symbolique lui-même plutôt que le fichier qu'il cible — c'est la raison principale de l'utiliser à la place de chown(). N'oubliez pas qu'elle nécessite des privilèges appropriés, qu'elle est réservée aux systèmes Unix, et qu'elle renvoie un booléen que vous devez toujours vérifier.

Pratique