The man Command UNIX Online Documentation

A few examples follow: To become user bjl while retaining the previously exported environment, execute: su bjl • To become user bjl but also change the environment as if bjl had originally logged in, execute: su − bjl • To execute commands with the temporary environment and permissions of user bjl, type: su − bjl −c command args •

3.2 UNIX Online Documentation

3.2.1 The man Command

UNIX has integrated online documentation, which is available to all users and UNIX administrators. It is very hard to imagine successful administration without the extensive online help provided by the UNIX manual pages. Every command, every option, all system calls, and many other details are fully documented and available whenever you need them, and they are always flavor−specific and accurate. The basic online version of the UNIX reference manuals is usually located under the manual page directory usrman, with possible additional topics located in the other man directories dirpathman. The environment variable MANPATH should include all man directories in a complete search of the selected manual page title; otherwise, the system will not be able to find and display the required manual pages. UNIX manual pages are divided into a number of sections, each containing similar topics. The basic section organization is presented in the following table: Contents BSD section System V section User commands 1 1 System calls 2 2 C and other library routines 3 3 Special files, device drivers, hardware 4 7 Configuration files 5 4 Games 6 6 or 1 or NA Miscellaneous commands 7 5 Administration commands 8 1M Maintenance commands 8 8 Note: An older organizational scheme under System V is also in use. Modern UNIX flavors introduced new sections that were usually appended to the existing ones. It is entirely possible for the manual pages to be organized somewhat differently on your UNIX system. 67 ls −F usrman cat−w man1f man3c man3r man4 man7fs man9f cat man1m man3e man3s man4b man7i man9s man.cf man1s man3g man3t man5 man7m man1 man1 man2 man3k man3x man6 man7p mann man1b man3 man3m man3xc man7 man9 windex man1c man3b man3n man3xn man7d man9e The UNIX man command is available to display specific manual pages. The command has several options, but its basic format is: man man_page_title where man_page_title A title we are looking for. If the specified title does not exist, or if it is spelled incorrectly, the system informs us; otherwise the required manual pages will be displayed, page by page. The general format of the displayed manual pages includes the following paragraphs, if applicable: NAME A specified title with a brief description SYNOPSIS A format for using the specified title DESCRIPTION A full description of the specified title OPTIONS Available options for the specified title ADDITIONAL INFO Title−specific additional information such as like environment issues, exceptions, additional explanation, etc. EXAMPLES Examples for further explanation FILES Title−related files SEE ALSO Other related titles The following example for the title man referring to the man command fully documents how to use the man command. man man MAN1 USER COMMANDS MAN1 NAME man — display reference manual pages; find reference pages by keyword • SYNOPSIS man [−] [−t] [−M path] [−T macro−package] [[section] title …]… • man [−M path] −k keyword… • man [−M path] −f filename… • DESCRIPTION 68 A section, when given, applies to the titles that follow it on the command line up to the next section, if any. man looks in the indicated section of the manual for those titles. section is either a digit perhaps followed by a single letter indicating the type of manual page, or one of the words new, local, old, or public. The abbreviations n, l, o, and p are also allowed. If section is omitted, man searches all reference sections giving preference to commands over functions and prints the first manual page it finds. If no manual page is located, man prints an error message. • The reference page sources are typically located in the usrmanman? directories. Since these directories are optionally installed, they may not reside on your host; you may have to mount usrman from a host on which they do reside. If there are preformatted, up−to−date versions in corresponding cat? or fmt? directories, man simply displays or prints those versions. If the preformatted version of interest is out of date or missing, man reformats it prior to display. If directories for the preformatted versions are not provided, man reformats a page whenever it is requested; it uses a temporary file to store the formatted text during display. • If the standard output is not a terminal, or if the − flag is given, man pipes its output through cat1V. Otherwise, man pipes its output through more1 to handle paging and underlining on the screen. • OPTIONS −t man arranges for the specified manual pages to be troffed to a suitable raster output device see troff1 or vtroff1. If both the − and −t flags are given, man updates the troffed versions of each named title if necessary, but does not display them. • −M path Change the search path for manual pages. path is a colon−separated list of directories that contain manual page directory subtrees. For example, usrmanu_man:usrmana_man makes man search in the standard System V locations. When used with the −k or −f options, the −M option must appear first. Each directory in the path is assumed to contain sub−directories of the form man[1–8l−p]. ♦ • −T macro−package man uses macro−package rather than the standard −man macros defined in usrlibtmactmac.an for formatting manual pages. ♦ • −k keyword… man prints out one−line summaries from the whatis database table of contents that contain any of the given keywords. The whatis database is created using the catman8 command with the −w option. ♦ • −f filename… man attempts to locate manual pages related to any of the given filenames. It strips the leading pathname components from each filename, and then prints one−line summaries containing the resulting basename or names. This option also uses the whatis database. ♦ • MANUAL PAGES 69 When formatting a manual page, man examines the first line to determine whether it requires special processing. Referring to Other Manual Pages If the first line of the manual page is a reference to another manual page entry fitting the pattern: .so man?sourcefile ♦ man processes the indicated file in place of the current one. The reference must be expressed as a pathname relative to the root of the manual page directory subtree. ♦ When the second or any subsequent line starts with .so, man ignores it; troff1 or nroff1 processes the request in the usual manner. ♦ • Preprocessing Manual Pages If the first line is a string of the form: \X ♦ where X is separated from the by a single SPACE and consists of any combination of characters in the following list, man pipes its input to troff1 or nroff1 through the corresponding preprocessors. e eqn1, or neqn for nroff r refer1 t tbl1 v vgrind1 ♦ If eqn or neqn is invoked, it will automatically read the file usrpubeqnchar see eqnchar7. If nroff1 is invoked, col1V is automatically used. ♦ • ENVIRONMENT MANPATH If set, its value overrides usrman as the default search path. The −M flag, in turn, overrides this value. PAGER A program to use for interactively delivering man s output to the screen. If not set, more −s see more1 is used. TCAT The name of the program to use to display troffed manual pages. If not set, lpr–t see lpr1 is used. TROFF The name of the formatter to use when the −t flag is given. If not set, troff is used. FILES • usr[share]man root of the standard manual page directory subtree usr[share]manman ? unformatted manual entries 70 usr[share]mancat ?nroffed manual entries usr[share]manfmt ?troffed manual entries usr[share]manwhat is table of contents and keyword database usr[share]libtma ctmac.an standard −man macro package usrpubeqnchar SEE ALSO apropos1, cat1V, col1V, eqn1, lpr1, more1, nroff1, refer1, tbl1, troff1, vgrind1, vtroff1, whatis1, eqnchar7, man7, catman8 NOTES Because troff is not 8−bit clean, man has not been made 8−bit clean. • The −f and −k options use the usrmanwhatis database, which is created by catman8. • BUGS The manual is supposed to be reproducible either on a photo−typesetter or on an ASCII terminal. However, on a terminal some information indicated by font changes, for instance is necessarily lost. • Some dumb terminals cannot process the vertical motions produced by the e eqn1 preprocessing flag. To prevent garbled output on these terminals, when you use e also use t, to invoke col1V implicitly. This workaround has the disadvantage of eliminating superscripts and subscripts even on those terminals that can display them. CTRL−Q will clear a terminal that gets confused by eqn1 output. • Linux provides even more; besides this, for UNIX standard online documentation, Linux also offers Texinfo Manual, which presents more detailed technical descriptions of related topics. Again its use is very simple; by typing info topic−name the required information about the specified topic is displayed.

3.2.2 The whatis Database