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