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