Linux / Comando whatis: consultar descrições de manuais

whatis mostra a descrição curta das páginas de manual que correspondem a um nome conhecido. Use, por exemplo, whatis ls para consultar o resumo de ls ou whatis passwd para procurar páginas com esse nome em diferentes seções. O resultado depende dos manuais e índices instalados.

Sem opções de padrão, a busca usa o nome exato da página. man -f tem a mesma finalidade no man-db. Para procurar por um assunto nas descrições, use apropos, explicado em português; para abrir o texto completo, consulte o comando man.

O que é o comando whatis?

A seção NAME de uma página de manual contém o nome da página e uma descrição curta. O whatis pesquisa o banco de dados de índice man-db por uma página que corresponda ao nome especificado e imprime essa descrição em uma única linha.

whatis permite consultar resumos sem abrir cada manual. Ele não mostra qual executável o shell escolherá nem comprova que o comando está instalado. Os exemplos a seguir usam a implementação do man-db; outros sistemas podem ter opções e códigos de saída diferentes.

Sintaxe básica e leitura da saída

Este é um esquema de sintaxe, não um comando pronto: colchetes indicam opções e as reticências indicam que vários nomes podem ser informados. Nos exemplos seguintes, não digite esses sinais literalmente.

whatis [opções] nome...

Verifique a descrição de uma linha de ls.

whatis ls

A saída pode ter o formato abaixo. Trata-se de um exemplo com descrição em inglês; o texto e a quantidade de resultados variam com os manuais, a versão e o idioma disponíveis. O número entre parênteses identifica a seção do manual.

ls (1)               - list directory contents

ls é o nome da página, (1) é a seção do manual, e o texto após o hífen é a descrição de uma linha. Para ver o uso completo, abra-o usando o número e o nome da seção do resultado.

man 1 ls

Consultar vários nomes de uma vez

Se você especificar múltiplos argumentos, pode ver os resultados para cada nome juntos.

whatis ls cp mv rm

Isto é útil ao comparar as funções de comandos básicos ou verificar os manuais instalados em um servidor. Mesmo que alguns nomes não existam, os resultados para outros nomes podem ser exibidos, portanto, na automação, você deve verificar tanto o status final de saída quanto os resultados individuais.

Quando o nome aparece em várias seções

Se o mesmo nome de página existir em múltiplas seções de manual, whatis pode gerar múltiplas linhas. Um exemplo comum é passwd, que é separado em um comando de usuário e um documento de formato de arquivo.

whatis passwd

Se você vir passwd(1) e passwd(5) nos resultados, abra cada um da seguinte forma.

man 1 passwd
man 5 passwd

O número entre parênteses não é a versão do programa, mas a seção do manual. O uso do comando geralmente é encontrado na seção 1 ou 8, e os formatos de arquivos de configuração são encontrados principalmente na seção 5.

Buscar com expressões regulares e curingas

Expressão regular com -r

-r ou --regex interpreta o nome inserido como uma expressão regular. Os resultados podem aparecer mesmo que apenas parte do nome da página corresponda.

whatis -r '^ssh'
whatis --regex 'printf$'

As aspas impedem que o shell interprete o padrão antes de passá-lo ao whatis; elas não desativam a expressão regular. ^ssh seleciona nomes que começam por ssh; printf$ seleciona nomes que terminam por printf. A busca continua sendo nos nomes das páginas, e não no texto das descrições.

Curinga -w

-w ou --wildcard encontra nomes usando padrões curinga no estilo shell. O padrão estendido deve corresponder ao nome completo da página.

whatis -w 'ssh*'
whatis --wildcard '*printf*'

Sem aspas, * poderia ser expandido primeiro para nomes de arquivos no diretório atual.

Limitar as seções do manual

Com -s ou --sections, você pode buscar apenas as seções desejadas.

whatis -s 1 passwd
whatis -s 5 passwd
whatis --sections=2,3 printf

Opções mais usadas do whatis

Relação entre whatis e man -f

Em um ambiente man-db, man -f procura a descrição curta da página da mesma forma que whatis.

whatis printf
man -f printf

Você pode usar o formato que for mais fácil de lembrar. man -f é fácil de lembrar como uma função relacionada de man, e whatis mostra claramente em seu nome que é para verificar uma descrição em uma linha.

