Comando man: uso e opções, números de seção e busca com man -k

Para conferir como se usa um comando ou um arquivo de configuração em um servidor Linux, abre-se a página de manual com o comando man e, quando não se sabe o nome, busca-se nas descrições curtas com man -k. Ao procurar a página do passwd em servidores AlmaLinux 9 e Debian 12, o Debian 12 tinha tanto a página de comando da seção 1 quanto a página de formato de arquivo da seção 5, enquanto o AlmaLinux 9 não tinha página na seção 5.

A saída abaixo foi obtida em um servidor AlmaLinux 9.8 com a conta root e em um servidor Debian 12 com uma conta comum. O nome do host e o endereço de conexão do simulador são valores de exemplo.

1️⃣ Uso básico do comando man

Ao escrever o nome de um comando depois de man, a página de manual desse comando é aberta. O man entrega a página a um programa paginador, que a mostra uma tela por vez, e por isso não volta ao prompt logo depois de ser executado. O paginador é definido pela variável de ambiente MANPAGER ou PAGER e, se as duas estiverem vazias, o less é usado.

Quando a saída é enviada por um pipe, aparece só o texto, sem paginador. Ao pegar com head as 12 primeiras linhas de [man ls], a primeira linha trazia LS(1) e, em seguida, vinham em ordem as seções NAME, SYNOPSIS e DESCRIPTION.

man ls | head -n 12

LS(1)                            User Commands                           LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information  about  the FILEs (the current directory by default).
       Sort entries alphabetically if none of -cftuvSUX nor --sort  is  speci-
       fied.

O número 1 entre parênteses em LS(1), na primeira linha, é o número da seção em que esta página está.

Dentro de uma página, [Space] mostra a próxima tela, e [/palavra] seguido de Enter procura uma palavra. [n] vai para o próximo ponto em que a mesma palavra aparece, e [q] encerra o man.

Ao escrever um nome que não existe, aparece o erro [No manual entry for], e o código de saída foi 16.

man no-such-cmd9

No manual entry for no-such-cmd9

echo $?

16

A seção EXIT STATUS da página do man descreve 16 como o valor para quando pelo menos uma das páginas, arquivos ou palavras não foi encontrada. Um erro de uso é 1, então um script pode tratar os dois casos separadamente.

2️⃣ Números de seção do man

Quando há páginas com o mesmo nome em várias seções, o man procura nas seções em uma ordem definida e abre apenas a primeira página que encontra. As seções vão de 1 a 9, e as mais abertas no trabalho com servidores são a seção 1, de comandos, a seção 5, de formatos de arquivo, e a seção 8, de comandos de administração.

O crontab tem páginas em duas seções porque o comando e o formato do arquivo de configuração têm o mesmo nome. Ao conferir com [man -f crontab], as linhas das seções 1 e 5 apareceram juntas.

man -f crontab

crontab (1)          - maintains crontab files for individual users
crontab (5)          - files used to schedule the execution of programs

Executar [man crontab] sem número de seção abre a página do comando crontab da seção 1. Para ver o formato do arquivo de tarefas agendadas, escreve-se 5 antes do nome.

man 5 crontab | head -n 4

CRONTAB(5)                       File Formats                       CRONTAB(5)

NAME
       crontab - files used to schedule the execution of programs

A primeira linha mudou para CRONTAB(5) e File Formats, e a linha NAME também passou a mostrar a descrição do arquivo de tarefas agendadas em vez da descrição do comando.

Se a seção indicada não tiver uma página com esse nome, aparece um erro. No servidor AlmaLinux 9.8, ao executar [man 5 passwd] para ver o formato do arquivo /etc/passwd, apareceu um erro dizendo que não havia página na seção 5.

man 5 passwd

No manual entry for passwd in section 5

No servidor Debian 12, [man -f passwd] mostrou também a linha do passwd da seção 5. Em quais seções há página depende dos manuais instalados no servidor, por isso vale conferir com [man -f] antes de acrescentar um número de seção.

man -f passwd

passwd (1)           - change user password
passwd (1ssl)        - OpenSSL application commands
passwd (5)           - the password file

A seção 8 contém comandos de administração executados principalmente pela conta root, como o useradd, que cria contas.

man -f useradd

useradd (8)          - create a new user or update default new user information

3️⃣ Opções do comando man e busca com -k e -f

[man -f] mostra a descrição de uma linha das páginas com o mesmo nome e funciona igual ao whatis. Ao executar [man -f passwd] e [whatis passwd] no servidor AlmaLinux 9.8, apareceram as mesmas duas linhas.

man -f passwd

passwd (1)           - update user's authentication tokens
passwd (1ossl)       - OpenSSL application commands

A linha 1ossl é a página de um comando do OpenSSL que usa o mesmo nome passwd.

Quando não se sabe o nome, [man -k] busca nos nomes de página e nas descrições curtas. Funciona igual ao apropos, e a palavra é lida como expressão regular.

man -k '^passwd'

