Linux / Comando / whatis: consultar descripciones breves del manual

whatis es un comando que busca el nombre de una página del manual y muestra una descripción de una línea de dicha página. Es útil cuando se conoce el nombre del comando pero se quiere verificar rápidamente su función, o cuando se desea comprobar si el mismo nombre aparece en varias secciones del manual.

Por defecto, encuentra el nombre exacto de la página, y man -f también se puede usar para este propósito. Si se desea buscar de manera más amplia usando palabras clave del tema o de la descripción, apropos es más adecuado que whatis.

¿Qué es el comando whatis?

En la sección NAME de la página del manual se incluye el nombre de la página y una breve descripción. whatis busca en la base de datos de índices de man-db la página que coincide con el nombre especificado y muestra esta descripción en una sola línea.

Debido a que no abre el contenido del manual, es bueno para verificar rápidamente el resumen de varios comandos. Sin embargo, no es una herramienta para indicar la ubicación del archivo ejecutable ni el comando que se selecciona realmente en el shell.

Sintaxis básica y lectura de la salida

whatis [OPCIONES] NOMBRE...

Verifique la descripción de una línea de ls.

whatis ls

La salida generalmente tiene la siguiente estructura.

ls (1)               - list directory contents

ls es el nombre de la página, (1) es la sección del manual, y lo que sigue después del guion es una descripción breve. El uso completo se abre utilizando el número de sección y el nombre en los resultados.

man 1 ls

Ver varios nombres a la vez

Si se especifican múltiples argumentos, se pueden ver los resultados de cada nombre juntos.

whatis ls cp mv rm

El resultado depende de los manuales instalados y del índice disponible. Con varios nombres, man-db puede devolver estado 0 si encuentra al menos uno; por tanto, ese estado no demuestra que haya encontrado todos. Para verificar cada nombre, consúltelos por separado.

Cuando un mismo nombre está en varias secciones

Si el mismo nombre de página existe en varias secciones del manual, whatis puede mostrar varias líneas. Un ejemplo representativo es que passwd distingue entre comandos de usuario y documentos de formato de archivo.

whatis passwd

Si los resultados muestran passwd(1) y passwd(5), se abren de la siguiente manera.

man 1 passwd
man 5 passwd

El número entre paréntesis no representa la versión del programa, sino la sección del manual. La forma de usar los comandos generalmente se encuentra en la sección 1 o 8, mientras que el formato de los archivos de configuración se encuentra principalmente en la sección 5.

Expresiones regulares y búsqueda con comodines

Expresiones regulares -r

-r o --regex interpretan el nombre ingresado como una expresión regular. Incluso si solo coincide una parte del nombre de la página, puede aparecer un resultado.

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

Es seguro encerrar entre comillas los caracteres especiales de la expresión regular para que no sean interpretados primero por el shell.

Comodín -w

-w o --wildcard buscan nombres según el patrón de comodín al estilo shell. El patrón extendido debe coincidir con todo el nombre de la página.

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

Sin comillas, * puede ser expandido primero a los nombres de archivos del directorio actual.

Limitar la sección del manual

Puede buscar solo la sección que desee con -s o --sections.

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

Opciones de whatis que se usan con frecuencia

Relación entre whatis y man -f

En el entorno man-db, man -f encuentra descripciones breves de las páginas de la misma manera que whatis.

whatis printf
man -f printf

Puede usar el formato que sea más fácil de recordar. man -f es fácil de recordar por su función relacionada con man, y whatis muestra en su nombre el propósito de verificar una descripción de una línea.

Diferencias entre whatis, apropos y type

Que haya un resultado en whatis no significa que un archivo ejecutable con el mismo nombre exista actualmente en PATH. Por el contrario, si hay un archivo ejecutable pero la página del manual no está instalada, puede que no haya resultados.

Resolver problemas cuando no hay resultados

Verificar el nombre de la página y el estado de la instalación

whatis busca por defecto el nombre exacto de la página. Si introdujo palabras del tema o descripción, utilice apropos y verifique la existencia del archivo ejecutable con command -v.

apropos archive
command -v tar
whatis tar

Actualizar la base de datos de índices

Si instaló el manual recientemente pero no aparecen resultados, es posible que el índice de man-db aún no se haya actualizado.

sudo mandb

El sistema también puede actualizar automáticamente durante el proceso de instalación de paquetes o mediante tareas programadas. En un entorno sin privilegios de administrador, primero verifique la ruta del manual del usuario y la configuración de la distribución.

Verificar la configuración regional y MANPATH

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

Es posible que no se encuentren los documentos esperados debido al índice de un idioma específico o al MANPATH especificado por el usuario.

Usar los resultados en un script

Guarde el siguiente bloque en check-manual.sh y ejecútelo, por ejemplo, con bash check-manual.sh ls. Debe disponer de Bash, man-db y un índice de manuales instalado. La condición comprueba el estado de whatis y muestra un mensaje; el bloque no conserva ese estado como estado final del script, pues después ejecuta printf. Si su automatización necesita fallar cuando no hay manual, establezca explícitamente el estado de salida correspondiente. Para comprobar un comando ejecutable, utilice command -v.

if whatis "$1" >/dev/null 2>&1; then
  printf '%s\n' 'Se encontró la descripción del manual.'
else
  printf '%s\n' 'No se encontró la descripción del manual.' >&2
fi

Preguntas frecuentes

¿whatis muestra la ruta real del comando?

No. Muestra el nombre y la descripción de la página del manual. Confirme la ruta de ejecución y el tipo de comando con type o command -v.

¿Cómo buscar a través de palabras incluidas en la descripción?

Use apropos PALABRA_CLAVE o man -k PALABRA_CLAVE. whatis es adecuado principalmente cuando conoce el nombre de la página.

¿Por qué se imprime varias líneas con el mismo nombre?

Es porque hay páginas con el mismo nombre en secciones de manual diferentes. Verifique el número de sección entre paréntesis y abra la página deseada con man SECCIÓN NOMBRE.

Cuando busque documentos con palabras clave de función, use apropos; para verificar la interpretación real de los comandos, use type o command -v. Puede consultar otros comandos básicos en Lista y descripción de comandos de Linux.

Para las reglas de búsqueda y mantenimiento del índice, consulte Página del manual whatis(1), Página del manual mandb(8) y el Proyecto man-db.