Diferenças entre whatis, apropos e type

Ter um resultado whatis não significa que um executável com o mesmo nome esteja em PATH, a lista de diretórios de busca do shell. Por outro lado, mesmo que haja um executável, pode não haver nenhum resultado se a página do manual não estiver instalada.

Quando a busca não encontra resultados

Conferir o nome e a documentação instalada

whatis procura o nome da página. Se você conhece apenas o assunto, use apropos. command -v ajuda a identificar como o shell resolve um nome, que pode corresponder a um executável, uma função ou um comando interno; isso é uma verificação diferente da presença de documentação.

apropos archive
command -v tar
whatis tar

Atualizar o índice

Se você instalou o manual recentemente, mas nenhum resultado aparecer, o índice man-db pode ainda não ter sido atualizado.

sudo mandb

mandb atualiza os índices da documentação já disponível; não baixa páginas nem instala o programa correspondente. O exemplo com sudo exige privilégios administrativos e modifica o cache. Muitas instalações atualizam esse índice automaticamente. Sem permissão administrativa, confira primeiro os caminhos de documentação e a configuração da distribuição.

Conferir locale e MANPATH

locale
manpath
printf '%s\n' "$MANPATH"

Locale é a configuração de idioma e convenções regionais. Uma tradução só aparece quando a documentação correspondente está instalada e é selecionada pelo locale; -L não instala traduções. MANPATH pode mudar os diretórios pesquisados e -M substitui temporariamente esse caminho. Uma variável vazia não significa ausência de caminhos padrão; consulte a raiz de uma hierarquia de manuais, não um arquivo isolado.

Usar o resultado em um script

Para consultar um único nome em automação, preserve o estado retornado pela busca. No man-db, 0 indica sucesso, 16 indica ausência de correspondência e 1 ou 2 indicam erros de uso/configuração ou de operação. Um erro não deve ser apresentado apenas como “manual ausente”. Para verificar a resolução de um comando pelo shell, use command -v ou type.

Salve o exemplo como consultar-descricao.sh. Ele requer Bash e whatis disponível. Execute bash consultar-descricao.sh ls e substitua ls pelo nome de uma página a consultar. A saída normal da busca é descartada, mas os diagnósticos de erro continuam visíveis.

#!/usr/bin/env bash
if [ "$#" -ne 1 ]; then
  printf '%s\n' 'Uso: bash consultar-descricao.sh nome' >&2
  exit 1
fi

if whatis "$1" >/dev/null; then
  printf '%s\n' 'Descrição de manual encontrada.'
else
  status=$?
  printf 'Consulta sem resultado ou com falha: status=%d\n' "$status" >&2
  exit "$status"
fi

Imediatamente depois, echo "$?" permite conferir o estado: 0 para correspondência, 16 para nenhuma correspondência e os códigos de erro preservados. O próprio script retorna 1 se não receber exatamente um argumento. O exemplo verifica um nome por execução; para uma lista de nomes, avalie também cada resultado, pois a saída pode ser parcial.

Perguntas frequentes

whatis mostra o caminho real de um comando?

Não. Ele mostra o nome e a descrição da página do manual. Verifique o caminho de execução e o tipo de comando com type ou command -v.

Como posso buscar usando palavras incluídas na descrição?

Use apropos palavra ou man -k palavra. whatis é basicamente adequado quando você já conhece o nome da página.

Por que o mesmo nome é impresso em várias linhas?

Porque há páginas com o mesmo nome em diferentes seções do manual. Verifique o número da seção entre parênteses e abra a página desejada com man seção nome.

Resumo

whatis é uma ferramenta para verificar o papel de um nome de página de manual conhecido em uma linha. Ele ajuda a diferenciar páginas com o mesmo nome em diferentes seções, revisar rapidamente vários nomes e verificar candidatos antes de abrir o documento necessário com man.

Ao procurar documentos usando palavras-chave funcionais, use apropos, e ao verificar a interpretação real do comando, use type ou command -v. Para outros comandos básicos, consulte a referência de comandos Linux em português.

Documentação oficial

• página de manual whatis(1)
• página de manual mandb(8)
• projeto man-db