test/test.1

   1 .\"     $NetBSD: test.1,v 1.10 1997/11/12 00:48:21 mrg Exp $
   2 .\"
   3 .\" Copyright (c) 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the Institute of Electrical and Electronics Engineers, Inc.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\"
  37 .\"     @(#)test.1      8.1 (Berkeley) 5/31/93
  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 expressions:
  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. 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 .Po Tn FIFO Pc .
 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 \&n\&1 Fl \&eq Ar \&n\&2
 218 True if the integers
 219 .Ar \&n\&1
 220 and
 221 .Ar \&n\&2
 222 are algebraically
 223 equal.
 224 .It Ar \&n\&1 Fl \&ne Ar \&n\&2
 225 True if the integers
 226 .Ar \&n\&1
 227 and
 228 .Ar \&n\&2
 229 are not
 230 algebraically equal.
 231 .It Ar \&n\&1 Fl \&gt Ar \&n\&2
 232 True if the integer
 233 .Ar \&n\&1
 234 is algebraically
 235 greater than the integer
 236 .Ar \&n\&2 .
 237 .It Ar \&n\&1 Fl \&ge Ar \&n\&2
 238 True if the integer
 239 .Ar \&n\&1
 240 is algebraically
 241 greater than or equal to the integer
 242 .Ar \&n\&2 .
 243 .It Ar \&n\&1 Fl \&lt Ar \&n\&2
 244 True if the integer
 245 .Ar \&n\&1
 246 is algebraically less
 247 than the integer
 248 .Ar \&n\&2 .
 249 .It Ar \&n\&1 Fl \&le Ar \&n\&2
 250 True if the integer
 251 .Ar \&n\&1
 252 is algebraically less
 253 than or equal to the integer
 254 .Ar \&n\&2 .
 255 .El
 256 .Pp
 257 These primaries can be combined with the following operators:
 258 .Bl -tag -width Ar
 259 .It Cm \&! Ar expression
 260 True if
 261 .Ar expression
 262 is false.
 263 .It Ar expression1 Fl a Ar expression2
 264 True if both
 265 .Ar expression1
 266 and
 267 .Ar expression2
 268 are true.
 269 .It Ar expression1 Fl o Ar expression2
 270 True if either
 271 .Ar expression1
 272 or
 273 .Ar expression2
 274 are true.
 275 .It Cm \&( Ns Ar expression Ns Cm \&)
 276 True if expression is true.
 277 .El
 278 .Pp
 279 The
 280 .Fl a
 281 operator has higher precedence than the
 282 .Fl o
 283 operator.
 284 .Sh GRAMMAR AMBIGUITY
 285 The
 286 .Nm
 287 grammar is inherently ambiguous.  In order to assure a degree of consistency,
 288 the cases described in
 289 .St -p1003.2
 290 section 4.62.4,
 291 are evaluated consistently according to the rules specified in the
 292 standards document.  All other cases are subject to the ambiguity in the
 293 command semantics.
 294 .Sh RETURN VALUES
 295 The
 296 .Nm
 297 utility exits with one of the following values:
 298 .Bl -tag -width Ds
 299 .It 0
 300 expression evaluated to true.
 301 .It 1
 302 expression evaluated to false or expression was
 303 missing.
 304 .It >1
 305 An error occurred.
 306 .El
 307 .Sh STANDARDS
 308 The
 309 .Nm
 310 utility implements a superset of the
 311 .St -p1003.2
 312 specification.