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