NOMBRE¶
man - una interfaz de los manuales de referencia electrónicos
SINOPSIS¶
man [
-c|
-w|
-tZT dispositivo] [
-adhu7V]
[
-m sistema[,...]] [
-L locale] [
-p
cadena] [
-M ruta] [
-P paginador] [
-r
prompt] [
-S lista] [
-e extension]
[[
sección]
pagina ...] ...
man -l [
-7] [
-tZT dispositivo] [
-p
cadena] [
-P paginador] [
-r prompt]
fichero ...
man -k [
-M ruta]
palabra_clave ...
man -f [
-M ruta]
pagina ...
DESCRIPCIÓN¶
man es el paginador del manual del sistema. Las
páginas
usadas como argumentos al ejecutar
man suelen ser normalmente nombres
de programas, útiles o funciones. La
página de manual
associada con cada uno de esos argumentos es buscada y presentada. Si la
llamada da también la
sección,
man buscará
sólo en dicha
sección del manual. Normalmente, la
búsqueda se lleva a cabo en todas las
secciones de manual
disponibles según un orden predeterminado, y sólo se presenta la
primera
página encontrada, incluso si esa
página se
encuentra en varias
secciones.
La siguiente tabla muestra los números de
sección del manual y
los tipos de páginas que contienen.
1 |
Programas ejecutables y guiones del intérprete de órdenes |
2 |
Llamadas del sistema (funciones servidas por el núcleo) |
3 |
Llamadas de la biblioteca (funciones contenidas en las bibliotecas del
sistema) |
4 |
Ficheros especiales (se encuentran generalmente en /dev) |
5 |
Formato de ficheros y convenios p.ej. I/etc/passwd |
6 |
Juegos |
7 |
Paquetes de macros y convenios p.ej. man(7),
groff(7). |
8 |
Órdenes de admistración del sistema (generalmente solo son
para root) |
9 |
Rutinas del núcleo [No es estándar] |
n |
nuevo [obsoleto] |
l |
local [obsoleto] |
p |
público [obsoleto] |
o |
viejo [obsoleto] |
Una
página de manual tiene varias partes.
Éstas están etiquetadas como
NOMBRE,
SINOPSIS,
DESCRIPCIÓN,
OPCIONES,
FICHEROS,
VÉASE
TAMBIÉN,
BUGS, y
AUTOR.
En la sección
SINOPSIS se siguen los siguientes convenios que pueden
servir de guía para otras secciones.
texto en negrita |
debe teclear esto exactamente. |
texto en cursiva |
reemplace esto por el argumento apropiado. |
[-abc] |
uno o todos los argumentos entre corchetes son opcionales. |
-a|-b |
las opciones separadas por | no pueden usarse conjuntamente. |
argumento ... |
argumento es repetible. |
[expresión] ... |
la expresión entre corchetes completa es
repetible. |
El ejemplo del empleo de la orden o función debe recogerá todos los
posibles usos. En algunos casos es recomendable ilustrar algunos usos
exclusivos como se puede ver en la
SINOPSIS de esta página de
manual.
EJEMPLOS¶
- man ls
- Presenta la página de manual del elemento
(programa) ls.
- man -a intro
- Presenta, secuencialmente, todas las páginas de
intro disponibles en el manual. Entre página y página se
puede decidir saltar a la siguiente o salir del paginador completamente.
- man -t alias | lpr -Pps
- Formatea la página de manual referenciada por
`alias', generalmente una página de manual de tipo shell,
usando el formato predeterminado troff o groff y redirige la
salida a la impresora llamada ps. La salida predeterminada de
groff generalmente es PostScript. man --help debería
informarle de que procesador está siendo usado con la opción
-t
- man -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi
- Esta orden descomprime y formatea el fichero fuente nroff
de la página de manual ./foo.1x.gz y lo convierte en un
fichero con formato independiente de dispositivo (dvi). Es
necesario usar la redirección pues la opción -T dirige la
salida al stdout sin paginador. La salida puede verse mediante un
programa como xdvi o puede incluso convertirse al formato
PostScript usando un programa como dvips.
- man -k printf
- Busca la palabra clave printf entre las
descripciones breves y las páginas de manual y presenta todas las que
casen.
- man -f smail
- Busca las páginas de manual referenciadas por
smail e imprime la descripcion breve de las que encuentre.
DESCRIPCIÓN DETALLADA¶
Existen muchas opciones en
man cuyo objeto es dar la mayor flexibilidad
posible al usuario. Se puede cambiar la ruta, el orden de las secciones, el
procesador de salida y otras propiedades y operaciones descritas a
continuación.
Si se activan, varias variables de entorno son interrogadas para determinar el
modo en que opera
man. Se puede activar la variable `conjunta'
$
MANOPT asignándole cualquier cadena en formato de línea de
órdenes con la excepción de que cualquier espacio en un argumento ha
de ser precedido de `\'.
man analizará $
MANOPT antes de
analizar su propia línea de órdenes. Aquellas opciones que tengan
argumentos, se pueden cambiar si se incluyen al invocar man. Para desactivar
todas las opciones activas en $
MANOPT, basta usar
-D como
primera opción en la línea de órdenes. Esto hace que man
`olvide' las opciones de $
MANOPT aunque el contenido de la variable
tiene que ser de todos modos el correcto.
Los útiles de páginas de manual incluidos en el paquete
man-db
hacen uso extenso de cachés
índices de las bases de datos.
Estos cachés contienen información sobre donde se encuentra cada una
de las páginas del manual en el sistema de ficheros y lo que contiene el
whatis (breve descripción de una línea de la página de
manual). Uno de los cometidos de
man es asegurarse de que los
cachés son siempre consistentes. Las bases de datos caché permiten
obviar el uso de software que actualice las bases de datos tipo texto
whatis tradicionales, e incrementan la velocidad de ejecución de
man si se compara con lo que tardaría si tuviese que buscar todo
el sistema de ficheros cada vez que necesitase encontrar la página de
manual adecuada.
Cuando
man no encuentra un fichero
índice de la base de datos
creado por
mandb para una jerarquía de páginas de manual
dada, se efectuará una búsqueda pero será necesario usar
expansión de caracteres comodín para buscar dentro de dicha
jerarquía.
Si
whatis o
apropos no encuentran un
fichero índice
intentarán extraer la información de una base de datos
whatis
tradicional.
Estos útiles permiten el uso de ficheros fuente nroff comprimidos (con
extensiones
.Z,
.z y
.gz). Es posible utilizar cualquier
extensión para las páginas comprimidas pero es necesario conocer
esta información durante la compilación. También, de forma
predeterminada, cualquier página cat generada, se comprime utilizando
gzip. Cualquier jerarquía de páginas de manual `global' como
/usr/man o
/usr/X11R6/man puede utilizar cualquier directorio
como raíz de su jerarquía de páginas cat. De forma tradicional,
se acostumbra a almacenarlas bajo la misma jerarquía que las man, pero
por razones del tipo de las mencionadas en el
Estándar del Sistema de
Ficheros Linux (FSSTND), puede ser más apropiado almacenarlas en
otros lugares.
Si precisa más detalles de cómo se hace, por favor, refiérase a
la página de
manpath(5). Si lo que quiere es enteder las razones,
refiérase al estándar.
Este paquete tiene sorporte internacional. Las páginas en lengua nativa
pueden accederse (si se encuentran disponibles) mediante el uso de las
funciones
locale . Para usarlo, debe bien activar las variables
$
LC_MESSAGES, $
LANG o cualquier variable de entorno del sistema
asignándoles el valor correspondiente a su idioma, generalmente usando el
formato especificado por el estándar
POSIX 1003.1 :
<
idioma>[
_<
territorio>[
.<
conjunto-de-caracteres>[
,<
versión>]]]
Si la página deseada esta disponible en sus informaciones
locale, se
presentará en vez de la página estándar (generalmente en
inglés americano).
Este paquete también incorpora el soporte de catálogos de mensajes
internacionales y es activado del mismo modo, siempre y cuando esté
disponible. En el caso de que las páginas de manual y los catálogos
de mensajes que acompañan este paquete no estén disponibles en su
lengua nativa y si quisiese colaborar en su traducción, por favor
póngase en contacto con el autor que actúa de coordinador.
Si necesita más información sobre otras características y
extensiones disponibles con este paginador de manual, por favor refiérase
a los documentos que se suministran con este paquete.
VALORES PREDETERMINADOS¶
man busca las páginas del manual deseadas en los
índices
bases de datos caché. Si la `busqueda' es infructuosa, se ejecuta una
comprobación de la consistencia de la base de datos caché para
asegurarse de que el caché refleja fielmente el sistema de ficheros.
Generalmente no es necesario ejecutar
mandb una vez que se ha creado el
caché inicial salvo que este quede corrompido.
Una vez se localice una página de manual, se intenta determinar si existe
una página relativa preformateada `cat' más reciente que el fichero
nroff. En caso afirmativo, esta página (generalmente) se descomprime y se
presenta mediante el paginador. Este paginador puede bien especificarse de uno
de los diversos modos o bien se usará el predeterminado (ver opción
-P para más detalles). Si no existe página cat, o si es
más antigua que el fichero nroff, éste último es filtrado y
presentando de forma inmediata.
Si se puede generar un fichero cat (existe un directorio cat relativo y tiene
los permisos apropiados),
man comprimirá y almacenará el
fichero en segundo plano.
Los filtros son descifrados de diversos modos. Primeramente, se intenta usar el
valor de la opción de la línea de órdenes
-p o el
contenido de la variable de entorno $
MANROFFSEQ. Si no se ha usado
-p ni tampoco se ha activado la variable de entorno, la primera
línea del fichero en formato nroff es analizada en busca de una cadena de
preprocesador. Para que esta línea contenga una cadena de preprocesador
válida, su aspecto debe asemejarse a
'\" <
cadena>
donde
cadena puede ser cualquier combinación letras descritas para
la opción
-p más abajo.
Si ninguno de los métodos anteriores proporciona información de
filtrado, se usa el conjunto predeterminado.
Se genera una tubería compuesta por los filtros y el formateador primario
(
nroff o [
tg]
roff con
-t) y se ejecuta.
Alternativamente, si existe en la raiz del árbol man, un programa
ejecutable
mandb_nfmt (o
mandb_tfmt con
-t) será
éste el que se ejecute. Los argumentos que recibirá son la
página de manual fuente, la cadena de preprocesador y, de forma opcional
el dispositivo que se especifique mediante el argumento
-T .
OPCIONES¶
La duplicación de opciones sin argumento tanto en la línea de
órdenes, en $
MANOPT, o en ámbos, no tiene ningún efecto
dañino. Para aquellas opciones que requieren un argumento, cada duplicado
sobreescribe el valor anterior del argumento.
- -l, --local-file
- Activa el modo `local'. Formatéa e imprime las
páginas de manual locales en vez de buscarlas entre la colección
de manuales del sistema. Cada página de manual argumento se supone
fichero fuente en formato nroff. No se genera un fichero cat. Si se
añade '-' a la lista de argumentos, se toma la entrada del
stdin.
- -L locales, --locale=locales
- man normalmente determina su estado de locales
actual mediante una llamada a la función de la biblioteca C
setlocale(3) que interroga varias variables de entorno, entre otras
$LC_MESSAGES y $LANG. Para sobreescribir temporalmente el
valor determinado, puede usar esta opción y suplir la cadena de
locales directamente a man. Es necesario notar que el cambio
no tendrá lugar hasta que comience la búsqueda propiamente
dicha. Salidas como el mensaje de ayuda siempre aparecen según los
locales determinados inicialmente.
- -D, --default
- Esta opción se usa generalmente la primera y restaura
el comportamiento de man al modo predeterminado. Se usa para
restaurar las opciones modificadas mediante $MANOPT. Cualquier
opción que siga a -D producirá el efecto usual.
- -M ruta, --manpath=ruta
- Especifica una ruta de manual alternativa. De forma
predeterminada, man utiliza código derivado de manpath
para determinar la ruta de búsqueda. Esta opción sobreescribe el
valor de la variable de entorno $MANPATH y hace que la opción
-m sea ignorada.
- -P paginador, --pager=paginador
- Especifica que paginador de salida se ha de usar. De forma
predeterminada, man usa pager-s. Esta opción
sobreescribe el valor de la variable de entorno $PAGER y no se
puede usar a la vez que -f o -k.
- -r prompt, --prompt=prompt
- Si se usa una versión reciente del paginador less
, man intentará fijar el prompt y alguna de sus opciones
de forma inteligente. El prompt predeterminado será
Página de
Manual nombre(sección) línea x
donde nombre denota el nombre de la página de manual,
sección denota la sección en la que se ha encontrado
dicha página y x, el renglón actual. Esto se consigue
usando la variable de entorno $LESS.
Si se suministra una cadena mediante la opción -r se
sobreescribe este comportamiento predeterminado. La cadena puede contener
el texto $MAN_PN que se convertirá en el nombre de la
página de manual presentada y su sección rodeada de `(' y `)'.
Así, la cadena que produce el comportamiento predeterminado se
podría expresar como
\ Página\ de\nual\ \$MAN_PN\ ?ltlínea\ %lt?L/%L.:
byte\ %bB?s/%s..?\ (END):?pB %pB\\%..
La cadena se presenta en dos líneas para facilitar su lectura
sólamente. Para entender su significado por favor vea la página
de manual de less(1). La cadena de prompt es evaluada
primero por la shell. Todas las dobles comillas comillas invertidas y
barras invertidas del prompt deben ser precedidas de `\'. Si se termina la
cadena de prompt con `\$', se podrán añadir posteriormente
más opciones de less. De forma predeterminada man usa las
opciones -ix8 .
- -7, --ascii
- Si está viendo una página de manual en
código ascii(7) puro o en una terminal o emulador de terminal
de 7 bits, algunos caracteres puede que no se impriman correctamente si
usa el descriptor de dispositivo latin1(7) con GNU
nroff. Esta opción permite que las páginas en puro
ascii puedan ser presentadas en ascii en un dispositivo
latin1 . No traducira ningún texto en latin1 . La
siguiente tabla explica las traducciones que se realizan.
Descripción |
Octal |
latin1 |
ascii |
|
guión de continuación |
255 |
‐ |
- |
marcador (punto medio) |
267 |
• |
o |
acento agudo |
264 |
´ |
' |
signo de multiplicar |
327 |
× |
x |
Si la columna de latin1 se imprime correctamente, su terminal puede
ser usada con el conjunto latin1 de caracteres y esta opción
no es necesaria. Si las columnas latin1 y ascii son
idénticas, está leyendo la página usando esta opción o
bien man no ha formateado la página usando la descripción
de dispositivo latin1 . Si la columna latin1 no existe o
está mal impresa, es posible que necesite esta opción.
Esta opción es ignorada cuando se usa a la vez que -t, -T
o -Z y puede ser completamente inútil si el nroff usado
es distinto del de GNU.
- -S lista, --sections=lista
- Lista es un compendio de secciones separadas por "dos
puntos" que determina el orden en el que se consultan las secciones
del manual. Esta opción sobreescribe el valor de la variable de
entorno $MANSECT.
- -a, --all
- Por defecto, man termina después de presentar
la página de manual que considera más apropiada de entre las
encontradas. Si usa esta opción, forzará a man a
presentar todas las páginas de manual cuyos nombres respondan a los
criterios de la búsqueda.
- -c, --catman
- Esta opción no es de uso general y debería ser
usada únicamente por el programa catman .
- -d, --debug
- En vez de presentar páginas de manual, imprime
información de depurado.
- -e sub-extensión, --extension=sub-extensión
- Algunos sistemas como por ejemplo el paquete Tcl
incorporan grandes paquetes de páginas de manual a la jerarquía
principal. Para evitar tener dos páginas con un mismo nombre como por
ejemplo exit(3), las páginas de Tcl han sido por lo
general asignadas a la sección l. Esta solución es
desafortunada y actualmente es posible poner las páginas en la
sección correcta y asignarles una `extensión' específica,
en este caso, exit(3tcl). En condiciones normales, man
preferirá presentar exit(3) a exit(3tcl). Para
solventar esta situación y evitar tener que saber a que sección
pertenece la páguina requerida, es posible darle a man una
extensión sub-extension indicando a que paquete tiene que
pertenecer dicha página. Así con el ejemplo anterior, basta
suministrar la opción -e tcl a man para que se
restrinja la búsqueda a páginas que tengan *tcl como
extensión.
- -f, --whatis
- Es equivalente a whatis. Presenta una breve
descripción tomada de la página de manual cuando ésta
está disponible. Véase whatis(1) para más
detalles.
- -h, --help
- Imprime un mensaje de ayuda y termina.
- -k, --apropos
- Es equivalente a apropos. Realiza una busqueda de
palabras clave entre las descripciones breves de las páginas de
manual y presenta las páginas identificadas. Véase
apropos(1) para más detalles.
-m sistema[,...]
, --systems=sistema[,...]
Si este sistema tiene acceso a las
páginas de manual de otro sistema operativo, se puede activar su
búsqueda mediante esta opción. Para buscar en las páginas de
NuevoSO, use la opción
-m NuevoSO. El
sistema
especificado puede ser una lista de nombres de sistemas operativos separada
por comas. Para incluir el sistema operativo nativo en la búsqueda basta
incluir
man como nombre de sistema en la lista de argumentos.
El valor de esta opción sobreescribe el contenido de la variable del
entorno $
SYSTEM.
- -p cadena, --preprocessor=cadena
- Especifica la secuencia de preprocesadores a ejecutar antes
de nroff o troff/groff. No todas las instalaciones
tienen el conjunto completo de preprocesadores. Algunos de los
preprocesadores y de las letras usadas para designarlos son: eqn
(e), grap (g), pic (p), tbl
(t), vgrind (v), refer (r). El valor de
esta opción sobreescribe al contenido de la variable del entorno
$MANROFFSEQ. zsoelim es ejecutado siempre en primer
lugar.
- -u, --update
- Los cachés de los índices de las bases de
datos son acutalizados `sobre la marcha', es decir, no es necesario que
mandb se ejecute periódicamente para mantener la consistencia.
Si la página que busca no se encuentra en los cachés o si se
emplea la opción -a , man automáticamente
comprobará la consistencia de los directorios para asegurar que los
cachés son una representación fiel del sistema de ficheros. Para
forzar una comprobación de consistencia de los `inodos' anterior a la
búsqueda, use la opción -u.
- -t, --troff
- Usa groff -mandoc para formatear las páginas de
manual y escribirlas en el stdout. Esta opción es innecesaria en
conjunción con -T o -Z.
-T dispositivo, --troff-device
[
=dispositivo]
Esta opción permite cambiar la salida
generada por groff (o incluso la de troff) de forma que sea
más apropiada para un dispositivo diferente del predeterminado. Implica
la opción -t. Posibles ejemplos (incluidos en Groff-1.17) son,
dvi, latin1, ps, utf8, X75 y
X100.
- -Z, --ditroff
- groff ejecuta troff y usa un post-procesador
para generar la salida apropiada para el dispositivo seleccionado. Si
groff -mandoc es groff, esta opción se pasa a
groff evitando el uso de un post-procesador. Implica la opción
-t.
- -w, --where, --location
- En vez de imprimir las páginas de manual, sólo
imprime el/los lugar(es) en los que se encuentran los ficheros que
serían formateados o impresos. Si se trata de un fichero cat, se
imprime también la situación del fichero fuente nroff.
- -V, --version
- Imprime la versión y el autor.
ESTADO DE SALIDA¶
- 0
- La ejecución del programa ha terminado con
éxito.
- 1
- Error de uso, sintaxis o del fichero de
configuración.
- 2
- Error operacional.
- 3
- Un proceso hijo ha terminado con estatus no-nulo.
- 16
- Al menos una de las/los páginas/ficheros/palabras
clave no existe o no ha producido ninguna identificación
positiva.
ENTORNO¶
- MANPATH
- Si se activa $MANPATH, su valor determina cual es la
ruta de búsqueda para las páginas del manual.
- MANROFFSEQ
- Si se activa $MANROFFSEQ, su valor determina el
conjunto de preprocesadores que filtran cada página de manual. La
lista predeterminada de preprocesadores depende del sistema.
- MANSECT
- Si se activa $MANSECT, su valor es una lista de
secciones delimitadas por "dos puntos" que permite determinar
qué secciones de manual se usan en la búsqueda y en qué
orden.
- PAGER
- Si se activa $PAGER, su valor determina el nombre
del programa usado para presentar la página de manual. El sistema, de
forma predeterminada, usará pager -s .
- SYSTEM
- Si se activa $SYSTEM, tiene el mismo efecto que la
opción -m cadena donde cadena es el contenido de la variable
$SYSTEM.
- MANOPT
- Si se activa $MANOPT, se analiza antes que la
línea de órdenes de man , suponiéndose que el
formato es similar. Como quiera que todas las demás variables de
entorno específicas de man pueden expresarse como argumentos
de la línea de órdenes y pueden por tanto ser incluidas en
$MANOPT, se espera que se vuelvan obsoletas. N.B.: Todos los
espacios que formen parte del argumento de una opción deben ir
precedidos de `´.
- LANG, LC_MESSAGES
- Dependiendo del sistema y la implementación, una o
ambas $LANG y $LC_MESSAGES son usadas para determinar los
mensajes locales que se van a usar. man imprime los mensajes en
dichos locales (si están disponibles). Veáse setlocale(3)
para más detalles.
FICHEROS¶
- /etc/manpath.config
- fichero de configuración de man-db.
- /usr/man
- Una jerarquía global de páginas de manual
- /usr/man/index.(bt|db|dir|pag)
- Caché de índice de base de datos global
tradicional.
- /var/catman/index.(bt|db|dir|pag)
- Caché del Índice de base de datos
alternativo o conforme al FSSTND.
- /usr/man/mandb_nfmt
- Ejemplo de un guión opcional nroff de formateo
por jerarquía.
- /usr/man/mandb_tfmt
- Ejemplo de un guión opcional [tg]roff de
formateo por jerarquía para usar con -t.
VÉASE TAMBIÉN¶
mandb(8),
manpath(1),
manpath(5),
apropos(1),
whatis(1),
catman(8),
less(1),
nroff(1),
troff(1),
groff(1),
zsoelim(1),
setlocale(3),
man(7),
ascii(7),
latin1(7),
FSSTND.
HISTORIA¶
1990, 1991 - Escrito originalmente por John W. Eaton (jwe@che.utexas.edu).
23 de Diciembre de 1992: Rik Faith (faith@cs.unc.edu) subsanó unos errores
mediante las correcciones proporcionadas por Willem Kasdorp
(wkasdo@nikhefk.nikef.nl).
30 de Abril de 1994 - 23 de Febrero de 2000: Wilf. (G.Wilford@ee.surrey.ac.uk)
ha ido desarrollando y manteniendo este paquete con la ayuda de algunas
personas con gran dedicación.
Traducción realizada por Luis F. González
(luisgh@cogs.susx.ac.uk)