Linux / Comando apropos: buscar manuais por descrição

apropos procura palavras-chave nos nomes e nas descrições curtas das páginas de manual. Use-o quando souber a tarefa, como copiar arquivos ou configurar uma rede, mas ainda não conhecer o nome do comando. No man-db, a busca usa o índice da documentação instalada, e não todos os programas existentes ou disponíveis nos repositórios.

man -k fornece a mesma funcionalidade de busca. Como os termos de pesquisa padrão podem ser processados como expressões regulares, entender os relacionamentos entre múltiplas palavras, pesquisas por correspondência exata, curingas e regras de citação do shell pode gerar resultados mais precisos.

O que é o comando apropos?

Cada página do manual tem uma breve descrição resumindo seu nome e funcionalidade. apropos pesquisa os nomes das páginas e descrições no banco de dados de índice man-db e exibe as entradas correspondentes.

A busca não percorre todo o corpo dos manuais. Uma página pode ficar fora dos resultados se nem seu nome nem sua descrição curta contiverem o termo, mesmo que o assunto apareça no texto completo. Os exemplos deste artigo pressupõem apropos do man-db e as páginas e índices relevantes instalados.

Sintaxe básica e leitura de resultados

O esquema abaixo não é um comando pronto para executar: colchetes indicam opções e as reticências indicam que você pode informar várias palavras-chave. Não digite esses sinais literalmente nos exemplos seguintes.

apropos [opções] palavra-chave...

Aqui está um exemplo de como encontrar manuais relacionados à cópia de arquivos.

apropos copy

Um resultado pode ter a estrutura abaixo. Este é um exemplo de descrições em inglês; os nomes, a redação e a quantidade de linhas dependem das páginas instaladas, da versão e do idioma selecionado. Não espere uma lista idêntica em todo sistema.

cp (1)               - copy files and directories
scp (1)              - OpenSSH secure file copy

O primeiro campo é o nome da página do manual, o número entre parênteses é a seção, e a descrição após o hífen é uma explicação de uma linha. Uma vez que você encontrar o item desejado, especifique a seção para abrir a página exata.

man 1 cp
man 1 scp

Métodos de pesquisa com múltiplas palavras-chave

O padrão é exibir se pelo menos uma corresponder

Ao especificar múltiplas palavras-chave, por padrão, itens que correspondam a qualquer uma delas podem ser exibidos. O alcance da pesquisa pode ficar amplo, resultando em muitos resultados.

apropos network address

Use -a se todos os termos-chave forem necessários

-a ou --and mostra apenas itens que correspondem a todos os termos-chave especificados. É útil para reduzir resultados não relacionados.

apropos -a network address
apropos --and user password

Você pode usar aspas para agrupar várias palavras em uma única expressão de pesquisa, mas tenha em mente que a pesquisa padrão é uma expressão regular.

Expressões regulares, pesquisas exatas e curingas

Pesquisa básica de expressão regular

Por padrão, o apropos do man-db interpreta cada termo como uma expressão regular, um padrão de correspondência de texto. Ponto, colchetes e asterisco podem ter significado especial. As aspas protegem o argumento da interpretação do shell, mas não desativam a expressão regular usada pelo apropos.

apropos '^ssh'
apropos 'file.*system'

^ssh exige que o nome ou a descrição comece por ssh. Em file.*system, .* admite zero ou mais caracteres entre file e system. A comparação é feita separadamente com os nomes e com as descrições.

Correspondência exata com -e

-e, ou --exact, exige correspondência exata com o nome da página ou a descrição. Se você já conhece o nome exato da página, whatis pode ser mais simples.

apropos -e printf

Curingas do shell com -w

-w ou --wildcard usa curingas no estilo do shell. Coloque o padrão entre aspas para que a expansão de nomes de arquivo não ocorra antes da busca. Esse modo admite correspondências nos limites de palavras da descrição; combiná-lo com -e exige a correspondência do nome ou da descrição inteira. Confira as regras no manual apropos(1).

apropos -w 'ssh*'
apropos --wildcard '*password*'

Limitar a busca por seção

Usar -s ou --sections para limitar as seções manuais pode reduzir os resultados com o mesmo nome de outros documentos ou entradas não relacionadas.

apropos -s 1 archive
apropos -s 2,3 socket
apropos --sections=5 password

