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 test
  48 .Ar expression
  49 .Nm [
  50 .Ar expression Cm ]
  51 .Sh DESCRIPTION
  52 The
  53 .Nm test
  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 test
  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. 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 \&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 .Sh GRAMMAR AMBIGUITY
 290 The
 291 .Nm test
 292 grammar is inherently ambiguous.  In order to assure a degree of consistency,
 293 the cases described in
 294 .St -p1003.2
 295 section 4.62.4,
 296 are evaluated consistently according to the rules specified in the
 297 standards document.  All other cases are subject to the ambiguity in the
 298 command semantics.
 299 .Sh RETURN VALUES
 300 The
 301 .Nm test
 302 utility exits with one of the following values:
 303 .Bl -tag -width Ds
 304 .It 0
 305 expression evaluated to true.
 306 .It 1
 307 expression evaluated to false or expression was
 308 missing.
 309 .It >1
 310 An error occurred.
 311 .El
 312 .Sh STANDARDS
 313 The
 314 .Nm test
 315 utility implements a superset of the
 316 .St -p1003.2
 317 specification.