1.\" $NetBSD: test.1,v 1.33 2017/10/18 18:11:54 wiz Exp $ 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.\" @(#)test.1 8.1 (Berkeley) 5/31/93 34.\" 35.Dd October 17, 2017 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 51.Ar expression 52and, if it evaluates 53to true, returns a zero (true) exit status; otherwise 54it returns 1 (false). 55If 56.Ar expression 57is not given, 58.Nm 59also 60returns 1 (false). 61.Pp 62All operators and flags are separate arguments to the 63.Nm 64utility. 65.Pp 66The following primaries are used to construct 67.Ar expression : 68.Bl -tag -width Ar 69.It Fl b Ar file 70True if 71.Ar file 72exists and is a block special 73file. 74.It Fl c Ar file 75True if 76.Ar file 77exists and is a character 78special file. 79.It Fl d Ar file 80True if 81.Ar file 82exists and is a directory. 83.It Fl e Ar file 84True if 85.Ar file 86exists (regardless of type). 87.It Fl f Ar file 88True if 89.Ar file 90exists and is a regular file. 91.It Fl g Ar file 92True if 93.Ar file 94exists and its set group ID flag 95is set. 96.It Fl h Ar file 97True if 98.Ar file 99exists and is a symbolic link. 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 111exists and is a named pipe (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 only that the write flag is on. 137The file is not writable on a read-only file 138system even if this test indicates true. 139.It Fl x Ar file 140True if 141.Ar file 142exists and is executable. 143True 144indicates only that the execute flag is on. 145If 146.Ar file 147is a directory, true indicates that 148.Ar file 149can be searched. 150.It Fl z Ar string 151True if the length of 152.Ar string 153is zero. 154.It Fl L Ar file 155True if 156.Ar file 157exists and is a symbolic link. 158This operator is retained for compatibility with previous versions of 159this program. 160Do not rely on its existence; use 161.Fl h 162instead. 163.It Fl O Ar file 164True if 165.Ar file 166exists and its owner matches the effective user id of this process. 167.It Fl G Ar file 168True if 169.Ar file 170exists and its group matches the effective group id of this process. 171.It Fl S Ar file 172True if 173.Ar file 174exists and is a socket. 175.It Ar file1 Fl nt Ar file2 176True if 177.Ar file1 178exists and is newer than 179.Ar file2 . 180.It Ar file1 Fl ot Ar file2 181True if 182.Ar file1 183exists and is older than 184.Ar file2 . 185.It Ar file1 Fl ef Ar file2 186True if 187.Ar file1 188and 189.Ar file2 190exist and refer to the same file. 191.It Ar string 192True if 193.Ar string 194is not the null 195string. 196.It Ar \&s\&1 Cm \&= Ar \&s\&2 197True if the strings 198.Ar \&s\&1 199and 200.Ar \&s\&2 201are identical. 202.It Ar \&s\&1 Cm \&!= Ar \&s\&2 203True if the strings 204.Ar \&s\&1 205and 206.Ar \&s\&2 207are not identical. 208.It Ar \&s\&1 Cm \&< Ar \&s\&2 209True if string 210.Ar \&s\&1 211comes before 212.Ar \&s\&2 213based on the ASCII value of their characters. 214.It Ar \&s\&1 Cm \&> Ar \&s\&2 215True if string 216.Ar \&s\&1 217comes after 218.Ar \&s\&2 219based on the ASCII value of their characters. 220.It Ar \&n\&1 Fl \&eq Ar \&n\&2 221True if the integers 222.Ar \&n\&1 223and 224.Ar \&n\&2 225are algebraically 226equal. 227.It Ar \&n\&1 Fl \&ne Ar \&n\&2 228True if the integers 229.Ar \&n\&1 230and 231.Ar \&n\&2 232are not 233algebraically equal. 234.It Ar \&n\&1 Fl \> Ar \&n\&2 235True if the integer 236.Ar \&n\&1 237is algebraically 238greater than the integer 239.Ar \&n\&2 . 240.It Ar \&n\&1 Fl \&ge Ar \&n\&2 241True if the integer 242.Ar \&n\&1 243is algebraically 244greater than or equal to the integer 245.Ar \&n\&2 . 246.It Ar \&n\&1 Fl \< Ar \&n\&2 247True if the integer 248.Ar \&n\&1 249is algebraically less 250than the integer 251.Ar \&n\&2 . 252.It Ar \&n\&1 Fl \&le Ar \&n\&2 253True if the integer 254.Ar \&n\&1 255is algebraically less 256than or equal to the integer 257.Ar \&n\&2 . 258.El 259.Pp 260These primaries can be combined with the following operators: 261.Bl -tag -width Ar 262.It Cm \&! Ar expression 263True if 264.Ar expression 265is false. 266.It Ar expression1 Fl a Ar expression2 267True if both 268.Ar expression1 269and 270.Ar expression2 271are true. 272.It Ar expression1 Fl o Ar expression2 273True if either 274.Ar expression1 275or 276.Ar expression2 277is true. 278.It Cm \&( Ar expression Cm \&) 279True if 280.Ar expression 281is true. 282.El 283.Pp 284The 285.Fl a 286operator has higher precedence than the 287.Fl o 288operator. 289.Pp 290Note that all file tests with the exception of 291.Fl h 292and 293.Fl L 294follow symbolic links and thus evaluate the test for the file pointed at. 295.Sh EXIT STATUS 296The 297.Nm 298utility exits with one of the following values: 299.Bl -tag -width Ds 300.It 0 301.Ar expression 302evaluated to true. 303.It 1 304.Ar expression 305evaluated to false or was missing. 306.It >1 307An error occurred. 308.El 309.Sh STANDARDS 310The 311.Nm 312utility implements a superset of the 313.St -p1003.2 314specification. 315.Sh HISTORY 316A 317.Nm 318utility appeared in 319.At v7 . 320.Sh CAVEATS 321The 322.Nm 323grammar is inherently ambiguous. 324In order to assure a degree of consistency, the cases described in 325.St -p1003.2 326section 4.62.4, 327are evaluated consistently according to the rules specified in the 328standards document. 329All other cases are subject to the ambiguity in the command semantics. 330.Pp 331This means that 332.Nm 333should not be used with more than 4 operands 334(where the terminating 335.Cm \&] 336in the case of the 337.Nm \&[ 338command does not count as an operand,) 339and that the obsolete 340.Fl a 341and 342.Fl o 343options should not be used. 344Instead invoke 345.Nm 346multiple times connected by the 347.Dq && 348and 349.Dq || 350operators from 351.Xr sh 1 . 352When those operators are not used, there is no need 353for the parentheses as grouping symbols, so those should also be 354avoided. 355Using 356.Xr sh 1 Ns 's 357.Cm \&! 358command instead of the equivalent operator from 359.Nm 360can also protect the script from future test enhancements. 361.Pp 362Most expressions with 3 or less operands will evaluate as expected, 363though be aware that with 3 operands, 364if the second is a known binary operator, 365that is always evaluated, 366regardless of what the other operands might suggest had been intended. 367If, and only if, the middle operand is not a defined binary operator 368is the first operand examined to see if it is 369.Cm \&! 370in which case the remaining operands are evaluated as a two operand test, 371and the result inverted. 372The only other defined three operand case is the meaningless 373degenerate case where parentheses (1st and 3rd operands) 374surround a one operand expression. 375.Pp 376With 4 operands there are just two defined cases, the first 377where the first operand is 378.Cm \&! 379in which case the result of the three operand test on the 380remaining operands is inverted, 381and the second is similar to the 3 operand case, 382the degenerate case of parentheses surrounding an (in this case) 3832 operand test expression. 384