Separe as seções por vírgulas ou dois-pontos. No man-db, pedir uma seção simples, como 3, também pode incluir extensões como 3perl; pedir 3perl restringe a essa extensão. A disponibilidade das páginas depende da documentação instalada.

Opções apropos comumente usadas

Qual é a relação entre apropos e man -k?

No ambiente man-db, man -k é uma interface que utiliza as opções de pesquisa apropos. Os dois comandos a seguir podem ser usados para o mesmo propósito.

apropos filesystem
man -k filesystem

Escolha a forma que facilitar seu trabalho. A explicação do comando man em português mostra como abrir a página encontrada e selecionar a seção correta.

Pontos a verificar quando nenhum resultado de pesquisa aparecer

Mudar para uma palavra-chave mais geral

Use termos que possam aparecer nas descrições disponíveis. Sem páginas traduzidas instaladas e selecionadas pelo locale, palavras em português podem não encontrar resultados. Nesse caso, experimente os termos em inglês abaixo. Locale é a configuração de idioma e convenções regionais usada pelo ambiente.

apropos compress
apropos archive
apropos -a user account

Atualizar o índice

Imediatamente após instalar um novo manual ou se o índice estiver corrompido, os resultados do apropos podem estar vazios. Em um ambiente man-db, você pode atualizar o índice com privilégios administrativos.

sudo mandb

mandb cria ou atualiza o índice das páginas já disponíveis; não instala comandos nem baixa documentação ausente. O exemplo com sudo precisa de privilégios administrativos e altera o cache do sistema. Algumas distribuições fazem essa atualização automaticamente, portanto não é necessário repeti-la sem motivo.

Conferir caminhos e locale

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

MANPATH pode alterar as hierarquias de manuais pesquisadas. -M substitui temporariamente esse caminho para uma execução; informe a raiz de uma hierarquia de manuais, não um arquivo isolado. -L seleciona temporariamente o locale da busca, mas não instala traduções. Uma variável MANPATH vazia não significa que nenhum caminho padrão será usado.

Usar em scripts de shell

No man-db, apropos retorna 0 em caso de sucesso, 1 para erro de uso ou configuração, 2 para erro operacional e 16 quando nada corresponde à busca. Para aproveitar essa distinção em automação, o script precisa preservar o código retornado, em vez de terminar com o sucesso de um printf.

Salve o exemplo completo como procurar-manual.sh. Ele exige Bash e apropos disponível. Execute, por exemplo, bash procurar-manual.sh printf; troque printf pelo nome exato de uma página que deseja consultar. Nenhuma permissão de execução é necessária quando o arquivo é passado ao comando bash.

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

if apropos -e "$1" >/dev/null; then
  printf '%s\n' 'Há uma entrada de manual correspondente.'
else
  status=$?
  printf 'Sem resultado ou falha na busca: status=%d\n' "$status" >&2
  exit "$status"
fi

Logo após executar o script, echo "$?" mostra o estado retornado: uma correspondência produz a mensagem de sucesso e estado 0; uma busca sem resultado devolve 16; erros mantêm seu código. Sem um único argumento, o próprio script mostra o uso e retorna 1. Esses códigos de busca são do man-db e podem diferir em outra implementação; confira man apropos.

Comparar comandos de consulta

Perguntas frequentes

Posso pesquisar com palavras-chave localizadas?

Sim, quando descrições em português estão instaladas e são selecionadas pelo locale. Se houver somente descrições em inglês, procure palavras em inglês. Alterar o idioma da busca não cria uma tradução ausente.

E se o termo de pesquisa contiver espaços?

Para passá-lo como uma única expressão, coloque-o entre aspas. Se você passar várias palavras-chave independentes e usar -a, ele só encontrará entradas onde cada palavra corresponda.

Devo usar apropos em vez de which?

Eles têm propósitos diferentes. apropos encontra manuais relevantes, e command -v ou type verifica como o nome do comando inserido é realmente interpretado.

Resumo

apropos é útil quando você quer encontrar um comando ou documento por palavras-chave de funcionalidade sem saber seu nome. Você pode encontrar candidatos com a pesquisa básica, satisfazer múltiplas condições com -a e restringir seções com -s para organizar os resultados de forma eficiente.

Depois de encontrar a página que você deseja, abra-a com man junto com o número da seção. Para outros comandos básicos, consulte a referência de comandos Linux em português.

Documentação oficial

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