1TEST(1P) POSIX Programmer's Manual TEST(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 test - evaluate expression
13
15 test [expression]
16 [ [expression] ]
18
21 The test utility shall evaluate the expression and indicate the result
22 of the evaluation by its exit status. An exit status of zero indicates
23 that the expression evaluated as true and an exit status of 1 indicates
24 that the expression evaluated as false.
25 In the second form of the utility, which uses "[]" rather than test,
27 the application shall ensure that the square brackets are separate
28 arguments.
29
31 The test utility shall not recognize the "--" argument in the manner
32 specified by guideline 10 in the Base Definitions volume of
33 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
34 No options shall be supported.
36
38 The application shall ensure that all operators and elements of pri‐
39 maries are presented as separate arguments to the test utility.
40 The following primaries can be used to construct expression:
42 -b file
44 True if file exists and is a block special file.
45 -c file
47 True if file exists and is a character special file.
48 -d file
50 True if file exists and is a directory.
51 -e file
53 True if file exists.
54 -f file
56 True if file exists and is a regular file.
57 -g file
59 True if file exists and its set-group-ID flag is set.
60 -h file
62 True if file exists and is a symbolic link.
63 -L file
65 True if file exists and is a symbolic link.
66 -n string
68 True if the length of string is non-zero.
69 -p file
71 True if file is a FIFO.
72 -r file
74 True if file exists and is readable. True shall indicate that
75 permission to read from file will be granted, as defined in File
76 Read, Write, and Creation .
77 -S file
79 True if file exists and is a socket.
80 -s file
82 True if file exists and has a size greater than zero.
83 -t file_descriptor
85 True if the file whose file descriptor number is file_descriptor
87 is open and is associated with a terminal.
88 -u file
90 True if file exists and its set-user-ID flag is set.
91 -w file
93 True if file exists and is writable. True shall indicate that
94 permission to write from file will be granted, as defined in
95 File Read, Write, and Creation .
96 -x file
98 True if file exists and is executable. True shall indicate that
99 permission to execute file will be granted, as defined in File
100 Read, Write, and Creation . If file is a directory, true shall
101 indicate that permission to search file will be granted.
102 -z string
104 True if the length of string string is zero.
105 string True if the string string is not the null string.
107 s1 = s2
109 True if the strings s1 and s2 are identical.
110 s1 != s2
112 True if the strings s1 and s2 are not identical.
113 n1 -eq n2
115 True if the integers n1 and n2 are algebraically equal.
116 n1 -ne n2
118 True if the integers n1 and n2 are not algebraically equal.
119 n1 -gt n2
121 True if the integer n1 is algebraically greater than the integer
122 n2.
123 n1 -ge n2
125 True if the integer n1 is algebraically greater than or equal to
126 the integer n2.
127 n1 -lt n2
129 True if the integer n1 is algebraically less than the integer
130 n2.
131 n1 -le n2
133 True if the integer n1 is algebraically less than or equal to
134 the integer n2.
135 expression1 -a expression2
137 True if both expression1 and expression2 are true. The -a binary
139 primary is left associative. It has a higher precedence than -o.
140 expression1 -o expression2
142 True if either expression1 or expression2 is true. The -o binary
144 primary is left associative.
145 With the exception of the -h file and -L file primaries, if a file
148 argument is a symbolic link, test shall evaluate the expression by
149 resolving the symbolic link and using the file referenced by the link.
150 These primaries can be combined with the following operators:
152 ! expression
154 True if expression is false.
155 ( expression )
157 True if expression is true. The parentheses can be used to alter
158 the normal precedence and associativity.
159 The primaries with two elements of the form:
162 -primary_operator primary_operand
165 are known as unary primaries. The primaries with three elements in
167 either of the two forms:
168 primary_operand -primary_operator primary_operand
171 primary_operand primary_operator primary_operand
174 are known as binary primaries. Additional implementation-defined opera‐
176 tors and primary_operators may be provided by implementations. They
177 shall be of the form - operator where the first character of operator
178 is not a digit.
179 The algorithm for determining the precedence of the operators and the
181 return value that shall be generated is based on the number of argu‐
182 ments presented to test. (However, when using the "[...]" form, the
183 right-bracket final argument shall not be counted in this algorithm.)
184 In the following list, $1, $2, $3, and $4 represent the arguments pre‐
186 sented to test:
187 0 arguments:
189 Exit false (1).
190 1 argument:
192 Exit true (0) if $1 is not null; otherwise, exit false.
193 2 arguments:
195 * If $1 is '!', exit true if $2 is null, false if $2 is not
197 null.
198 * If $1 is a unary primary, exit true if the unary test is
200 true, false if the unary test is false.
201 * Otherwise, produce unspecified results.
203 3 arguments:
205 * If $2 is a binary primary, perform the binary test of $1 and
207 $3.
208 * If $1 is '!', negate the two-argument test of $2 and $3.
210 * If $1 is '(' and $3 is ')', perform the unary test of $2.
212 * Otherwise, produce unspecified results.
214 4 arguments:
216 * If $1 is '!', negate the three-argument test of $2, $3, and
218 $4.
219 * If $1 is '(' and $4 is ')', perform the two-argument test of
221 $2 and $3.
222 * Otherwise, the results are unspecified.
224 >4 arguments:
226 The results are unspecified.
227 On XSI-conformant systems, combinations of primaries and operators
229 shall be evaluated using the precedence and associativity rules
230 described previously. In addition, the string comparison binary pri‐
231 maries '=' and "!=" shall have a higher precedence than any unary pri‐
232 mary.
233
236 Not used.
237
239 None.
240
242 The following environment variables shall affect the execution of test:
243 LANG Provide a default value for the internationalization variables
245 that are unset or null. (See the Base Definitions volume of
246 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
247 ables for the precedence of internationalization variables used
248 to determine the values of locale categories.)
249 LC_ALL If set to a non-empty string value, override the values of all
251 the other internationalization variables.
252 LC_CTYPE
254 Determine the locale for the interpretation of sequences of
255 bytes of text data as characters (for example, single-byte as
256 opposed to multi-byte characters in arguments).
257 LC_MESSAGES
259 Determine the locale that should be used to affect the format
260 and contents of diagnostic messages written to standard error.
261 NLSPATH
263 Determine the location of message catalogs for the processing of
264 LC_MESSAGES .
265
268 Default.
269
271 Not used.
272
274 The standard error shall be used only for diagnostic messages.
275
277 None.
278
280 None.
281
283 The following exit values shall be returned:
284 0 expression evaluated to true.
286 1 expression evaluated to false or expression was missing.
288 >1 An error occurred.
290
293 Default.
294 The following sections are informative.
296
298 Scripts should be careful when dealing with user-supplied input that
299 could be confused with primaries and operators. Unless the application
300 writer knows all the cases that produce input to the script, invoca‐
301 tions like:
302 test "$1" -a "$2"
305 should be written as:
307 test "$1" && test "$2"
310 to avoid problems if a user supplied values such as $1 set to '!' and
312 $2 set to the null string. That is, in cases where maximal portability
313 is of concern, replace:
314 test expr1 -a expr2
317 with:
319 test expr1 && test expr2
322 and replace:
324 test expr1 -o expr2
327 with:
329 test expr1 || test expr2
332 but note that, in test, -a has higher precedence than -o while "&&" and
334 "||" have equal precedence in the shell.
335 Parentheses or braces can be used in the shell command language to
337 effect grouping.
338 Parentheses must be escaped when using sh; for example:
340 test \( expr1 -a expr2 \) -o expr3
343 This command is not always portable outside XSI-conformant systems.
345 The following form can be used instead:
346 ( test expr1 && test expr2 ) || test expr3
349 The two commands:
351 test "$1"
354 test ! "$1"
355 could not be used reliably on some historical systems. Unexpected
357 results would occur if such a string expression were used and $1
358 expanded to '!', '(', or a known unary primary. Better constructs are:
359 test -n "$1"
362 test -z "$1"
363 respectively.
364 Historical systems have also been unreliable given the common con‐
366 struct:
367 test "$response" = "expected string"
370 One of the following is a more reliable form:
372 test "X$response" = "Xexpected string"
375 test "expected string" = "$response"
376 Note that the second form assumes that expected string could not be
378 confused with any unary primary. If expected string starts with '-',
379 '(', '!', or even '=', the first form should be used instead. Using
380 the preceding rules without the XSI marked extensions, any of the three
381 comparison forms is reliable, given any input. (However, note that the
382 strings are quoted in all cases.)
383 Because the string comparison binary primaries, '=' and "!=", have a
385 higher precedence than any unary primary in the greater than 4 argument
386 case, unexpected results can occur if arguments are not properly pre‐
387 pared. For example, in:
388 test -d $1 -o -d $2
391 If $1 evaluates to a possible directory name of '=', the first three
393 arguments are considered a string comparison, which shall cause a syn‐
394 tax error when the second -d is encountered. One of the following
395 forms prevents this; the second is preferred:
396 test \( -d "$1" \) -o \( -d "$2" \)
399 test -d "$1" || test -d "$2"
400 Also in the greater than 4 argument case:
402 test "$1" = "bat" -a "$2" = "ball"
405 syntax errors occur if $1 evaluates to '(' or '!' . One of the follow‐
407 ing forms prevents this; the third is preferred:
408 test "X$1" = "Xbat" -a "X$2" = "Xball"
411 test "$1" = "bat" && test "$2" = "ball"
412 test "X$1" = "Xbat" && test "X$2" = "Xball"
413
415 1. Exit if there are not two or three arguments (two variations):
416 if [ $# -ne 2 -a $# -ne 3 ]; then exit 1; fi
419 if [ $# -lt 2 -o $# -gt 3 ]; then exit 1; fi
420 2. Perform a mkdir if a directory does not exist:
422 test ! -d tempdir && mkdir tempdir
425 3. Wait for a file to become non-readable:
427 while test -r thefile
430 do
431 sleep 30
432 done
433 echo '"thefile" is no longer readable'
434 4. Perform a command if the argument is one of three strings (two
436 variations):
437 if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
440 then
441 command
442 fi
443 case "$1" in
446 pear|grape|apple) command ;;
447 esac
448
450 The KornShell-derived conditional command (double bracket [[]]) was
451 removed from the shell command language description in an early pro‐
452 posal. Objections were raised that the real problem is misuse of the
453 test command ( [), and putting it into the shell is the wrong way to
454 fix the problem. Instead, proper documentation and a new shell reserved
455 word ( !) are sufficient.
456 Tests that require multiple test operations can be done at the shell
458 level using individual invocations of the test command and shell logi‐
459 cals, rather than using the error-prone -o flag of test.
460 XSI-conformant systems support more than four arguments.
462 XSI-conformant systems support the combining of primaries with the fol‐
464 lowing constructs:
465 expression1 -a expression2
467 True if both expression1 and expression2 are true.
469 expression1 -o expression2
471 True if at least one of expression1 and expression2 are true.
473 ( expression )
475 True if expression is true.
477 In evaluating these more complex combined expressions, the following
480 precedence rules are used:
481 * The unary primaries have higher precedence than the algebraic binary
483 primaries.
484 * The unary primaries have lower precedence than the string binary
486 primaries.
487 * The unary and binary primaries have higher precedence than the unary
489 string primary.
490 * The ! operator has higher precedence than the -a operator, and the
492 -a operator has higher precedence than the -o operator.
493 * The -a and -o operators are left associative.
495 * The parentheses can be used to alter the normal precedence and asso‐
497 ciativity.
498 The BSD and System V versions of -f are not the same. The BSD defini‐
500 tion was:
501 -f file
503 True if file exists and is not a directory.
504 The SVID version (true if the file exists and is a regular file) was
507 chosen for this volume of IEEE Std 1003.1-2001 because its use is con‐
508 sistent with the -b, -c, -d, and -p operands ( file exists and is a
509 specific file type).
510 The -e primary, possessing similar functionality to that provided by
512 the C shell, was added because it provides the only way for a shell
513 script to find out if a file exists without trying to open the file.
514 Since implementations are allowed to add additional file types, a por‐
515 table script cannot use:
516 test -b foo -o -c foo -o -d foo -o -f foo -o -p foo
519 to find out if foo is an existing file. On historical BSD systems, the
521 existence of a file could be determined by:
522 test -f foo -o -d foo
525 but there was no easy way to determine that an existing file was a reg‐
527 ular file. An early proposal used the KornShell -a primary (with the
528 same meaning), but this was changed to -e because there were concerns
529 about the high probability of humans confusing the -a primary with the
530 -a binary operator.
531 The following options were not included in this volume of
533 IEEE Std 1003.1-2001, although they are provided by some implementa‐
534 tions. These operands should not be used by new implementations for
535 other purposes:
536 -k file
538 True if file exists and its sticky bit is set.
539 -C file
541 True if file is a contiguous file.
542 -V file
544 True if file is a version file.
545 The following option was not included because it was undocumented in
548 most implementations, has been removed from some implementations
549 (including System V), and the functionality is provided by the shell
550 (see Parameter Expansion .
551 -l string
553 The length of the string string.
554 The -b, -c, -g, -p, -u, and -x operands are derived from the SVID; his‐
557 torical BSD does not provide them. The -k operand is derived from Sys‐
558 tem V; historical BSD does not provide it.
559 On historical BSD systems, test -w directory always returned false
561 because test tried to open the directory for writing, which always
562 fails.
563 Some additional primaries newly invented or from the KornShell appeared
565 in an early proposal as part of the conditional command ( [[]]): s1 >
566 s2, s1 < s2, str = pattern, str != pattern, f1 -nt f2, f1 -ot f2, and
567 f1 -ef f2. They were not carried forward into the test utility when the
568 conditional command was removed from the shell because they have not
569 been included in the test utility built into historical implementations
570 of the sh utility.
571 The -t file_descriptor primary is shown with a mandatory argument
573 because the grammar is ambiguous if it can be omitted. Historical
574 implementations have allowed it to be omitted, providing a default of
575 1.
576
578 None.
579
581 File Read, Write, and Creation, find
582
584 Portions of this text are reprinted and reproduced in electronic form
585 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
586 -- Portable Operating System Interface (POSIX), The Open Group Base
587 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
588 Electrical and Electronics Engineers, Inc and The Open Group. In the
589 event of any discrepancy between this version and the original IEEE and
590 The Open Group Standard, the original IEEE and The Open Group Standard
591 is the referee document. The original Standard can be obtained online
592 at http://www.opengroup.org/unix/online.html .
593IEEE/The Open Group 2003 TEST(1P)