bin/test/test.1

   1 .\" Copyright (c) 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the Institute of Electrical and Electronics Engineers, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)test.1      8.1 (Berkeley) 5/31/93
  36 .\" $FreeBSD: src/bin/test/test.1,v 1.11.2.5 2001/12/14 14:22:09 ru Exp $
  37 .\" $DragonFly: src/bin/test/test.1,v 1.7 2007/10/20 17:56:46 swildner Exp $
  38 .\"
  39 .Dd May 31, 1993
  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 \&s\&1 Cm \&= Ar \&s\&2
 202 True if the strings
 203 .Ar \&s\&1
 204 and
 205 .Ar \&s\&2
 206 are identical.
 207 .It Ar \&s\&1 Cm \&!= Ar \&s\&2
 208 True if the strings
 209 .Ar \&s\&1
 210 and
 211 .Ar \&s\&2
 212 are not identical.
 213 .It Ar \&s\&1 Cm \&< Ar \&s\&2
 214 True if string
 215 .Ar \&s\&1
 216 comes before
 217 .Ar \&s\&2
 218 based on the ASCII value of their characters.
 219 .It Ar \&s\&1 Cm \&> Ar \&s\&2
 220 True if string
 221 .Ar \&s\&1
 222 comes after
 223 .Ar \&s\&2
 224 based on the ASCII value of their characters.
 225 .It Ar \&s\&1
 226 True if
 227 .Ar \&s\&1
 228 is not the null
 229 string.
 230 .It Ar \&n\&1 Fl \&eq Ar \&n\&2
 231 True if the integers
 232 .Ar \&n\&1
 233 and
 234 .Ar \&n\&2
 235 are algebraically
 236 equal.
 237 .It Ar \&n\&1 Fl \&ne Ar \&n\&2
 238 True if the integers
 239 .Ar \&n\&1
 240 and
 241 .Ar \&n\&2
 242 are not
 243 algebraically equal.
 244 .It Ar \&n\&1 Fl \&gt Ar \&n\&2
 245 True if the integer
 246 .Ar \&n\&1
 247 is algebraically
 248 greater than the integer
 249 .Ar \&n\&2 .
 250 .It Ar \&n\&1 Fl \&ge Ar \&n\&2
 251 True if the integer
 252 .Ar \&n\&1
 253 is algebraically
 254 greater than or equal to the integer
 255 .Ar \&n\&2 .
 256 .It Ar \&n\&1 Fl \&lt Ar \&n\&2
 257 True if the integer
 258 .Ar \&n\&1
 259 is algebraically less
 260 than the integer
 261 .Ar \&n\&2 .
 262 .It Ar \&n\&1 Fl \&le Ar \&n\&2
 263 True if the integer
 264 .Ar \&n\&1
 265 is algebraically less
 266 than or equal to the integer
 267 .Ar \&n\&2 .
 268 .El
 269 .Pp
 270 These primaries can be combined with the following operators:
 271 .Bl -tag -width Ar
 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 \&( Ns Ar expression Ns Cm \&)
 289 True if expression is true.
 290 .El
 291 .Pp
 292 The
 293 .Fl a
 294 operator has higher precedence than the
 295 .Fl o
 296 operator.
 297 .Pp
 298 Some shells may provide a builtin
 299 .Nm
 300 command which is similar or identical to this utility.
 301 Consult the
 302 .Xr builtin 1
 303 manual page.
 304 .Sh GRAMMAR AMBIGUITY
 305 The
 306 .Nm
 307 grammar is inherently ambiguous.  In order to assure a degree of consistency,
 308 the cases described in the
 309 .St -p1003.2 ,
 310 section D11.2/4.62.4, standard
 311 are evaluated consistently according to the rules specified in the
 312 standards document.  All other cases are subject to the ambiguity in the
 313 command semantics.
 314 .Sh DIAGNOSTICS
 315 The
 316 .Nm
 317 utility exits with one of the following values:
 318 .Bl -tag -width Ds
 319 .It 0
 320 expression evaluated to true.
 321 .It 1
 322 expression evaluated to false or expression was
 323 missing.
 324 .It >1
 325 An error occurred.
 326 .El
 327 .Sh SEE ALSO
 328 .Xr builtin 1 ,
 329 .Xr expr 1 ,
 330 .Xr sh 1
 331 .Sh STANDARDS
 332 The
 333 .Nm
 334 utility implements a superset of the
 335 .St -p1003.2
 336 specification.