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