bin/test/test.1

   1 .\"     $NetBSD: test.1,v 1.26 2009/05/06 08:26:43 wiz 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. Neither the name of the University nor the names of its contributors
  18 .\"    may be used to endorse or promote products derived from this software
  19 .\"    without specific prior written permission.
  20 .\"
  21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31 .\" SUCH DAMAGE.
  32 .\"
  33 .\"     @(#)test.1      8.1 (Berkeley) 5/31/93
  34 .\"
  35 .Dd November 10, 2009
  36 .Dt TEST 1
  37 .Os
  38 .Sh NAME
  39 .Nm test ,
  40 .Nm \&[
  41 .Nd condition evaluation utility
  42 .Sh SYNOPSIS
  43 .Nm test
  44 .Ar expression
  45 .Nm \&[
  46 .Ar expression Cm \&]
  47 .Sh DESCRIPTION
  48 The
  49 .Nm test
  50 utility evaluates
  51 .Ar expression
  52 and, if it evaluates
  53 to true, returns a zero (true) exit status; otherwise
  54 it returns 1 (false).
  55 If
  56 .Ar expression
  57 is not given,
  58 .Nm test
  59 also
  60 returns 1 (false).
  61 .Pp
  62 All operators and flags are separate arguments to the
  63 .Nm test
  64 utility.
  65 .Pp
  66 The following primaries are used to construct
  67 .Ar expression :
  68 .Bl -tag -width Ar
  69 .It Fl b Ar file
  70 True if
  71 .Ar file
  72 exists and is a block special
  73 file.
  74 .It Fl c Ar file
  75 True if
  76 .Ar file
  77 exists and is a character
  78 special file.
  79 .It Fl d Ar file
  80 True if
  81 .Ar file
  82 exists and is a directory.
  83 .It Fl e Ar file
  84 True if
  85 .Ar file
  86 exists (regardless of type).
  87 .It Fl f Ar file
  88 True if
  89 .Ar file
  90 exists and is a regular file.
  91 .It Fl g Ar file
  92 True if
  93 .Ar file
  94 exists and its set group ID flag
  95 is set.
  96 .It Fl h Ar file
  97 True if
  98 .Ar file
  99 exists and is a symbolic link.
 100 .It Fl k Ar file
 101 True if
 102 .Ar file
 103 exists and its sticky bit is set.
 104 .It Fl n Ar string
 105 True if the length of
 106 .Ar string
 107 is nonzero.
 108 .It Fl p Ar file
 109 True if
 110 .Ar file
 111 exists and is a named pipe
 112 .Po Tn FIFO Pc .
 113 .It Fl r Ar file
 114 True if
 115 .Ar file
 116 exists and is readable.
 117 .It Fl s Ar file
 118 True if
 119 .Ar file
 120 exists and has a size greater
 121 than zero.
 122 .It Fl t Ar file_descriptor
 123 True if the file whose file descriptor number
 124 is
 125 .Ar file_descriptor
 126 is open and is associated with a terminal.
 127 .It Fl u Ar file
 128 True if
 129 .Ar file
 130 exists and its set user ID flag
 131 is set.
 132 .It Fl w Ar file
 133 True if
 134 .Ar file
 135 exists and is writable.
 136 True
 137 indicates only that the write flag is on.
 138 The file is not writable on a read-only file
 139 system even if this test indicates true.
 140 .It Fl x Ar file
 141 True if
 142 .Ar file
 143 exists and is executable.
 144 True
 145 indicates only that the execute flag is on.
 146 If
 147 .Ar file
 148 is a directory, true indicates that
 149 .Ar file
 150 can be searched.
 151 .It Fl z Ar string
 152 True if the length of
 153 .Ar string
 154 is zero.
 155 .It Fl L Ar file
 156 True if
 157 .Ar file
 158 exists and is a symbolic link.
 159 This operator is retained for compatibility with previous versions of
 160 this program.
 161 Do not rely on its existence; use
 162 .Fl h
 163 instead.
 164 .It Fl O Ar file
 165 True if
 166 .Ar file
 167 exists and its owner matches the effective user id of this process.
 168 .It Fl G Ar file
 169 True if
 170 .Ar file
 171 exists and its group matches the effective group id of this process.
 172 .It Fl S Ar file
 173 True if
 174 .Ar file
 175 exists and is a socket.
 176 .It Ar file1 Fl nt Ar file2
 177 True if
 178 .Ar file1
 179 exists and is newer than
 180 .Ar file2 .
 181 .It Ar file1 Fl ot Ar file2
 182 True if
 183 .Ar file1
 184 exists and is older than
 185 .Ar file2 .
 186 .It Ar file1 Fl ef Ar file2
 187 True if
 188 .Ar file1
 189 and
 190 .Ar file2
 191 exist and refer to the same file.
 192 .It Ar string
 193 True if
 194 .Ar string
 195 is not the null
 196 string.
 197 .It Ar \&s\&1 Cm \&= Ar \&s\&2
 198 True if the strings
 199 .Ar \&s\&1
 200 and
 201 .Ar \&s\&2
 202 are identical.
 203 .It Ar \&s\&1 Cm \&!= Ar \&s\&2
 204 True if the strings
 205 .Ar \&s\&1
 206 and
 207 .Ar \&s\&2
 208 are not identical.
 209 .It Ar \&s\&1 Cm \&\*[Lt] Ar \&s\&2
 210 True if string
 211 .Ar \&s\&1
 212 comes before
 213 .Ar \&s\&2
 214 based on the ASCII value of their characters.
 215 .It Ar \&s\&1 Cm \&\*[Gt] Ar \&s\&2
 216 True if string
 217 .Ar \&s\&1
 218 comes after
 219 .Ar \&s\&2
 220 based on the ASCII value of their characters.
 221 .It Ar \&n\&1 Fl \&eq Ar \&n\&2
 222 True if the integers
 223 .Ar \&n\&1
 224 and
 225 .Ar \&n\&2
 226 are algebraically
 227 equal.
 228 .It Ar \&n\&1 Fl \&ne Ar \&n\&2
 229 True if the integers
 230 .Ar \&n\&1
 231 and
 232 .Ar \&n\&2
 233 are not
 234 algebraically equal.
 235 .It Ar \&n\&1 Fl \&gt Ar \&n\&2
 236 True if the integer
 237 .Ar \&n\&1
 238 is algebraically
 239 greater than the integer
 240 .Ar \&n\&2 .
 241 .It Ar \&n\&1 Fl \&ge Ar \&n\&2
 242 True if the integer
 243 .Ar \&n\&1
 244 is algebraically
 245 greater than or equal to the integer
 246 .Ar \&n\&2 .
 247 .It Ar \&n\&1 Fl \&lt Ar \&n\&2
 248 True if the integer
 249 .Ar \&n\&1
 250 is algebraically less
 251 than the integer
 252 .Ar \&n\&2 .
 253 .It Ar \&n\&1 Fl \&le Ar \&n\&2
 254 True if the integer
 255 .Ar \&n\&1
 256 is algebraically less
 257 than or equal to the integer
 258 .Ar \&n\&2 .
 259 .El
 260 .Pp
 261 These primaries can be combined with the following operators:
 262 .Bl -tag -width Ar
 263 .It Cm \&! Ar expression
 264 True if
 265 .Ar expression
 266 is false.
 267 .It Ar expression1 Fl a Ar expression2
 268 True if both
 269 .Ar expression1
 270 and
 271 .Ar expression2
 272 are true.
 273 .It Ar expression1 Fl o Ar expression2
 274 True if either
 275 .Ar expression1
 276 or
 277 .Ar expression2
 278 are true.
 279 .It Cm \&( Ar expression Cm \&)
 280 True if
 281 .Ar expression
 282 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 Note that all file tests with the exception of
 292 .Fl h
 293 and
 294 .Fl L
 295 follow symbolic links and thus evaluate the test for the file pointed at.
 296 .Sh GRAMMAR AMBIGUITY
 297 The
 298 .Nm test
 299 grammar is inherently ambiguous.
 300 In order to assure a degree of consistency, the cases described in
 301 .St -p1003.2
 302 section 4.62.4,
 303 are evaluated consistently according to the rules specified in the
 304 standards document.
 305 All other cases are subject to the ambiguity in the command semantics.
 306 .Sh EXIT STATUS
 307 The
 308 .Nm test
 309 utility exits with one of the following values:
 310 .Bl -tag -width Ds
 311 .It 0
 312 .Ar expression
 313 evaluated to true.
 314 .It 1
 315 .Ar expression
 316 evaluated to false or was missing.
 317 .It \*[Gt]1
 318 An error occurred.
 319 .El
 320 .Sh STANDARDS
 321 The
 322 .Nm test
 323 utility implements a superset of the
 324 .St -p1003.2
 325 specification.