bin/test/test.1

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