bin/test/test.1

   1 .\"     $OpenBSD: test.1,v 1.30 2010/09/11 20:54:22 jmc Exp $
   2 .\"     $NetBSD: test.1,v 1.6 1995/03/21 07:04:03 cgd Exp $
   3 .\"
   4 .\" Copyright (c) 1991, 1993
   5 .\"     The Regents of the University of California.  All rights reserved.
   6 .\"
   7 .\" This code is derived from software contributed to Berkeley by
   8 .\" the Institute of Electrical and Electronics Engineers, Inc.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)test.1      8.1 (Berkeley) 5/31/93
  35 .\"
  36 .Dd $Mdocdate: September 11 2010 $
  37 .Dt TEST 1
  38 .Os
  39 .Sh NAME
  40 .Nm test
  41 .Nd condition evaluation utility
  42 .Sh SYNOPSIS
  43 .Nm test
  44 .Ar expression
  45 .Nm \&[
  46 .Ar expression Nm \&]
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility evaluates the
  51 .Ar expression
  52 and, if it evaluates
  53 to true, returns a zero (true) exit status; otherwise
  54 it returns 1 (false).
  55 If no
  56 .Ar expression
  57 is given,
  58 .Nm
  59 also
  60 returns 1 (false).
  61 .Pp
  62 All operators and flags are separate arguments to the
  63 .Nm
  64 utility.
  65 Symbolic links are followed for all primaries except
  66 .Fl h
  67 and
  68 .Fl L .
  69 .Pp
  70 The following primaries are used to construct
  71 .Ar expression :
  72 .Bl -tag -width Ds
  73 .It Fl b Ar file
  74 True if
  75 .Ar file
  76 exists and is a block special
  77 file.
  78 .It Fl c Ar file
  79 True if
  80 .Ar file
  81 exists and is a character
  82 special file.
  83 .It Fl d Ar file
  84 True if
  85 .Ar file
  86 exists and is a directory.
  87 .It Fl e Ar file
  88 True if
  89 .Ar file
  90 exists (regardless of type).
  91 .It Fl f Ar file
  92 True if
  93 .Ar file
  94 exists and is a regular file.
  95 .It Fl G Ar file
  96 True if
  97 .Ar file
  98 exists and its group matches the effective group ID of this process.
  99 .It Fl g Ar file
 100 True if
 101 .Ar file
 102 exists and its set-group-ID flag
 103 is set.
 104 .It Fl h Ar file
 105 True if
 106 .Ar file
 107 exists and is a symbolic link.
 108 .It Fl k Ar file
 109 True if
 110 .Ar file
 111 exists and its sticky bit is set.
 112 .It Fl L Ar file
 113 True if
 114 .Ar file
 115 exists and is a symbolic link.
 116 This operator is for compatibility purposes.
 117 Do not rely on its existence;
 118 use
 119 .Fl h
 120 instead.
 121 .It Fl n Ar string
 122 True if the length of
 123 .Ar string
 124 is nonzero.
 125 .It Fl O Ar file
 126 True if
 127 .Ar file
 128 exists and its owner matches the effective user ID of this process.
 129 .It Fl p Ar file
 130 True if
 131 .Ar file
 132 is a named pipe
 133 .Pq Tn FIFO .
 134 .It Fl r Ar file
 135 True if
 136 .Ar file
 137 exists and is readable.
 138 .It Fl S Ar file
 139 True if
 140 .Ar file
 141 exists and is a socket.
 142 .It Fl s Ar file
 143 True if
 144 .Ar file
 145 exists and has a size greater
 146 than zero.
 147 .It Fl t Ar file_descriptor
 148 True if the file whose file descriptor number
 149 is
 150 .Ar file_descriptor
 151 (default 1) is open and is associated with a terminal.
 152 .It Fl u Ar file
 153 True if
 154 .Ar file
 155 exists and its set-user-ID flag
 156 is set.
 157 .It Fl w Ar file
 158 True if
 159 .Ar file
 160 exists and is writable.
 161 True
 162 indicates only that the write flag is on.
 163 The file is not writable on a read-only file
 164 system even if this test indicates true.
 165 .It Fl x Ar file
 166 True if
 167 .Ar file
 168 exists and is executable.
 169 True
 170 indicates only that the execute flag is on.
 171 If
 172 .Ar file
 173 is a directory, true indicates that
 174 .Ar file
 175 can be searched.
 176 .It Fl z Ar string
 177 True if the length of
 178 .Ar string
 179 is zero.
 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 s1 Cm = Ar s2
 197 True if the strings
 198 .Ar s1
 199 and
 200 .Ar s2
 201 are identical.
 202 .It Ar s1 Cm != Ar s2
 203 True if the strings
 204 .Ar s1
 205 and
 206 .Ar s2
 207 are not identical.
 208 .It Ar s1 Cm \*(Lt Ar s2
 209 True if string
 210 .Ar s1
 211 comes before
 212 .Ar s2
 213 based on the ASCII value of their characters.
 214 .It Ar s1 Cm \*(Gt Ar s2
 215 True if string
 216 .Ar s1
 217 comes after
 218 .Ar s2
 219 based on the ASCII value of their characters.
 220 .It Ar s1
 221 True if
 222 .Ar s1
 223 is not the null
 224 string.
 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 These primaries can be combined with the following operators.
 266 The
 267 .Fl a
 268 operator has higher precedence than the
 269 .Fl o
 270 operator.
 271 .Bl -tag -width Ds
 272 .It Cm \&! Ar expression
 273 True if
 274 .Ar expression
 275 is false.
 276 .It Ar expression1 Fl a Ar expression2
 277 True if both
 278 .Ar expression1
 279 and
 280 .Ar expression2
 281 are true.
 282 .It Ar expression1 Fl o Ar expression2
 283 True if either
 284 .Ar expression1
 285 or
 286 .Ar expression2
 287 are true.
 288 .It Cm \&( Ar expression Cm \&)
 289 True if
 290 .Ar expression
 291 is true.
 292 .El
 293 .Sh EXIT STATUS
 294 The
 295 .Nm
 296 utility exits with one of the following values:
 297 .Pp
 298 .Bl -tag -width Ds -offset indent -compact
 299 .It 0
 300 Expression evaluated to true.
 301 .It 1
 302 Expression evaluated to false or expression was
 303 missing.
 304 .It \*(Gt1
 305 An error occurred.
 306 .El
 307 .Sh GRAMMAR AMBIGUITY
 308 The
 309 .Nm
 310 grammar is inherently ambiguous.
 311 In order to assure a degree of consistency,
 312 the cases described in
 313 .St -p1003.2
 314 section D11.2/4.62.4
 315 are evaluated consistently according to the rules specified in the
 316 standards document.
 317 All other cases are subject to the ambiguity in the
 318 command semantics.
 319 .Sh SEE ALSO
 320 .Xr ksh 1
 321 .Sh STANDARDS
 322 The
 323 .Nm
 324 utility is compliant with the
 325 .St -p1003.1-2008
 326 specification.
 327 .Pp
 328 The primaries
 329 .Fl G ,
 330 .Fl k ,
 331 .Fl O ,
 332 .Fl nt ,
 333 .Fl ot ,
 334 .Fl ef ,
 335 .Cm \*(Lt ,
 336 and
 337 .Cm \*(Gt
 338 are extensions to that specification.
 339 .Pp
 340 .Nm
 341 also exists as a built-in to
 342 .Xr ksh 1 ,
 343 though with a different syntax.