1test(1) User Commands test(1)
2
6 test - evaluate condition(s)
7
9 /usr/bin/test [condition]
10 [ [condition] ]
13 sh
16 test [condition]
17 [ [condition] ]
20 csh
23 test [condition]
24 [ [condition] ]
27 ksh
30 test [condition]
31 [ [condition] ]
34 ksh93
37 test [condition]
38 [ [condition] ]
41
44 The test utility evaluates the condition and indicates the result of
45 the evaluation by its exit status. An exit status of zero indicates
46 that the condition evaluated as true and an exit status of 1 indicates
47 that the condition evaluated as false.
48 In the first form of the utility shown using the SYNOPSIS:
51 test [condition]
53 the square brackets denote that condition is an optional operand and
58 are not to be entered on the command line.
59 In the second form of the utility shown using the SYNOPSIS:
62 [ [ condition ] ]
64 the first open square bracket, [, is the required utility name. condi‐
69 tion is optional, as denoted by the inner pair of square brackets. The
70 final close square bracket, ], is a required operand.
71 See largefile(5) for the description of the behavior of test when
74 encountering files greater than or equal to 2 Gbyte (2^31 bytes).
75 The test and [ utilities evaluate the condition condition and, if its
78 value is true, set exit status to 0. Otherwise, a non-zero (false) exit
79 status is set. test and [ also set a non-zero exit status if there are
80 no arguments. When permissions are tested, the effective user ID of the
81 process is used.
82 All operators, flags, and brackets (brackets used as shown in the last
85 SYNOPSIS line) must be separate arguments to these commands. Normally
86 these arguments are separated by spaces.
87
89 The primaries listed below with two elements of the form:
90 -primary_operator primary_operand
92 are known as unary primaries. The primaries with three elements in
96 either of the two forms:
97 primary_operand -primary_operator primary_operand
99 primary_operand primary_operator primary_operand
100 are known as binary primaries.
104 If any file operands except for -h and -L primaries refer to symbolic
107 links, the symbolic link is expanded and the test is performed on the
108 resulting file.
109 If you test a file you own (the -r -w or -x tests), but the permission
112 tested does not have the owner bit set, a non-zero (false) exit status
113 is returned even though the file can have the group or other bit set
114 for that permission.
115 The = and != primaries have a higher precedence than the unary pri‐
118 maries. The = and != primaries always expect arguments; therefore, =
119 and != cannot be used as an argument to the unary primaries.
120 The following primaries can be used to construct condition:
123 -a file True if file exists. (Not available in sh.)
125 -b file True if file exists and is a block special
128 file.
129 -c file True if file exists and is a character spe‐
132 cial file.
133 -d file True if file exists and is a directory.
136 -e file True if file exists. (Not available in sh.)
139 -f file True if file exists and is a regular file.
142 Alternatively, if /usr/bin/sh users specify
143 /usr/ucb before /usr/bin in their PATH
144 environment variable, then test returns
145 true if file exists and is (not−a−direc‐
146 tory). The csh test and [ built-ins always
147 use this alternative behavior.
148 -g file True if file exists and its set group ID
151 flag is set.
152 -G file True if file exists and its group matches
155 the effective group ID of this process.
156 (Not available in sh.)
157 -h file True if file exists and is a symbolic link.
160 -k file True if file exists and has its sticky bit
163 set.
164 -L file True if file exists and is a symbolic link.
167 -n string True if the length of string is non-zero.
170 -o option True if option named option is on. This
173 option is not available in csh or sh.
174 -O file True if file exists and is owned by the
177 effective user ID of this process. This
178 option is not available in sh.
179 -p file True if file is a named pipe (FIFO).
182 -r file True if file exists and is readable.
185 -s file True if file exists and has a size greater
188 than zero.
189 -S file True if file exists and is a socket. This
192 option is not available in sh.
193 -t [file_descriptor] True if the file whose file descriptor num‐
196 ber is file_descriptor is open and is asso‐
197 ciated with a terminal. If file_descriptor
198 is not specified, 1 is used as a default
199 value.
200 -u file True if file exists and its set-user-ID
203 flag is set.
204 -w file True if file exists and is writable. True
207 indicates only that the write flag is on.
208 The file is not writable on a read-only
209 file system even if this test indicates
210 true.
211 -x file True if file exists and is executable. True
214 indicates only that the execute flag is on.
215 If file is a directory, true indicates that
216 file can be searched.
217 -z string True if the length of string string is
220 zero.
221 file1 -nt file2 True if file1 exists and is newer than
224 file2. This option is not available in sh.
225 file1 -ot file2 True if file1 exists and is older than
228 file2. This option is not available in sh.
229 file1 -ef file2 True if file1 and file2 exist and refer to
232 the same file. This option is not available
233 in sh.
234 string True if the string string is not the null
237 string.
238 string1 = string2 True if the strings string1 and string2 are
241 identical.
242 string1 != string2 True if the strings string1 and string2 are
245 not identical.
246 n1 -eq n2 True if the numbers n1 and n2 are algebrai‐
249 cally equal. A number may be integer,
250 floating point or floating-point constant
251 (such as [+/-]Inf, [+/-]NaN) in any format
252 specified by C99/XPG6/SUS.
253 n1 -ne n2 True if the numbers n1 and n2 are not alge‐
256 braically equal. A number may be integer,
257 floating point or floating-point constant
258 (such as [+/-]Inf, [+/-]NaN) in any format
259 specified by C99/XPG6/SUS.
260 n1 -gt n2 True if the number n1 is algebraically
263 greater than the number n2. A number may be
264 integer, floating point or floating-point
265 constant (such as [+/-]Inf, [+/-]NaN) in
266 any format specified by C99/XPG6/SUS.
267 n1 -ge n2 True if the number n1 is algebraically
270 greater than or equal to the number n2. A
271 number may be integer, floating point or
272 floating-point constant (such as [+/-]Inf,
273 [+/-]NaN) in any format specified by
274 C99/XPG6/SUS.
275 n1 -lt n2 True if the number n1 is algebraically less
278 than the number n2. A number may be inte‐
279 ger, floating point or floating-point con‐
280 stant (such as [+/-]Inf, [+/-]NaN) in any
281 format specified by C99/XPG6/SUS.
282 n1 -le n2 True if the number n1 is algebraically less
285 than or equal to the number n2. A number
286 may be integer, floating point or floating-
287 point constant (such as [+/-]Inf, [+/-]NaN)
288 in any format specified by C99/XPG6/SUS.
289 condition1 -a condition2 True if both condition1 and condition2 are
292 true. The -a binary primary is left asso‐
293 ciative and has higher precedence than the
294 -o binary primary.
295 condition1 -o condition2 True if either condition1 or condition2 is
298 true. The -o binary primary is left asso‐
299 ciative.
300 These primaries can be combined with the following operators:
304 ! condition True if condition is false.
306 ( condition ) True if condition is true. The parentheses ( ) can be
309 used to alter the normal precedence and associativity.
310 The parentheses are meaningful to the shell and,
311 therefore, must be quoted.
312 The algorithm for determining the precedence of the operators and the
316 return value that is generated is based on the number of arguments pre‐
317 sented to test. (However, when using the [...] form, the right-bracket
318 final argument is not counted in this algorithm.)
319 In the following list, $1, $2, $3 and $4 represent the arguments pre‐
322 sented to test as a condition, condition1, or condition2.
323 0 arguments: Exit false (1).
325 1 argument: Exit true (0) if $1 is not null. Otherwise, exit false.
328 2 arguments:
331 o If $1 is !, exit true if $2 is null, false
332 if $2 is not null.
333 o If $1 is a unary primary, exit true if the
335 unary test is true, false if the unary test
336 is false.
337 o Otherwise, produce unspecified results.
339 3 arguments:
342 o If $2 is a binary primary, perform the
343 binary test of $1 and $3.
344 o If $1 is !, negate the two-argument test of
346 $2 and $3.
347 o Otherwise, produce unspecified results.
349 4 arguments:
352 o If $1 is !, negate the three-argument test
353 of $2, $3, and $4.
354 o Otherwise, the results are unspecified.
356
359 Scripts should be careful when dealing with user-supplied input that
360 could be confused with primaries and operators. Unless the application
361 writer knows all the cases that produce input to the script, invoca‐
362 tions like test "$1" -a "$2" should be written as test "$1" && test
363 "$2" to avoid problems if a user supplied values such as $1 set to !
364 and $2 set to the null string. That is, in cases where maximal porta‐
365 bility is of concern, replace test expr1 -a expr2 with test expr1 &&
366 test expr2, and replace test expr1 -o expr2 with test expr1 || test
367 expr2. But notice that, in test, -a has higher precedence than -o,
368 while && and || have equal precedence in the shell.
369 Parentheses or braces can be used in the shell command language to
372 effect grouping.
373 Parentheses must be escaped when using sh. For example:
376 test \( expr1 -a expr2 \) -o expr3
378 This command is not always portable outside XSI-conformant systems. The
382 following form can be used instead:
383 ( test expr1 && test expr2 ) || test expr3
385 The two commands:
389 test "$1"
391 test ! "$1"
392 could not be used reliably on some historical systems. Unexpected
396 results would occur if such a string condition were used and $1
397 expanded to !, (, or a known unary primary. Better constructs are,
398 respectively,
399 test -n "$1"
401 test -z "$1"
402 Historical systems have also been unreliable given the common con‐
406 struct:
407 test "$response" = "expected string"
409 One of the following is a more reliable form:
413 test "X$response" = "Xexpected string"
415 test "expected string" = "$response"
416 The second form assumes that expected string could not be confused with
420 any unary primary. If expected string starts with −, (, ! or even =,
421 the first form should be used instead. Using the preceding rules with‐
422 out the marked extensions, any of the three comparison forms is reli‐
423 able, given any input. (However, observe that the strings are quoted in
424 all cases.)
425 Because the string comparison binary primaries, = and !=, have a higher
428 precedence than any unary primary in the >4 argument case, unexpected
429 results can occur if arguments are not properly prepared. For example,
430 in
431 test -d $1 -o -d $2
433 If $1 evaluates to a possible directory name of =, the first three
437 arguments are considered a string comparison, which causes a syntax
438 error when the second -d is encountered. is encountered. One of the
439 following forms prevents this; the second is preferred:
440 test \( -d "$1" \) -o \( -d "$2" \)
442 test -d "$1" || test -d "$2"
443 Also in the >4 argument case:
447 test "$1" = "bat" -a "$2" = "ball"
449 Syntax errors occur if $1 evaluates to ( or !. One of the following
453 forms prevents this; the third is preferred:
454 test "X$1" = "Xbat" -a "X$2" = "Xball"
456 test "$1" = "bat" && test "$2" = "ball"
457 test "X$1" = "Xbat" && test "X$2" = "Xball"
458
461 In the if command examples, three conditions are tested, and if all
462 three evaluate as true or successful, then their validities are written
463 to the screen. The three tests are:
464 o if a variable set to 1 is greater than 0,
466 o if a variable set to 2 is equal to 2, and
468 o if the word root is included in the text file /etc/passwd.
470 /usr/bin/test
472 Example 1 Using /usr/bin/test
473 Perform a mkdir if a directory does not exist:
476 test ! -d tempdir && mkdir tempdir
479 Wait for a file to become non-readable:
483 while test -r thefile
486 do
487 sleep 30
488 done
489 echo'"thefile" is no longer readable'
490 Perform a command if the argument is one of three strings (two varia‐
494 tions), using the open bracket version [ of the test command:
495 if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
498 then
499 command
500 fi
501 case "$1" in
502 pear|grape|apple) command;;
503 esac
504 Example 2 Using /usr/bin/test for the -e option
507 If one really wants to use the -e option in sh, use /usr/bin/test, as
510 in the following:
511 if [ ! -h $PKG_INSTALL_ROOT$rLink ] && /usr/bin/test -e
514 $PKG_INSTALL_ROOT/usr/bin/$rFile ; then
515 ln -s $rFile $PKG_INSTALL_ROOT$rLink
516 fi
517 The test built-in
520 The two forms of the test built-in follow the Bourne shell's if exam‐
521 ple.
522 Example 3 Using the sh built-in
524 ZERO=0 ONE=1 TWO=2 ROOT=root
526 if [ $ONE -gt $ZERO ]
528 [ $TWO -eq 2 ]
530 grep $ROOT /etc/passwd >&1 > /dev/null # discard output
532 then
534 echo "$ONE is greater than 0, $TWO equals 2, and $ROOT is" \
536 "a user-name in the password file"
537 else
539 echo "At least one of the three test conditions is false"
541 fi
542 Example 4 Using the test built-in
545 Examples of the test built-in:
548 test `grep $ROOT /etc/passwd >&1 /dev/null` # discard output
551 echo $? # test for success
553 [ `grep nosuchname /etc/passwd >&1 /dev/null` ]
554 echo $? # test for failure
556 csh
559 Example 5 Using the csh built-in
560 @ ZERO = 0; @ ONE = 1; @ TWO = 2; set ROOT = root
562 grep $ROOT /etc/passwd >&1 /dev/null # discard output
563 # $status must be tested for immediately following grep
564 if ( "$status" == "0" && $ONE > $ZERO && $TWO == 2 ) then
565 echo "$ONE is greater than 0, $TWO equals 2, and $ROOT is" \
566 "a user-name in the password file"
567 endif
568 ksh
571 Example 6 Using the ksh/ksh93 built-in
572 ZERO=0 ONE=1 TWO=$((ONE+ONE)) ROOT=root
574 if ((ONE > ZERO)) # arithmetical comparison
575 [[ $TWO = 2 ]] # string comparison
576 [ `grep $ROOT /etc/passwd >&1 /dev/null` ] # discard output
577 then
578 echo "$ONE is greater than 0, $TWO equals 2, and $ROOT is" \
579 "a user-name in the password file"
580 else
582 echo "At least one of the three test conditions is false"
583 fi
584
587 See environ(5) for descriptions of the following environment variables
588 that affect the execution of test: LANG, LC_ALL, LC_CTYPE, LC_MESSAGES,
589 and NLSPATH.
590
592 The following exit values are returned:
593 0 condition evaluated to true.
595 1 condition evaluated to false or condition was missing.
598 >1 An error occurred.
601
604 See attributes(5) for descriptions of the following attributes:
605 /usr/bin/test, csh, ksh, sh
607 ┌─────────────────────────────┬─────────────────────────────┐
608 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
609 ├─────────────────────────────┼─────────────────────────────┤
610 │Availability │SUNWcsu │
611 ├─────────────────────────────┼─────────────────────────────┤
612 │Interface Stability │Committed │
613 ├─────────────────────────────┼─────────────────────────────┤
614 │Standard │See standards(5). │
615 └─────────────────────────────┴─────────────────────────────┘
616 ksh93
618 ┌─────────────────────────────┬─────────────────────────────┐
619 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
620 ├─────────────────────────────┼─────────────────────────────┤
621 │Availability │SUNWcsu │
622 ├─────────────────────────────┼─────────────────────────────┤
623 │Interface Stability │Uncommitted │
624 └─────────────────────────────┴─────────────────────────────┘
625
627 csh(1), ksh(1), ksh93(1), sh(1), test(1B), attributes(5), environ(5),
628 largefile(5), standards(5)
629
631 The not−a−directory alternative to the -f option is a transition aid
632 for BSD applications and may not be supported in future releases.
633 XPG4 sh, ksh, ksh93
635 Use arithmetic expressions such as
636 $(( x > 3.1 )) #
638 instead of
643 $ /usr/bin/test "$x" -gt 3.1 # )
645 when comparing two floating-point variables or a constant and a float‐
650 ing-point variable to prevent rounding errors (caused by the base16 to
651 base10 transformation) to affect the result. Additionally the built-in
652 arithmetic support in XPG4 sh, ksh and ksh93 is significantly faster
653 because it does not require the explicit transformation to strings for
654 each comparison.
655SunOS 5.11 11 Aug 2009 test(1)