1TEST(P) POSIX Programmer's Manual TEST(P)
2
6 test - evaluate expression
7
9 test [expression]
10 [ [expression] ]
12
15 The test utility shall evaluate the expression and indicate the result
16 of the evaluation by its exit status. An exit status of zero indicates
17 that the expression evaluated as true and an exit status of 1 indicates
18 that the expression evaluated as false.
19 In the second form of the utility, which uses "[]" rather than test,
21 the application shall ensure that the square brackets are separate
22 arguments.
23
25 The test utility shall not recognize the "--" argument in the manner
26 specified by guideline 10 in the Base Definitions volume of
27 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
28 No options shall be supported.
30
32 The application shall ensure that all operators and elements of pri‐
33 maries are presented as separate arguments to the test utility.
34 The following primaries can be used to construct expression:
36 -b file
38 True if file exists and is a block special file.
39 -c file
41 True if file exists and is a character special file.
42 -d file
44 True if file exists and is a directory.
45 -e file
47 True if file exists.
48 -f file
50 True if file exists and is a regular file.
51 -g file
53 True if file exists and its set-group-ID flag is set.
54 -h file
56 True if file exists and is a symbolic link.
57 -L file
59 True if file exists and is a symbolic link.
60 -n string
62 True if the length of string is non-zero.
63 -p file
65 True if file is a FIFO.
66 -r file
68 True if file exists and is readable. True shall indicate that
69 permission to read from file will be granted, as defined in File
70 Read, Write, and Creation .
71 -S file
73 True if file exists and is a socket.
74 -s file
76 True if file exists and has a size greater than zero.
77 -t file_descriptor
79 True if the file whose file descriptor number is file_descriptor
81 is open and is associated with a terminal.
82 -u file
84 True if file exists and its set-user-ID flag is set.
85 -w file
87 True if file exists and is writable. True shall indicate that
88 permission to write from file will be granted, as defined in
89 File Read, Write, and Creation .
90 -x file
92 True if file exists and is executable. True shall indicate that
93 permission to execute file will be granted, as defined in File
94 Read, Write, and Creation . If file is a directory, true shall
95 indicate that permission to search file will be granted.
96 -z string
98 True if the length of string string is zero.
99 string True if the string string is not the null string.
101 s1 = s2
103 True if the strings s1 and s2 are identical.
104 s1 != s2
106 True if the strings s1 and s2 are not identical.
107 n1 -eq n2
109 True if the integers n1 and n2 are algebraically equal.
110 n1 -ne n2
112 True if the integers n1 and n2 are not algebraically equal.
113 n1 -gt n2
115 True if the integer n1 is algebraically greater than the integer
116 n2.
117 n1 -ge n2
119 True if the integer n1 is algebraically greater than or equal to
120 the integer n2.
121 n1 -lt n2
123 True if the integer n1 is algebraically less than the integer
124 n2.
125 n1 -le n2
127 True if the integer n1 is algebraically less than or equal to
128 the integer n2.
129 expression1 -a expression2
131 True if both expression1 and expression2 are true. The -a binary
133 primary is left associative. It has a higher precedence than -o.
134 expression1 -o expression2
136 True if either expression1 or expression2 is true. The -o binary
138 primary is left associative.
139 With the exception of the -h file and -L file primaries, if a file
142 argument is a symbolic link, test shall evaluate the expression by
143 resolving the symbolic link and using the file referenced by the link.
144 These primaries can be combined with the following operators:
146 ! expression
148 True if expression is false.
149 ( expression )
151 True if expression is true. The parentheses can be used to alter
152 the normal precedence and associativity.
153 The primaries with two elements of the form:
156 -primary_operator primary_operand
159 are known as unary primaries. The primaries with three elements in
161 either of the two forms:
162 primary_operand -primary_operator primary_operand
165 primary_operand primary_operator primary_operand
168 are known as binary primaries. Additional implementation-defined opera‐
170 tors and primary_operators may be provided by implementations. They
171 shall be of the form - operator where the first character of operator
172 is not a digit.
173 The algorithm for determining the precedence of the operators and the
175 return value that shall be generated is based on the number of argu‐
176 ments presented to test. (However, when using the "[...]" form, the
177 right-bracket final argument shall not be counted in this algorithm.)
178 In the following list, $1, $2, $3, and $4 represent the arguments pre‐
180 sented to test:
181 0 arguments:
183 Exit false (1).
184 1 argument:
186 Exit true (0) if $1 is not null; otherwise, exit false.
187 2 arguments:
189 * If $1 is '!' , exit true if $2 is null, false if $2 is not
191 null.
192 * If $1 is a unary primary, exit true if the unary test is
194 true, false if the unary test is false.
195 * Otherwise, produce unspecified results.
197 3 arguments:
199 * If $2 is a binary primary, perform the binary test of $1 and
201 $3.
202 * If $1 is '!' , negate the two-argument test of $2 and $3.
204 * If $1 is '(' and $3 is ')' , perform the unary test of $2.
206 * Otherwise, produce unspecified results.
208 4 arguments:
210 * If $1 is '!' , negate the three-argument test of $2, $3, and
212 $4.
213 * If $1 is '(' and $4 is ')' , perform the two-argument test of
215 $2 and $3.
216 * Otherwise, the results are unspecified.
218 >4 arguments:
220 The results are unspecified.
221 On XSI-conformant systems, combinations of primaries and operators
223 shall be evaluated using the precedence and associativity rules
224 described previously. In addition, the string comparison binary pri‐
225 maries '=' and "!=" shall have a higher precedence than any unary pri‐
226 mary.
227
230 Not used.
231
233 None.
234
236 The following environment variables shall affect the execution of test:
237 LANG Provide a default value for the internationalization variables
239 that are unset or null. (See the Base Definitions volume of
240 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
241 ables for the precedence of internationalization variables used
242 to determine the values of locale categories.)
243 LC_ALL If set to a non-empty string value, override the values of all
245 the other internationalization variables.
246 LC_CTYPE
248 Determine the locale for the interpretation of sequences of
249 bytes of text data as characters (for example, single-byte as
250 opposed to multi-byte characters in arguments).
251 LC_MESSAGES
253 Determine the locale that should be used to affect the format
254 and contents of diagnostic messages written to standard error.
255 NLSPATH
257 Determine the location of message catalogs for the processing of
258 LC_MESSAGES .
259
262 Default.
263
265 Not used.
266
268 The standard error shall be used only for diagnostic messages.
269
271 None.
272
274 None.
275
277 The following exit values shall be returned:
278 0 expression evaluated to true.
280 1 expression evaluated to false or expression was missing.
282 >1 An error occurred.
284
287 Default.
288 The following sections are informative.
290
292 Scripts should be careful when dealing with user-supplied input that
293 could be confused with primaries and operators. Unless the application
294 writer knows all the cases that produce input to the script, invoca‐
295 tions like:
296 test "$1" -a "$2"
299 should be written as:
301 test "$1" && test "$2"
304 to avoid problems if a user supplied values such as $1 set to '!' and
306 $2 set to the null string. That is, in cases where maximal portability
307 is of concern, replace:
308 test expr1 -a expr2
311 with:
313 test expr1 && test expr2
316 and replace:
318 test expr1 -o expr2
321 with:
323 test expr1 || test expr2
326 but note that, in test, -a has higher precedence than -o while "&&" and
328 "||" have equal precedence in the shell.
329 Parentheses or braces can be used in the shell command language to
331 effect grouping.
332 Parentheses must be escaped when using sh; for example:
334 test \( expr1 -a expr2 \) -o expr3
337 This command is not always portable outside XSI-conformant systems.
339 The following form can be used instead:
340 ( test expr1 && test expr2 ) || test expr3
343 The two commands:
345 test "$1"
348 test ! "$1"
349 could not be used reliably on some historical systems. Unexpected
351 results would occur if such a string expression were used and $1
352 expanded to '!' , '(' , or a known unary primary. Better constructs
353 are:
354 test -n "$1"
357 test -z "$1"
358 respectively.
359 Historical systems have also been unreliable given the common con‐
361 struct:
362 test "$response" = "expected string"
365 One of the following is a more reliable form:
367 test "X$response" = "Xexpected string"
370 test "expected string" = "$response"
371 Note that the second form assumes that expected string could not be
373 confused with any unary primary. If expected string starts with '-' ,
374 '(' , '!' , or even '=' , the first form should be used instead. Using
375 the preceding rules without the XSI marked extensions, any of the three
376 comparison forms is reliable, given any input. (However, note that the
377 strings are quoted in all cases.)
378 Because the string comparison binary primaries, '=' and "!=" , have a
380 higher precedence than any unary primary in the greater than 4 argument
381 case, unexpected results can occur if arguments are not properly pre‐
382 pared. For example, in:
383 test -d $1 -o -d $2
386 If $1 evaluates to a possible directory name of '=' , the first three
388 arguments are considered a string comparison, which shall cause a syn‐
389 tax error when the second -d is encountered. One of the following
390 forms prevents this; the second is preferred:
391 test \( -d "$1" \) -o \( -d "$2" \)
394 test -d "$1" || test -d "$2"
395 Also in the greater than 4 argument case:
397 test "$1" = "bat" -a "$2" = "ball"
400 syntax errors occur if $1 evaluates to '(' or '!' . One of the follow‐
402 ing forms prevents this; the third is preferred:
403 test "X$1" = "Xbat" -a "X$2" = "Xball"
406 test "$1" = "bat" && test "$2" = "ball"
407 test "X$1" = "Xbat" && test "X$2" = "Xball"
408
410 1. Exit if there are not two or three arguments (two variations):
411 if [ $# -ne 2 -a $# -ne 3 ]; then exit 1; fi
414 if [ $# -lt 2 -o $# -gt 3 ]; then exit 1; fi
415 2. Perform a mkdir if a directory does not exist:
417 test ! -d tempdir && mkdir tempdir
420 3. Wait for a file to become non-readable:
422 while test -r thefile
425 do
426 sleep 30
427 done
428 echo '"thefile" is no longer readable'
429 4. Perform a command if the argument is one of three strings (two
431 variations):
432 if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
435 then
436 command
437 fi
438 case "$1" in
441 pear|grape|apple) command ;;
442 esac
443
445 The KornShell-derived conditional command (double bracket [[]]) was
446 removed from the shell command language description in an early pro‐
447 posal. Objections were raised that the real problem is misuse of the
448 test command ( [), and putting it into the shell is the wrong way to
449 fix the problem. Instead, proper documentation and a new shell reserved
450 word ( !) are sufficient.
451 Tests that require multiple test operations can be done at the shell
453 level using individual invocations of the test command and shell logi‐
454 cals, rather than using the error-prone -o flag of test.
455 XSI-conformant systems support more than four arguments.
457 XSI-conformant systems support the combining of primaries with the fol‐
459 lowing constructs:
460 expression1 -a expression2
462 True if both expression1 and expression2 are true.
464 expression1 -o expression2
466 True if at least one of expression1 and expression2 are true.
468 ( expression )
470 True if expression is true.
472 In evaluating these more complex combined expressions, the following
475 precedence rules are used:
476 * The unary primaries have higher precedence than the algebraic binary
478 primaries.
479 * The unary primaries have lower precedence than the string binary
481 primaries.
482 * The unary and binary primaries have higher precedence than the unary
484 string primary.
485 * The ! operator has higher precedence than the -a operator, and the
487 -a operator has higher precedence than the -o operator.
488 * The -a and -o operators are left associative.
490 * The parentheses can be used to alter the normal precedence and asso‐
492 ciativity.
493 The BSD and System V versions of -f are not the same. The BSD defini‐
495 tion was:
496 -f file
498 True if file exists and is not a directory.
499 The SVID version (true if the file exists and is a regular file) was
502 chosen for this volume of IEEE Std 1003.1-2001 because its use is con‐
503 sistent with the -b, -c, -d, and -p operands ( file exists and is a
504 specific file type).
505 The -e primary, possessing similar functionality to that provided by
507 the C shell, was added because it provides the only way for a shell
508 script to find out if a file exists without trying to open the file.
509 Since implementations are allowed to add additional file types, a por‐
510 table script cannot use:
511 test -b foo -o -c foo -o -d foo -o -f foo -o -p foo
514 to find out if foo is an existing file. On historical BSD systems, the
516 existence of a file could be determined by:
517 test -f foo -o -d foo
520 but there was no easy way to determine that an existing file was a reg‐
522 ular file. An early proposal used the KornShell -a primary (with the
523 same meaning), but this was changed to -e because there were concerns
524 about the high probability of humans confusing the -a primary with the
525 -a binary operator.
526 The following options were not included in this volume of
528 IEEE Std 1003.1-2001, although they are provided by some implementa‐
529 tions. These operands should not be used by new implementations for
530 other purposes:
531 -k file
533 True if file exists and its sticky bit is set.
534 -C file
536 True if file is a contiguous file.
537 -V file
539 True if file is a version file.
540 The following option was not included because it was undocumented in
543 most implementations, has been removed from some implementations
544 (including System V), and the functionality is provided by the shell
545 (see Parameter Expansion .
546 -l string
548 The length of the string string.
549 The -b, -c, -g, -p, -u, and -x operands are derived from the SVID; his‐
552 torical BSD does not provide them. The -k operand is derived from Sys‐
553 tem V; historical BSD does not provide it.
554 On historical BSD systems, test -w directory always returned false
556 because test tried to open the directory for writing, which always
557 fails.
558 Some additional primaries newly invented or from the KornShell appeared
560 in an early proposal as part of the conditional command ( [[]]): s1 >
561 s2, s1 < s2, str = pattern, str != pattern, f1 -nt f2, f1 -ot f2, and
562 f1 -ef f2. They were not carried forward into the test utility when the
563 conditional command was removed from the shell because they have not
564 been included in the test utility built into historical implementations
565 of the sh utility.
566 The -t file_descriptor primary is shown with a mandatory argument
568 because the grammar is ambiguous if it can be omitted. Historical
569 implementations have allowed it to be omitted, providing a default of
570 1.
571
573 None.
574
576 File Read, Write, and Creation , find
577
579 Portions of this text are reprinted and reproduced in electronic form
580 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
581 -- Portable Operating System Interface (POSIX), The Open Group Base
582 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
583 Electrical and Electronics Engineers, Inc and The Open Group. In the
584 event of any discrepancy between this version and the original IEEE and
585 The Open Group Standard, the original IEEE and The Open Group Standard
586 is the referee document. The original Standard can be obtained online
587 at http://www.opengroup.org/unix/online.html .
588IEEE/The Open Group 2003 TEST(P)