passwd (1)           - update user's authentication tokens
passwd (1ossl)       - OpenSSL application commands

^ indica o início da linha, então só apareceram as linhas que começam com passwd. Também dá para buscar por uma palavra da descrição: [man -k 'directory contents'] encontrou as páginas dir e vdir junto com ls.

man -k 'directory contents'

dir (1)              - list directory contents
ls (1)               - list directory contents
vdir (1)             - list directory contents

[man -k] busca apenas nas descrições curtas da seção NAME, por isso não encontra uma página pelo nome de uma opção nem por uma palavra do texto. [man -K], que busca também no texto, lê todas as páginas uma a uma e demora bastante.

Quando a palavra buscada não existe, aparece [nothing appropriate], e o código de saída foi 16.

man -k no-such-word9

no-such-word9: nothing appropriate.

echo $?

16

[man -w] mostra apenas a localização do arquivo de origem, sem abrir a página.

man -w ls

/usr/share/man/man1/ls.1.gz

man -w 5 crontab

/usr/share/man/man5/crontab.5.gz

Os dois arquivos estavam nas pastas man1 e man5 em /usr/share/man, e o número no nome da pasta era igual ao número da seção. O arquivo da página 1ossl, encontrado com [man -w 1ossl passwd], também estava na pasta man1, a mesma da seção 1.

As opções estão reunidas nas duas abas abaixo.

🔲 Simulador do comando man

No simulador abaixo, é possível abrir uma página com [man ls] e passar pelas telas com os chips [Space], [/list], [n] e [q]. No mesmo servidor virtual, dá para acrescentar um número de seção, como em [man 5 crontab], ou digitar [man -f], [man -k] e [man -w].

4️⃣ Estrutura de uma página do man

Uma página do man é dividida em seções com títulos em maiúsculas. Ao extrair apenas os títulos com grep e comparar, a página do ls trazia a descrição das opções dentro de DESCRIPTION, enquanto a página do crontab tinha uma seção OPTIONS separada.

man ls | grep -E '^[A-Z]+( [A-Z]+)*$'

NAME
SYNOPSIS
DESCRIPTION
AUTHOR
REPORTING BUGS
COPYRIGHT
SEE ALSO

man crontab | grep -E '^[A-Z]+( [A-Z]+)*$'

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CAVEATS
SEE ALSO
FILES
STANDARDS
DIAGNOSTICS
AUTHOR

Os nomes das seções mudam um pouco de uma página para outra, e as mais comuns são as seguintes.

Os símbolos da SYNOPSIS seguem regras definidas pela página do man. O que está entre colchetes pode ser omitido. Opções separadas por uma barra vertical (|) não podem ser usadas juntas, e um argumento seguido de três pontos (...) pode ser escrito várias vezes.

A SYNOPSIS do ls é ls [OPTION]... [FILE]..., então tanto as opções de comando quanto os argumentos de linha de comando, como nomes de arquivo, podem ser todos omitidos ou escritos várias vezes.

[--help] é um resumo de uso impresso pelo próprio programa, por isso sai direto no terminal, sem paginador. O Usage da primeira linha de [ls --help] tinha a mesma forma da SYNOPSIS, e a saída inteira tinha 121 linhas, menos que as 245 linhas de [man ls].

ls --help | head -n 3

Usage: ls [OPTION]... [FILE]...
List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor --sort is specified.

Uma página do man tem outras seções que não existem em [--help], como AUTHOR e SEE ALSO. Para ver rapidamente uma única opção, use [--help]; quando for preciso uma explicação dividida em seções, como o formato de um arquivo de configuração ou os códigos de saída, abra o man.

🔢 FAQ & conteúdo recomendado

🔗 Conteúdo recomendado

Paginador · less Como usar o comando less do Linux Um artigo que explica em detalhes as teclas para passar páginas e procurar palavras na tela do less, onde as páginas do man são abertas. Ver post →

Agendamento Linux: configuração do crontab Como agendar com o comando crontab tarefas do servidor para rodarem em horários definidos. Encontrar a localização Linux which, whereis, locate: 3 comandos para achar a localização (caminho) de um arquivo Comandos para descobrir em qual caminho estão o arquivo executável e o arquivo de manual de um comando. Encaminhar a saída Redirecionamento no Linux (Redirection) O fluxo de entrada padrão e saída padrão que envia a saída de um comando para um arquivo ou para outro comando.

ℹ️ Aviso de afiliados
O conteúdo deste site contém links de afiliados. Quando um visitante compra um produto ou serviço por meio de um desses links, o site recebe uma comissão do vendedor. O valor que o comprador paga ^{(em promoções, ele diminui ↓)} não aumenta por causa disso. Preços, descontos e informações de estoque valem para o momento em que o texto foi escrito e podem ter mudado, por isso confirme com o vendedor antes de comprar. Os produtos são escolhidos e avaliados por critérios próprios, e o recebimento de comissão não influencia a ordem de apresentação nem o conteúdo das avaliações.