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: src/bin/test/test.1,v 1.31 2010/09/11 10:49:56 brucec Exp $ 34.\" 35.Dd September 10, 2010 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 returns 1 (false). 56.Pp 57All operators and flags are separate arguments to the 58.Nm 59utility. 60.Pp 61The following primaries are used to construct expression: 62.Bl -tag -width Ar 63.It Fl b Ar file 64True if 65.Ar file 66exists and is a block special 67file. 68.It Fl c Ar file 69True if 70.Ar file 71exists and is a character 72special file. 73.It Fl d Ar file 74True if 75.Ar file 76exists and is a directory. 77.It Fl e Ar file 78True if 79.Ar file 80exists (regardless of type). 81.It Fl f Ar file 82True if 83.Ar file 84exists and is a regular file. 85.It Fl g Ar file 86True if 87.Ar file 88exists and its set group ID flag 89is set. 90.It Fl h Ar file 91True if 92.Ar file 93exists and is a symbolic link. 94This operator is retained for compatibility with previous versions of 95this program. 96Do not rely on its existence; use 97.Fl L 98instead. 99.It Fl k Ar file 100True if 101.Ar file 102exists and its sticky bit is set. 103.It Fl n Ar string 104True if the length of 105.Ar string 106is nonzero. 107.It Fl p Ar file 108True if 109.Ar file 110is a named pipe 111.Pq Tn FIFO . 112.It Fl r Ar file 113True if 114.Ar file 115exists and is readable. 116.It Fl s Ar file 117True if 118.Ar file 119exists and has a size greater 120than zero. 121.It Fl t Ar file_descriptor 122True if the file whose file descriptor number 123is 124.Ar file_descriptor 125is open and is associated with a terminal. 126.It Fl u Ar file 127True if 128.Ar file 129exists and its set user ID flag 130is set. 131.It Fl w Ar file 132True if 133.Ar file 134exists and is writable. 135True 136indicates both that the write flag is on and that 137.Ar file 138resides on a read-write file system. 139.Pp 140Note that this behaviour is specific to 141.Dx . 142When writing portable scripts, keep in mind that 143on some systems, this test may 144indicate only that the write flag is on. 145.It Fl x Ar file 146True if 147.Ar file 148exists and is executable. 149True 150indicates only that the execute flag is on. 151If 152.Ar file 153is a directory, true indicates that 154.Ar file 155can be searched. 156.It Fl z Ar string 157True if the length of 158.Ar string 159is zero. 160.It Fl L Ar file 161True if 162.Ar file 163exists and is a symbolic link. 164.It Fl O Ar file 165True if 166.Ar file 167exists and its owner matches the effective user id of this process. 168.It Fl G Ar file 169True if 170.Ar file 171exists and its group matches the effective group id of this process. 172.It Fl S Ar file 173True if 174.Ar file 175exists and is a socket. 176.It Ar file1 Fl nt Ar file2 177True if 178.Ar file1 179exists and is newer than 180.Ar file2 . 181.It Ar file1 Fl ot Ar file2 182True if 183.Ar file1 184exists and is older than 185.Ar file2 . 186.It Ar file1 Fl ef Ar file2 187True if 188.Ar file1 189and 190.Ar file2 191exist and refer to the same file. 192.It Ar string 193True if 194.Ar string 195is not the null 196string. 197.It Ar s1 Cm = Ar s2 198True if the strings 199.Ar s1 200and 201.Ar s2 202are identical. 203.It Ar s1 Cm != Ar s2 204True if the strings 205.Ar s1 206and 207.Ar s2 208are not identical. 209.It Ar s1 Cm < Ar s2 210True if string 211.Ar s1 212comes before 213.Ar s2 214based on the binary value of their characters. 215.It Ar s1 Cm > Ar s2 216True if string 217.Ar s1 218comes after 219.Ar s2 220based on the binary value of their characters. 221.It Ar n1 Fl eq Ar n2 222True if the integers 223.Ar n1 224and 225.Ar n2 226are algebraically 227equal. 228.It Ar n1 Fl ne Ar n2 229True if the integers 230.Ar n1 231and 232.Ar n2 233are not 234algebraically equal. 235.It Ar n1 Fl gt Ar n2 236True if the integer 237.Ar n1 238is algebraically 239greater than the integer 240.Ar n2 . 241.It Ar n1 Fl ge Ar n2 242True if the integer 243.Ar n1 244is algebraically 245greater than or equal to the integer 246.Ar n2 . 247.It Ar n1 Fl lt Ar n2 248True if the integer 249.Ar n1 250is algebraically less 251than the integer 252.Ar n2 . 253.It Ar n1 Fl le Ar n2 254True if the integer 255.Ar n1 256is algebraically less 257than or equal to the integer 258.Ar n2 . 259.El 260.Pp 261If 262.Ar file 263is a symbolic link, 264.Nm 265will fully dereference it and then evaluate the expression 266against the file referenced, except for the 267.Fl h 268and 269.Fl L 270primaries. 271.Pp 272These primaries can be combined with the following operators: 273.Bl -tag -width Ar 274.It Cm \&! Ar expression 275True if 276.Ar expression 277is false. 278.It Ar expression1 Fl a Ar expression2 279True if both 280.Ar expression1 281and 282.Ar expression2 283are true. 284.It Ar expression1 Fl o Ar expression2 285True if either 286.Ar expression1 287or 288.Ar expression2 289are true. 290.It Cm \&( Ar expression Cm \&) 291True if expression is true. 292.El 293.Pp 294The 295.Fl a 296operator has higher precedence than the 297.Fl o 298operator. 299.Pp 300Some shells may provide a builtin 301.Nm 302command which is similar or identical to this utility. 303Consult the 304.Xr builtin 1 305manual page. 306.Sh GRAMMAR AMBIGUITY 307The 308.Nm 309grammar is inherently ambiguous. 310In order to assure a degree of consistency, 311the cases described in the 312.St -p1003.2 , 313section D11.2/4.62.4, standard 314are evaluated consistently according to the rules specified in the 315standards document. 316All other cases are subject to the ambiguity in the 317command semantics. 318.Pp 319In particular, only expressions containing 320.Fl a , 321.Fl o , 322.Cm \&( 323or 324.Cm \&) 325can be ambiguous. 326.Sh EXIT STATUS 327The 328.Nm 329utility exits with one of the following values: 330.Bl -tag -width indent 331.It 0 332expression evaluated to true. 333.It 1 334expression evaluated to false or expression was 335missing. 336.It >1 337An error occurred. 338.El 339.Sh SEE ALSO 340.Xr builtin 1 , 341.Xr expr 1 , 342.Xr sh 1 , 343.Xr symlink 7 344.Sh STANDARDS 345The 346.Nm 347utility implements a superset of the 348.St -p1003.2 349specification. 350.Sh BUGS 351Both sides are always evaluated in 352.Fl a 353and 354.Fl o . 355For instance, the writable status of 356.Pa file 357will be tested by the following command even though the former expression 358indicated false, which results in a gratuitous access to the file system: 359.Dl "[ -z abc -a -w file ]" 360To avoid this, write 361.Dl "[ -z abc ] && [ -w file ]" 362