Linux / Comando / apropos: buscar manuales por nombres y descripciones

apropos busca palabras clave en los nombres y las descripciones breves de las páginas de manual. Resulta útil cuando conoce una tarea, como comprimir archivos o administrar cuentas, pero desconoce el nombre del comando. La búsqueda depende de los manuales instalados y del índice de man-db.

man -k también proporciona la misma función de búsqueda. Las palabras clave predeterminadas se pueden procesar como expresiones regulares, por lo que comprender las relaciones entre varias palabras, la búsqueda exacta y las reglas de comodines y comillas del shell permite obtener resultados más precisos.

¿Qué es el comando apropos?

Cada página del manual tiene un nombre y una breve descripción de su función. apropos busca en la base de datos de índice de man-db los nombres y descripciones de las páginas y muestra los elementos coincidentes.

No es un comando para buscar en todo el contenido del manual. Por lo tanto, los resultados son rápidos y útiles para encontrar candidatos por tema, pero las páginas que no incluyen la palabra clave en la descripción pueden no aparecer, aunque el contenido relevante esté presente en el texto completo.

Sintaxis básica y lectura de resultados

apropos [OPCIONES] PALABRA_CLAVE...

Este es un ejemplo de búsqueda de manuales relacionados con la copia de archivos.

apropos copy

Los resultados típicos tienen la siguiente estructura.

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

El primer campo es el nombre de la página del manual, el número entre paréntesis indica la sección, y lo que sigue al guion es una breve descripción. Una vez que encuentre el elemento deseado, especifique la sección para abrir la página exacta.

man 1 cp
man 1 scp

Método de búsqueda de varias palabras clave

El valor predeterminado es mostrar aunque coincida con una sola

Si especifica varias palabras clave, de manera predeterminada se pueden mostrar los elementos que coincidan con cualquiera de ellas. El alcance de búsqueda se amplía y los resultados pueden ser demasiados.

apropos network address

Use -a si necesita todas las palabras clave

-a o --and solo muestran los elementos que coinciden con todas las palabras clave especificadas. Es útil para reducir resultados irrelevantes.

apropos -a network address
apropos --and user password

Puede usar comillas para agrupar varias palabras en una sola expresión de búsqueda, pero también tenga en cuenta que la búsqueda básica utiliza expresiones regulares.

Expresiones regulares, búsqueda exacta y comodines

Búsqueda básica con expresiones regulares

apropos de man-db trata las palabras clave como expresiones regulares de manera predeterminada. Los caracteres como puntos, corchetes y asteriscos pueden tener significados especiales, por lo que, para buscarlos literalmente, se deben escapar o usar otro modo de búsqueda.

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

El primer ejemplo encuentra partes que comienzan con ssh en el nombre o la descripción, y el segundo ejemplo encuentra entradas donde hay caracteres arbitrarios después de file y luego aparece system.

Coincidencia exacta -e

-e o --exact hacen coincidir exactamente la palabra clave con el nombre de la página o la descripción. Si ya conoce el nombre exacto de la página, whatis puede ser más simple.

apropos -e printf

Comodín estilo shell -w

-w interpreta cada palabra clave como un patrón de comodines del shell. En man-db puede coincidir con el nombre o con límites de palabras en la descripción. Con -e, se exige que el patrón abarque todo el nombre o toda la descripción. Encierre el patrón entre comillas para evitar que el shell lo expanda primero a nombres de archivos.

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

Limitar el alcance de la búsqueda a secciones

Si se limita la sección del manual a -s o --sections, se pueden reducir otros documentos con el mismo nombre o resultados no relacionados.

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

La lista de secciones se puede separar por comas o dos puntos. Dependiendo de la implementación y de los documentos instalados, pueden existir subsecciones como 3p o 3perl.

Opciones de apropos que se usan con frecuencia

¿Cuál es la relación entre apropos y man -k?

En el entorno de man-db, man -k es una interfaz que utiliza la opción de búsqueda apropos. Los siguientes dos comandos pueden usarse con el mismo propósito.

apropos filesystem
man -k filesystem

Puede elegir según sus hábitos de uso. Si desea enfatizar que está en el proceso de buscar en el manual, es intuitivo usar man -k; si desea recordarlo como un comando de búsqueda independiente, es intuitivo usar apropos.

Puntos a verificar cuando no hay resultados de búsqueda

Cambiar a palabras clave más generales

Busque palabras que realmente aparezcan en el nombre o en la descripción del manual. Si solo dispone de documentación en inglés, una consulta en español puede no devolver resultados; pruebe términos como compress, archive o user account.

apropos compress
apropos archive
apropos -a user account

Actualizar la base de datos de índices

Justo después de instalar un nuevo manual o si el índice está dañado, apropos puede estar vacío. En un entorno man-db, puede actualizar el índice con privilegios de administrador.

sudo mandb

mandb crea o actualiza la memoria caché del índice de páginas del manual. El sistema puede actualizarlo automáticamente durante la instalación de paquetes o trabajos periódicos, por lo que no es necesario ejecutarlo repetidamente de forma innecesaria.

Verificar la ruta del manual y la configuración regional

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

Si ha configurado MANPATH directamente o ha instalado los documentos en una ruta especial, la jerarquía de manuales predeterminada puede omitirse en la búsqueda. La opción -M se puede usar temporalmente para especificar otra ruta al diagnosticar problemas.

Cuando se utiliza en scripts de shell

El apropos de man-db devuelve 0 cuando se ejecuta normalmente, 1 en caso de errores de uso o configuración, 2 en caso de errores operativos y 16 cuando no hay resultados coincidentes. En lugar de simplemente verificar si la salida está vacía, al diferenciar los estados de finalización se puede distinguir entre error y ausencia de resultados de búsqueda.

if apropos -e "$1" >/dev/null; then
  printf '%s\n' 'Hay una entrada de manual coincidente.'
else
  status=$?
  printf 'Búsqueda fallida o sin resultados: status=%d\n' "$status" >&2
fi

Guarde el bloque en check-apropos.sh y ejecútelo con un argumento, por ejemplo bash check-apropos.sh printf. La condición lee el estado de apropos y el mensaje muestra el valor original cuando falla; el script termina después de printf, por lo que no transmite automáticamente ese estado al programa que lo llamó. Si la automatización lo necesita, añada una salida explícita según su política. Estos estados corresponden a man-db; compruebe el manual local en otras implementaciones.

Comparación con herramientas relacionadas

Preguntas frecuentes

¿Puedo buscar en español?

Es posible buscar en español si hay descripciones traducidas instaladas e indexadas y se utiliza la configuración regional adecuada. Si el sistema solo dispone de descripciones en inglés, pruebe las palabras clave correspondientes en ese idioma.

¿Qué hacer si hay espacios en la palabra clave?

Para transmitirlo como una sola expresión, colóquelo entre comillas. Si se transmite como varias palabras clave independientes y se utiliza -a, sólo se encontrarán elementos que coincidan con cada palabra.

¿Se usa apropos en lugar de which?

Tienen usos diferentes. apropos busca manuales relacionados, mientras que command -v o type verifican cómo se interpreta realmente el nombre del comando ingresado.

Después de encontrar la página deseada, ábrala con man junto con el número de sección. Otros comandos básicos se pueden consultar en Lista y resumen de comandos de Linux.

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