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