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