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

find.1p (30066B)


  1. '\" et
  2. .TH FIND "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. find
  12. \(em find files
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. find \fB[\fR-H|-L\fB] \fIpath\fR... \fB[\fIoperand_expression\fR...\fB]
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR find
  21. utility shall recursively descend the directory hierarchy from each
  22. file specified by
  23. .IR path ,
  24. evaluating a Boolean expression composed of the primaries described in
  25. the OPERANDS section for each file encountered. Each
  26. .IR path
  27. operand shall be evaluated unaltered as it was provided, including
  28. all trailing
  29. <slash>
  30. characters; all pathnames for other files encountered in the hierarchy
  31. shall consist of the concatenation of the current
  32. .IR path
  33. operand, a
  34. <slash>
  35. if the current
  36. .IR path
  37. operand did not end in one, and the filename relative to the
  38. .IR path
  39. operand. The relative portion shall contain no dot or dot-dot components,
  40. no trailing
  41. <slash>
  42. characters, and only single
  43. <slash>
  44. characters between pathname components.
  45. .P
  46. The
  47. .IR find
  48. utility shall be able to descend to arbitrary depths in a file
  49. hierarchy and shall not fail due to path length limitations (unless a
  50. .IR path
  51. operand specified by the application exceeds
  52. {PATH_MAX}
  53. requirements).
  54. .P
  55. The
  56. .IR find
  57. utility shall detect infinite loops; that is, entering a previously
  58. visited directory that is an ancestor of the last file encountered.
  59. When it detects an infinite loop,
  60. .IR find
  61. shall write a diagnostic message to standard error and shall either
  62. recover its position in the hierarchy or terminate.
  63. .P
  64. If a file is removed from or added to the directory hierarchy being
  65. searched it is unspecified whether or not
  66. .IR find
  67. includes that file in its search.
  68. .SH OPTIONS
  69. The
  70. .IR find
  71. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  72. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  73. .P
  74. The following options shall be supported by the implementation:
  75. .IP "\fB\-H\fP" 10
  76. Cause the file information and file type evaluated for each symbolic
  77. link encountered as a
  78. .IR path
  79. operand on the command line to be those of the file referenced by the
  80. link, and not the link itself. If the referenced file does not exist, the
  81. file information and type shall be for the link itself. File information
  82. and type for symbolic links encountered during the traversal of a file
  83. hierarchy shall be that of the link itself.
  84. .IP "\fB\-L\fP" 10
  85. Cause the file information and file type evaluated for each symbolic
  86. link encountered as a
  87. .IR path
  88. operand on the command line or encountered during the traversal of
  89. a file hierarchy to be those of the file referenced by the link, and
  90. not the link itself. If the referenced file does not exist, the file
  91. information and type shall be for the link itself.
  92. .P
  93. Specifying more than one of the mutually-exclusive options
  94. .BR \-H
  95. and
  96. .BR \-L
  97. shall not be considered an error. The last option specified shall
  98. determine the behavior of the utility. If neither the
  99. .BR \-H
  100. nor the
  101. .BR \-L
  102. option is specified, then the file information and type for symbolic
  103. links encountered as a
  104. .IR path
  105. operand on the command line or encountered during the traversal of a
  106. file hierarchy shall be that of the link itself.
  107. .SH OPERANDS
  108. The following operands shall be supported:
  109. .P
  110. The first operand and subsequent operands up to but not including the
  111. first operand that starts with a
  112. .BR '\-' ,
  113. or is a
  114. .BR '!'
  115. or a
  116. .BR '(' ,
  117. shall be interpreted as
  118. .IR path
  119. operands. If the first operand starts with a
  120. .BR '\-' ,
  121. or is a
  122. .BR '!'
  123. or a
  124. .BR '(' ,
  125. the behavior is unspecified. Each
  126. .IR path
  127. operand is a pathname of a starting point in the file hierarchy.
  128. .P
  129. The first operand that starts with a
  130. .BR '\-' ,
  131. or is a
  132. .BR '!'
  133. or a
  134. .BR '(' ,
  135. and all subsequent arguments shall be interpreted as an
  136. .IR expression
  137. made up of the following primaries and operators. In the descriptions,
  138. wherever
  139. .IR n
  140. is used as a primary argument, it shall be interpreted as a decimal
  141. integer optionally preceded by a
  142. <plus-sign>
  143. (\c
  144. .BR '\(pl' )
  145. or
  146. <hyphen-minus>
  147. (\c
  148. .BR '\-' ),
  149. as follows:
  150. .IP "+\fIn\fR" 10
  151. More than
  152. .IR n .
  153. .IP "\fIn\fR" 10
  154. Exactly
  155. .IR n .
  156. .IP "\-\fIn\fR" 10
  157. Less than
  158. .IR n .
  159. .P
  160. The following primaries shall be supported:
  161. .IP "\fB\-name\ \fIpattern\fR" 10
  162. .br
  163. The primary shall evaluate as true if the basename of the current
  164. pathname matches
  165. .IR pattern
  166. using the pattern matching notation described in
  167. .IR "Section 2.13" ", " "Pattern Matching Notation".
  168. The additional rules in
  169. .IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion"
  170. do not apply as this is a matching operation, not an expansion.
  171. .IP "\fB\-path\ \fIpattern\fR" 10
  172. .br
  173. The primary shall evaluate as true if the current pathname matches
  174. .IR pattern
  175. using the pattern matching notation described in
  176. .IR "Section 2.13" ", " "Pattern Matching Notation".
  177. The additional rules in
  178. .IR "Section 2.13.3" ", " "Patterns Used for Filename Expansion"
  179. do not apply as this is a matching operation, not an expansion.
  180. .IP "\fB\-nouser\fP" 10
  181. The primary shall evaluate as true if the file belongs to a user ID for
  182. which the
  183. \fIgetpwuid\fR()
  184. function defined in the System Interfaces volume of POSIX.1\(hy2017 (or equivalent) returns NULL.
  185. .IP "\fB\-nogroup\fP" 10
  186. The primary shall evaluate as true if the file belongs to a group ID
  187. for which the
  188. \fIgetgrgid\fR()
  189. function defined in the System Interfaces volume of POSIX.1\(hy2017 (or equivalent) returns NULL.
  190. .IP "\fB\-xdev\fP" 10
  191. The primary shall always evaluate as true; it shall cause
  192. .IR find
  193. not to continue descending past directories that have a different
  194. device ID (\c
  195. .IR st_dev ,
  196. see the
  197. \fIstat\fR()
  198. function defined in the System Interfaces volume of POSIX.1\(hy2017). If any
  199. .BR \-xdev
  200. primary is specified, it shall apply to the entire expression even if
  201. the
  202. .BR \-xdev
  203. primary would not normally be evaluated.
  204. .IP "\fB\-prune\fP" 10
  205. The primary shall always evaluate as true; it shall cause
  206. .IR find
  207. not to descend the current pathname if it is a directory. If the
  208. .BR \-depth
  209. primary is specified, the
  210. .BR \-prune
  211. primary shall have no effect.
  212. .IP "\fB\-perm\ [\-]\fImode\fR" 10
  213. .br
  214. The
  215. .IR mode
  216. argument is used to represent file mode bits. It shall be identical in
  217. format to the
  218. .IR symbolic_mode
  219. operand described in
  220. .IR chmod ,
  221. and shall be interpreted as follows. To start, a template shall be
  222. assumed with all file mode bits cleared. An
  223. .IR op
  224. symbol of
  225. .BR '\(pl'
  226. shall set the appropriate mode bits in the template;
  227. .BR '\-'
  228. shall clear the appropriate bits;
  229. .BR '='
  230. shall set the appropriate mode bits, without regard to the contents of
  231. the file mode creation mask of the process. The
  232. .IR op
  233. symbol of
  234. .BR '\-'
  235. cannot be the first character of
  236. .IR mode ;
  237. this avoids ambiguity with the optional leading
  238. <hyphen-minus>.
  239. Since the initial mode is all bits off, there are not any symbolic modes
  240. that need to use
  241. .BR '\-'
  242. as the first character.
  243. .RS 10
  244. .P
  245. If the
  246. <hyphen-minus>
  247. is omitted, the primary shall evaluate as true when the file permission
  248. bits exactly match the value of the resulting template.
  249. .P
  250. Otherwise, if
  251. .IR mode
  252. is prefixed by a
  253. <hyphen-minus>,
  254. the primary shall evaluate as true if at least all the bits in the
  255. resulting template are set in the file permission bits.
  256. .RE
  257. .IP "\fB\-perm\ [\-]\fIonum\fR" 10
  258. .br
  259. If the
  260. <hyphen-minus>
  261. is omitted, the primary shall evaluate as true when the file mode bits
  262. exactly match the value of the octal number
  263. .IR onum
  264. (see the description of the octal
  265. .IR mode
  266. in
  267. .IR chmod ).
  268. Otherwise, if
  269. .IR onum
  270. is prefixed by a
  271. <hyphen-minus>,
  272. the primary shall evaluate as true if at least all of the bits specified in
  273. .IR onum
  274. are set. In both cases, the behavior is unspecified when
  275. .IR onum
  276. exceeds 07777.
  277. .IP "\fB\-type\ \fIc\fR" 10
  278. The primary shall evaluate as true if the type of the file is
  279. .IR c ,
  280. where
  281. .IR c
  282. is
  283. .BR 'b' ,
  284. .BR 'c' ,
  285. .BR 'd' ,
  286. .BR 'l' ,
  287. .BR 'p' ,
  288. .BR 'f' ,
  289. or
  290. .BR 's'
  291. for block special file, character special file, directory, symbolic
  292. link, FIFO, regular file, or socket, respectively.
  293. .IP "\fB\-links\ \fIn\fR" 10
  294. The primary shall evaluate as true if the file has
  295. .IR n
  296. links.
  297. .IP "\fB\-user\ \fIuname\fR" 10
  298. The primary shall evaluate as true if the file belongs to the user
  299. .IR uname.
  300. If
  301. .IR uname
  302. is a decimal integer and the
  303. \fIgetpwnam\fR()
  304. (or equivalent) function does not return a valid user name,
  305. .IR uname
  306. shall be interpreted as a user ID.
  307. .IP "\fB\-group\ \fIgname\fR" 10
  308. .br
  309. The primary shall evaluate as true if the file belongs to the group
  310. .IR gname .
  311. If
  312. .IR gname
  313. is a decimal integer and the
  314. \fIgetgrnam\fR()
  315. (or equivalent) function does not return a valid group name,
  316. .IR gname
  317. shall be interpreted as a group ID.
  318. .IP "\fB\-size\ \fIn\fB[c]\fR" 10
  319. The primary shall evaluate as true if the file size in bytes, divided
  320. by 512 and rounded up to the next integer, is
  321. .IR n .
  322. If
  323. .IR n
  324. is followed by the character
  325. .BR 'c' ,
  326. the size shall be in bytes.
  327. .IP "\fB\-atime\ \fIn\fR" 10
  328. The primary shall evaluate as true if the file access time subtracted
  329. from the initialization time, divided by 86\|400 (with any remainder
  330. discarded), is
  331. .IR n .
  332. .IP "\fB\-ctime\ \fIn\fR" 10
  333. The primary shall evaluate as true if the time of last change of file
  334. status information subtracted from the initialization time, divided by
  335. 86\|400 (with any remainder discarded), is
  336. .IR n .
  337. .IP "\fB\-mtime\ \fIn\fR" 10
  338. The primary shall evaluate as true if the file modification time
  339. subtracted from the initialization time, divided by 86\|400 (with any
  340. remainder discarded), is
  341. .IR n .
  342. .IP "\fB\-exec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10
  343. .IP "\fB\-exec\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ \ \fR{\|}\0+" 10
  344. .br
  345. The end of the primary expression shall be punctuated by a
  346. <semicolon>
  347. or by a
  348. <plus-sign>.
  349. Only a
  350. <plus-sign>
  351. that immediately follows an argument containing only the two characters
  352. .BR \(dq{}\(dq
  353. shall punctuate the end of the primary expression. Other uses of the
  354. <plus-sign>
  355. shall not be treated as special.
  356. .RS 10
  357. .P
  358. If the primary expression is punctuated by a
  359. <semicolon>,
  360. the utility
  361. .IR utility_name
  362. shall be invoked once for each pathname and the primary shall evaluate
  363. as true if the utility returns a zero value as exit status. A
  364. .IR utility_name
  365. or
  366. .IR argument
  367. containing only the two characters
  368. .BR \(dq{}\(dq
  369. shall be replaced by the current pathname. If a
  370. .IR utility_name
  371. or
  372. .IR argument
  373. string contains the two characters
  374. .BR \(dq{}\(dq ,
  375. but not just the two characters
  376. .BR \(dq{}\(dq ,
  377. it is implementation-defined whether
  378. .IR find
  379. replaces those two characters or uses the string without change.
  380. .P
  381. If the primary expression is punctuated by a
  382. <plus-sign>,
  383. the primary shall always evaluate as true, and the pathnames for which
  384. the primary is evaluated shall be aggregated into sets. The utility
  385. .IR utility_name
  386. shall be invoked once for each set of aggregated pathnames. Each
  387. invocation shall begin after the last pathname in the set is
  388. aggregated, and shall be completed before the
  389. .IR find
  390. utility exits and before the first pathname in the next set (if any) is
  391. aggregated for this primary, but it is otherwise unspecified whether
  392. the invocation occurs before, during, or after the evaluations of other
  393. primaries. If any invocation returns a non-zero value as exit status,
  394. the
  395. .IR find
  396. utility shall return a non-zero exit status. An argument containing
  397. only the two characters
  398. .BR \(dq{}\(dq
  399. shall be replaced by the set of aggregated pathnames, with each
  400. pathname passed as a separate argument to the invoked utility in the
  401. same order that it was aggregated. The size of any set of two or more
  402. pathnames shall be limited such that execution of the utility does not
  403. cause the system's
  404. {ARG_MAX}
  405. limit to be exceeded. If more than one argument containing the two
  406. characters
  407. .BR \(dq{}\(dq
  408. is present, the behavior is unspecified.
  409. .P
  410. The current directory for the invocation of
  411. .IR utility_name
  412. shall be the same as the current directory when the
  413. .IR find
  414. utility was started. If the
  415. .IR utility_name
  416. names any of the special built-in utilities (see
  417. .IR "Section 2.14" ", " "Special Built-In Utilities"),
  418. the results are undefined.
  419. .RE
  420. .IP "\fB\-ok\ \fIutility_name\ \fB[\fIargument\fR\ .\|.\|.\fB]\ ;\fR" 10
  421. .br
  422. The
  423. .BR \-ok
  424. primary shall be equivalent to
  425. .BR \-exec ,
  426. except that the use of a
  427. <plus-sign>
  428. to punctuate the end of the primary expression need not be supported, and
  429. .IR find
  430. shall request affirmation of the invocation of
  431. .IR utility_name
  432. using the current file as an argument by writing to standard error as
  433. described in the STDERR section. If the response on standard input is
  434. affirmative, the utility shall be invoked. Otherwise, the command
  435. shall not be invoked and the value of the
  436. .BR \-ok
  437. operand shall be false.
  438. .IP "\fB\-print\fR" 10
  439. The primary shall always evaluate as true; it shall cause the current
  440. pathname to be written to standard output.
  441. .IP "\fB\-newer\ \fIfile\fR" 10
  442. The primary shall evaluate as true if the modification time of the
  443. current file is more recent than the modification time of the file
  444. named by the pathname
  445. .IR file .
  446. .IP "\fB\-depth\fR" 10
  447. The primary shall always evaluate as true; it shall cause descent of
  448. the directory hierarchy to be done so that all entries in a directory
  449. are acted on before the directory itself. If a
  450. .BR \-depth
  451. primary is not specified, all entries in a directory shall be acted on
  452. after the directory itself. If any
  453. .BR \-depth
  454. primary is specified, it shall apply to the entire expression even if
  455. the
  456. .BR \-depth
  457. primary would not normally be evaluated.
  458. .P
  459. The primaries can be combined using the following operators (in order
  460. of decreasing precedence):
  461. .IP "(\ \fIexpression\fR\ )" 10
  462. True if
  463. .IR expression
  464. is true.
  465. .IP "\fB!\ \fIexpression\fR" 10
  466. Negation of a primary; the unary NOT operator.
  467. .IP "\fIexpression\ \fB[\-a]\ \fIexpression\fR" 10
  468. .br
  469. Conjunction of primaries; the AND operator is implied by the
  470. juxtaposition of two primaries or made explicit by the optional
  471. .BR \-a
  472. operator. The second expression shall not be evaluated if the first
  473. expression is false.
  474. .IP "\fIexpression\ \fB\-o\ \fIexpression\fR" 10
  475. .br
  476. Alternation of primaries; the OR operator. The second expression shall
  477. not be evaluated if the first expression is true.
  478. .P
  479. If no
  480. .IR expression
  481. is present,
  482. .BR \-print
  483. shall be used as the expression. Otherwise, if the given expression
  484. does not contain any of the primaries
  485. .BR \-exec ,
  486. .BR \-ok ,
  487. or
  488. .BR \-print ,
  489. the given expression shall be effectively replaced by:
  490. .sp
  491. .RS 4
  492. .nf
  493. ( \fIgiven_expression\fP ) -print
  494. .fi
  495. .P
  496. .RE
  497. .P
  498. The
  499. .BR \-user ,
  500. .BR \-group ,
  501. and
  502. .BR \-newer
  503. primaries each shall evaluate their respective arguments only once.
  504. .P
  505. When the file type evaluated for the current file is a symbolic link,
  506. the results of evaluating the
  507. .BR \-perm
  508. primary are implementation-defined.
  509. .SH STDIN
  510. If the
  511. .BR \-ok
  512. primary is used, the response shall be read from the standard input.
  513. An entire line shall be read as the response. Otherwise, the standard
  514. input shall not be used.
  515. .SH "INPUT FILES"
  516. None.
  517. .SH "ENVIRONMENT VARIABLES"
  518. The following environment variables shall affect the execution of
  519. .IR find :
  520. .IP "\fILANG\fP" 10
  521. Provide a default value for the internationalization variables that are
  522. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  523. .IR "Section 8.2" ", " "Internationalization Variables"
  524. for the precedence of internationalization variables used to determine
  525. the values of locale categories.)
  526. .IP "\fILC_ALL\fP" 10
  527. If set to a non-empty string value, override the values of all the
  528. other internationalization variables.
  529. .IP "\fILC_COLLATE\fP" 10
  530. .br
  531. Determine the locale for the behavior of ranges, equivalence classes,
  532. and multi-character collating elements used in the pattern matching
  533. notation for the
  534. .BR \-n
  535. option and in the extended regular expression defined for the
  536. .BR yesexpr
  537. locale keyword in the
  538. .IR LC_MESSAGES
  539. category.
  540. .IP "\fILC_CTYPE\fP" 10
  541. This variable determines the locale for the interpretation of sequences
  542. of bytes of text data as characters (for example, single-byte
  543. as opposed to multi-byte characters in arguments), the behavior of
  544. character classes within the pattern matching notation used for the
  545. .BR \-n
  546. option, and the behavior of character classes within regular
  547. expressions used in the extended regular expression defined for the
  548. .BR yesexpr
  549. locale keyword in the
  550. .IR LC_MESSAGES
  551. category.
  552. .IP "\fILC_MESSAGES\fP" 10
  553. .br
  554. Determine the locale used to process affirmative responses, and the
  555. locale used to affect the format and contents of diagnostic messages
  556. and prompts written to standard error.
  557. .IP "\fINLSPATH\fP" 10
  558. Determine the location of message catalogs for the processing of
  559. .IR LC_MESSAGES .
  560. .IP "\fIPATH\fP" 10
  561. Determine the location of the
  562. .IR utility_name
  563. for the
  564. .BR \-exec
  565. and
  566. .BR \-ok
  567. primaries, as described in the Base Definitions volume of POSIX.1\(hy2017,
  568. .IR "Chapter 8" ", " "Environment Variables".
  569. .SH "ASYNCHRONOUS EVENTS"
  570. Default.
  571. .SH STDOUT
  572. The
  573. .BR \-print
  574. primary shall cause the current pathnames to be written to standard
  575. output. The format shall be:
  576. .sp
  577. .RS 4
  578. .nf
  579. "%s\en", <\fIpath\fR>
  580. .fi
  581. .P
  582. .RE
  583. .SH STDERR
  584. The
  585. .BR \-ok
  586. primary shall write a prompt to standard error containing at least the
  587. .IR utility_name
  588. to be invoked and the current pathname. In the POSIX locale, the last
  589. non-\c
  590. <blank>
  591. in the prompt shall be
  592. .BR '?' .
  593. The exact format used is unspecified.
  594. .P
  595. Otherwise, the standard error shall be used only for diagnostic
  596. messages.
  597. .SH "OUTPUT FILES"
  598. None.
  599. .SH "EXTENDED DESCRIPTION"
  600. None.
  601. .SH "EXIT STATUS"
  602. The following exit values shall be returned:
  603. .IP "\00" 6
  604. All
  605. .IR path
  606. operands were traversed successfully.
  607. .IP >0 6
  608. An error occurred.
  609. .SH "CONSEQUENCES OF ERRORS"
  610. Default.
  611. .LP
  612. .IR "The following sections are informative."
  613. .SH "APPLICATION USAGE"
  614. When used in operands, pattern matching notation,
  615. <semicolon>,
  616. <left-parenthesis>,
  617. and
  618. <right-parenthesis>
  619. characters are special to the shell and must be quoted (see
  620. .IR "Section 2.2" ", " "Quoting").
  621. .P
  622. The bit that is traditionally used for sticky (historically 01000) is
  623. specified in the
  624. .BR \-perm
  625. primary using the octal number argument form. Since this bit is not
  626. defined by this volume of POSIX.1\(hy2017, applications must not assume that it actually refers
  627. to the traditional sticky bit.
  628. .SH EXAMPLES
  629. .IP " 1." 4
  630. The following commands are equivalent:
  631. .RS 4
  632. .sp
  633. .RS 4
  634. .nf
  635. find .
  636. find . -print
  637. .fi
  638. .P
  639. .RE
  640. .P
  641. They both write out the entire directory hierarchy from the current
  642. directory.
  643. .RE
  644. .IP " 2." 4
  645. The following command:
  646. .RS 4
  647. .sp
  648. .RS 4
  649. .nf
  650. find / \e( -name tmp -o -name \(aq*.xx\(aq \e) -atime +7 -exec rm {} \e;
  651. .fi
  652. .P
  653. .RE
  654. .P
  655. removes all files named
  656. .BR tmp
  657. or ending in
  658. .BR .xx
  659. that have not been accessed for seven or more 24-hour periods.
  660. .RE
  661. .IP " 3." 4
  662. The following command:
  663. .RS 4
  664. .sp
  665. .RS 4
  666. .nf
  667. find . -perm -o+w,+s
  668. .fi
  669. .P
  670. .RE
  671. .P
  672. prints (\c
  673. .BR \-print
  674. is assumed) the names of all files in or below the current directory,
  675. with all of the file permission bits S_ISUID, S_ISGID, and S_IWOTH set.
  676. .RE
  677. .IP " 4." 4
  678. The following command:
  679. .RS 4
  680. .sp
  681. .RS 4
  682. .nf
  683. find . -name SCCS -prune -o -print
  684. .fi
  685. .P
  686. .RE
  687. .P
  688. recursively prints pathnames of all files in the current directory and
  689. below, but skips directories named SCCS and files in them.
  690. .RE
  691. .IP " 5." 4
  692. The following command:
  693. .RS 4
  694. .sp
  695. .RS 4
  696. .nf
  697. find . -print -name SCCS -prune
  698. .fi
  699. .P
  700. .RE
  701. .P
  702. behaves as in the previous example, but prints the names of the SCCS
  703. directories.
  704. .RE
  705. .IP " 6." 4
  706. The following command is roughly equivalent to the
  707. .BR \-nt
  708. extension to
  709. .IR test :
  710. .RS 4
  711. .sp
  712. .RS 4
  713. .nf
  714. if [ -n "$(find file1 -prune -newer file2)" ]; then
  715. printf %s\e\en "file1 is newer than file2"
  716. fi
  717. .fi
  718. .P
  719. .RE
  720. .RE
  721. .IP " 7." 4
  722. The descriptions of
  723. .BR \-atime ,
  724. .BR \-ctime ,
  725. and
  726. .BR \-mtime
  727. use the terminology
  728. .IR n
  729. ``86\|400 second periods (days)''. For example, a file accessed at 23:59
  730. is selected by:
  731. .RS 4
  732. .sp
  733. .RS 4
  734. .nf
  735. find . -atime -1 -print
  736. .fi
  737. .P
  738. .RE
  739. .P
  740. at 00:01 the next day (less than 24 hours later, not more than one day
  741. ago); the midnight boundary between days has no effect on the 24-hour
  742. calculation.
  743. .RE
  744. .IP " 8." 4
  745. The following command:
  746. .RS 4
  747. .sp
  748. .RS 4
  749. .nf
  750. find . ! -name . -prune -name \(aq*.old\(aq -exec \e
  751. sh -c \(aqmv "$@" ../old/\(aq sh {} +
  752. .fi
  753. .P
  754. .RE
  755. .P
  756. performs the same task as:
  757. .sp
  758. .RS 4
  759. .nf
  760. mv ./*.old ./.old ./.*.old ../old/
  761. .fi
  762. .P
  763. .RE
  764. .P
  765. while avoiding an ``Argument list too long'' error if there are
  766. a large number of files ending with
  767. .BR .old
  768. and without running
  769. .IR mv
  770. if there are no such files (and avoiding ``No such file or directory''
  771. errors if
  772. .BR ./.old
  773. does not exist or no files match
  774. .BR ./*.old
  775. or
  776. .BR ./.*.old ).
  777. .P
  778. The alternative:
  779. .sp
  780. .RS 4
  781. .nf
  782. find . ! -name . -prune -name \(aq*.old\(aq -exec mv {} ../old/ \e;
  783. .fi
  784. .P
  785. .RE
  786. .P
  787. is less efficient if there are many files to move because it executes one
  788. .IR mv
  789. command per file.
  790. .RE
  791. .IP " 9." 4
  792. On systems configured to mount removable media on directories under
  793. .BR /media ,
  794. the following command searches the file hierarchy for files larger
  795. than 100\|000 KB without searching any mounted removable media:
  796. .RS 4
  797. .sp
  798. .RS 4
  799. .nf
  800. find / -path /media -prune -o -size +200000 -print
  801. .fi
  802. .P
  803. .RE
  804. .RE
  805. .IP 10. 4
  806. Except for the root directory, and
  807. .BR \(dq//\(dq
  808. on implementations where
  809. .BR \(dq//\(dq
  810. does not refer to the root directory, no pattern given to
  811. .BR \-name
  812. will match a
  813. <slash>,
  814. because trailing
  815. <slash>
  816. characters are ignored when computing the basename of the file under
  817. evaluation. Given two empty directories named
  818. .BR foo
  819. and
  820. .BR bar ,
  821. the following command:
  822. .RS 4
  823. .sp
  824. .RS 4
  825. .nf
  826. find foo/// bar/// -name foo -o -name \(aqbar?*\(aq
  827. .fi
  828. .P
  829. .RE
  830. .P
  831. prints only the line
  832. .BR \(dqfoo///\(dq .
  833. .RE
  834. .SH RATIONALE
  835. The
  836. .BR \-a
  837. operator was retained as an optional operator for compatibility with
  838. historical shell scripts, even though it is redundant with expression
  839. concatenation.
  840. .P
  841. The descriptions of the
  842. .BR '\-'
  843. modifier on the
  844. .IR mode
  845. and
  846. .IR onum
  847. arguments to the
  848. .BR \-perm
  849. primary agree with historical practice on BSD and System V
  850. implementations. System V and BSD documentation both describe it in
  851. terms of checking additional bits; in fact, it uses the same bits, but
  852. checks for having at least all of the matching bits set instead of
  853. having exactly the matching bits set.
  854. .P
  855. The exact format of the interactive prompts is unspecified. Only the
  856. general nature of the contents of prompts are specified because:
  857. .IP " *" 4
  858. Implementations may desire more descriptive prompts than those
  859. used on historical implementations.
  860. .IP " *" 4
  861. Since the historical prompt strings do not terminate with
  862. <newline>
  863. characters, there is no portable way for another program to interact
  864. with the prompts of this utility via pipes.
  865. .P
  866. Therefore, an application using this prompting option relies on the
  867. system to provide the most suitable dialog directly with the user,
  868. based on the general guidelines specified.
  869. .P
  870. The
  871. .BR \-name
  872. .IR file
  873. operand was changed to use the shell pattern matching notation
  874. so that
  875. .IR find
  876. is consistent with other utilities using pattern matching.
  877. .P
  878. The
  879. .BR \-size
  880. operand refers to the size of a file, rather than the number of blocks
  881. it may occupy in the file system. The intent is that the
  882. .IR st_size
  883. field defined in the System Interfaces volume of POSIX.1\(hy2017 should be used, not the
  884. .IR st_blocks
  885. found in historical implementations. There are at least two reasons for
  886. this:
  887. .IP " 1." 4
  888. In both System V and BSD,
  889. .IR find
  890. only uses
  891. .IR st_size
  892. in size calculations for the operands specified by this volume of POSIX.1\(hy2017. (BSD uses
  893. .IR st_blocks
  894. only when processing the
  895. .BR \-ls
  896. primary.)
  897. .IP " 2." 4
  898. Users usually think of file size in terms of bytes, which is also the
  899. unit used by the
  900. .IR ls
  901. utility for the output from the
  902. .BR \-l
  903. option. (In both System V and BSD,
  904. .IR ls
  905. uses
  906. .IR st_size
  907. for the
  908. .BR \-l
  909. option size field and uses
  910. .IR st_blocks
  911. for the
  912. .IR ls
  913. .BR \-s
  914. calculations. This volume of POSIX.1\(hy2017 does not specify
  915. .IR ls
  916. .BR \-s .)
  917. .P
  918. The descriptions of
  919. .BR \-atime ,
  920. .BR \-ctime ,
  921. and
  922. .BR \-mtime
  923. were changed from the SVID description of
  924. .IR n
  925. ``days'' to
  926. .IR n
  927. being the result of the integer division of the time difference in
  928. seconds by 86\|400. The description is also different in terms of the
  929. exact timeframe for the
  930. .IR n
  931. case (\fIversus\fP the
  932. .IR +n
  933. or
  934. .IR \-n ),
  935. but it matches all known historical implementations. It refers to one
  936. 86\|400 second period in the past, not any time from the beginning of
  937. that period to the current time. For example,
  938. .BR \-atime
  939. 2 is true if the file was accessed any time in the period from 72 hours
  940. to 48 hours ago.
  941. .P
  942. Historical implementations do not modify
  943. .BR \(dq{}\(dq
  944. when it appears as a substring of an
  945. .BR \-exec
  946. or
  947. .BR \-ok
  948. .IR utility_name
  949. or argument string. There have been numerous user requests for this
  950. extension, so this volume of POSIX.1\(hy2017 allows the desired behavior. At least one recent
  951. implementation does support this feature, but encountered several
  952. problems in managing memory allocation and dealing with multiple
  953. occurrences of
  954. .BR \(dq{}\(dq
  955. in a string while it was being developed, so it is not yet required
  956. behavior.
  957. .P
  958. Assuming the presence of
  959. .BR \-print
  960. was added to correct a historical pitfall that plagues novice users, it
  961. is entirely upwards-compatible from the historical System V
  962. .IR find
  963. utility. In its simplest form (\c
  964. .IR find
  965. .IR directory ),
  966. it could be confused with the historical BSD fast
  967. .IR find .
  968. The BSD developers agreed that adding
  969. .BR \-print
  970. as a default expression was the correct decision and have added the
  971. fast
  972. .IR find
  973. functionality within a new utility called
  974. .IR locate .
  975. .P
  976. Historically, the
  977. .BR \-L
  978. option was implemented using the primary
  979. .BR \-follow .
  980. The
  981. .BR \-H
  982. and
  983. .BR \-L
  984. options were added for two reasons. First, they offer a finer
  985. granularity of control and consistency with other programs that walk
  986. file hierarchies. Second, the
  987. .BR \-follow
  988. primary always evaluated to true. As they were historically really
  989. global variables that took effect before the traversal began, some
  990. valid expressions had unexpected results. An example is the expression
  991. .BR \-print
  992. .BR \-o
  993. .BR \-follow .
  994. Because
  995. .BR \-print
  996. always evaluates to true, the standard order of evaluation implies that
  997. .BR \-follow
  998. would never be evaluated. This was never the case. Historical practice
  999. for the
  1000. .BR \-follow
  1001. primary, however, is not consistent. Some implementations always follow
  1002. symbolic links on the command line whether
  1003. .BR \-follow
  1004. is specified or not. Others follow symbolic links on the command line
  1005. only if
  1006. .BR \-follow
  1007. is specified. Both behaviors are provided by the
  1008. .BR \-H
  1009. and
  1010. .BR \-L
  1011. options, but scripts using the current
  1012. .BR \-follow
  1013. primary would be broken if the
  1014. .BR \-follow
  1015. option is specified to work either way.
  1016. .P
  1017. Since the
  1018. .BR \-L
  1019. option resolves all symbolic links and the
  1020. .BR \-type
  1021. .IR l
  1022. primary is true for symbolic links that still exist after symbolic
  1023. links have been resolved, the command:
  1024. .sp
  1025. .RS 4
  1026. .nf
  1027. find -L . -type l
  1028. .fi
  1029. .P
  1030. .RE
  1031. .P
  1032. prints a list of symbolic links reachable from the current directory
  1033. that do not resolve to accessible files.
  1034. .P
  1035. A feature of SVR4's
  1036. .IR find
  1037. utility was the
  1038. .BR \-exec
  1039. primary's
  1040. .BR +
  1041. terminator. This allowed filenames containing special characters
  1042. (especially
  1043. <newline>
  1044. characters) to be grouped together without the problems that occur if
  1045. such filenames are piped to
  1046. .IR xargs .
  1047. Other implementations have added other ways to get around this problem,
  1048. notably a
  1049. .BR \-print0
  1050. primary that wrote filenames with a null byte terminator. This was
  1051. considered here, but not adopted. Using a null terminator meant that
  1052. any utility that was going to process
  1053. .IR find 's
  1054. .BR \-print0
  1055. output had to add a new option to parse the null terminators it would
  1056. now be reading.
  1057. .P
  1058. The
  1059. .BR \(dq-exec ... {} +\(dq
  1060. syntax adopted was a result of IEEE PASC Interpretation 1003.2 #210. It
  1061. should be noted that this is an incompatible change to IEEE\ Std 1003.2\(hy1992. For example,
  1062. the following command printed all files with a
  1063. .BR '\-'
  1064. after their name if they are regular files, and a
  1065. .BR '\(pl'
  1066. otherwise:
  1067. .sp
  1068. .RS 4
  1069. .nf
  1070. find / -type f -exec echo {} - \(aq;\(aq -o -exec echo {} + \(aq;\(aq
  1071. .fi
  1072. .P
  1073. .RE
  1074. .P
  1075. The change invalidates usage like this. Even though the previous
  1076. standard stated that this usage would work, in practice many did not
  1077. support it and the standard developers felt it better to now state that
  1078. this was not allowable.
  1079. .SH "FUTURE DIRECTIONS"
  1080. None.
  1081. .SH "SEE ALSO"
  1082. .IR "Section 2.2" ", " "Quoting",
  1083. .IR "Section 2.13" ", " "Pattern Matching Notation",
  1084. .IR "Section 2.14" ", " "Special Built-In Utilities",
  1085. .IR "\fIchmod\fR\^",
  1086. .IR "\fImv\fR\^",
  1087. .IR "\fIpax\fR\^",
  1088. .IR "\fIsh\fR\^",
  1089. .IR "\fItest\fR\^"
  1090. .P
  1091. The Base Definitions volume of POSIX.1\(hy2017,
  1092. .IR "Chapter 8" ", " "Environment Variables",
  1093. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  1094. .P
  1095. The System Interfaces volume of POSIX.1\(hy2017,
  1096. .IR "\fIfstatat\fR\^(\|)",
  1097. .IR "\fIgetgrgid\fR\^(\|)",
  1098. .IR "\fIgetpwuid\fR\^(\|)"
  1099. .\"
  1100. .SH COPYRIGHT
  1101. Portions of this text are reprinted and reproduced in electronic form
  1102. from IEEE Std 1003.1-2017, Standard for Information Technology
  1103. -- Portable Operating System Interface (POSIX), The Open Group Base
  1104. Specifications Issue 7, 2018 Edition,
  1105. Copyright (C) 2018 by the Institute of
  1106. Electrical and Electronics Engineers, Inc and The Open Group.
  1107. In the event of any discrepancy between this version and the original IEEE and
  1108. The Open Group Standard, the original IEEE and The Open Group Standard
  1109. is the referee document. The original Standard can be obtained online at
  1110. http://www.opengroup.org/unix/online.html .
  1111. .PP
  1112. Any typographical or formatting errors that appear
  1113. in this page are most likely
  1114. to have been introduced during the conversion of the source files to
  1115. man page format. To report such errors, see
  1116. https://www.kernel.org/doc/man-pages/reporting_bugs.html .