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

apropos.1 (10983B)


  1. .\" $Id: apropos.1,v 1.51 2020/10/01 22:50:00 schwarze Exp $
  2. .\"
  3. .\" Copyright (c) 2011, 2012 Kristaps Dzonsons <kristaps@bsd.lv>
  4. .\" Copyright (c) 2011,2012,2014,2017,2018 Ingo Schwarze <schwarze@openbsd.org>
  5. .\"
  6. .\" Permission to use, copy, modify, and distribute this software for any
  7. .\" purpose with or without fee is hereby granted, provided that the above
  8. .\" copyright notice and this permission notice appear in all copies.
  9. .\"
  10. .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11. .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12. .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13. .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14. .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15. .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16. .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17. .\"
  18. .Dd $Mdocdate: October 1 2020 $
  19. .Dt APROPOS 1
  20. .Os
  21. .Sh NAME
  22. .Nm apropos ,
  23. .Nm whatis
  24. .Nd search manual page databases
  25. .Sh SYNOPSIS
  26. .Nm
  27. .Op Fl afk
  28. .Op Fl C Ar file
  29. .Op Fl M Ar path
  30. .Op Fl m Ar path
  31. .Op Fl O Ar outkey
  32. .Op Fl S Ar arch
  33. .Op Fl s Ar section
  34. .Ar expression ...
  35. .Sh DESCRIPTION
  36. The
  37. .Nm apropos
  38. and
  39. .Nm whatis
  40. utilities query manual page databases generated by
  41. .Xr makewhatis 8 ,
  42. evaluating
  43. .Ar expression
  44. for each file in each database.
  45. By default, they display the names, section numbers, and description lines
  46. of all matching manuals.
  47. .Pp
  48. By default,
  49. .Nm
  50. searches for
  51. .Xr makewhatis 8
  52. databases in the default paths stipulated by
  53. .Xr man 1
  54. and uses case-insensitive extended regular expression matching
  55. over manual names and descriptions
  56. .Pq the Li \&Nm No and Li \&Nd No macro keys .
  57. Multiple terms imply pairwise
  58. .Fl o .
  59. .Pp
  60. .Nm whatis
  61. is a synonym for
  62. .Nm
  63. .Fl f .
  64. .Pp
  65. The options are as follows:
  66. .Bl -tag -width Ds
  67. .It Fl a
  68. Instead of showing only the title lines, show the complete manual pages,
  69. just like
  70. .Xr man 1
  71. .Fl a
  72. would.
  73. If the standard output is a terminal device and
  74. .Fl c
  75. is not specified, use
  76. .Xr less 1
  77. to paginate them.
  78. In
  79. .Fl a
  80. mode, the options
  81. .Fl IKOTW
  82. described in the
  83. .Xr mandoc 1
  84. manual are also available.
  85. .It Fl C Ar file
  86. Specify an alternative configuration
  87. .Ar file
  88. in
  89. .Xr man.conf 5
  90. format.
  91. .It Fl f
  92. Search for all words in
  93. .Ar expression
  94. in manual page names only.
  95. The search is case-insensitive and matches whole words only.
  96. In this mode, macro keys, comparison operators, and logical operators
  97. are not available.
  98. .It Fl k
  99. Support the full
  100. .Ar expression
  101. syntax.
  102. It is the default for
  103. .Nm .
  104. .It Fl M Ar path
  105. Use the colon-separated path instead of the default list of paths
  106. searched for
  107. .Xr makewhatis 8
  108. databases.
  109. Invalid paths, or paths without manual databases, are ignored.
  110. .It Fl m Ar path
  111. Prepend the colon-separated paths to the list of paths searched
  112. for
  113. .Xr makewhatis 8
  114. databases.
  115. Invalid paths, or paths without manual databases, are ignored.
  116. .It Fl O Ar outkey
  117. Show the values associated with the key
  118. .Ar outkey
  119. instead of the manual descriptions.
  120. .It Fl S Ar arch
  121. Restrict the search to pages for the specified
  122. .Xr machine 1
  123. architecture.
  124. .Ar arch
  125. is case-insensitive.
  126. By default, pages for all architectures are shown.
  127. .It Fl s Ar section
  128. Restrict the search to the specified section of the manual.
  129. By default, pages from all sections are shown.
  130. See
  131. .Xr man 1
  132. for a listing of sections.
  133. .El
  134. .Pp
  135. The options
  136. .Fl chlw
  137. are also supported and are documented in
  138. .Xr man 1 .
  139. The options
  140. .Fl fkl
  141. are mutually exclusive and override each other.
  142. .Pp
  143. An
  144. .Ar expression
  145. consists of search terms joined by logical operators
  146. .Fl a
  147. .Pq and
  148. and
  149. .Fl o
  150. .Pq or .
  151. The
  152. .Fl a
  153. operator has precedence over
  154. .Fl o
  155. and both are evaluated left-to-right.
  156. .Bl -tag -width Ds
  157. .It \&( Ar expr No \&)
  158. True if the subexpression
  159. .Ar expr
  160. is true.
  161. .It Ar expr1 Fl a Ar expr2
  162. True if both
  163. .Ar expr1
  164. and
  165. .Ar expr2
  166. are true (logical
  167. .Sq and ) .
  168. .It Ar expr1 Oo Fl o Oc Ar expr2
  169. True if
  170. .Ar expr1
  171. and/or
  172. .Ar expr2
  173. evaluate to true (logical
  174. .Sq or ) .
  175. .It Ar term
  176. True if
  177. .Ar term
  178. is satisfied.
  179. This has syntax
  180. .Sm off
  181. .Oo
  182. .Op Ar key Op , Ar key ...
  183. .Pq Cm = | \(ti
  184. .Oc
  185. .Ar val ,
  186. .Sm on
  187. where
  188. .Ar key
  189. is an
  190. .Xr mdoc 7
  191. macro to query and
  192. .Ar val
  193. is its value.
  194. See
  195. .Sx Macro Keys
  196. for a list of available keys.
  197. Operator
  198. .Cm =
  199. evaluates a substring, while
  200. .Cm \(ti
  201. evaluates a case-sensitive extended regular expression.
  202. .It Fl i Ar term
  203. If
  204. .Ar term
  205. is a regular expression, it
  206. is evaluated case-insensitively.
  207. Has no effect on substring terms.
  208. .El
  209. .Pp
  210. Results are sorted first according to the section number in ascending
  211. numerical order, then by the page name in ascending
  212. .Xr ascii 7
  213. alphabetical order, case-insensitive.
  214. .Pp
  215. Each output line is formatted as
  216. .Pp
  217. .D1 name[, name...](sec) \- description
  218. .Pp
  219. Where
  220. .Dq name
  221. is the manual's name,
  222. .Dq sec
  223. is the manual section, and
  224. .Dq description
  225. is the manual's short description.
  226. If an architecture is specified for the manual, it is displayed as
  227. .Pp
  228. .D1 name(sec/arch) \- description
  229. .Pp
  230. Resulting manuals may be accessed as
  231. .Pp
  232. .Dl $ man \-s sec name
  233. .Pp
  234. If an architecture is specified in the output, use
  235. .Pp
  236. .Dl $ man \-s sec \-S arch name
  237. .Ss Macro Keys
  238. Queries evaluate over a subset of
  239. .Xr mdoc 7
  240. macros indexed by
  241. .Xr makewhatis 8 .
  242. In addition to the macro keys listed below, the special key
  243. .Cm any
  244. may be used to match any available macro key.
  245. .Pp
  246. Names and description:
  247. .Bl -column "xLix" description -offset indent -compact
  248. .It Li \&Nm Ta manual name
  249. .It Li \&Nd Ta one-line manual description
  250. .It Li arch Ta machine architecture (case-insensitive)
  251. .It Li sec Ta manual section number
  252. .El
  253. .Pp
  254. Sections and cross references:
  255. .Bl -column "xLix" description -offset indent -compact
  256. .It Li \&Sh Ta section header (excluding standard sections)
  257. .It Li \&Ss Ta subsection header
  258. .It Li \&Xr Ta cross reference to another manual page
  259. .It Li \&Rs Ta bibliographic reference
  260. .El
  261. .Pp
  262. Semantic markup for command line utilities:
  263. .Bl -column "xLix" description -offset indent -compact
  264. .It Li \&Fl Ta command line options (flags)
  265. .It Li \&Cm Ta command modifier
  266. .It Li \&Ar Ta command argument
  267. .It Li \&Ic Ta internal or interactive command
  268. .It Li \&Ev Ta environmental variable
  269. .It Li \&Pa Ta file system path
  270. .El
  271. .Pp
  272. Semantic markup for function libraries:
  273. .Bl -column "xLix" description -offset indent -compact
  274. .It Li \&Lb Ta function library name
  275. .It Li \&In Ta include file
  276. .It Li \&Ft Ta function return type
  277. .It Li \&Fn Ta function name
  278. .It Li \&Fa Ta function argument type and name
  279. .It Li \&Vt Ta variable type
  280. .It Li \&Va Ta variable name
  281. .It Li \&Dv Ta defined variable or preprocessor constant
  282. .It Li \&Er Ta error constant
  283. .It Li \&Ev Ta environmental variable
  284. .El
  285. .Pp
  286. Various semantic markup:
  287. .Bl -column "xLix" description -offset indent -compact
  288. .It Li \&An Ta author name
  289. .It Li \&Lk Ta hyperlink
  290. .It Li \&Mt Ta Do mailto Dc hyperlink
  291. .It Li \&Cd Ta kernel configuration declaration
  292. .It Li \&Ms Ta mathematical symbol
  293. .It Li \&Tn Ta tradename
  294. .El
  295. .Pp
  296. Physical markup:
  297. .Bl -column "xLix" description -offset indent -compact
  298. .It Li \&Em Ta italic font or underline
  299. .It Li \&Sy Ta boldface font
  300. .It Li \&Li Ta typewriter font
  301. .El
  302. .Pp
  303. Text production:
  304. .Bl -column "xLix" description -offset indent -compact
  305. .It Li \&St Ta reference to a standards document
  306. .It Li \&At Ta At No version reference
  307. .It Li \&Bx Ta Bx No version reference
  308. .It Li \&Bsx Ta Bsx No version reference
  309. .It Li \&Nx Ta Nx No version reference
  310. .It Li \&Fx Ta Fx No version reference
  311. .It Li \&Ox Ta Ox No version reference
  312. .It Li \&Dx Ta Dx No version reference
  313. .El
  314. .Pp
  315. In general, macro keys are supposed to yield complete results without
  316. expecting the user to consider actual macro usage.
  317. For example, results include:
  318. .Pp
  319. .Bl -tag -width 3n -offset 3n -compact
  320. .It Li \&Fa
  321. function arguments appearing on
  322. .Ic \&Fn
  323. lines
  324. .It Li \&Fn
  325. function names marked up with
  326. .Ic \&Fo
  327. macros
  328. .It Li \&In
  329. include file names marked up with
  330. .Ic \&Fd
  331. macros
  332. .It Li \&Vt
  333. types appearing as function return types and
  334. .It \&
  335. types appearing in function arguments in the SYNOPSIS
  336. .El
  337. .Sh ENVIRONMENT
  338. .Bl -tag -width MANPAGER
  339. .It Ev MANPAGER
  340. Any non-empty value of the environment variable
  341. .Ev MANPAGER
  342. is used instead of the standard pagination program,
  343. .Xr less 1 ;
  344. see
  345. .Xr man 1
  346. for details.
  347. Only used if
  348. .Fl a
  349. or
  350. .Fl l
  351. is specified.
  352. .It Ev MANPATH
  353. A colon-separated list of directories to search for manual pages; see
  354. .Xr man 1
  355. for details.
  356. Overridden by
  357. .Fl M ,
  358. ignored if
  359. .Fl l
  360. is specified.
  361. .It Ev PAGER
  362. Specifies the pagination program to use when
  363. .Ev MANPAGER
  364. is not defined.
  365. If neither PAGER nor MANPAGER is defined,
  366. .Xr less 1
  367. is used.
  368. Only used if
  369. .Fl a
  370. or
  371. .Fl l
  372. is specified.
  373. .El
  374. .Sh FILES
  375. .Bl -tag -width "/etc/man.conf" -compact
  376. .It Pa mandoc.db
  377. name of the
  378. .Xr makewhatis 8
  379. keyword database
  380. .It Pa /etc/man.conf
  381. default
  382. .Xr man 1
  383. configuration file
  384. .El
  385. .Sh EXIT STATUS
  386. .Ex -std
  387. .Sh EXAMPLES
  388. Search for
  389. .Qq .cf
  390. as a substring of manual names and descriptions:
  391. .Pp
  392. .Dl $ apropos =.cf
  393. .Pp
  394. Include matches for
  395. .Qq .cnf
  396. and
  397. .Qq .conf
  398. as well:
  399. .Pp
  400. .Dl $ apropos =.cf =.cnf =.conf
  401. .Pp
  402. Search in names and descriptions using a case-sensitive regular expression:
  403. .Pp
  404. .Dl $ apropos \(aq\(tiset.?[ug]id\(aq
  405. .Pp
  406. Search for all manual pages in a given section:
  407. .Pp
  408. .Dl $ apropos \-s 9 \&.
  409. .Pp
  410. Search for manuals in the library section mentioning both the
  411. .Qq optind
  412. and the
  413. .Qq optarg
  414. variables:
  415. .Pp
  416. .Dl $ apropos \-s 3 Va=optind \-a Va=optarg
  417. .Pp
  418. Do exactly the same as calling
  419. .Nm whatis
  420. with the argument
  421. .Qq ssh :
  422. .Pp
  423. .Dl $ apropos \-\- \-i \(aqNm\(ti[[:<:]]ssh[[:>:]]\(aq
  424. .Pp
  425. The following two invocations are equivalent:
  426. .Pp
  427. .D1 Li $ apropos -S Ar arch Li -s Ar section expression
  428. .Bd -ragged -offset indent
  429. .Li $ apropos \e( Ar expression Li \e)
  430. .Li -a arch\(ti^( Ns Ar arch Ns Li |any)$
  431. .Li -a sec\(ti^ Ns Ar section Ns Li $
  432. .Ed
  433. .Sh SEE ALSO
  434. .Xr man 1 ,
  435. .Xr re_format 7 ,
  436. .Xr makewhatis 8
  437. .Sh STANDARDS
  438. The
  439. .Nm
  440. utility is compliant with the
  441. .St -p1003.1-2008
  442. specification of
  443. .Xr man 1
  444. .Fl k .
  445. .Pp
  446. All options, the
  447. .Nm whatis
  448. command, support for logical operators, macro keys,
  449. substring matching, sorting of results, the environment variables
  450. .Ev MANPAGER
  451. and
  452. .Ev MANPATH ,
  453. the database format, and the configuration file
  454. are extensions to that specification.
  455. .Sh HISTORY
  456. Part of the functionality of
  457. .Nm whatis
  458. was already provided by the former
  459. .Nm manwhere
  460. utility in
  461. .Bx 1 .
  462. The
  463. .Nm
  464. and
  465. .Nm whatis
  466. utilities first appeared in
  467. .Bx 2 .
  468. They were rewritten from scratch for
  469. .Ox 5.6 .
  470. .Pp
  471. The
  472. .Fl M
  473. option and the
  474. .Ev MANPATH
  475. variable first appeared in
  476. .Bx 4.3 ;
  477. .Fl m
  478. in
  479. .Bx 4.3 Reno ;
  480. .Fl C
  481. in
  482. .Bx 4.4 Lite1 ;
  483. and
  484. .Fl S
  485. and
  486. .Fl s
  487. in
  488. .Ox 4.5
  489. for
  490. .Nm
  491. and in
  492. .Ox 5.6
  493. for
  494. .Nm whatis .
  495. The options
  496. .Fl acfhIKklOTWw
  497. appeared in
  498. .Ox 5.7 .
  499. .Sh AUTHORS
  500. .An -nosplit
  501. .An Bill Joy
  502. wrote
  503. .Nm manwhere
  504. in 1977 and the original
  505. .Bx
  506. .Nm
  507. and
  508. .Nm whatis
  509. in February 1979.
  510. The current version was written by
  511. .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
  512. and
  513. .An Ingo Schwarze Aq Mt schwarze@openbsd.org .