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
13 test — evaluate expression
14
16 test [expression]
17 [ [expression] ]
19
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 POSIX.1‐2008, 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 pathname
44 True if pathname resolves to en existing directory entry for
45 a block special file. False if pathname cannot be resolved,
46 or if pathname resolves to an existing directory entry for a
47 file that is not a block special file.
48 −c pathname
50 True if pathname resolves to an existing directory entry for
51 a character special file. False if pathname cannot be
52 resolved, or if pathname resolves to an existing directory
53 entry for a file that is not a character special file.
54 −d pathname
56 True if pathname resolves to an existing directory entry for
57 a directory. False if pathname cannot be resolved, or if
58 pathname resolves to an existing directory entry for a file
59 that is not a directory.
60 −e pathname
62 True if pathname resolves to an existing directory entry.
63 False if pathname cannot be resolved.
64 −f pathname
66 True if pathname resolves to an existing directory entry for
67 a regular file. False if pathname cannot be resolved, or if
68 pathname resolves to an existing directory entry for a file
69 that is not a regular file.
70 −g pathname
72 True if pathname resolves to an existing directory entry for
73 a file that has its set-group-ID flag set. False if pathname
74 cannot be resolved, or if pathname resolves to an existing
75 directory entry for a file that does not have its set-group-
76 ID flag set.
77 −h pathname
79 True if pathname resolves to an existing directory entry for
80 a symbolic link. False if pathname cannot be resolved, or if
81 pathname resolves to an existing directory entry for a file
82 that is not a symbolic link. If the final component of path‐
83 name is a symbolic link, that symbolic link is not followed.
84 −L pathname
86 True if pathname resolves to an existing directory entry for
87 a symbolic link. False if pathname cannot be resolved, or if
88 pathname resolves to an existing directory entry for a file
89 that is not a symbolic link. If the final component of path‐
90 name is a symbolic link, that symbolic link is not followed.
91 −n string True if the length of string is non-zero; otherwise, false.
93 −p pathname
95 True if pathname resolves to an existing directory entry for
96 a FIFO. False if pathname cannot be resolved, or if pathname
97 resolves to an existing directory entry for a file that is
98 not a FIFO.
99 −r pathname
101 True if pathname resolves to an existing directory entry for
102 a file for which permission to read from the file will be
103 granted, as defined in Section 1.1.1.4, File Read, Write, and
104 Creation. False if pathname cannot be resolved, or if path‐
105 name resolves to an existing directory entry for a file for
106 which permission to read from the file will not be granted.
107 −S pathname
109 True if pathname resolves to an existing directory entry for
110 a socket. False if pathname cannot be resolved, or if path‐
111 name resolves to an existing directory entry for a file that
112 is not a socket.
113 −s pathname
115 True if pathname resolves to an existing directory entry for
116 a file that has a size greater than zero. False if pathname
117 cannot be resolved, or if pathname resolves to an existing
118 directory entry for a file that does not have a size greater
119 than zero.
120 −t file_descriptor
122 True if file descriptor number file_descriptor is open and is
123 associated with a terminal. False if file_descriptor is not a
124 valid file descriptor number, or if file descriptor number
125 file_descriptor is not open, or if it is open but is not
126 associated with a terminal.
127 −u pathname
129 True if pathname resolves to an existing directory entry for
130 a file that has its set-user-ID flag set. False if pathname
131 cannot be resolved, or if pathname resolves to an existing
132 directory entry for a file that does not have its set-user-ID
133 flag set.
134 −w pathname
136 True if pathname resolves to an existing directory entry for
137 a file for which permission to write to the file will be
138 granted, as defined in Section 1.1.1.4, File Read, Write, and
139 Creation. False if pathname cannot be resolved, or if path‐
140 name resolves to an existing directory entry for a file for
141 which permission to write to the file will not be granted.
142 −x pathname
144 True if pathname resolves to an existing directory entry for
145 a file for which permission to execute the file (or search
146 it, if it is a directory) will be granted, as defined in Sec‐
147 tion 1.1.1.4, File Read, Write, and Creation. False if path‐
148 name cannot be resolved, or if pathname resolves to an exist‐
149 ing directory entry for a file for which permission to exe‐
150 cute (or search) the file will not be granted.
151 −z string True if the length of string string is zero; otherwise,
153 false.
154 string True if the string string is not the null string; otherwise,
156 false.
157 s1 = s2 True if the strings s1 and s2 are identical; otherwise,
159 false.
160 s1 != s2 True if the strings s1 and s2 are not identical; otherwise,
162 false.
163 n1 −eq n2 True if the integers n1 and n2 are algebraically equal; oth‐
165 erwise, false.
166 n1 −ne n2 True if the integers n1 and n2 are not algebraically equal;
168 otherwise, false.
169 n1 −gt n2 True if the integer n1 is algebraically greater than the
171 integer n2; otherwise, false.
172 n1 −ge n2 True if the integer n1 is algebraically greater than or equal
174 to the integer n2; otherwise, false.
175 n1 −lt n2 True if the integer n1 is algebraically less than the integer
177 n2; otherwise, false.
178 n1 −le n2 True if the integer n1 is algebraically less than or equal to
180 the integer n2; otherwise, false.
181 expression1 −a expression2
183 True if both expression1 and expression2 are true; otherwise,
184 false. The −a binary primary is left associative. It has a
185 higher precedence than −o.
186 expression1 −o expression2
188 True if either expression1 or expression2 is true; otherwise,
189 false. The −o binary primary is left associative.
190 With the exception of the −h pathname and −L pathname primaries, if a
192 pathname argument is a symbolic link, test shall evaluate the expres‐
193 sion by resolving the symbolic link and using the file referenced by
194 the link.
195 These primaries can be combined with the following operators:
197 ! expression
199 True if expression is false. False if expression is true.
200 ( expression )
202 True if expression is true. False if expression is false. The
203 parentheses can be used to alter the normal precedence and
204 associativity.
205 The primaries with two elements of the form:
207 −primary_operator primary_operand
209 are known as unary primaries. The primaries with three elements in
211 either of the two forms:
212 primary_operand −primary_operator primary_operand
214 primary_operand primary_operator primary_operand
216 are known as binary primaries. Additional implementation-defined oper‐
218 ators and primary_operators may be provided by implementations. They
219 shall be of the form −operator where the first character of operator is
220 not a digit.
221 The algorithm for determining the precedence of the operators and the
223 return value that shall be generated is based on the number of argu‐
224 ments presented to test. (However, when using the "[...]" form, the
225 <right-square-bracket> final argument shall not be counted in this
226 algorithm.)
227 In the following list, $1, $2, $3, and $4 represent the arguments pre‐
229 sented to test:
230 0 arguments:
232 Exit false (1).
233 1 argument: Exit true (0) if $1 is not null; otherwise, exit false.
235 2 arguments:
237 * If $1 is '!', exit true if $2 is null, false if $2 is
238 not null.
239 * If $1 is a unary primary, exit true if the unary test
241 is true, false if the unary test is false.
242 * Otherwise, produce unspecified results.
244 3 arguments:
246 * If $2 is a binary primary, perform the binary test of
247 $1 and $3.
248 * If $1 is '!', negate the two-argument test of $2 and
250 $3.
251 * If $1 is '(' and $3 is ')', perform the unary test of
253 $2. On systems that do not support the XSI option, the
254 results are unspecified if $1 is '(' and $3 is ')'.
255 * Otherwise, produce unspecified results.
257 4 arguments:
259 * If $1 is '!', negate the three-argument test of $2, $3,
260 and $4.
261 * If $1 is '(' and $4 is ')', perform the two-argument
263 test of $2 and $3. On systems that do not support the
264 XSI option, the results are unspecified if $1 is '('
265 and $4 is ')'.
266 * Otherwise, the results are unspecified.
268 >4 arguments:
270 The results are unspecified.
271 On XSI-conformant systems, combinations of primaries and
273 operators shall be evaluated using the precedence and asso‐
274 ciativity rules described previously. In addition, the
275 string comparison binary primaries '=' and "!=" shall have
276 a higher precedence than any unary primary.
277
279 Not used.
280
282 None.
283
285 The following environment variables shall affect the execution of test:
286 LANG Provide a default value for the internationalization vari‐
288 ables that are unset or null. (See the Base Definitions vol‐
289 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
290 ables for the precedence of internationalization variables
291 used to determine the values of locale categories.)
292 LC_ALL If set to a non-empty string value, override the values of
294 all the other internationalization variables.
295 LC_CTYPE Determine the locale for the interpretation of sequences of
297 bytes of text data as characters (for example, single-byte as
298 opposed to multi-byte characters in arguments).
299 LC_MESSAGES
301 Determine the locale that should be used to affect the format
302 and contents of diagnostic messages written to standard
303 error.
304 NLSPATH Determine the location of message catalogs for the processing
306 of LC_MESSAGES.
307
309 Default.
310
312 Not used.
313
315 The standard error shall be used only for diagnostic messages.
316
318 None.
319
321 None.
322
324 The following exit values shall be returned:
325 0 expression evaluated to true.
327 1 expression evaluated to false or expression was missing.
329 >1 An error occurred.
331
333 Default.
334 The following sections are informative.
336
338 The XSI extensions specifying the −a and −o binary primaries and the
339 '(' and ')' operators have been marked obsolescent. (Many expressions
340 using them are ambiguously defined by the grammar depending on the spe‐
341 cific expressions being evaluated.) Scripts using these expressions
342 should be converted to the forms given below. Even though many imple‐
343 mentations will continue to support these obsolescent forms, scripts
344 should be extremely careful when dealing with user-supplied input that
345 could be confused with these and other primaries and operators. Unless
346 the application developer knows all the cases that produce input to the
347 script, invocations like:
348 test "$1" −a "$2"
350 should be written as:
352 test "$1" && test "$2"
354 to avoid problems if a user supplied values such as $1 set to '!' and
356 $2 set to the null string. That is, in cases where maximal portability
357 is of concern, replace:
358 test expr1 −a expr2
360 with:
362 test expr1 && test expr2
364 and replace:
366 test expr1 −o expr2
368 with:
370 test expr1 || test expr2
372 but note that, in test, −a has higher precedence than −o while "&&" and
374 "||" have equal precedence in the shell.
375 Parentheses or braces can be used in the shell command language to
377 effect grouping.
378 Parentheses must be escaped when using sh; for example:
380 test \( expr1 −a expr2 \) −o expr3
382 This command is not always portable even on XSI-conformant systems
384 depending on the expressions specified by expr1, expr2, and expr3. The
385 following form can be used instead:
386 ( test expr1 && test expr2 ) || test expr3
388 The two commands:
390 test "$1"
392 test ! "$1"
393 could not be used reliably on some historical systems. Unexpected
395 results would occur if such a string expression were used and $1
396 expanded to '!', '(', or a known unary primary. Better constructs are:
397 test −n "$1"
399 test −z "$1"
400 respectively.
402 Historical systems have also been unreliable given the common con‐
404 struct:
405 test "$response" = "expected string"
407 One of the following is a more reliable form:
409 test "X$response" = "Xexpected string"
411 test "expected string" = "$response"
412 Note that the second form assumes that expected string could not be
414 confused with any unary primary. If expected string starts with '−',
415 '(', '!', or even '=', the first form should be used instead. Using the
416 preceding rules without the XSI marked extensions, any of the three
417 comparison forms is reliable, given any input. (However, note that the
418 strings are quoted in all cases.)
419 Because the string comparison binary primaries, '=' and "!=", have a
421 higher precedence than any unary primary in the greater than 4 argument
422 case, unexpected results can occur if arguments are not properly pre‐
423 pared. For example, in:
424 test −d $1 −o −d $2
426 If $1 evaluates to a possible directory name of '=', the first three
428 arguments are considered a string comparison, which shall cause a syn‐
429 tax error when the second −d is encountered. One of the following forms
430 prevents this; the second is preferred:
431 test \( −d "$1" \) −o \( −d "$2" \)
433 test −d "$1" || test −d "$2"
434 Also in the greater than 4 argument case:
436 test "$1" = "bat" −a "$2" = "ball"
438 syntax errors occur if $1 evaluates to '(' or '!'. One of the follow‐
440 ing forms prevents this; the third is preferred:
441 test "X$1" = "Xbat" −a "X$2" = "Xball"
443 test "$1" = "bat" && test "$2" = "ball"
444 test "X$1" = "Xbat" && test "X$2" = "Xball"
445
447 1. Exit if there are not two or three arguments (two variations):
448 if [ $# −ne 2 ] && [ $# −ne 3 ]; then exit 1; fi
450 if [ $# −lt 2 ] || [ $# −gt 3 ]; then exit 1; fi
451 2. Perform a mkdir if a directory does not exist:
453 test ! −d tempdir && mkdir tempdir
455 3. Wait for a file to become non-readable:
457 while test −r thefile
459 do
460 sleep 30
461 done
462 echo '"thefile" is no longer readable'
463 4. Perform a command if the argument is one of three strings (two
465 variations):
466 if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
468 then
469 command
470 fi
471 case "$1" in
473 pear|grape|apple) command ;;
474 esac
475
477 The KornShell-derived conditional command (double bracket [[]]) was
478 removed from the shell command language description in an early pro‐
479 posal. Objections were raised that the real problem is misuse of the
480 test command ([), and putting it into the shell is the wrong way to fix
481 the problem. Instead, proper documentation and a new shell reserved
482 word (!) are sufficient.
483 Tests that require multiple test operations can be done at the shell
485 level using individual invocations of the test command and shell logi‐
486 cals, rather than using the error-prone −o flag of test.
487 XSI-conformant systems support more than four arguments.
489 XSI-conformant systems support the combining of primaries with the fol‐
491 lowing constructs:
492 expression1 −a expression2
494 True if both expression1 and expression2 are true.
495 expression1 −o expression2
497 True if at least one of expression1 and expression2 are true.
498 ( expression )
500 True if expression is true.
501 In evaluating these more complex combined expressions, the following
503 precedence rules are used:
504 * The unary primaries have higher precedence than the algebraic
506 binary primaries.
507 * The unary primaries have lower precedence than the string binary
509 primaries.
510 * The unary and binary primaries have higher precedence than the
512 unary string primary.
513 * The ! operator has higher precedence than the −a operator, and the
515 −a operator has higher precedence than the −o operator.
516 * The −a and −o operators are left associative.
518 * The parentheses can be used to alter the normal precedence and
520 associativity.
521 The BSD and System V versions of −f are not the same. The BSD defini‐
523 tion was:
524 −f file True if file exists and is not a directory.
526 The SVID version (true if the file exists and is a regular file) was
528 chosen for this volume of POSIX.1‐2008 because its use is consistent
529 with the −b, −c, −d, and −p operands (file exists and is a specific
530 file type).
531 The −e primary, possessing similar functionality to that provided by
533 the C shell, was added because it provides the only way for a shell
534 script to find out if a file exists without trying to open the file.
535 Since implementations are allowed to add additional file types, a por‐
536 table script cannot use:
537 test −b foo −o −c foo −o −d foo −o −f foo −o −p foo
539 to find out if foo is an existing file. On historical BSD systems, the
541 existence of a file could be determined by:
542 test −f foo −o −d foo
544 but there was no easy way to determine that an existing file was a reg‐
546 ular file. An early proposal used the KornShell −a primary (with the
547 same meaning), but this was changed to −e because there were concerns
548 about the high probability of humans confusing the −a primary with the
549 −a binary operator.
550 The following options were not included in this volume of POSIX.1‐2008,
552 although they are provided by some implementations. These operands
553 should not be used by new implementations for other purposes:
554 −k file True if file exists and its sticky bit is set.
556 −C file True if file is a contiguous file.
558 −V file True if file is a version file.
560 The following option was not included because it was undocumented in
562 most implementations, has been removed from some implementations
563 (including System V), and the functionality is provided by the shell
564 (see Section 2.6.2, Parameter Expansion.
565 −l string The length of the string string.
567 The −b, −c, −g, −p, −u, and −x operands are derived from the SVID; his‐
569 torical BSD does not provide them. The −k operand is derived from Sys‐
570 tem V; historical BSD does not provide it.
571 On historical BSD systems, test −w directory always returned false
573 because test tried to open the directory for writing, which always
574 fails.
575 Some additional primaries newly invented or from the KornShell appeared
577 in an early proposal as part of the conditional command ([[]]): s1 >
578 s2, s1 < s2, str = pattern, str != pattern, f1 −nt f2, f1 −ot f2, and
579 f1 −ef f2. They were not carried forward into the test utility when
580 the conditional command was removed from the shell because they have
581 not been included in the test utility built into historical implementa‐
582 tions of the sh utility.
583 The −t file_descriptor primary is shown with a mandatory argument
585 because the grammar is ambiguous if it can be omitted. Historical
586 implementations have allowed it to be omitted, providing a default of
587 1.
588 It is noted that '[' is not part of the portable filename character
590 set; however, since it is required to be encoded by a single byte, and
591 is part of the portable character set, the name of this utility forms a
592 character string across all supported locales.
593
595 None.
596
598 Section 1.1.1.4, File Read, Write, and Creation, find
599 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
601 Variables, Section 12.2, Utility Syntax Guidelines
602
604 Portions of this text are reprinted and reproduced in electronic form
605 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
606 -- Portable Operating System Interface (POSIX), The Open Group Base
607 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
608 cal and Electronics Engineers, Inc and The Open Group. (This is
609 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
610 event of any discrepancy between this version and the original IEEE and
611 The Open Group Standard, the original IEEE and The Open Group Standard
612 is the referee document. The original Standard can be obtained online
613 at http://www.unix.org/online.html .
614 Any typographical or formatting errors that appear in this page are
616 most likely to have been introduced during the conversion of the source
617 files to man page format. To report such errors, see https://www.ker‐
618 nel.org/doc/man-pages/reporting_bugs.html .
619IEEE/The Open Group 2013 TEST(1P)