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.2 2003/06/17 04:22:50 dillon 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 only that the write flag is on.
 140 The file is not writable on a read-only file
 141 system even if this test indicates true.
 142 .It Fl x Ar file
 143 True if
 144 .Ar file
 145 exists and is executable.
 146 True
 147 indicates only that the execute flag is on.
 148 If
 149 .Ar file
 150 is a directory, true indicates that
 151 .Ar file
 152 can be searched.
 153 .It Fl z Ar string
 154 True if the length of
 155 .Ar string
 156 is zero.
 157 .It Fl L Ar file
 158 True if
 159 .Ar file
 160 exists and is a symbolic link.
 161 .It Fl O Ar file
 162 True if
 163 .Ar file
 164 exists and its owner matches the effective user id of this process.
 165 .It Fl G Ar file
 166 True if
 167 .Ar file
 168 exists and its group matches the effective group id of this process.
 169 .It Fl S Ar file
 170 True if
 171 .Ar file
 172 exists and is a socket.
 173 .It Ar file1 Fl nt Ar file2
 174 True if
 175 .Ar file1
 176 exists and is newer than
 177 .Ar file2 .
 178 .It Ar file1 Fl ot Ar file2
 179 True if
 180 .Ar file1
 181 exists and is older than
 182 .Ar file2 .
 183 .It Ar file1 Fl ef Ar file2
 184 True if
 185 .Ar file1
 186 and
 187 .Ar file2
 188 exist and refer to the same file.
 189 .It Ar string
 190 True if
 191 .Ar string
 192 is not the null
 193 string.
 194 .It Ar \&s\&1 Cm \&= Ar \&s\&2
 195 True if the strings
 196 .Ar \&s\&1
 197 and
 198 .Ar \&s\&2
 199 are identical.
 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 not identical.
 206 .It Ar \&s\&1 Cm \&< Ar \&s\&2
 207 True if string
 208 .Ar \&s\&1
 209 comes before
 210 .Ar \&s\&2
 211 based on the ASCII value of their characters.
 212 .It Ar \&s\&1 Cm \&> Ar \&s\&2
 213 True if string
 214 .Ar \&s\&1
 215 comes after
 216 .Ar \&s\&2
 217 based on the ASCII value of their characters.
 218 .It Ar \&s\&1
 219 True if
 220 .Ar \&s\&1
 221 is not the null
 222 string.
 223 .It Ar \&n\&1 Fl \&eq Ar \&n\&2
 224 True if the integers
 225 .Ar \&n\&1
 226 and
 227 .Ar \&n\&2
 228 are algebraically
 229 equal.
 230 .It Ar \&n\&1 Fl \&ne Ar \&n\&2
 231 True if the integers
 232 .Ar \&n\&1
 233 and
 234 .Ar \&n\&2
 235 are not
 236 algebraically equal.
 237 .It Ar \&n\&1 Fl \&gt Ar \&n\&2
 238 True if the integer
 239 .Ar \&n\&1
 240 is algebraically
 241 greater than the integer
 242 .Ar \&n\&2 .
 243 .It Ar \&n\&1 Fl \&ge Ar \&n\&2
 244 True if the integer
 245 .Ar \&n\&1
 246 is algebraically
 247 greater than or equal to the integer
 248 .Ar \&n\&2 .
 249 .It Ar \&n\&1 Fl \&lt Ar \&n\&2
 250 True if the integer
 251 .Ar \&n\&1
 252 is algebraically less
 253 than the integer
 254 .Ar \&n\&2 .
 255 .It Ar \&n\&1 Fl \&le Ar \&n\&2
 256 True if the integer
 257 .Ar \&n\&1
 258 is algebraically less
 259 than or equal to the integer
 260 .Ar \&n\&2 .
 261 .El
 262 .Pp
 263 These primaries can be combined with the following operators:
 264 .Bl -tag -width Ar
 265 .It Cm \&! Ar expression
 266 True if
 267 .Ar expression
 268 is false.
 269 .It Ar expression1 Fl a Ar expression2
 270 True if both
 271 .Ar expression1
 272 and
 273 .Ar expression2
 274 are true.
 275 .It Ar expression1 Fl o Ar expression2
 276 True if either
 277 .Ar expression1
 278 or
 279 .Ar expression2
 280 are true.
 281 .It Cm \&( Ns Ar expression Ns Cm \&)
 282 True if expression is true.
 283 .El
 284 .Pp
 285 The
 286 .Fl a
 287 operator has higher precedence than the
 288 .Fl o
 289 operator.
 290 .Pp
 291 Some shells may provide a builtin
 292 .Nm
 293 command which is similar or identical to this utility.
 294 Consult the
 295 .Xr builtin 1
 296 manual page.
 297 .Sh GRAMMAR AMBIGUITY
 298 The
 299 .Nm
 300 grammar is inherently ambiguous.  In order to assure a degree of consistency,
 301 the cases described in the
 302 .St -p1003.2 ,
 303 section D11.2/4.62.4, standard
 304 are evaluated consistently according to the rules specified in the
 305 standards document.  All other cases are subject to the ambiguity in the
 306 command semantics.
 307 .Sh RETURN VALUES
 308 The
 309 .Nm
 310 utility exits with one of the following values:
 311 .Bl -tag -width Ds
 312 .It 0
 313 expression evaluated to true.
 314 .It 1
 315 expression evaluated to false or expression was
 316 missing.
 317 .It >1
 318 An error occurred.
 319 .El
 320 .Sh SEE ALSO
 321 .Xr builtin 1 ,
 322 .Xr expr 1 ,
 323 .Xr sh 1
 324 .Sh STANDARDS
 325 The
 326 .Nm
 327 utility implements a superset of the
 328 .St -p1003.2
 329 specification.