logo

utils-std

Collection of commonly available Unix tools git clone https://anongit.hacktivis.me/git/utils-std.git

test.1 (8311B)


  1. .\" SPDX-License-Identifier: BSD-3-Clause
  2. .\"-
  3. .\" Copyright (c) 1991, 1993
  4. .\" The Regents of the University of California. All rights reserved.
  5. .\"
  6. .\" This code is derived from software contributed to Berkeley by
  7. .\" the Institute of Electrical and Electronics Engineers, Inc.
  8. .\"
  9. .\" Redistribution and use in source and binary forms, with or without
  10. .\" modification, are permitted provided that the following conditions
  11. .\" are met:
  12. .\" 1. Redistributions of source code must retain the above copyright
  13. .\" notice, this list of conditions and the following disclaimer.
  14. .\" 2. Redistributions in binary form must reproduce the above copyright
  15. .\" notice, this list of conditions and the following disclaimer in the
  16. .\" documentation and/or other materials provided with the distribution.
  17. .\" 3. Neither the name of the University nor the names of its contributors
  18. .\" may be used to endorse or promote products derived from this software
  19. .\" without specific prior written permission.
  20. .\"
  21. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31. .\" SUCH DAMAGE.
  32. .\"
  33. .Dd October 5, 2016
  34. .Dt TEST 1
  35. .Os
  36. .Sh NAME
  37. .Nm test ,
  38. .Nm \&[
  39. .Nd condition evaluation utility
  40. .Sh SYNOPSIS
  41. .Nm
  42. .Ar expression
  43. .Nm \&[
  44. .Ar expression Cm \&]
  45. .Sh DESCRIPTION
  46. The
  47. .Nm
  48. utility evaluates the expression and, if it evaluates
  49. to true, returns a zero (true) exit status; otherwise
  50. it returns 1 (false).
  51. If there is no expression,
  52. .Nm
  53. also
  54. returns 1 (false).
  55. .Pp
  56. All operators and flags are separate arguments to the
  57. .Nm
  58. utility.
  59. .Pp
  60. When checking
  61. .Ar file ,
  62. one should consider TOCTOU race-conditions.
  63. Avoiding the issue altogether with directly using
  64. .Ar file
  65. instead is strongly recommended.
  66. .Pp
  67. The following primaries are used to construct expression:
  68. .Bl -tag -width Ar
  69. .It Fl b Ar file
  70. True if
  71. .Ar file
  72. exists and is a block special
  73. file.
  74. .It Fl c Ar file
  75. True if
  76. .Ar file
  77. exists and is a character
  78. special file.
  79. .It Fl d Ar file
  80. True if
  81. .Ar file
  82. exists and is a directory.
  83. .It Fl e Ar file
  84. True if
  85. .Ar file
  86. exists (regardless of type).
  87. .It Ar file1 Fl ef Ar file2
  88. True if
  89. .Ar file1
  90. and
  91. .Ar file2
  92. exist and refer to the same file.
  93. .It Fl f Ar file
  94. True if
  95. .Ar file
  96. exists and is a regular file.
  97. .It Fl g Ar file
  98. True if
  99. .Ar file
  100. exists and its set group ID flag
  101. is set.
  102. .It Fl h Ar file
  103. True if
  104. .Ar file
  105. exists and is a symbolic link.
  106. This operator is retained for compatibility with previous versions of
  107. this program.
  108. Do not rely on its existence; use
  109. .Fl L
  110. instead.
  111. .It Fl L Ar file
  112. True if
  113. .Ar file
  114. exists and is a symbolic link.
  115. .It Fl k Ar file
  116. True if
  117. .Ar file
  118. exists and its sticky bit is set.
  119. .It Fl n Ar string
  120. True if the length of
  121. .Ar string
  122. is nonzero.
  123. .It Ar file1 Fl nt Ar file2
  124. True if
  125. .Ar file1
  126. exists and is newer than
  127. .Ar file2 .
  128. .It Ar file1 Fl ot Ar file2
  129. True if
  130. .Ar file1
  131. exists and is older than
  132. .Ar file2 .
  133. .It Fl p Ar file
  134. True if
  135. .Ar file
  136. is a named pipe
  137. .Pq Tn FIFO .
  138. .It Fl r Ar file
  139. True if
  140. .Ar file
  141. exists and is readable.
  142. .It Fl S Ar file
  143. True if
  144. .Ar file
  145. exists and is a socket.
  146. .It Fl s Ar file
  147. True if
  148. .Ar file
  149. exists and has a size greater
  150. than zero.
  151. .It Fl t Ar file_descriptor
  152. True if the file whose file descriptor number
  153. is
  154. .Ar file_descriptor
  155. is open and is associated with a terminal.
  156. .It Fl u Ar file
  157. True if
  158. .Ar file
  159. exists and its set user ID flag
  160. is set.
  161. .It Fl w Ar file
  162. True if
  163. .Ar file
  164. exists and is writable.
  165. True
  166. indicates only that the write flag is on.
  167. The file is not writable on a read-only file
  168. system even if this test indicates true.
  169. .It Fl x Ar file
  170. True if
  171. .Ar file
  172. exists and is executable.
  173. True
  174. indicates only that the execute flag is on.
  175. If
  176. .Ar file
  177. is a directory, true indicates that
  178. .Ar file
  179. can be searched.
  180. .It Fl z Ar string
  181. True if the length of
  182. .Ar string
  183. is zero.
  184. .It Fl O Ar file
  185. True if
  186. .Ar file
  187. exists and its owner matches the effective user id of this process.
  188. .It Fl G Ar file
  189. True if
  190. .Ar file
  191. exists and its group matches the effective group id of this process.
  192. .It Ar string
  193. True if
  194. .Ar string
  195. is not the null
  196. string.
  197. .It Ar s1 Cm = Ar s2
  198. True if the strings
  199. .Ar s1
  200. and
  201. .Ar s2
  202. are identical.
  203. .It Ar s1 Cm != Ar s2
  204. True if the strings
  205. .Ar s1
  206. and
  207. .Ar s2
  208. are not identical.
  209. .It Ar s1 Cm < Ar s2
  210. True if string
  211. .Ar s1
  212. comes before
  213. .Ar s2
  214. based on the binary value of their characters.
  215. .It Ar s1 Cm > Ar s2
  216. True if string
  217. .Ar s1
  218. comes after
  219. .Ar s2
  220. based on the binary value of their characters.
  221. .It Ar n1 Fl eq Ar n2
  222. True if the integers
  223. .Ar n1
  224. and
  225. .Ar n2
  226. are algebraically
  227. equal.
  228. .It Ar n1 Fl ne Ar n2
  229. True if the integers
  230. .Ar n1
  231. and
  232. .Ar n2
  233. are not
  234. algebraically equal.
  235. .It Ar n1 Fl gt Ar n2
  236. True if the integer
  237. .Ar n1
  238. is algebraically
  239. greater than the integer
  240. .Ar n2 .
  241. .It Ar n1 Fl ge Ar n2
  242. True if the integer
  243. .Ar n1
  244. is algebraically
  245. greater than or equal to the integer
  246. .Ar n2 .
  247. .It Ar n1 Fl lt Ar n2
  248. True if the integer
  249. .Ar n1
  250. is algebraically less
  251. than the integer
  252. .Ar n2 .
  253. .It Ar n1 Fl le Ar n2
  254. True if the integer
  255. .Ar n1
  256. is algebraically less
  257. than or equal to the integer
  258. .Ar n2 .
  259. .El
  260. .Pp
  261. If
  262. .Ar file
  263. is a symbolic link,
  264. .Nm
  265. will fully dereference it and then evaluate the expression
  266. against the file referenced, except for the
  267. .Fl h
  268. and
  269. .Fl L
  270. primaries.
  271. .Pp
  272. These primaries can be combined with the following operators:
  273. .Bl -tag -width Ar
  274. .It Cm \&! Ar expression
  275. True if
  276. .Ar expression
  277. is false.
  278. .It Ar expression1 Fl a Ar expression2
  279. True if both
  280. .Ar expression1
  281. and
  282. .Ar expression2
  283. are true.
  284. .It Ar expression1 Fl o Ar expression2
  285. True if either
  286. .Ar expression1
  287. or
  288. .Ar expression2
  289. are true.
  290. .It Cm \&( Ar expression Cm \&)
  291. True if expression is true.
  292. .El
  293. .Pp
  294. The
  295. .Fl a
  296. operator has higher precedence than the
  297. .Fl o
  298. operator.
  299. .Pp
  300. Some shells may provide a builtin
  301. .Nm
  302. command which is similar or identical to this utility.
  303. Consult the
  304. .Xr builtin 1
  305. manual page.
  306. .Sh GRAMMAR AMBIGUITY
  307. The
  308. .Nm
  309. grammar is inherently ambiguous.
  310. In order to assure a degree of consistency,
  311. the cases described in the
  312. .St -p1003.2 ,
  313. section D11.2/4.62.4, standard
  314. are evaluated consistently according to the rules specified in the
  315. standards document.
  316. All other cases are subject to the ambiguity in the
  317. command semantics.
  318. .Pp
  319. In particular, only expressions containing
  320. .Fl a ,
  321. .Fl o ,
  322. .Cm \&(
  323. or
  324. .Cm \&)
  325. can be ambiguous.
  326. .Sh EXIT STATUS
  327. The
  328. .Nm
  329. utility exits with one of the following values:
  330. .Bl -tag -width indent
  331. .It 0
  332. expression evaluated to true.
  333. .It 1
  334. expression evaluated to false or expression was
  335. missing.
  336. .It >1
  337. An error occurred.
  338. .El
  339. .Sh EXAMPLES
  340. Implement
  341. .Li test FILE1 -nt FILE2
  342. using only
  343. .Tn POSIX
  344. functionality:
  345. .Pp
  346. .Dl test -n \&"$(find -L -- FILE1 -prune -newer FILE2 2>/dev/null)\&"
  347. .Pp
  348. This can be modified using non-standard
  349. .Xr find 1
  350. primaries like
  351. .Cm -newerca
  352. to compare other timestamps.
  353. .Sh COMPATIBILITY
  354. For compatibility with some other implementations,
  355. the
  356. .Cm =
  357. primary can be substituted with
  358. .Cm ==
  359. with the same meaning.
  360. .Sh SEE ALSO
  361. .Xr builtin 1 ,
  362. .Xr expr 1 ,
  363. .Xr find 1 ,
  364. .Xr sh 1 ,
  365. .Xr stat 1 ,
  366. .Xr symlink 7
  367. .Sh STANDARDS
  368. .Nm
  369. should be compliant with the
  370. IEEE Std 1003.1-2024 (“POSIX.1”)
  371. specification.
  372. .Pp
  373. The primaries
  374. .Cm == ,
  375. .Fl G ,
  376. and
  377. .Fl O
  378. are extensions.
  379. The
  380. .Fl a ,
  381. .Fl o
  382. binary primaries, and
  383. .Ql \&(
  384. and
  385. .Ql \&)
  386. operators are kept for backward compatibility but should be taken as deprecated.
  387. .Sh HISTORY
  388. A
  389. .Nm
  390. utility appeared in
  391. .At v7 .
  392. .Sh BUGS
  393. Both sides are always evaluated in
  394. .Fl a
  395. and
  396. .Fl o .
  397. For instance, the writable status of
  398. .Pa file
  399. will be tested by the following command even though the former expression
  400. indicated false, which results in a gratuitous access to the file system:
  401. .Dl "[ -z abc -a -w file ]"
  402. To avoid this, write
  403. .Dl "[ -z abc ] && [ -w file ]"