logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

man.1 (9833B)


  1. .\" $Id: man.1,v 1.40 2020/07/20 16:57:30 schwarze Exp $
  2. .\"
  3. .\" Copyright (c) 1989, 1990, 1993
  4. .\" The Regents of the University of California. All rights reserved.
  5. .\" Copyright (c) 2003, 2007, 2008, 2014 Jason McIntyre <jmc@openbsd.org>
  6. .\" Copyright (c) 2010, 2011, 2014-2020 Ingo Schwarze <schwarze@openbsd.org>
  7. .\"
  8. .\" Redistribution and use in source and binary forms, with or without
  9. .\" modification, are permitted provided that the following conditions
  10. .\" are met:
  11. .\" 1. Redistributions of source code must retain the above copyright
  12. .\" notice, this list of conditions and the following disclaimer.
  13. .\" 2. Redistributions in binary form must reproduce the above copyright
  14. .\" notice, this list of conditions and the following disclaimer in the
  15. .\" documentation and/or other materials provided with the distribution.
  16. .\" 3. Neither the name of the University nor the names of its contributors
  17. .\" may be used to endorse or promote products derived from this software
  18. .\" without specific prior written permission.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30. .\" SUCH DAMAGE.
  31. .\"
  32. .\" @(#)man.1 8.2 (Berkeley) 1/2/94
  33. .\"
  34. .Dd $Mdocdate: July 20 2020 $
  35. .Dt MAN 1
  36. .Os
  37. .Sh NAME
  38. .Nm man
  39. .Nd display manual pages
  40. .Sh SYNOPSIS
  41. .Nm man
  42. .Op Fl acfhklw
  43. .Op Fl C Ar file
  44. .Op Fl M Ar path
  45. .Op Fl m Ar path
  46. .Op Fl S Ar subsection
  47. .Op Oo Fl s Oc Ar section
  48. .Ar name ...
  49. .Sh DESCRIPTION
  50. The
  51. .Nm
  52. utility
  53. displays the
  54. manual page entitled
  55. .Ar name .
  56. Pages may be selected according to
  57. a specific category
  58. .Pq Ar section
  59. or
  60. machine architecture
  61. .Pq Ar subsection .
  62. .Pp
  63. The options are as follows:
  64. .Bl -tag -width Ds
  65. .It Fl a
  66. Display all matching manual pages.
  67. .It Fl C Ar file
  68. Use the specified
  69. .Ar file
  70. instead of the default configuration file.
  71. This permits users to configure their own manual environment.
  72. See
  73. .Xr man.conf 5
  74. for a description of the contents of this file.
  75. .It Fl c
  76. Copy the manual page to the standard output instead of using
  77. .Xr less 1
  78. to paginate it.
  79. This is done by default if the standard output is not a terminal device.
  80. .Pp
  81. When using
  82. .Fl c ,
  83. most terminal devices are unable to show the markup.
  84. To print the output of
  85. .Nm
  86. to the terminal with markup but without using a pager, pipe it to
  87. .Xr ul 1 .
  88. To remove the markup, pipe the output to
  89. .Xr col 1
  90. .Fl b
  91. instead.
  92. .It Fl f
  93. A synonym for
  94. .Xr whatis 1 .
  95. It searches for
  96. .Ar name
  97. in manual page names and displays the header lines from all matching pages.
  98. The search is case insensitive and matches whole words only.
  99. .It Fl h
  100. Display only the SYNOPSIS lines of the requested manual pages.
  101. Implies
  102. .Fl a
  103. and
  104. .Fl c .
  105. .It Fl k
  106. A synonym for
  107. .Xr apropos 1 .
  108. Instead of
  109. .Ar name ,
  110. an expression can be provided using the syntax described in the
  111. .Xr apropos 1
  112. manual.
  113. By default, it displays the header lines of all matching pages.
  114. .It Fl l
  115. A synonym for
  116. .Xr mandoc 1 .
  117. The
  118. .Ar name
  119. arguments are interpreted as filenames.
  120. No search is done and
  121. .Ar file ,
  122. .Ar path ,
  123. .Ar section ,
  124. .Ar subsection ,
  125. and
  126. .Fl w
  127. are ignored.
  128. This option implies
  129. .Fl a .
  130. .It Fl M Ar path
  131. Override the list of directories to search for manual pages.
  132. The supplied
  133. .Ar path
  134. must be a colon
  135. .Pq Ql \&:
  136. separated list of directories.
  137. This option also overrides the environment variable
  138. .Ev MANPATH
  139. and any directories specified in the
  140. .Xr man.conf 5
  141. file.
  142. .It Fl m Ar path
  143. Augment the list of directories to search for manual pages.
  144. The supplied
  145. .Ar path
  146. must be a colon
  147. .Pq Ql \&:
  148. separated list of directories.
  149. These directories will be searched before those specified using the
  150. .Fl M
  151. option, the
  152. .Ev MANPATH
  153. environment variable, the
  154. .Xr man.conf 5
  155. file, or the default directories.
  156. .It Fl S Ar subsection
  157. Only show pages for the specified
  158. .Xr machine 1
  159. architecture.
  160. .Ar subsection
  161. is case insensitive.
  162. .Pp
  163. By default manual pages for all architectures are installed.
  164. Therefore this option can be used to view pages for one
  165. architecture whilst using another.
  166. .Pp
  167. This option overrides the
  168. .Ev MACHINE
  169. environment variable.
  170. .Tg s
  171. .It Oo Fl s Oc Ar section
  172. Only select manuals from the specified
  173. .Ar section .
  174. The currently available sections are:
  175. .Pp
  176. .Bl -tag -width "localXXX" -offset indent -compact
  177. .It 1
  178. General commands
  179. .Pq tools and utilities .
  180. .It 2
  181. System calls and error numbers.
  182. .It 3
  183. Library functions.
  184. .It 3p
  185. .Xr perl 1
  186. programmer's reference guide.
  187. .It 4
  188. Device drivers.
  189. .It 5
  190. File formats.
  191. .It 6
  192. Games.
  193. .It 7
  194. Miscellaneous information.
  195. .It 8
  196. System maintenance and operation commands.
  197. .It 9
  198. Kernel internals.
  199. .El
  200. .It Fl w
  201. List the pathnames of all matching manual pages instead of displaying
  202. any of them.
  203. If no
  204. .Ar name
  205. is given, list the directories that would be searched.
  206. .El
  207. .Pp
  208. The options
  209. .Fl IKOTW
  210. are also supported and are documented in
  211. .Xr mandoc 1 .
  212. The options
  213. .Fl fkl
  214. are mutually exclusive and override each other.
  215. .Pp
  216. The search starts with the
  217. .Fl m
  218. argument if provided, then continues with the
  219. .Fl M
  220. argument, the
  221. .Ev MANPATH
  222. variable, the
  223. .Ic manpath
  224. entries in the
  225. .Xr man.conf 5
  226. file, or with
  227. .Pa /usr/share/man : Ns Pa /usr/X11R6/man : Ns Pa /usr/local/man
  228. by default.
  229. Within each of these, directories are searched in the order provided.
  230. Within each directory, the search proceeds according to the following
  231. list of sections: 1, 8, 6, 2, 3, 5, 7, 4, 9, 3p.
  232. The first match found is shown.
  233. .Pp
  234. The
  235. .Xr mandoc.db 5
  236. database is used for looking up manual page entries.
  237. In cases where the database is absent, outdated, or corrupt,
  238. .Nm
  239. falls back to looking for files called
  240. .Ar name . Ns Ar section .
  241. If both a formatted and an unformatted version of the same manual page,
  242. for example
  243. .Pa cat1/foo.0
  244. and
  245. .Pa man1/foo.1 ,
  246. exist in the same directory, only the unformatted version is used.
  247. The database is kept up to date with
  248. .Xr makewhatis 8 ,
  249. which is run by the
  250. .Xr weekly 8
  251. maintenance script.
  252. .Pp
  253. Guidelines for writing
  254. man pages can be found in
  255. .Xr mdoc 7 .
  256. .Sh ENVIRONMENT
  257. .Bl -tag -width MANPATHX
  258. .It Ev MACHINE
  259. As some manual pages are intended only for specific architectures,
  260. .Nm
  261. searches any subdirectories,
  262. with the same name as the current architecture,
  263. in every directory which it searches.
  264. Machine specific areas are checked before general areas.
  265. The current machine type may be overridden by setting the environment
  266. variable
  267. .Ev MACHINE
  268. to the name of a specific architecture,
  269. or with the
  270. .Fl S
  271. option.
  272. .Ev MACHINE
  273. is case insensitive.
  274. .It Ev MANPAGER
  275. Any non-empty value of the environment variable
  276. .Ev MANPAGER
  277. is used instead of the standard pagination program,
  278. .Xr less 1 .
  279. If
  280. .Xr less 1
  281. is used, the interactive
  282. .Ic :t
  283. command can be used to go to the definitions of various terms, for
  284. example command line options, command modifiers, internal commands,
  285. environment variables, function names, preprocessor macros,
  286. .Xr errno 2
  287. values, and some other emphasized words.
  288. Some terms may have defining text at more than one place.
  289. In that case, the
  290. .Xr less 1
  291. interactive commands
  292. .Ic t
  293. and
  294. .Ic T
  295. can be used to move to the next and to the previous place providing
  296. information about the term last searched for with
  297. .Ic :t .
  298. The
  299. .Fl O Cm tag Ns Op = Ns Ar term
  300. option documented in the
  301. .Xr mandoc 1
  302. manual opens a manual page at the definition of a specific
  303. .Ar term
  304. rather than at the beginning.
  305. .It Ev MANPATH
  306. Override the standard search path which is either specified in
  307. .Xr man.conf 5
  308. or the default path.
  309. The format of
  310. .Ev MANPATH
  311. is a colon
  312. .Pq Ql \&:
  313. separated list of directories.
  314. Invalid directories are ignored.
  315. Overridden by
  316. .Fl M ,
  317. ignored if
  318. .Fl l
  319. is specified.
  320. .Pp
  321. If
  322. .Ev MANPATH
  323. begins with a colon, it is appended to the standard path;
  324. if it ends with a colon, it is prepended to the standard path;
  325. or if it contains two adjacent colons,
  326. the standard path is inserted between the colons.
  327. .It Ev PAGER
  328. Specifies the pagination program to use when
  329. .Ev MANPAGER
  330. is not defined.
  331. If neither PAGER nor MANPAGER is defined,
  332. .Xr less 1
  333. is used.
  334. .El
  335. .Sh FILES
  336. .Bl -tag -width /etc/man.conf -compact
  337. .It Pa /etc/man.conf
  338. default
  339. .Nm
  340. configuration file
  341. .El
  342. .Sh EXIT STATUS
  343. .Ex -std man
  344. See
  345. .Xr mandoc 1
  346. for details.
  347. .Sh EXAMPLES
  348. Format a page for pasting extracts into an email message \(em
  349. avoid printing any UTF-8 characters, reduce the width to ease
  350. quoting in replies, and remove markup:
  351. .Pp
  352. .Dl $ man -T ascii -O width=65 pledge | col -b
  353. .Pp
  354. Read a typeset page in a PDF viewer:
  355. .Pp
  356. .Dl $ MANPAGER=mupdf man -T pdf lpd
  357. .Sh SEE ALSO
  358. .Xr apropos 1 ,
  359. .Xr col 1 ,
  360. .Xr mandoc 1 ,
  361. .Xr ul 1 ,
  362. .Xr whereis 1 ,
  363. .Xr man.conf 5 ,
  364. .Xr mdoc 7
  365. .Sh STANDARDS
  366. The
  367. .Nm
  368. utility is compliant with the
  369. .St -p1003.1-2008
  370. specification.
  371. .Pp
  372. The flags
  373. .Op Fl aCcfhIKlMmOSsTWw ,
  374. as well as the environment variables
  375. .Ev MACHINE ,
  376. .Ev MANPAGER ,
  377. and
  378. .Ev MANPATH ,
  379. are extensions to that specification.
  380. .Sh HISTORY
  381. A
  382. .Nm
  383. command first appeared in
  384. .At v2 .
  385. .Pp
  386. The
  387. .Fl w
  388. option first appeared in
  389. .At v7 ;
  390. .Fl f
  391. and
  392. .Fl k
  393. in
  394. .Bx 4 ;
  395. .Fl M
  396. in
  397. .Bx 4.3 ;
  398. .Fl a
  399. in
  400. .Bx 4.3 Tahoe ;
  401. .Fl c
  402. and
  403. .Fl m
  404. in
  405. .Bx 4.3 Reno ;
  406. .Fl h
  407. in
  408. .Bx 4.3 Net/2 ;
  409. .Fl C
  410. in
  411. .Nx 1.0 ;
  412. .Fl s
  413. and
  414. .Fl S
  415. in
  416. .Ox 2.3 ;
  417. and
  418. .Fl I ,
  419. .Fl K ,
  420. .Fl l ,
  421. .Fl O ,
  422. and
  423. .Fl W
  424. in
  425. .Ox 5.7 .
  426. The
  427. .Fl T
  428. option first appeared in
  429. .At III
  430. and was also added in
  431. .Ox 5.7 .