1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
2 .TH "TEST" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
5 test \- evaluate expression
8 \fBtest\fP \fB[\fP\fIexpression\fP\fB]\fP\fB
11 [\fP \fB[\fP\fIexpression\fP\fB]\fP \fB]
16 The \fItest\fP utility shall evaluate the \fIexpression\fP and indicate
17 the result of the evaluation by its exit status. An
18 exit status of zero indicates that the expression evaluated as true
19 and an exit status of 1 indicates that the expression evaluated
22 In the second form of the utility, which uses \fB"[]"\fP rather than
23 \fItest\fP, the application shall ensure that the
24 square brackets are separate arguments.
27 The \fItest\fP utility shall not recognize the \fB"--"\fP argument
28 in the manner specified by guideline 10 in the Base
29 Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility
33 No options shall be supported.
36 The application shall ensure that all operators and elements of primaries
37 are presented as separate arguments to the \fItest\fP
40 The following primaries can be used to construct \fIexpression\fP:
43 True if \fIfile\fP exists and is a block special file.
46 True if \fIfile\fP exists and is a character special file.
49 True if \fIfile\fP exists and is a directory.
52 True if \fIfile\fP exists.
55 True if \fIfile\fP exists and is a regular file.
58 True if \fIfile\fP exists and its set-group-ID flag is set.
61 True if \fIfile\fP exists and is a symbolic link.
64 True if \fIfile\fP exists and is a symbolic link.
66 \fB-n\ \fP \fIstring\fP
67 True if the length of \fIstring\fP is non-zero.
70 True if \fIfile\fP is a FIFO.
73 True if \fIfile\fP exists and is readable. True shall indicate that
74 permission to read from \fIfile\fP will be granted, as
75 defined in \fIFile Read, Write, and Creation\fP .
78 True if \fIfile\fP exists and is a socket.
81 True if \fIfile\fP exists and has a size greater than zero.
83 \fB-t\ \fP \fIfile_descriptor\fP
85 True if the file whose file descriptor number is \fIfile_descriptor\fP
86 is open and is associated with a terminal.
89 True if \fIfile\fP exists and its set-user-ID flag is set.
92 True if \fIfile\fP exists and is writable. True shall indicate that
93 permission to write from \fIfile\fP will be granted, as
94 defined in \fIFile Read, Write, and Creation\fP .
97 True if \fIfile\fP exists and is executable. True shall indicate that
98 permission to execute \fIfile\fP will be granted, as
99 defined in \fIFile Read, Write, and Creation\fP . If \fIfile\fP is
101 true shall indicate that permission to search \fIfile\fP will be granted.
103 \fB-z\ \fP \fIstring\fP
104 True if the length of string \fIstring\fP is zero.
107 True if the string \fIstring\fP is not the null string.
109 \fIs1\fP\fB\ =\ \fP \fIs2\fP
110 True if the strings \fIs1\fP and \fIs2\fP are identical.
112 \fIs1\fP\fB\ !=\ \fP \fIs2\fP
113 True if the strings \fIs1\fP and \fIs2\fP are not identical.
115 \fIn1\fP\fB\ -eq\ \fP \fIn2\fP
116 True if the integers \fIn1\fP and \fIn2\fP are algebraically equal.
118 \fIn1\fP\fB\ -ne\ \fP \fIn2\fP
119 True if the integers \fIn1\fP and \fIn2\fP are not algebraically equal.
121 \fIn1\fP\fB\ -gt\ \fP \fIn2\fP
122 True if the integer \fIn1\fP is algebraically greater than the integer
125 \fIn1\fP\fB\ -ge\ \fP \fIn2\fP
126 True if the integer \fIn1\fP is algebraically greater than or equal
127 to the integer \fIn2\fP.
129 \fIn1\fP\fB\ -lt\ \fP \fIn2\fP
130 True if the integer \fIn1\fP is algebraically less than the integer
133 \fIn1\fP\fB\ -le\ \fP \fIn2\fP
134 True if the integer \fIn1\fP is algebraically less than or equal to
135 the integer \fIn2\fP.
137 \fIexpression1\fP\fB\ -a\ \fP \fIexpression2\fP
139 True if both \fIexpression1\fP and \fIexpression2\fP are true. The
140 \fB-a\fP binary primary is left associative. It has a higher
141 precedence than \fB-o\fP.
143 \fIexpression1\fP\fB\ -o\ \fP \fIexpression2\fP
145 True if either \fIexpression1\fP or \fIexpression2\fP is true. The
146 \fB-o\fP binary primary is left associative.
149 With the exception of the \fB-h\fP \fIfile\fP and \fB-L\fP \fIfile\fP
150 primaries, if a \fIfile\fP argument is a symbolic
151 link, \fItest\fP shall evaluate the expression by resolving the symbolic
152 link and using the file referenced by the link.
154 These primaries can be combined with the following operators:
156 \fB!\ \fP \fIexpression\fP
157 True if \fIexpression\fP is false.
159 \fB(\ \fP \fIexpression\ \fP \fB)\fP
160 True if \fIexpression\fP is true. The parentheses can be used to alter
161 the normal precedence and associativity.
164 The primaries with two elements of the form:
169 \fB-\fP\fIprimary_operator primary_operand\fP
173 are known as \fIunary primaries\fP. The primaries with three elements
174 in either of the two forms:
179 \fIprimary_operand\fP \fB-\fP\fIprimary_operator primary_operand
182 primary_operand primary_operator primary_operand\fP
186 are known as \fIbinary primaries\fP. Additional implementation-defined
187 operators and \fIprimary_operator\fPs may be provided
188 by implementations. They shall be of the form - \fIoperator\fP where
189 the first character of \fIoperator\fP is not a digit.
191 The algorithm for determining the precedence of the operators and
192 the return value that shall be generated is based on the
193 number of arguments presented to \fItest\fP. (However, when using
194 the \fB"[...]"\fP form, the right-bracket final argument
195 shall not be counted in this algorithm.)
197 In the following list, $1, $2, $3, and $4 represent the arguments
198 presented to \fItest\fP:
204 Exit true (0) if $1 is not null; otherwise, exit false.
209 If $1 is \fB'!'\fP , exit true if $2 is null, false if $2 is not null.
212 If $1 is a unary primary, exit true if the unary test is true, false
213 if the unary test is false.
216 Otherwise, produce unspecified results.
223 If $2 is a binary primary, perform the binary test of $1 and $3.
226 If $1 is \fB'!'\fP , negate the two-argument test of $2 and $3.
229 If $1 is \fB'('\fP and $3 is \fB')'\fP , perform the unary test of
233 Otherwise, produce unspecified results.
240 If $1 is \fB'!'\fP , negate the three-argument test of $2, $3, and
244 If $1 is \fB'('\fP and $4 is \fB')'\fP , perform the two-argument
248 Otherwise, the results are unspecified.
253 The results are unspecified.
255 On XSI-conformant systems, combinations of primaries and operators
256 shall be evaluated using the precedence and associativity rules
257 described previously. In addition, the string comparison binary primaries
258 \fB'='\fP and \fB"!="\fP shall have a higher
259 precedence than any unary primary.
267 .SH ENVIRONMENT VARIABLES
269 The following environment variables shall affect the execution of
273 Provide a default value for the internationalization variables that
274 are unset or null. (See the Base Definitions volume of
275 IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
277 the precedence of internationalization variables used to determine
278 the values of locale categories.)
281 If set to a non-empty string value, override the values of all the
282 other internationalization variables.
285 Determine the locale for the interpretation of sequences of bytes
286 of text data as characters (for example, single-byte as
287 opposed to multi-byte characters in arguments).
290 Determine the locale that should be used to affect the format and
291 contents of diagnostic messages written to standard
295 Determine the location of message catalogs for the processing of \fILC_MESSAGES
298 .SH ASYNCHRONOUS EVENTS
306 The standard error shall be used only for diagnostic messages.
310 .SH EXTENDED DESCRIPTION
315 The following exit values shall be returned:
318 \fIexpression\fP evaluated to true.
321 \fIexpression\fP evaluated to false or \fIexpression\fP was missing.
326 .SH CONSEQUENCES OF ERRORS
330 \fIThe following sections are informative.\fP
331 .SH APPLICATION USAGE
333 Scripts should be careful when dealing with user-supplied input that
334 could be confused with primaries and operators. Unless the
335 application writer knows all the cases that produce input to the script,
346 should be written as:
351 \fBtest "$1" && test "$2"
356 to avoid problems if a user supplied values such as $1 set to \fB'!'\fP
357 and $2 set to the null string. That is, in cases
358 where maximal portability is of concern, replace:
363 \fBtest expr1 -a expr2
373 \fBtest expr1 && test expr2
383 \fBtest expr1 -o expr2
393 \fBtest expr1 || test expr2
398 but note that, in \fItest\fP, \fB-a\fP has higher precedence than
399 \fB-o\fP while \fB"&&"\fP and \fB"||"\fP have
400 equal precedence in the shell.
402 Parentheses or braces can be used in the shell command language to
405 Parentheses must be escaped when using \fIsh\fP; for example:
410 \fBtest \\( expr1 -a expr2 \\) -o expr3
415 This command is not always portable outside XSI-conformant systems.
416 The following form can be used instead:
421 \fB( test expr1 && test expr2 ) || test expr3
437 could not be used reliably on some historical systems. Unexpected
438 results would occur if such a \fIstring\fP expression were
439 used and $1 expanded to \fB'!'\fP , \fB'('\fP , or a known unary primary.
440 Better constructs are:
452 Historical systems have also been unreliable given the common construct:
457 \fBtest "$response" = "expected string"
462 One of the following is a more reliable form:
467 \fBtest "X$response" = "Xexpected string"
468 test "expected string" = "$response"
473 Note that the second form assumes that \fIexpected string\fP could
474 not be confused with any unary primary. If \fIexpected
475 string\fP starts with \fB'-'\fP , \fB'('\fP , \fB'!'\fP , or even
476 \fB'='\fP , the first form should be used instead.
477 Using the preceding rules without the XSI marked extensions, any of
478 the three comparison forms is reliable, given any input.
479 (However, note that the strings are quoted in all cases.)
481 Because the string comparison binary primaries, \fB'='\fP and \fB"!="\fP
482 , have a higher precedence than any unary primary
483 in the greater than 4 argument case, unexpected results can occur
484 if arguments are not properly prepared. For example, in:
489 \fBtest -d $1 -o -d $2
494 If $1 evaluates to a possible directory name of \fB'='\fP , the first
495 three arguments are considered a string comparison,
496 which shall cause a syntax error when the second \fB-d\fP is encountered.
497 One of the following forms prevents this; the second is
503 \fBtest \\( -d "$1" \\) -o \\( -d "$2" \\)
504 test -d "$1" || test -d "$2"
509 Also in the greater than 4 argument case:
514 \fBtest "$1" = "bat" -a "$2" = "ball"
519 syntax errors occur if $1 evaluates to \fB'('\fP or \fB'!'\fP . One
520 of the following forms prevents this; the third is
526 \fBtest "X$1" = "Xbat" -a "X$2" = "Xball"
527 test "$1" = "bat" && test "$2" = "ball"
528 test "X$1" = "Xbat" && test "X$2" = "Xball"
534 Exit if there are not two or three arguments (two variations):
539 \fBif [ $# -ne 2 -a $# -ne 3 ]; then exit 1; fi
540 if [ $# -lt 2 -o $# -gt 3 ]; then exit 1; fi
546 Perform a \fImkdir\fP if a directory does not exist:
551 \fBtest ! -d tempdir && mkdir tempdir
557 Wait for a file to become non-readable:
562 \fBwhile test -r thefile
566 echo '"thefile" is no longer readable'
572 Perform a command if the argument is one of three strings (two variations):
577 \fBif [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
584 pear|grape|apple)\fP \fIcommand\fP \fB;;
592 The KornShell-derived conditional command (double bracket \fB[[]]\fP)
593 was removed from the shell command language description
594 in an early proposal. Objections were raised that the real problem
595 is misuse of the \fItest\fP command ( \fB[\fP), and putting it
596 into the shell is the wrong way to fix the problem. Instead, proper
597 documentation and a new shell reserved word ( \fB!\fP) are
600 Tests that require multiple \fItest\fP operations can be done at the
601 shell level using individual invocations of the
602 \fItest\fP command and shell logicals, rather than using the error-prone
603 \fB-o\fP flag of \fItest\fP.
605 XSI-conformant systems support more than four arguments.
607 XSI-conformant systems support the combining of primaries with the
608 following constructs:
610 \fIexpression1\fP \fB-a\fP \fIexpression2\fP
612 True if both \fIexpression1\fP and \fIexpression2\fP are true.
614 \fIexpression1\fP \fB-o\fP \fIexpression2\fP
616 True if at least one of \fIexpression1\fP and \fIexpression2\fP are
619 \fB(\fP \fIexpression\fP \fB)\fP
621 True if \fIexpression\fP is true.
624 In evaluating these more complex combined expressions, the following
625 precedence rules are used:
627 The unary primaries have higher precedence than the algebraic binary
631 The unary primaries have lower precedence than the string binary primaries.
634 The unary and binary primaries have higher precedence than the unary
635 \fIstring\fP primary.
638 The \fB!\fP operator has higher precedence than the \fB-a\fP operator,
639 and the \fB-a\fP operator has higher precedence than
640 the \fB-o\fP operator.
643 The \fB-a\fP and \fB-o\fP operators are left associative.
646 The parentheses can be used to alter the normal precedence and associativity.
649 The BSD and System V versions of \fB-f\fP are not the same. The BSD
652 \fB-f\ \fP \fIfile\fP
653 True if \fIfile\fP exists and is not a directory.
656 The SVID version (true if the file exists and is a regular file) was
657 chosen for this volume of IEEE\ Std\ 1003.1-2001
658 because its use is consistent with the \fB-b\fP, \fB-c\fP, \fB-d\fP,
659 and \fB-p\fP operands ( \fIfile\fP exists and is a
662 The \fB-e\fP primary, possessing similar functionality to that provided
663 by the C shell, was added because it provides the only
664 way for a shell script to find out if a file exists without trying
665 to open the file. Since implementations are allowed to add
666 additional file types, a portable script cannot use:
671 \fBtest -b foo -o -c foo -o -d foo -o -f foo -o -p foo
676 to find out if \fBfoo\fP is an existing file. On historical BSD systems,
677 the existence of a file could be determined by:
682 \fBtest -f foo -o -d foo
687 but there was no easy way to determine that an existing file was a
688 regular file. An early proposal used the KornShell \fB-a\fP
689 primary (with the same meaning), but this was changed to \fB-e\fP
690 because there were concerns about the high probability of humans
691 confusing the \fB-a\fP primary with the \fB-a\fP binary operator.
693 The following options were not included in this volume of IEEE\ Std\ 1003.1-2001,
694 although they are provided by some
695 implementations. These operands should not be used by new implementations
698 \fB-k\ \fP \fIfile\fP
699 True if \fIfile\fP exists and its sticky bit is set.
701 \fB-C\ \fP \fIfile\fP
702 True if \fIfile\fP is a contiguous file.
704 \fB-V\ \fP \fIfile\fP
705 True if \fIfile\fP is a version file.
708 The following option was not included because it was undocumented
709 in most implementations, has been removed from some
710 implementations (including System V), and the functionality is provided
711 by the shell (see \fIParameter Expansion\fP .
713 \fB-l\ \fP \fIstring\fP
714 The length of the string \fIstring\fP.
717 The \fB-b\fP, \fB-c\fP, \fB-g\fP, \fB-p\fP, \fB-u\fP, and \fB-x\fP
718 operands are derived from the SVID; historical BSD does
719 not provide them. The \fB-k\fP operand is derived from System V; historical
720 BSD does not provide it.
722 On historical BSD systems, \fItest\fP \fB-w\fP \fIdirectory\fP always
723 returned false because \fItest\fP tried to open the
724 directory for writing, which always fails.
726 Some additional primaries newly invented or from the KornShell appeared
727 in an early proposal as part of the conditional command
728 ( \fB[[]]\fP): \fIs1\fP \fB>\fP \fIs2\fP, \fIs1\fP \fB<\fP \fIs2\fP,
729 \fIstr\fP \fB=\fP \fIpattern\fP, \fIstr\fP
730 \fB!=\fP \fIpattern\fP, \fIf1\fP \fB-nt\fP \fIf2\fP, \fIf1\fP \fB-ot\fP
731 \fIf2\fP, and \fIf1\fP \fB-ef\fP \fIf2\fP. They
732 were not carried forward into the \fItest\fP utility when the conditional
733 command was removed from the shell because they have not
734 been included in the \fItest\fP utility built into historical implementations
738 The \fB-t\fP \fIfile_descriptor\fP primary is shown with a mandatory
739 argument because the grammar is ambiguous if it can be
740 omitted. Historical implementations have allowed it to be omitted,
741 providing a default of 1.
742 .SH FUTURE DIRECTIONS
747 \fIFile Read, Write, and Creation\fP , \fIfind\fP
749 Portions of this text are reprinted and reproduced in electronic form
750 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
751 -- Portable Operating System Interface (POSIX), The Open Group Base
752 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
753 Electrical and Electronics Engineers, Inc and The Open Group. In the
754 event of any discrepancy between this version and the original IEEE and
755 The Open Group Standard, the original IEEE and The Open Group Standard
756 is the referee document. The original Standard can be obtained online at
757 http://www.opengroup.org/unix/online.html .
projects / thirdparty / man-pages.git / blob