lchown()

A função PHP lchown() altera o proprietário do próprio link simbólico, sem seguir o link até seu destino. Esta página explica o que ela faz, como difere de chown(), a assinatura exata e o valor de retorno, quando você realmente precisa dela, e as regras de permissão que fazem com que ela tenha sucesso ou falhe.

O que é a função lchown()?

lchown() é uma função PHP embutida que define o usuário (proprietário) de um link simbólico. O prefixo "l" significa que ela opera no link, não no arquivo para o qual o link aponta — a mesma convenção usada pelas chamadas da biblioteca C subjacente (lchown vs chown).

Essa distinção só importa para links simbólicos. Um symlink é um pequeno arquivo que armazena um caminho para outro arquivo. A maioria das chamadas do sistema de arquivos desreferencia um symlink automaticamente: se você chamar chown() em um symlink, você altera o proprietário do arquivo destino. lchown() é a variante que para no link e altera a propriedade do próprio link.

lchown() é o equivalente de propriedade de usuário de lchgrp(), que altera o grupo de um symlink.

Sintaxe

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

Valor de retorno. lchown() retorna true em caso de sucesso e false em caso de falha (e emite um aviso, por exemplo, quando você não tem permissão ou o caminho não existe).

Exemplo básico

<?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';
}

Aqui o proprietário do link simbólico /path/to/link é definido como myuser. O if verifica o resultado booleano para que você possa reagir a uma falha em vez de silenciosamente ignorá-la.

lchown() vs chown(): por que isso importa

A diferença é mais fácil de ver quando um link e seu destino pertencem a proprietários diferentes. Suponha que report.txt seja um arquivo real e latest seja um symlink para ele:

<?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');

Use lchown() sempre que você quiser especificamente que os metadados do link mudem sem tocar — ou acidentalmente reatribuir a propriedade de — o arquivo para o qual ele aponta. Usar chown() aqui seria um erro se sua intenção fosse reatribuir a propriedade do próprio link.

Demonstrando do início ao fim

Este script cria um arquivo real e um symlink para ele, depois altera o proprietário do link para o usuário atual e confirma o resultado. Como alterar a propriedade normalmente requer privilégios elevados, reatribuir para o usuário atual é o único caso em que um usuário comum tem permissão para fazer.

<?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() (em vez de stat()) é usado para ler os metadados do próprio link, espelhando a forma como lchown() os escreve.

Permissões e observações importantes

• Privilégio necessário. Alterar o proprietário de um item para outro usuário geralmente requer root. Como usuário não-root, você normalmente só pode "alterar" o proprietário para você mesmo, o que é efetivamente uma operação sem efeito. Espere false mais um aviso caso contrário.
• Windows. lchown() é uma operação no estilo POSIX e não está disponível no Windows. Destina-se a sistemas de arquivos semelhantes ao Unix.
• O caminho deve ser um symlink. Apontar lchown() para um arquivo regular ainda funciona através do SO, mas o objetivo da função é symlinks — use chown() para arquivos comuns.
• Suprima, não ignore. Falhas geram um E_WARNING. Prefira verificar o valor de retorno (como acima) a silenciar o aviso com @ e torcer para o melhor.

Funções relacionadas

• chown() — altera o proprietário de um arquivo (segue symlinks).
• lchgrp() — altera o grupo de um link simbólico.
• chgrp() — altera o grupo de um arquivo.
• fileowner() — lê o ID de usuário do proprietário de um arquivo.
• symlink() — cria um link simbólico.
• readlink() — retorna o destino para o qual um symlink aponta.

Conclusão

lchown() altera o proprietário do próprio link simbólico, em vez do arquivo que ele aponta — a principal razão para usá-la em vez de chown(). Lembre-se de que ela precisa de privilégios adequados, é exclusiva para Unix e retorna um booleano que você deve sempre verificar.

Prática