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