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

test.1p (24855B)


  1. '\" et
  2. .TH TEST "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. test
  12. \(em evaluate expression
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. test \fB[\fIexpression\fB]\fR
  17. .P
  18. [ \fB[\fIexpression\fB]\fR ]
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. .IR test
  23. utility shall evaluate the
  24. .IR expression
  25. and indicate the result of the evaluation by its exit status. An exit
  26. status of zero indicates that the expression evaluated as true and an
  27. exit status of 1 indicates that the expression evaluated as false.
  28. .P
  29. In the second form of the utility, where the utility name used is
  30. .IR [
  31. rather than
  32. .IR test ,
  33. the application shall ensure that the closing square bracket is a
  34. separate argument. The
  35. .IR test
  36. and
  37. .IR [
  38. utilities may be implemented as a single linked utility which examines
  39. the basename of the zeroth command line argument to determine whether
  40. to behave as the
  41. .IR test
  42. or
  43. .IR [
  44. variant. Applications using the
  45. \fIexec\fR()
  46. family of functions to execute these utilities shall ensure that the
  47. argument passed in
  48. .IR arg0
  49. or
  50. .IR argv [0]
  51. is
  52. .BR '['
  53. when executing the
  54. .IR [
  55. utility and has a basename of
  56. .BR \(dqtest\(dq
  57. when executing the
  58. .IR test
  59. utility.
  60. .SH OPTIONS
  61. The
  62. .IR test
  63. utility shall not recognize the
  64. .BR \(dq--\(dq
  65. argument in the manner specified by Guideline 10 in the Base Definitions volume of POSIX.1\(hy2017,
  66. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  67. .P
  68. No options shall be supported.
  69. .SH OPERANDS
  70. The application shall ensure that all operators and elements of
  71. primaries are presented as separate arguments to the
  72. .IR test
  73. utility.
  74. .P
  75. The following primaries can be used to construct
  76. .IR expression :
  77. .IP "\fB\-b\ \fIpathname\fR" 10
  78. True if
  79. .IR pathname
  80. resolves to an existing directory entry for a block special file.
  81. False if
  82. .IR pathname
  83. cannot be resolved, or if
  84. .IR pathname
  85. resolves to an existing directory entry for a file that is not a block
  86. special file.
  87. .IP "\fB\-c\ \fIpathname\fR" 10
  88. True if
  89. .IR pathname
  90. resolves to an existing directory entry for a character special file.
  91. False if
  92. .IR pathname
  93. cannot be resolved, or if
  94. .IR pathname
  95. resolves to an existing directory entry for a file that is not a character
  96. special file.
  97. .IP "\fB\-d\ \fIpathname\fR" 10
  98. True if
  99. .IR pathname
  100. resolves to an existing directory entry for a directory. False if
  101. .IR pathname
  102. cannot be resolved, or if
  103. .IR pathname
  104. resolves to an existing directory entry for a file that is not a
  105. directory.
  106. .IP "\fB\-e\ \fIpathname\fR" 10
  107. True if
  108. .IR pathname
  109. resolves to an existing directory entry. False if
  110. .IR pathname
  111. cannot be resolved.
  112. .IP "\fB\-f\ \fIpathname\fR" 10
  113. True if
  114. .IR pathname
  115. resolves to an existing directory entry for a regular file. False if
  116. .IR pathname
  117. cannot be resolved, or if
  118. .IR pathname
  119. resolves to an existing directory entry for a file that is not a
  120. regular file.
  121. .IP "\fB\-g\ \fIpathname\fR" 10
  122. True if
  123. .IR pathname
  124. resolves to an existing directory entry for a file that has its
  125. set-group-ID flag set. False if
  126. .IR pathname
  127. cannot be resolved, or if
  128. .IR pathname
  129. resolves to an existing directory entry for a file that does not have
  130. its set-group-ID flag set.
  131. .IP "\fB\-h\ \fIpathname\fR" 10
  132. True if
  133. .IR pathname
  134. resolves to an existing directory entry for a symbolic link. False if
  135. .IR pathname
  136. cannot be resolved, or if
  137. .IR pathname
  138. resolves to an existing directory entry for a file that is not a symbolic
  139. link. If the final component of
  140. .IR pathname
  141. is a symbolic link, that symbolic link is not followed.
  142. .IP "\fB\-L\ \fIpathname\fR" 10
  143. True if
  144. .IR pathname
  145. resolves to an existing directory entry for a symbolic link. False if
  146. .IR pathname
  147. cannot be resolved, or if
  148. .IR pathname
  149. resolves to an existing directory entry for a file that is not a symbolic
  150. link. If the final component of
  151. .IR pathname
  152. is a symbolic link, that symbolic link is not followed.
  153. .IP "\fB\-n\ \fIstring\fR" 10
  154. True if the length of
  155. .IR string
  156. is non-zero; otherwise, false.
  157. .IP "\fB\-p\ \fIpathname\fR" 10
  158. True if
  159. .IR pathname
  160. resolves to an existing directory entry for a FIFO. False if
  161. .IR pathname
  162. cannot be resolved, or if
  163. .IR pathname
  164. resolves to an existing directory entry for a file that is not a FIFO.
  165. .IP "\fB\-r\ \fIpathname\fR" 10
  166. True if
  167. .IR pathname
  168. resolves to an existing directory entry for a file for which permission
  169. to read from the file will be granted, as defined in
  170. .IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation".
  171. False if
  172. .IR pathname
  173. cannot be resolved, or if
  174. .IR pathname
  175. resolves to an existing directory entry for a file for which permission
  176. to read from the file will not be granted.
  177. .IP "\fB\-S\ \fIpathname\fR" 10
  178. True if
  179. .IR pathname
  180. resolves to an existing directory entry for a socket. False if
  181. .IR pathname
  182. cannot be resolved, or if
  183. .IR pathname
  184. resolves to an existing directory entry for a file that is not a socket.
  185. .IP "\fB\-s\ \fIpathname\fR" 10
  186. True if
  187. .IR pathname
  188. resolves to an existing directory entry for a file that has a size
  189. greater than zero. False if
  190. .IR pathname
  191. cannot be resolved, or if
  192. .IR pathname
  193. resolves to an existing directory entry for a file that does not have
  194. a size greater than zero.
  195. .IP "\fB\-t\ \fIfile_descriptor\fR" 10
  196. .br
  197. True if file descriptor number
  198. .IR file_descriptor
  199. is open and is associated with a terminal. False if
  200. .IR file_descriptor
  201. is not a valid file descriptor number, or if file descriptor number
  202. .IR file_descriptor
  203. is not open, or if it is open but is not associated with a terminal.
  204. .IP "\fB\-u\ \fIpathname\fR" 10
  205. True if
  206. .IR pathname
  207. resolves to an existing directory entry for a file that has its
  208. set-user-ID flag set. False if
  209. .IR pathname
  210. cannot be resolved, or if
  211. .IR pathname
  212. resolves to an existing directory entry for a file that does not have
  213. its set-user-ID flag set.
  214. .IP "\fB\-w\ \fIpathname\fR" 10
  215. True if
  216. .IR pathname
  217. resolves to an existing directory entry for a file for which permission
  218. to write to the file will be granted, as defined in
  219. .IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation".
  220. False if
  221. .IR pathname
  222. cannot be resolved, or if
  223. .IR pathname
  224. resolves to an existing directory entry for a file for which permission
  225. to write to the file will not be granted.
  226. .IP "\fB\-x\ \fIpathname\fR" 10
  227. True if
  228. .IR pathname
  229. resolves to an existing directory entry for a file for which permission
  230. to execute the file (or search it, if it is a directory) will be granted,
  231. as defined in
  232. .IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation".
  233. False if
  234. .IR pathname
  235. cannot be resolved, or if
  236. .IR pathname
  237. resolves to an existing directory entry for a file for which permission
  238. to execute (or search) the file will not be granted.
  239. .IP "\fB\-z\ \fIstring\fR" 10
  240. True if the length of string
  241. .IR string
  242. is zero; otherwise, false.
  243. .IP "\fIstring\fR" 10
  244. True if the string
  245. .IR string
  246. is not the null string; otherwise, false.
  247. .IP "\fIs1\fB\ \(eq\ \fIs2\fR" 10
  248. True if the strings
  249. .IR s1
  250. and
  251. .IR s2
  252. are identical; otherwise, false.
  253. .IP "\fIs1\fB\ !=\ \fIs2\fR" 10
  254. True if the strings
  255. .IR s1
  256. and
  257. .IR s2
  258. are not identical; otherwise, false.
  259. .IP "\fIn1\fB\ \-eq\ \fIn2\fR" 10
  260. True if the integers
  261. .IR n1
  262. and
  263. .IR n2
  264. are algebraically equal; otherwise, false.
  265. .IP "\fIn1\fB\ \-ne\ \fIn2\fR" 10
  266. True if the integers
  267. .IR n1
  268. and
  269. .IR n2
  270. are not algebraically equal; otherwise, false.
  271. .IP "\fIn1\fB\ \-gt\ \fIn2\fR" 10
  272. True if the integer
  273. .IR n1
  274. is algebraically greater than the integer
  275. .IR n2 ;
  276. otherwise, false.
  277. .IP "\fIn1\fB\ \-ge\ \fIn2\fR" 10
  278. True if the integer
  279. .IR n1
  280. is algebraically greater than or equal to the integer
  281. .IR n2 ;
  282. otherwise, false.
  283. .IP "\fIn1\fB\ \-lt\ \fIn2\fR" 10
  284. True if the integer
  285. .IR n1
  286. is algebraically less than the integer
  287. .IR n2 ;
  288. otherwise, false.
  289. .IP "\fIn1\fB\ \-le\ \fIn2\fR" 10
  290. True if the integer
  291. .IR n1
  292. is algebraically less than or equal to the integer
  293. .IR n2 ;
  294. otherwise, false.
  295. .IP "\fIexpression1\fB\ \-a\ \fIexpression2\fR" 10
  296. .br
  297. True if both
  298. .IR expression1
  299. and
  300. .IR expression2
  301. are true; otherwise, false. The
  302. .BR \-a
  303. binary primary is left associative. It has a higher precedence than
  304. .BR \-o .
  305. .IP "\fIexpression1\fB\ \-o\ \fIexpression2\fR" 10
  306. .br
  307. True if either
  308. .IR expression1
  309. or
  310. .IR expression2
  311. is true; otherwise, false. The
  312. .BR \-o
  313. binary primary is left associative.
  314. .P
  315. With the exception of the
  316. .BR \-h
  317. .IR pathname
  318. and
  319. .BR \-L
  320. .IR pathname
  321. primaries, if a
  322. .IR pathname
  323. argument is a symbolic link,
  324. .IR test
  325. shall evaluate the expression by resolving the symbolic link and using
  326. the file referenced by the link.
  327. .P
  328. These primaries can be combined with the following operators:
  329. .IP "\fB!\ \fIexpression\fR" 10
  330. True if
  331. .IR expression
  332. is false. False if
  333. .IR expression
  334. is true.
  335. .IP "\fB(\ \fIexpression\ \fB)\fR" 10
  336. True if
  337. .IR expression
  338. is true. False if
  339. .IR expression
  340. is false. The parentheses can be used to alter the normal precedence
  341. and associativity.
  342. .P
  343. The primaries with two elements of the form:
  344. .sp
  345. .RS 4
  346. .nf
  347. -\fIprimary_operator primary_operand\fR
  348. .fi
  349. .P
  350. .RE
  351. .P
  352. are known as
  353. .IR "unary primaries" .
  354. The primaries with three elements in either of the two forms:
  355. .sp
  356. .RS 4
  357. .nf
  358. \fIprimary_operand \fR-\fIprimary_operator primary_operand
  359. .P
  360. primary_operand primary_operator primary_operand\fR
  361. .fi
  362. .P
  363. .RE
  364. .P
  365. are known as
  366. .IR "binary primaries" .
  367. Additional implementation-defined operators and
  368. .IR primary_operator s
  369. may be provided by implementations. They shall be of the form \-\c
  370. .IR operator
  371. where the first character of
  372. .IR operator
  373. is not a digit.
  374. .P
  375. The algorithm for determining the precedence of the operators and the
  376. return value that shall be generated is based on the number of
  377. arguments presented to
  378. .IR test .
  379. (However, when using the
  380. .BR \(dq[...]\(dq
  381. form, the
  382. <right-square-bracket>
  383. final argument shall not be counted in this algorithm.)
  384. .P
  385. In the following list, $1, $2, $3, and $4 represent the arguments
  386. presented to
  387. .IR test :
  388. .IP "0\ arguments:" 12
  389. Exit false (1).
  390. .IP "1\ argument:" 12
  391. Exit true (0) if $1 is not null; otherwise, exit false.
  392. .IP "2\ arguments:" 12
  393. .sp -1v
  394. .RS 12
  395. .IP " *" 4
  396. If $1 is
  397. .BR '!' ,
  398. exit true if $2 is null, false if $2 is not null.
  399. .IP " *" 4
  400. If $1 is a unary primary, exit true if the unary test is true, false if
  401. the unary test is false.
  402. .IP " *" 4
  403. Otherwise, produce unspecified results.
  404. .RE
  405. .IP "3\ arguments:" 12
  406. .sp -1v
  407. .RS 12
  408. .IP " *" 4
  409. If $2 is a binary primary, perform the binary test of $1 and $3.
  410. .IP " *" 4
  411. If $1 is
  412. .BR '!' ,
  413. negate the two-argument test of $2 and $3.
  414. .IP " *" 4
  415. If $1 is
  416. .BR '('
  417. and $3 is
  418. .BR ')' ,
  419. perform the unary test of $2.
  420. On systems that do not support the XSI option, the results are
  421. unspecified if $1 is
  422. .BR '('
  423. and $3 is
  424. .BR ')' .
  425. .IP " *" 4
  426. Otherwise, produce unspecified results.
  427. .RE
  428. .IP "4\ arguments:" 12
  429. .sp -1v
  430. .RS 12
  431. .IP " *" 4
  432. If $1 is
  433. .BR '!' ,
  434. negate the three-argument test of $2, $3, and $4.
  435. .IP " *" 4
  436. If $1 is
  437. .BR '('
  438. and $4 is
  439. .BR ')' ,
  440. perform the two-argument test of $2 and $3.
  441. On systems that do not support the XSI option, the results are
  442. unspecified if $1 is
  443. .BR '('
  444. and $4 is
  445. .BR ')' .
  446. .IP " *" 4
  447. Otherwise, the results are unspecified.
  448. .RE
  449. .IP ">4\ arguments:" 12
  450. The results are unspecified.
  451. .RS 12
  452. .P
  453. On XSI-conformant systems, combinations of primaries and operators
  454. shall be evaluated using the precedence and associativity rules
  455. described previously. In addition, the string comparison binary
  456. primaries
  457. .BR '='
  458. and
  459. .BR \(dq!=\(dq
  460. shall have a higher precedence than any unary primary.
  461. .RE
  462. .SH STDIN
  463. Not used.
  464. .SH "INPUT FILES"
  465. None.
  466. .SH "ENVIRONMENT VARIABLES"
  467. The following environment variables shall affect the execution of
  468. .IR test :
  469. .IP "\fILANG\fP" 10
  470. Provide a default value for the internationalization variables that are
  471. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  472. .IR "Section 8.2" ", " "Internationalization Variables"
  473. for the precedence of internationalization variables used to determine
  474. the values of locale categories.)
  475. .IP "\fILC_ALL\fP" 10
  476. If set to a non-empty string value, override the values of all the
  477. other internationalization variables.
  478. .IP "\fILC_CTYPE\fP" 10
  479. Determine the locale for the interpretation of sequences of bytes of
  480. text data as characters (for example, single-byte as opposed to
  481. multi-byte characters in arguments).
  482. .IP "\fILC_MESSAGES\fP" 10
  483. .br
  484. Determine the locale that should be used to affect the format and
  485. contents of diagnostic messages written to standard error.
  486. .IP "\fINLSPATH\fP" 10
  487. Determine the location of message catalogs for the processing of
  488. .IR LC_MESSAGES .
  489. .SH "ASYNCHRONOUS EVENTS"
  490. Default.
  491. .SH STDOUT
  492. Not used.
  493. .SH STDERR
  494. The standard error shall be used only for diagnostic messages.
  495. .SH "OUTPUT FILES"
  496. None.
  497. .SH "EXTENDED DESCRIPTION"
  498. None.
  499. .SH "EXIT STATUS"
  500. The following exit values shall be returned:
  501. .IP "\00" 6
  502. .IR expression
  503. evaluated to true.
  504. .IP "\01" 6
  505. .IR expression
  506. evaluated to false or
  507. .IR expression
  508. was missing.
  509. .IP >1 6
  510. An error occurred.
  511. .SH "CONSEQUENCES OF ERRORS"
  512. Default.
  513. .LP
  514. .IR "The following sections are informative."
  515. .SH "APPLICATION USAGE"
  516. The XSI extensions specifying the
  517. .BR \-a
  518. and
  519. .BR \-o
  520. binary primaries and the
  521. .BR '('
  522. and
  523. .BR ')'
  524. operators have been marked obsolescent. (Many expressions using them
  525. are ambiguously defined by the grammar depending on the specific
  526. expressions being evaluated.) Scripts using these expressions should be
  527. converted to the forms given below. Even though many implementations
  528. will continue to support these obsolescent forms, scripts should be
  529. extremely careful when dealing with user-supplied input that could be
  530. confused with these and other primaries and operators. Unless the
  531. application developer knows all the cases that produce input to the
  532. script, invocations like:
  533. .sp
  534. .RS 4
  535. .nf
  536. test "$1" -a "$2"
  537. .fi
  538. .P
  539. .RE
  540. .P
  541. should be written as:
  542. .sp
  543. .RS 4
  544. .nf
  545. test "$1" && test "$2"
  546. .fi
  547. .P
  548. .RE
  549. .P
  550. to avoid problems if a user supplied values such as $1 set to
  551. .BR '!'
  552. and $2 set to the null string. That is, in cases where maximal
  553. portability is of concern, replace:
  554. .sp
  555. .RS 4
  556. .nf
  557. test expr1 -a expr2
  558. .fi
  559. .P
  560. .RE
  561. .P
  562. with:
  563. .sp
  564. .RS 4
  565. .nf
  566. test expr1 && test expr2
  567. .fi
  568. .P
  569. .RE
  570. .P
  571. and replace:
  572. .sp
  573. .RS 4
  574. .nf
  575. test expr1 -o expr2
  576. .fi
  577. .P
  578. .RE
  579. .P
  580. with:
  581. .sp
  582. .RS 4
  583. .nf
  584. test expr1 || test expr2
  585. .fi
  586. .P
  587. .RE
  588. .P
  589. but note that, in
  590. .IR test ,
  591. .BR \-a
  592. has higher precedence than
  593. .BR \-o
  594. while
  595. .BR \(dq&&\(dq
  596. and
  597. .BR \(dq||\(dq
  598. have equal precedence in the shell.
  599. .P
  600. Parentheses or braces can be used in the shell command language to
  601. effect grouping.
  602. .P
  603. Parentheses must be escaped when using
  604. .IR sh ;
  605. for example:
  606. .sp
  607. .RS 4
  608. .nf
  609. test \e( expr1 -a expr2 \e) -o expr3
  610. .fi
  611. .P
  612. .RE
  613. .P
  614. This command is not always portable even on XSI-conformant systems
  615. depending on the expressions specified by
  616. .IR expr 1,
  617. .IR expr 2,
  618. and
  619. .IR expr 3.
  620. The following form can be used instead:
  621. .sp
  622. .RS 4
  623. .nf
  624. ( test expr1 && test expr2 ) || test expr3
  625. .fi
  626. .P
  627. .RE
  628. .P
  629. The two commands:
  630. .sp
  631. .RS 4
  632. .nf
  633. test "$1"
  634. test ! "$1"
  635. .fi
  636. .P
  637. .RE
  638. .P
  639. could not be used reliably on some historical systems. Unexpected
  640. results would occur if such a
  641. .IR string
  642. expression were used and $1 expanded to
  643. .BR '!' ,
  644. .BR '(' ,
  645. or a known unary primary. Better constructs are:
  646. .sp
  647. .RS 4
  648. .nf
  649. test -n "$1"
  650. test -z "$1"
  651. .fi
  652. .P
  653. .RE
  654. respectively.
  655. .P
  656. Historical systems have also been unreliable given the common
  657. construct:
  658. .sp
  659. .RS 4
  660. .nf
  661. test "$response" = "expected string"
  662. .fi
  663. .P
  664. .RE
  665. .P
  666. One of the following is a more reliable form:
  667. .sp
  668. .RS 4
  669. .nf
  670. test "X$response" = "Xexpected string"
  671. test "expected string" = "$response"
  672. .fi
  673. .P
  674. .RE
  675. .P
  676. Note that the second form assumes that
  677. .IR "expected string"
  678. could not be confused with any unary primary. If
  679. .IR "expected string"
  680. starts with
  681. .BR '\-' ,
  682. .BR '(' ,
  683. .BR '!' ,
  684. or even
  685. .BR '=' ,
  686. the first form should be used instead. Using the preceding rules
  687. without the XSI marked extensions, any of the three comparison forms is
  688. reliable, given any input. (However, note that the strings are quoted
  689. in all cases.)
  690. .P
  691. Because the string comparison binary primaries,
  692. .BR '='
  693. and
  694. .BR \(dq!=\(dq ,
  695. have a higher precedence than any unary primary in the greater than 4
  696. argument case, unexpected results can occur if arguments are not
  697. properly prepared. For example, in:
  698. .sp
  699. .RS 4
  700. .nf
  701. test -d $1 -o -d $2
  702. .fi
  703. .P
  704. .RE
  705. .P
  706. If $1 evaluates to a possible directory name of
  707. .BR '=' ,
  708. the first three arguments are considered a string comparison, which
  709. shall cause a syntax error when the second
  710. .BR \-d
  711. is encountered. One of the following forms prevents this; the second
  712. is preferred:
  713. .sp
  714. .RS 4
  715. .nf
  716. test \e( -d "$1" \e) -o \e( -d "$2" \e)
  717. test -d "$1" || test -d "$2"
  718. .fi
  719. .P
  720. .RE
  721. .P
  722. Also in the greater than 4 argument case:
  723. .sp
  724. .RS 4
  725. .nf
  726. test "$1" = "bat" -a "$2" = "ball"
  727. .fi
  728. .P
  729. .RE
  730. .P
  731. syntax errors occur if $1 evaluates to
  732. .BR '('
  733. or
  734. .BR '!' .
  735. One of the following forms prevents this; the third is preferred:
  736. .sp
  737. .RS 4
  738. .nf
  739. test "X$1" = "Xbat" -a "X$2" = "Xball"
  740. test "$1" = "bat" && test "$2" = "ball"
  741. test "X$1" = "Xbat" && test "X$2" = "Xball"
  742. .fi
  743. .P
  744. .RE
  745. .P
  746. Note that none of the following examples are permitted by the
  747. syntax described:
  748. .sp
  749. .RS 4
  750. .nf
  751. [-f file]
  752. [-f file ]
  753. [ -f file]
  754. [ -f file
  755. test -f file ]
  756. .fi
  757. .P
  758. .RE
  759. .P
  760. In the first two cases, if a utility named
  761. .IR [\(hyf
  762. exists, that utility would be invoked, and not
  763. .IR test .
  764. In the remaining cases, the brackets are mismatched, and the behavior
  765. is unspecified. However:
  766. .sp
  767. .RS 4
  768. .nf
  769. test ! ]
  770. .fi
  771. .P
  772. .RE
  773. .P
  774. does have a defined meaning, and must exit with status 1. Similarly:
  775. .sp
  776. .RS 4
  777. .nf
  778. test ]
  779. .fi
  780. .P
  781. .RE
  782. .P
  783. must exit with status 0.
  784. .SH EXAMPLES
  785. .IP " 1." 4
  786. Exit if there are not two or three arguments (two variations):
  787. .RS 4
  788. .sp
  789. .RS 4
  790. .nf
  791. if [ $# -ne 2 ] && [ $# -ne 3 ]; then exit 1; fi
  792. if [ $# -lt 2 ] || [ $# -gt 3 ]; then exit 1; fi
  793. .fi
  794. .P
  795. .RE
  796. .RE
  797. .IP " 2." 4
  798. Perform a
  799. .IR mkdir
  800. if a directory does not exist:
  801. .RS 4
  802. .sp
  803. .RS 4
  804. .nf
  805. test ! -d tempdir && mkdir tempdir
  806. .fi
  807. .P
  808. .RE
  809. .RE
  810. .IP " 3." 4
  811. Wait for a file to become non-readable:
  812. .RS 4
  813. .sp
  814. .RS 4
  815. .nf
  816. while test -r thefile
  817. do
  818. sleep 30
  819. done
  820. echo \(aq"thefile" is no longer readable\(aq
  821. .fi
  822. .P
  823. .RE
  824. .RE
  825. .IP " 4." 4
  826. Perform a command if the argument is one of three strings (two
  827. variations):
  828. .RS 4
  829. .sp
  830. .RS 4
  831. .nf
  832. if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
  833. then
  834. \fIcommand\fP
  835. fi
  836. .P
  837. case "$1" in
  838. pear|grape|apple) \fIcommand\fP ;;
  839. esac
  840. .fi
  841. .P
  842. .RE
  843. .RE
  844. .SH RATIONALE
  845. The KornShell-derived conditional command (double bracket
  846. .BR [[\|]] )
  847. was removed from the shell command language description in an early
  848. proposal. Objections were raised that the real problem is misuse of the
  849. .IR test
  850. command (\c
  851. .BR [ ),
  852. and putting it into the shell is the wrong way to fix the problem.
  853. Instead, proper documentation and a new shell reserved word (\c
  854. .BR ! )
  855. are sufficient.
  856. .P
  857. Tests that require multiple
  858. .IR test
  859. operations can be done at the shell level using individual invocations
  860. of the
  861. .IR test
  862. command and shell logicals, rather than using the error-prone
  863. .BR \-o
  864. flag of
  865. .IR test .
  866. .P
  867. XSI-conformant systems support more than four arguments.
  868. .P
  869. XSI-conformant systems support the combining of primaries with the
  870. following constructs:
  871. .IP "\fIexpression1\fB \-a \fIexpression2\fR" 6
  872. .br
  873. True if both
  874. .IR expression1
  875. and
  876. .IR expression2
  877. are true.
  878. .IP "\fIexpression1\fB \-o \fIexpression2\fR" 6
  879. .br
  880. True if at least one of
  881. .IR expression1
  882. and
  883. .IR expression2
  884. are true.
  885. .IP "\fB( \fIexpression \fB)\fR" 6
  886. .br
  887. True if
  888. .IR expression
  889. is true.
  890. .P
  891. In evaluating these more complex combined expressions, the following
  892. precedence rules are used:
  893. .IP " *" 4
  894. The unary primaries have higher precedence than the algebraic binary
  895. primaries.
  896. .IP " *" 4
  897. The unary primaries have lower precedence than the string binary
  898. primaries.
  899. .IP " *" 4
  900. The unary and binary primaries have higher precedence than the unary
  901. .IR string
  902. primary.
  903. .IP " *" 4
  904. The
  905. .BR !
  906. operator has higher precedence than the
  907. .BR \-a
  908. operator, and the
  909. .BR \-a
  910. operator has higher precedence than the
  911. .BR \-o
  912. operator.
  913. .IP " *" 4
  914. The
  915. .BR \-a
  916. and
  917. .BR \-o
  918. operators are left associative.
  919. .IP " *" 4
  920. The parentheses can be used to alter the normal precedence and
  921. associativity.
  922. .P
  923. The BSD and System V versions of
  924. .BR \-f
  925. are not the same. The BSD definition was:
  926. .IP "\fB\-f\ \fIfile\fR" 10
  927. True if
  928. .IR file
  929. exists and is not a directory.
  930. .P
  931. The SVID version (true if the file exists and is a regular file) was
  932. chosen for this volume of POSIX.1\(hy2017 because its use is consistent with the
  933. .BR \-b ,
  934. .BR \-c ,
  935. .BR \-d ,
  936. and
  937. .BR \-p
  938. operands (\c
  939. .IR file
  940. exists and is a specific file type).
  941. .P
  942. The
  943. .BR \-e
  944. primary, possessing similar functionality to that provided by the C
  945. shell, was added because it provides the only way for a shell script to
  946. find out if a file exists without trying to open the file. Since
  947. implementations are allowed to add additional file types, a portable
  948. script cannot use:
  949. .sp
  950. .RS 4
  951. .nf
  952. test -b foo -o -c foo -o -d foo -o -f foo -o -p foo
  953. .fi
  954. .P
  955. .RE
  956. .P
  957. to find out if
  958. .BR foo
  959. is an existing file. On historical BSD systems, the existence of a
  960. file could be determined by:
  961. .sp
  962. .RS 4
  963. .nf
  964. test -f foo -o -d foo
  965. .fi
  966. .P
  967. .RE
  968. .P
  969. but there was no easy way to determine that an existing file was a
  970. regular file. An early proposal used the KornShell
  971. .BR \-a
  972. primary (with the same meaning), but this was changed to
  973. .BR \-e
  974. because there were concerns about the high probability of humans
  975. confusing the
  976. .BR \-a
  977. primary with the
  978. .BR \-a
  979. binary operator.
  980. .P
  981. The following options were not included in this volume of POSIX.1\(hy2017, although they are
  982. provided by some implementations. These operands should not be used by
  983. new implementations for other purposes:
  984. .IP "\fB\-k\ \fIfile\fR" 10
  985. True if
  986. .IR file
  987. exists and its sticky bit is set.
  988. .IP "\fB\-C\ \fIfile\fR" 10
  989. True if
  990. .IR file
  991. is a contiguous file.
  992. .IP "\fB\-V\ \fIfile\fR" 10
  993. True if
  994. .IR file
  995. is a version file.
  996. .P
  997. The following option was not included because it was undocumented in
  998. most implementations, has been removed from some implementations
  999. (including System V), and the functionality is provided by the shell
  1000. (see
  1001. .IR "Section 2.6.2" ", " "Parameter Expansion".
  1002. .IP "\fB\-l\ \fIstring\fR" 10
  1003. The length of the string
  1004. .IR string .
  1005. .P
  1006. The
  1007. .BR \-b ,
  1008. .BR \-c ,
  1009. .BR \-g ,
  1010. .BR \-p ,
  1011. .BR \-u ,
  1012. and
  1013. .BR \-x
  1014. operands are derived from the SVID; historical BSD does not provide
  1015. them. The
  1016. .BR \-k
  1017. operand is derived from System V; historical BSD does not provide it.
  1018. .P
  1019. On historical BSD systems,
  1020. .IR test
  1021. .BR \-w
  1022. .IR directory
  1023. always returned false because
  1024. .IR test
  1025. tried to open the directory for writing, which always fails.
  1026. .P
  1027. Some additional primaries newly invented or from the KornShell appeared
  1028. in an early proposal as part of the conditional command (\c
  1029. .BR [[\|]] ):
  1030. .IR s1
  1031. .BR >
  1032. .IR s2 ,
  1033. .IR s1
  1034. .BR <
  1035. .IR s2 ,
  1036. .IR str
  1037. .BR =
  1038. .IR pattern ,
  1039. .IR str
  1040. .BR !=
  1041. .IR pattern ,
  1042. .IR f1
  1043. .BR \-nt
  1044. .IR f2 ,
  1045. .IR f1
  1046. .BR \-ot
  1047. .IR f2 ,
  1048. and
  1049. .IR f1
  1050. .BR \-ef
  1051. .IR f2 .
  1052. They were not carried forward into the
  1053. .IR test
  1054. utility when the conditional command was removed from the shell because
  1055. they have not been included in the
  1056. .IR test
  1057. utility built into historical implementations of the
  1058. .IR sh
  1059. utility.
  1060. .P
  1061. The
  1062. .BR \-t
  1063. .IR file_descriptor
  1064. primary is shown with a mandatory argument because the grammar is
  1065. ambiguous if it can be omitted. Historical implementations have allowed
  1066. it to be omitted, providing a default of 1.
  1067. .P
  1068. It is noted that
  1069. .BR '['
  1070. is not part of the portable filename character set; however, since it
  1071. is required to be encoded by a single byte, and is part of the portable
  1072. character set, the name of this utility forms a character string across
  1073. all supported locales.
  1074. .SH "FUTURE DIRECTIONS"
  1075. None.
  1076. .SH "SEE ALSO"
  1077. .IR "Section 1.1.1.4" ", " "File Read" ", " "Write" ", " "and Creation",
  1078. .IR "\fIfind\fR\^"
  1079. .P
  1080. The Base Definitions volume of POSIX.1\(hy2017,
  1081. .IR "Chapter 8" ", " "Environment Variables",
  1082. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  1083. .\"
  1084. .SH COPYRIGHT
  1085. Portions of this text are reprinted and reproduced in electronic form
  1086. from IEEE Std 1003.1-2017, Standard for Information Technology
  1087. -- Portable Operating System Interface (POSIX), The Open Group Base
  1088. Specifications Issue 7, 2018 Edition,
  1089. Copyright (C) 2018 by the Institute of
  1090. Electrical and Electronics Engineers, Inc and The Open Group.
  1091. In the event of any discrepancy between this version and the original IEEE and
  1092. The Open Group Standard, the original IEEE and The Open Group Standard
  1093. is the referee document. The original Standard can be obtained online at
  1094. http://www.opengroup.org/unix/online.html .
  1095. .PP
  1096. Any typographical or formatting errors that appear
  1097. in this page are most likely
  1098. to have been introduced during the conversion of the source files to
  1099. man page format. To report such errors, see
  1100. https://www.kernel.org/doc/man-pages/reporting_bugs.html .