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 June 1, 2013
  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
 173 .Ar file1
 174 exists and is newer than
 175 .Ar file2 .
 176 .It Ar file1 Fl ot Ar file2
 177 True if
 178 .Ar file1
 179 exists and is older than
 180 .Ar file2 .
 181 .It Ar file1 Fl ef Ar file2
 182 True if
 183 .Ar file1
 184 and
 185 .Ar file2
 186 exist and refer to the same file.
 187 .It Ar string
 188 True if
 189 .Ar string
 190 is not the null
 191 string.
 192 .It Ar s1 Cm = Ar s2
 193 True if the strings
 194 .Ar s1
 195 and
 196 .Ar s2
 197 are identical.
 198 .It Ar s1 Cm != Ar s2
 199 True if the strings
 200 .Ar s1
 201 and
 202 .Ar s2
 203 are not identical.
 204 .It Ar s1 Cm < Ar s2
 205 True if string
 206 .Ar s1
 207 comes before
 208 .Ar s2
 209 based on the binary value of their characters.
 210 .It Ar s1 Cm > Ar s2
 211 True if string
 212 .Ar s1
 213 comes after
 214 .Ar s2
 215 based on the binary value of their characters.
 216 .It Ar n1 Fl eq Ar n2
 217 True if the integers
 218 .Ar n1
 219 and
 220 .Ar n2
 221 are algebraically
 222 equal.
 223 .It Ar n1 Fl ne Ar n2
 224 True if the integers
 225 .Ar n1
 226 and
 227 .Ar n2
 228 are not
 229 algebraically equal.
 230 .It Ar n1 Fl gt Ar n2
 231 True if the integer
 232 .Ar n1
 233 is algebraically
 234 greater than the integer
 235 .Ar n2 .
 236 .It Ar n1 Fl ge Ar n2
 237 True if the integer
 238 .Ar n1
 239 is algebraically
 240 greater than or equal to the integer
 241 .Ar n2 .
 242 .It Ar n1 Fl lt Ar n2
 243 True if the integer
 244 .Ar n1
 245 is algebraically less
 246 than the integer
 247 .Ar n2 .
 248 .It Ar n1 Fl le Ar n2
 249 True if the integer
 250 .Ar n1
 251 is algebraically less
 252 than or equal to the integer
 253 .Ar n2 .
 254 .El
 255 .Pp
 256 If
 257 .Ar file
 258 is a symbolic link,
 259 .Nm
 260 will fully dereference it and then evaluate the expression
 261 against the file referenced, except for the
 262 .Fl h
 263 and
 264 .Fl L
 265 primaries.
 266 .Pp
 267 These primaries can be combined with the following operators:
 268 .Bl -tag -width Ar
 269 .It Cm \&! Ar expression
 270 True if
 271 .Ar expression
 272 is false.
 273 .It Ar expression1 Fl a Ar expression2
 274 True if both
 275 .Ar expression1
 276 and
 277 .Ar expression2
 278 are true.
 279 .It Ar expression1 Fl o Ar expression2
 280 True if either
 281 .Ar expression1
 282 or
 283 .Ar expression2
 284 are true.
 285 .It Cm \&( Ar expression Cm \&)
 286 True if expression is true.
 287 .El
 288 .Pp
 289 The
 290 .Fl a
 291 operator has higher precedence than the
 292 .Fl o
 293 operator.
 294 .Pp
 295 Some shells may provide a builtin
 296 .Nm
 297 command which is similar or identical to this utility.
 298 Consult the
 299 .Xr builtin 1
 300 manual page.
 301 .Sh GRAMMAR AMBIGUITY
 302 The
 303 .Nm
 304 grammar is inherently ambiguous.
 305 In order to assure a degree of consistency,
 306 the cases described in the
 307 .St -p1003.2 ,
 308 section D11.2/4.62.4, standard
 309 are evaluated consistently according to the rules specified in the
 310 standards document.
 311 All other cases are subject to the ambiguity in the
 312 command semantics.
 313 .Pp
 314 In particular, only expressions containing
 315 .Fl a ,
 316 .Fl o ,
 317 .Cm \&(
 318 or
 319 .Cm \&)
 320 can be ambiguous.
 321 .Sh EXIT STATUS
 322 The
 323 .Nm
 324 utility exits with one of the following values:
 325 .Bl -tag -width indent
 326 .It 0
 327 expression evaluated to true.
 328 .It 1
 329 expression evaluated to false or expression was
 330 missing.
 331 .It >1
 332 An error occurred.
 333 .El
 334 .Sh EXAMPLES
 335 Implement
 336 .Li test FILE1 -nt FILE2
 337 using only
 338 .Tn POSIX
 339 functionality:
 340 .Pp
 341 .Dl test -n \&"$(find -L -- FILE1 -prune -newer FILE2 2>/dev/null)\&"
 342 .Pp
 343 This can be modified using non-standard
 344 .Xr find 1
 345 primaries like
 346 .Cm -newerca
 347 to compare other timestamps.
 348 .Sh COMPATIBILITY
 349 For compatibility with some other implementations,
 350 the
 351 .Cm =
 352 primary can be substituted with
 353 .Cm ==
 354 with 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
 363 The
 364 .Nm
 365 utility implements a superset of the
 366 .St -p1003.2
 367 specification.
 368 The primaries
 369 .Cm < ,
 370 .Cm == ,
 371 .Cm > ,
 372 .Fl ef ,
 373 .Fl nt ,
 374 .Fl ot ,
 375 .Fl G ,
 376 and
 377 .Fl O
 378 are extensions.
 379 .Sh BUGS
 380 Both sides are always evaluated in
 381 .Fl a
 382 and
 383 .Fl o .
 384 For instance, the writable status of
 385 .Pa file
 386 will be tested by the following command even though the former expression
 387 indicated false, which results in a gratuitous access to the file system:
 388 .Dl "[ -z abc -a -w file ]"
 389 To avoid this, write
 390 .Dl "[ -z abc ] && [ -w file ]"