man(n) tiles de Pginas de Manual man(n) NOMBRE man - una interfaz de los manuales de referencia electrni- cos SINOPSIS man [-c|-w|-tZT dispositivo] [-adhu7V] [-m sistema[,...]] [-L locale] [-p cadena] [-M ruta] [-P paginador] [-r prompt] [-S lista] [-e extension] [[seccin] pag- ina ...] ... man -l [-7] [-tZT dispositivo] [-p cadena] [-P paginador] [-r prompt] fichero ... man -k [-M ruta] palabra_clave ... man -f [-M ruta] pagina ... DESCRIPCIN man es el paginador del manual del sistema. Las pginas usadas como argumentos al ejecutar man suelen ser normal- mente nombres de programas, tiles o funciones. La pgina de manual associada con cada uno de esos argumentos es buscada y presentada. Si la llamada da tambin la seccin, man buscar slo en dicha seccin del manual. Normalmente, la bsqueda se lleva a cabo en todas las secciones de man- ual disponibles segn un orden predeterminado, y slo se presenta la primera pgina encontrada, incluso si esa pgina se encuentra en varias secciones. La siguiente tabla muestra los nmeros de seccin del manual y los tipos de pginas que contienen. tab (@); l l. 1@Programas ejecutables y guiones del intr- prete de @rdenes 2@Llamadas del sistema (funciones servi- das por el ncleo) 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(n), groff(f). 8@rdenes de admistracin del sistema (generalmente solo son @para root) 9@Rutinas del ncleo [No es estndar] n@nuevo [obsoleto] l@local [obsoleto] p@pblico [obsoleto] o@viejo [obsoleto] Una pgina de manual tiene varias partes. stas estn etiquetadas como NOMBRE, SINOPSIS, DESCRIPCIN, OPCIONES, FICHEROS, VASE TAMBIN, BUGS, y AUTOR. En la seccin SINOPSIS se siguen los siguientes convenios que pueden servir de gua para otras secciones. tab (@); l l. texto en negrita@debe teclear esto exacta- mente. 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. [expresin] ...@la expresin entre corchetes completa @es repetible. El ejemplo del empleo de la orden o funcin debe recoger todos los posibles usos. En algunos casos es recomendable ilustrar algunos usos exclusivos como se puede ver en la SINOPSIS de esta pgina de manual. EJEMPLOS man ls Presenta la pgina de manual del elemento (programa) ls. man -a intro Presenta, secuencialmente, todas las pginas de intro disponibles en el manual. Entre pgina y pgina se puede decidir saltar a la siguiente o salir del paginador completamente. man -t alias | lpr -Pps Formatea la pgina de manual referenciada por `alias', generalmente una pgina de manual de tipo shell, usando el formato predeterminado troff o groff y redirige la salida a la impresora llamada ps. La salida predeter- minada de groff generalmente es PostScript. man --help debera informarle de que procesador est siendo usado con la opcin -t man -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi Esta orden descomprime y formatea el fichero fuente nroff de la pgina de manual ./foo.1x.gz y lo convierte en un fichero con formato independiente de dispositivo (dvi) -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 pginas de manual y presenta todas las que casen. man -f smail Busca las pginas de manual referenciadas por smail e imprime la descripcion breve de las que encuentre. DESCRIPCIN 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 continuacin. Si se activan, varias variables de entorno son interro- gadas para determinar el modo en que opera man. Se puede activar la variable `conjunta' $MANOPT asignndole cualquier cadena en formato de lnea de rdenes con la excepcin de que cualquier espacio en un argumento ha de ser precedido de `\'. man analizar $MANOPT antes de analizar su propia lnea 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 opcin en la lnea 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 pginas de manual incluidos en el paquete man_db hacen uso extenso de cachs ndices de las bases de datos. Estos cachs contienen informacin sobre donde se encuentra cada una de las pginas del manual en el sistema de ficheros y lo que contiene el whatis (breve descripcin de una lnea de la pgina de manual). Uno de los cometidos de man es asegurarse de que los cachs 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 ejecucin de man si se compara con lo que tardara si tuviese que buscar todo el sistema de ficheros cada vez que necesitase encontrar la pgina de manual adecuada. Cuando man no encuentra un fichero ndice de la base de datos creado por mandb para una jerarqua de pginas de man- ual dada, se efectuar una bsqueda pero ser necesario usar expansin de caracteres comodn para buscar dentro de dicha jerarqua. Si whatis o apropos no encuentran un fichero ndice inten- tarn extraer la informacin de una base de datos whatis tradicional. Estos tiles permiten el uso de ficheros fuente nroff com- primidos (con extensiones .Z, .z y .gz). Es posible uti- lizar cualquier extensin para las pginas comprimidas pero es necesario conocer esta informacin durante la compi- lacin. Tambin, de forma predeterminada, cualquier pgina cat generada, se comprime utilizando gzip. Cualquier jer- arqua de pginas de manual `global' como /usr/man o /usr/X11R6/man puede utilizar cualquier directorio como raz de su jerarqua de pginas cat. De forma tradicional, se acostumbra a almacenarlas bajo la misma jerarqua que las man, pero por razones del tipo de las mencionadas en el Estndar del Sistema de Ficheros Linux (FSSTND), puede ser ms apropiado almacenarlas en otros lugares. Si precisa ms detalles de cmo se hace, por favor, refirase a la pgina de manpath(h). Si lo que quiere es enteder las razones, refirase al estndar. Este paquete tiene sorporte internacional. Las pginas 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 estndar POSIX 1003.1 : <idioma>[_<territorio>[.<conjunto-de-carac- teres>[,<versin>]]] Si la pgina deseada esta disponible en sus informaciones locale, se presentar en vez de la pgina estndar (general- mente en ingls americano). Este paquete tambin incorpora el soporte de catlogos de mensajes internacionales y es activado del mismo modo, siempre y cuando est disponible. En el caso de que las pginas de manual y los catlogos de mensajes que acompaan este paquete no estn disponibles en su lengua nativa y si quisiese colaborar en su traduccin, por favor pngase en contacto con el autor que acta de coordinador. Si necesita ms informacin sobre otras caractersticas y extensiones disponibles con este paginador de manual, por favor refirase a los documentos que se suministran con este paquete. VALORES PREDETERMINADOS man busca las pginas del manual deseadas en los ndices bases de datos cach. Si la `busqueda' es infructuosa, se ejecuta una comprobacin de la consistencia de la base de datos cach para asegurarse de que el cach refleja fiel- mente el sistema de ficheros. Generalmente no es nece- sario ejecutar mandb una vez que se ha creado el cach ini- cial salvo que este quede corrompido. Una vez se localice una pgina de manual, se intenta deter- minar si existe una pgina relativa preformateada `cat' ms reciente que el fichero nroff. En caso afirmativo, esta pgina (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 opcin -P para ms detalles). Si no existe pgina cat, o si es ms antigua que el fichero nroff, ste ltimo es fil- trado y presentando de forma inmediata. Si se puede generar un fichero cat (existe un directorio cat relativo y tiene los permisos apropiados), man com- primir y almacenar el fichero en segundo plano. Los filtros son descifrados de diversos modos. Primera- mente, se intenta usar el valor de la opcin de la lnea de rdenes -p o el contenido de la variable de entorno $MAN- ROFFSEQ. Si no se ha usado -p ni tampoco se ha activado la variable de entorno, la primera lnea del fichero en formato nroff es analizada en busca de una cadena de pre- procesador. Para que esta lnea contenga una cadena de pre- procesador vlida, su aspecto debe asemejarse a '\" <cadena> donde cadena puede ser cualquier combinacin letras descritas para la opcin -p ms abajo. Si ninguno de los mtodos anteriores proporciona informacin de filtrado, se usa el conjunto predeterminado. Se genera una tubera compuesta por los filtros y el for- mateador 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 pgina de manual fuente, la cadena de preprocesador y, de forma opcional el dispositivo que se especifique mediante el argumento -T . OPCIONES La duplicacin de opciones sin argumento tanto en la lnea de rdenes, en $MANOPT, o en mbos, no tiene ningn efecto daino. Para aquellas opciones que requieren un argumento, cada duplicado sobreescribe el valor anterior del argu- mento. -l, --local-file Activa el modo `local'. Formata e imprime las pgi- nas de manual locales en vez de buscarlas entre la coleccin de manuales del sistema. Cada pgina de manual argumento se supone fichero fuente en for- mato nroff. No se genera un fichero cat. Si se aade '-' 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 funcin de la bib- lioteca C setlocale(e) que interroga varias vari- ables de entorno, entre otras $LC_MESSAGES y $LANG. Para sobreescribir temporalmente el valor determi- nado, puede usar esta opcin y suplir la cadena de locales directamente a man. Es necesario notar que el cambio no tendr lugar hasta que comience la bsqueda propiamente dicha. Salidas como el mensaje de ayuda siempre aparecen segn los locales determi- nados inicialmente. -D, --default Esta opcin se usa generalmente la primera y restaura el comportamiento de man al modo predeter- minado. Se usa para restaurar las opciones modifi- cadas mediante $MANOPT. Cualquier opcin que siga a -D producir el efecto usual. -M ruta, --manpath=ruta Especifica una ruta de manual alternativa. De forma predeterminada, man utiliza cdigo derivado de man- path para determinar la ruta de bsqueda. Esta opcin sobreescribe el valor de la variable de entorno $MANPATH y hace que la opcin -m sea ignorada. -P paginador, --pager=paginador Especifica que paginador de salida se ha de usar. De forma predeterminada, man usa exec /usr/bin/pager -s. Esta opcin 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 versin reciente del paginador less , man intentar fijar el prompt y alguna de sus opciones de forma inteligente. El prompt predeter- minado ser Pgina de Manual nombre(e) lnea x donde nombre denota el nombre de la pgina de man- ual, seccin denota la seccin en la que se ha encon- trado dicha pgina y x, el rengln actual. Esto se consigue usando la variable de entorno $LESS. Si se suministra una cadena mediante la opcin -r se sobreescribe este comportamiento predeterminado. La cadena puede contener el texto $MAN_PN que se convertir en el nombre de la pgina de manual pre- sentada y su seccin rodeada de `(' y `)'. As, la cadena que produce el comportamiento predeterminado se podra expresar como \ Pgina\ de\Manual\ \$MAN_PN\ ?ltlnea\ %lt?L/%L.: byte\ %bB?s/%s..?\ (END):?pB %pB\\%.. La cadena se presenta en dos lneas para facilitar su lectura slamente. Para entender su significado por favor vea la pgina de manual de less(s). 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 podrn aadir posteriormente ms opciones de less. De forma predeterminada man usa las opciones -ix8 . -7, --ascii Si est viendo una pgina de manual en cdigo ascii(i) 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(1) con GNU nroff. Esta opcin permite que las pginas en puro ascii puedan ser presentadas en ascii en un dispositivo latin1 . No traducira ningn texto en latin1 . La siguiente tabla explica las traducciones que se realizan. tab (@); l c c c. Descripcin@Octal@latin1@ascii _ guin de continuacin@255@@- marcador (punto medio)@267@o@o acento agudo@264@'@' signo de multi- plicar@327@x@x Si la columna de latin1 se imprime correctamente, su terminal puede ser usada con el conjunto latin1 de caracteres y esta opcin no es necesaria. Si las columnas latin1 y ascii son idnticas, est leyendo la pgina usando esta opcin o bien man no ha for- mateado la pgina usando la descripcin de disposi- tivo latin1 . Si la columna latin1 no existe o est mal impresa, es posible que necesite esta opcin. Esta opcin es ignorada cuando se usa a la vez que -t, -T o -Z y puede ser completamente intil 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 opcin sobreescribe el valor de la variable de entorno $MANSECT. -a, --all Por defecto, man termina despus de presentar la pgina de manual que considera ms apropiada de entre las encontradas. Si usa esta opcin, forzar a man a presentar todas las pginas de manual cuyos nombres respondan a los criterios de la bsqueda. -c, --catman Esta opcin no es de uso general y debera ser usada nicamente por el programa catman . -d, --debug En vez de presentar pginas de manual, imprime informacin de depurado. -e sub-extensin, --extension=sub-extensin Algunos sistemas como por ejemplo el paquete Tcl incorporan grandes paquetes de pginas de manual a la jerarqua principal. Para evitar tener dos pgi- nas con un mismo nombre como por ejemplo exit(t), las pginas de Tcl han sido por lo general asignadas a la seccin l. Esta solucin es desafortunada y actualmente es posible poner las pginas en la sec- cin correcta y asignarles una `extensin' especfica, en este caso, exit(t). En condiciones normales, man preferir presentar exit(t) a exit(t). Para solventar esta situacin y evitar tener que saber a que seccin pertenece la pguina requerida, es posi- ble darle a man una extensin indicando a que paquete tiene que pertenecer dicha pgina. As con el ejemplo anterior, basta suministrar la opcin -e tcl a man para que se restrinja la bsqueda a pginas que tengan *tcl como extensin. -f, --whatis Es equivalente a whatis. Presenta una breve descripcin tomada de la pgina de manual cuando sta est disponible. Vase whatis(s) para ms 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 pginas de manual y presenta las pginas identi- ficadas. Vase apropos(s) para ms detalles. -m sistema[,...], --systems=sistema[,...] Si este sistema tiene acceso a las pginas de manual de otro sistema operativo, se puede activar su bsqueda mediante esta opcin. Para buscar en las pginas de NuevoSO, use la opcin -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 bsqueda basta incluir man como nombre de sistema en la lista de argumentos. El valor de esta opcin sobreescribe el contenido de la variable del entorno $SYSTEM. -p cadena, --preprocessor=cadena Especifica la secuencia de preprocesadores a ejecu- tar antes de nroff o troff/groff. No todas las instalaciones tienen el conjunto completo de pre- procesadores. 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 opcin sobreescribe al contenido de la variable del entorno $MANROFFSEQ. zsoelim es ejecutado siempre en primer lugar. -u, --update Los cachs de los ndices de las bases de datos son acutalizados `sobre la marcha', es decir, no es necesario que mandb se ejecute peridicamente para mantener la consistencia. Si la pgina que busca no se encuentra en los cachs o si se emplea la opcin -a , man automticamente comprobar la consistencia de los directorios para asegurar que los cachs son una representacin fiel del sistema de ficheros. Para forzar una comprobacin de consistencia de los `inodos' anterior a la bsqueda, use la opcin -u. -t, --troff Usa /usr/bin/groff -mandoc para formatear las pgi- nas de manual y escribirlas en el stdout. Esta opcin es innecesaria en conjuncin con -T o -Z. -T dispositivo, --troff-device [=dispositivo] Esta opcin permite cambiar la salida generada por groff (o incluso la de troff) de forma que sea ms apropiada para un dispositivo diferente del prede- terminado. Implica la opcin -t. Posibles ejemplos (incluidos en Groff-1.09) son, dvi, latin1, X75 and X100. -Z, --ditroff groff ejecuta troff y usa un post-procesador para generar la salida apropiada para el dispositivo seleccionado. Si /usr/bin/groff -mandoc es groff, esta opcin se pasa a groff evitando el uso de un post-procesador. Implica la opcin -t. -w, --where, --location En vez de imprimir las pginas de manual, slo imprime el/los lugar(r) en los que se encuentran los ficheros que seran formateados o impresos. Si se trata de un fichero cat, se imprime tambin la situacin del fichero fuente nroff. -V, --version Imprime la versin y el autor. ESTADO DE SALIDA 0 La ejecucin del programa ha terminado con xito. 1 Error de uso, sintaxis o del fichero de configu- racin. 2 Error operacional. 3 Un proceso hijo ha terminado con estatus no-nulo. 16 Al menos una de las/los pginas/ficheros/palabras clave no existe o no ha producido ninguna identifi- cacin positiva. ENTORNO MANPATH Si se activa $MANPATH, su valor determina cual es la ruta de bsqueda para las pginas del manual. MANROFFSEQ Si se activa $MANROFFSEQ, su valor determina el conjunto de preprocesadores que filtran cada pgina de manual. La lista predeterminada de preproce- sadores 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 bsqueda y en qu orden. PAGER Si se activa $PAGER, su valor determina el nombre del programa usado para presentar la pgina de man- ual. El sistema, de forma predeterminada, usar exec /usr/bin/pager -s . SYSTEM Si se activa $SYSTEM, tiene el mismo efecto que la opcin -m cadena donde cadena es el contenido de la variable $SYSTEM. MANOPT Si se activa $MANOPT, se analiza antes que la lnea de rdenes de man , suponindose que el formato es similar. Como quiera que todas las dems variables de entorno especficas de man pueden expresarse como argumentos de la lnea 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 opcin deben ir precedi- dos de `'. LANG, LC_MESSAGES Dependiendo del sistema y la implementacin, una o ambas $LANG y $LC_MESSAGES son usadas para determi- nar los mensajes locales que se van a usar. man imprime los mensajes en dichos locales (si estn disponibles). Vese setlocale(e) para ms detalles. FICHEROS /etc/manpath.config fichero de configuracin de man_db. /usr/man Una jerarqua global de pginas 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 con- forme al FSSTND. /usr/man/mandb_nfmt Ejemplo de un guin opcional nroff de formateo por jerarqua. /usr/man/mandb_tfmt Ejemplo de un guin opcional [tg]roff de formateo por jerarqua para usar con -t. VASE TAMBIN mandb(b), manpath(h), manpath(h), apropos(s), whatis(s), catman(n), less(s), nroff(f), troff(f), groff(f), zsoe- lim(m), setlocale(e), man(n), ascii(i), latin1(1), 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) sub- san 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 mante- niendo este paquete con la ayuda de algunas personas con gran dedicacin. Traduccin realizada por Luis F. Gonzlez (luisgh@cogs.susx.ac.uk) 2.3.20 07 September 2001 man(n)