bin/test/test.1

   1 .\"     $OpenBSD: test.1,v 1.33 2016/08/16 18:51:25 schwarze 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: August 16 2016 $
  37 .Dt TEST 1
  38 .Os
  39 .Sh NAME
  40 .Nm test ,
  41 .Nm \&[
  42 .Nd condition evaluation utility
  43 .Sh SYNOPSIS
  44 .Nm test
  45 .Ar expression
  46 .Nm \&[
  47 .Ar expression Nm \&]
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility evaluates the
  52 .Ar expression
  53 and, if it evaluates
  54 to true, returns a zero (true) exit status; otherwise
  55 it returns 1 (false).
  56 If no
  57 .Ar expression
  58 is given,
  59 .Nm
  60 also
  61 returns 1 (false).
  62 The form
  63 .Nm \&[
  64 is an alias for
  65 .Nm test .
  66 .Pp
  67 All operators and flags are separate arguments to the
  68 .Nm
  69 utility.
  70 Symbolic links are followed for all primaries except
  71 .Fl h
  72 and
  73 .Fl L .
  74 .Pp
  75 The following primaries are used to construct
  76 .Ar expression :
  77 .Bl -tag -width Ds
  78 .It Fl b Ar file
  79 True if
  80 .Ar file
  81 exists and is a block special
  82 file.
  83 .It Fl c Ar file
  84 True if
  85 .Ar file
  86 exists and is a character
  87 special file.
  88 .It Fl d Ar file
  89 True if
  90 .Ar file
  91 exists and is a directory.
  92 .It Fl e Ar file
  93 True if
  94 .Ar file
  95 exists (regardless of type).
  96 .It Fl f Ar file
  97 True if
  98 .Ar file
  99 exists and is a regular file.
 100 .It Fl G Ar file
 101 True if
 102 .Ar file
 103 exists and its group matches the effective group ID of this process.
 104 .It Fl g Ar file
 105 True if
 106 .Ar file
 107 exists and its set-group-ID flag
 108 is set.
 109 .It Fl h Ar file
 110 True if
 111 .Ar file
 112 exists and is a symbolic link.
 113 .It Fl k Ar file
 114 True if
 115 .Ar file
 116 exists and its sticky bit is set.
 117 .It Fl L Ar file
 118 True if
 119 .Ar file
 120 exists and is a symbolic link.
 121 This operator is for compatibility purposes.
 122 Do not rely on its existence;
 123 use
 124 .Fl h
 125 instead.
 126 .It Fl n Ar string
 127 True if the length of
 128 .Ar string
 129 is nonzero.
 130 .It Fl O Ar file
 131 True if
 132 .Ar file
 133 exists and its owner matches the effective user ID of this process.
 134 .It Fl p Ar file
 135 True if
 136 .Ar file
 137 is a named pipe
 138 .Pq Tn FIFO .
 139 .It Fl r Ar file
 140 True if
 141 .Ar file
 142 exists and is readable.
 143 .It Fl S Ar file
 144 True if
 145 .Ar file
 146 exists and is a socket.
 147 .It Fl s Ar file
 148 True if
 149 .Ar file
 150 exists and has a size greater
 151 than zero.
 152 .It Fl t Ar file_descriptor
 153 True if the file whose file descriptor number
 154 is
 155 .Ar file_descriptor
 156 (default 1) is open and is associated with a terminal.
 157 .It Fl u Ar file
 158 True if
 159 .Ar file
 160 exists and its set-user-ID flag
 161 is set.
 162 .It Fl w Ar file
 163 True if
 164 .Ar file
 165 exists and is writable.
 166 True
 167 indicates only that the write flag is on.
 168 The file is not writable on a read-only file
 169 system even if this test indicates true.
 170 .It Fl x Ar file
 171 True if
 172 .Ar file
 173 exists and is executable.
 174 True
 175 indicates only that the execute flag is on.
 176 If
 177 .Ar file
 178 is a directory, true indicates that
 179 .Ar file
 180 can be searched.
 181 .It Fl z Ar string
 182 True if the length of
 183 .Ar string
 184 is zero.
 185 .It Ar file1 Fl nt Ar file2
 186 True if
 187 .Ar file1
 188 exists and is newer than
 189 .Ar file2 .
 190 .It Ar file1 Fl ot Ar file2
 191 True if
 192 .Ar file1
 193 exists and is older than
 194 .Ar file2 .
 195 .It Ar file1 Fl ef Ar file2
 196 True if
 197 .Ar file1
 198 and
 199 .Ar file2
 200 exist and refer to the same file.
 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 \*(Lt Ar s2
 214 True if string
 215 .Ar s1
 216 comes before
 217 .Ar s2
 218 based on the ASCII value of their characters.
 219 .It Ar s1 Cm \*(Gt Ar s2
 220 True if string
 221 .Ar s1
 222 comes after
 223 .Ar s2
 224 based on the ASCII value of their characters.
 225 .It Ar s1
 226 True if
 227 .Ar s1
 228 is not the null
 229 string.
 230 .It Ar n1 Fl eq Ar n2
 231 True if the integers
 232 .Ar n1
 233 and
 234 .Ar n2
 235 are algebraically
 236 equal.
 237 .It Ar n1 Fl ne Ar n2
 238 True if the integers
 239 .Ar n1
 240 and
 241 .Ar n2
 242 are not
 243 algebraically equal.
 244 .It Ar n1 Fl gt Ar n2
 245 True if the integer
 246 .Ar n1
 247 is algebraically
 248 greater than the integer
 249 .Ar n2 .
 250 .It Ar n1 Fl ge Ar n2
 251 True if the integer
 252 .Ar n1
 253 is algebraically
 254 greater than or equal to the integer
 255 .Ar n2 .
 256 .It Ar n1 Fl \&lt Ar n2
 257 True if the integer
 258 .Ar n1
 259 is algebraically less
 260 than the integer
 261 .Ar n2 .
 262 .It Ar n1 Fl le Ar n2
 263 True if the integer
 264 .Ar n1
 265 is algebraically less
 266 than or equal to the integer
 267 .Ar n2 .
 268 .El
 269 .Pp
 270 These primaries can be combined with the following operators.
 271 The
 272 .Fl a
 273 operator has higher precedence than the
 274 .Fl o
 275 operator.
 276 .Bl -tag -width Ds
 277 .It Cm \&! Ar expression
 278 True if
 279 .Ar expression
 280 is false.
 281 .It Ar expression1 Fl a Ar expression2
 282 True if both
 283 .Ar expression1
 284 and
 285 .Ar expression2
 286 are true.
 287 .It Ar expression1 Fl o Ar expression2
 288 True if either
 289 .Ar expression1
 290 or
 291 .Ar expression2
 292 are true.
 293 .It Cm \&( Ar expression Cm \&)
 294 True if
 295 .Ar expression
 296 is true.
 297 .El
 298 .Sh EXIT STATUS
 299 The
 300 .Nm
 301 utility exits with one of the following values:
 302 .Pp
 303 .Bl -tag -width Ds -offset indent -compact
 304 .It 0
 305 Expression evaluated to true.
 306 .It 1
 307 Expression evaluated to false or expression was
 308 missing.
 309 .It \*(Gt1
 310 An error occurred.
 311 .El
 312 .Sh GRAMMAR AMBIGUITY
 313 The
 314 .Nm
 315 grammar is inherently ambiguous.
 316 In order to assure a degree of consistency,
 317 the cases described in
 318 .St -p1003.2
 319 section D11.2/4.62.4
 320 are evaluated consistently according to the rules specified in the
 321 standards document.
 322 All other cases are subject to the ambiguity in the
 323 command semantics.
 324 .Sh SEE ALSO
 325 .Xr ksh 1
 326 .Sh STANDARDS
 327 The
 328 .Nm
 329 utility is compliant with the
 330 .St -p1003.1-2008
 331 specification.
 332 .Pp
 333 The primaries
 334 .Fl G ,
 335 .Fl k ,
 336 .Fl O ,
 337 .Fl nt ,
 338 .Fl ot ,
 339 .Fl ef ,
 340 .Cm \*(Lt ,
 341 and
 342 .Cm \*(Gt
 343 are extensions to that specification.
 344 .Pp
 345 The operators
 346 .Fl a ,
 347 .Fl o ,
 348 and
 349 .Cm ()
 350 are marked by
 351 .St -p1003.1-2008
 352 as part of X/Open System Interfaces and obsolete.
 353 .Pp
 354 .Nm
 355 also exists as a built-in to
 356 .Xr ksh 1 ,
 357 though with a different syntax.
 358 .Sh HISTORY
 359 A
 360 .Nm
 361 utility appeared in
 362 .At v7 .