Linux / Comando realpath: normalizar caminhos, links e saídas relativas

realpath normaliza um caminho e, no modo físico padrão do GNU, resolve links simbólicos para produzir uma localização absoluta. Ele processa caminhos relativos, ., .. e barras redundantes. Use -e para exigir que o destino exista, -m para permitir componentes ausentes e as opções de saída relativa quando precisar de um caminho em relação a outra pasta.

Os exemplos usam GNU Coreutils em Bash; confirme a implementação com realpath --version e as opções com realpath --help. A opção -E, com a forma longa --canonicalize, foi adicionada no GNU Coreutils 9.8, conforme o registro oficial de alterações do Coreutils. Versões anteriores podem oferecer o mesmo comportamento padrão sem aceitar a opção explícita. Resolver um caminho não equivale a abrir o arquivo nem a autorizar acesso a ele.

O que é o comando realpath?

realpath gera o nome de arquivo ou caminho de diretório normalizado. O resultado típico é um caminho absoluto, e componentes desnecessários /, ., .. e links simbólicos são tratados.

realpath ./docs/../images/logo.webp

Se a pasta atual for /home/user/project, docs e images existirem e não houver links que mudem a resolução, uma saída ilustrativa é:

/home/user/project/images/logo.webp

O resultado depende da pasta de trabalho e dos componentes realmente encontrados. No GNU, por padrão, todos os componentes anteriores ao último precisam ser diretórios existentes e acessíveis. O último nome pode ainda não existir. Se faltar uma pasta intermediária, a consulta pode falhar em vez de imprimir o caminho ilustrado.

Sintaxe e uso básico

realpath [opções] arquivo ...

A sinopse usa colchetes para partes opcionais e reticências para repetição; não os copie literalmente. GNU realpath aceita vários argumentos e escreve um resultado por linha. Nas três consultas independentes abaixo, ../logs e os diretórios de /var/log/nginx precisam existir para o comportamento padrão. Adapte os caminhos a pastas de teste acessíveis.

realpath .
realpath ../logs/app.log
realpath /var//log/./nginx/../syslog

Para consultar somente a posição física atual, o comando pwd -P é direto. realpath também aceita outros caminhos. O formato POSIX (Portable Operating System Interface) padronizado é realpath [-E|-e] arquivo, com um único arquivo e existência padrão não especificada; consulte a especificação POSIX de realpath ao precisar de portabilidade.

Escolher a condição de existência

Escolha a condição de existência conforme a próxima operação. Nas implementações que aceitam -E, indicar -e ou -E deixa a intenção explícita em vez de depender de um padrão que pode variar entre sistemas.

Exigir um caminho existente com -e

realpath -e /etc/passwd
realpath --canonicalize-existing /srv/app/config.yml

Cada linha é uma consulta independente e exige o caminho correspondente existente. Um erro de resolução produz retorno diferente de zero; não use a saída como válida sem verificar esse retorno. -e também pode aceitar diretórios: ele não certifica o formato de um arquivo de configuração nem mantém o objeto imutável após a consulta.

Permitir o último nome ausente com -E

realpath -E /srv/uploads/new-file.txt

Neste exemplo, /srv/uploads precisa ser um diretório existente; apenas new-file.txt pode estar ausente. O comando exige uma implementação que ofereça -E, como GNU Coreutils 9.8 ou posterior. Se a opção não aparecer na ajuda da versão instalada, não suponha que ela será aceita; consulte a documentação dessa versão. Um resultado calculado não garante permissão para criar o arquivo.

Permitir componentes ausentes com -m

realpath -m /srv/not-created/../future/file.txt

Com -m, o resultado pode ser /srv/future/file.txt mesmo que essas pastas não existam. Isso não cria diretórios nem garante que seja possível gravar ali. -m sozinho ainda resolve links simbólicos existentes; para um cálculo puramente textual que não siga links, combine-o com -s.

Links simbólicos e -L, -P, -s

Um link simbólico aponta para outro caminho. Com .., resolver primeiro o link ou retirar primeiro um componente do texto pode produzir locais diferentes. Em realpath, tanto -L como -P resolvem links: -L não preserva seus nomes como pode ocorrer com pwd -L.

Consultar a resolução física

realpath -P /srv/current/../shared

Considere uma estrutura já preparada: /srv/current aponta para /srv/releases/2026-09, e existem /srv/releases/shared e /srv/shared, sem outros links. A consulta física acima resolve o destino antes de .. e resulta em /srv/releases/shared. Com realpath -L /srv/current/../shared, a redução lógica do texto resulta em /srv/shared. Não altere links de uma implantação real apenas para experimentar.

Normalizar texto sem seguir links

realpath -s -m /srv/current/../shared

A combinação -s -m calcula /srv/shared pelo texto, sem seguir o link current nem exigir que as pastas existam. Esse resultado não descreve necessariamente a localização física que o kernel usaria para abrir o caminho original. -s sem -m ainda obedece à condição de existência selecionada.

Produzir caminhos relativos

Definir a base com --relative-to

--relative-to muda a apresentação para um caminho relativo à pasta indicada. Para o resultado abaixo, suponha que /srv/www/assets/css exista e não haja links que levem a outra árvore. Um destino fora da base também pode produzir componentes ..; esta opção não limita o acesso à base.

realpath --relative-to=/srv/www /srv/www/assets/css/site.css

A saída é a seguinte.

assets/css/site.css

Relativizar seletivamente com --relative-base

--relative-base produz um nome relativo quando o resultado está na própria pasta-base ou em seus descendentes; fora dela, mantém o nome absoluto. Considere as pastas intermediárias existentes e sem links que alterem estes destinos:

realpath --relative-base=/srv/www /srv/www/index.html /var/log/syslog

As saídas esperadas são index.html e /var/log/syslog, nessa ordem. Para o próprio diretório-base, a forma relativa é .. As opções de existência, como -e ou -m, também se aplicam a essas consultas.

Diferenças entre readlink -f e realpath

Usar em scripts Bash

Consultar o caminho de um arquivo de configuração

Salve o script completo como show-config-path.sh e execute bash show-config-path.sh "./config.yml", usando um arquivo regular de teste que já exista. Ele requer Bash e GNU realpath com -e. A quantidade incorreta de argumentos retorna 2; falha de resolução ou objeto que não seja arquivo regular retorna 1.

#!/usr/bin/env bash
if [ "$#" -ne 1 ]; then
  printf '%s\n' 'Uso: bash show-config-path.sh ARQUIVO' >&2
  exit 2
fi
config=$(realpath -e -- "$1") || {
  printf '%s\n' 'Não foi possível resolver o caminho do arquivo.' >&2
  exit 1
}
if [ ! -f "$config" ]; then
  printf '%s\n' 'O caminho não representa um arquivo regular.' >&2
  exit 1
fi
printf 'Arquivo de configuração: %s\n' "$config"

A mensagem mostra o caminho absoluto do arquivo de teste. O script não lê nem valida o conteúdo ou o formato do arquivo, não testa todas as permissões de uso e não abre o arquivo de forma protegida contra mudanças simultâneas. A substituição de comando também remove quebras de linha finais; para preservar nomes Unix incomuns, use uma saída delimitada por NUL com um consumidor apropriado.

Separar vários resultados com NUL

A extensão GNU -z, ou --zero, termina cada resultado com um byte nulo, NUL. Substitua os dois nomes abaixo por caminhos de teste cujos diretórios anteriores ao último componente sejam acessíveis. O nome com espaços é um único argumento graças às aspas:

realpath -z -- file1 "file with space"

O programa consumidor precisa aceitar registros NUL, inclusive quando os nomes contêm quebras de linha. Não use $(...) para guardar esse fluxo em uma variável Bash, pois ela não preserva bytes NUL. Um retorno diferente de zero continua indicando falha mesmo quando houver alguma saída referente aos outros argumentos.

Limites da normalização na validação de caminhos

Distinguir normalização e autorização

Um caminho normalizado não concede autorização de leitura ou gravação. Proprietário, permissões, listas de controle de acesso (ACLs) e políticas de segurança continuam relevantes. O comando stat ajuda a consultar metadados, mas também não transforma uma consulta em uma abertura segura do arquivo.

Evitar a separação entre conferir e abrir

Existe uma condição de corrida se links ou pastas puderem mudar entre a consulta e a abertura do arquivo. Em programas Linux que precisam restringir caminhos de terceiros, a documentação de openat2 descreve restrições de resolução, como RESOLVE_BENEATH, aplicadas durante a abertura em relação a um descritor de diretório. A escolha exige considerar o kernel e as regras da aplicação; não é uma garantia obtida com uma comparação posterior de strings no shell.

Considerar limites de componentes, não apenas prefixos

/srv/www-safe também começa com /srv/www na string. Ao verificar a inclusão de um caminho base, considere os limites do diretório, pois a normalização de caminho sozinha não cria um ambiente protegido.

Opções principais

A referência de comandos Linux por tarefa reúne outras ferramentas para consultar caminhos e arquivos.

Perguntas frequentes

É possível usar realpath em arquivos que não existem?

No padrão GNU, o último componente pode estar ausente se o prefixo resolver para um diretório existente. GNU Coreutils 9.8 ou posterior também permite pedir isso explicitamente com -E. Para permitir componentes intermediários ausentes, use -m; para exigir a existência de todos, use -e.

O realpath sempre resolve links simbólicos?

O padrão físico GNU segue links. -L também os resolve, mudando a ordem em relação a ... Para não seguir links, use -s; combine com -m quando quiser apenas normalização textual sem exigir a existência dos componentes.

Qual é a diferença entre pwd -P e realpath .?

Ambos podem mostrar o caminho absoluto físico da localização atual. pwd -P é especializado para o diretório de trabalho atual, enquanto realpath fornece opções para múltiplos caminhos arbitrários, condições de existência e saída de caminho relativo.

Checar apenas o resultado do realpath pode prevenir ataques de travessia de diretório?

Não. O caminho pode mudar entre a verificação e o uso do arquivo, e questões de permissão são separadas. Em limites de confiança, você deve usar interfaces de abertura de arquivos com as restrições apropriadas junto com separação de permissões e verificações do limite do diretório.

Documentação oficial

• Documentação Oficial do realpath do GNU Coreutils
• Exemplos de Uso do realpath do GNU Coreutils