diff options
Diffstat (limited to 'man-pages-posix-2003/man1p/test.1p')
| -rw-r--r-- | man-pages-posix-2003/man1p/test.1p | 762 |
1 files changed, 762 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man1p/test.1p b/man-pages-posix-2003/man1p/test.1p new file mode 100644 index 0000000..b1bfab9 --- /dev/null +++ b/man-pages-posix-2003/man1p/test.1p @@ -0,0 +1,762 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TEST" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" test +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +test \- evaluate expression +.SH SYNOPSIS +.LP +\fBtest\fP \fB[\fP\fIexpression\fP\fB]\fP\fB +.br +.sp +[\fP \fB[\fP\fIexpression\fP\fB]\fP \fB] +.br +\fP +.SH DESCRIPTION +.LP +The \fItest\fP utility shall evaluate the \fIexpression\fP and indicate +the result of the evaluation by its exit status. An +exit status of zero indicates that the expression evaluated as true +and an exit status of 1 indicates that the expression evaluated +as false. +.LP +In the second form of the utility, which uses \fB"[]"\fP rather than +\fItest\fP, the application shall ensure that the +square brackets are separate arguments. +.SH OPTIONS +.LP +The \fItest\fP utility shall not recognize the \fB"--"\fP argument +in the manner specified by guideline 10 in the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility +Syntax +Guidelines. +.LP +No options shall be supported. +.SH OPERANDS +.LP +The application shall ensure that all operators and elements of primaries +are presented as separate arguments to the \fItest\fP +utility. +.LP +The following primaries can be used to construct \fIexpression\fP: +.TP 7 +\fB-b\ \fP \fIfile\fP +True if \fIfile\fP exists and is a block special file. +.TP 7 +\fB-c\ \fP \fIfile\fP +True if \fIfile\fP exists and is a character special file. +.TP 7 +\fB-d\ \fP \fIfile\fP +True if \fIfile\fP exists and is a directory. +.TP 7 +\fB-e\ \fP \fIfile\fP +True if \fIfile\fP exists. +.TP 7 +\fB-f\ \fP \fIfile\fP +True if \fIfile\fP exists and is a regular file. +.TP 7 +\fB-g\ \fP \fIfile\fP +True if \fIfile\fP exists and its set-group-ID flag is set. +.TP 7 +\fB-h\ \fP \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP 7 +\fB-L\ \fP \fIfile\fP +True if \fIfile\fP exists and is a symbolic link. +.TP 7 +\fB-n\ \fP \fIstring\fP +True if the length of \fIstring\fP is non-zero. +.TP 7 +\fB-p\ \fP \fIfile\fP +True if \fIfile\fP is a FIFO. +.TP 7 +\fB-r\ \fP \fIfile\fP +True if \fIfile\fP exists and is readable. True shall indicate that +permission to read from \fIfile\fP will be granted, as +defined in \fIFile Read, Write, and Creation\fP . +.TP 7 +\fB-S\ \fP \fIfile\fP +True if \fIfile\fP exists and is a socket. +.TP 7 +\fB-s\ \fP \fIfile\fP +True if \fIfile\fP exists and has a size greater than zero. +.TP 7 +\fB-t\ \fP \fIfile_descriptor\fP +.sp +True if the file whose file descriptor number is \fIfile_descriptor\fP +is open and is associated with a terminal. +.TP 7 +\fB-u\ \fP \fIfile\fP +True if \fIfile\fP exists and its set-user-ID flag is set. +.TP 7 +\fB-w\ \fP \fIfile\fP +True if \fIfile\fP exists and is writable. True shall indicate that +permission to write from \fIfile\fP will be granted, as +defined in \fIFile Read, Write, and Creation\fP . +.TP 7 +\fB-x\ \fP \fIfile\fP +True if \fIfile\fP exists and is executable. True shall indicate that +permission to execute \fIfile\fP will be granted, as +defined in \fIFile Read, Write, and Creation\fP . If \fIfile\fP is +a directory, +true shall indicate that permission to search \fIfile\fP will be granted. +.TP 7 +\fB-z\ \fP \fIstring\fP +True if the length of string \fIstring\fP is zero. +.TP 7 +\fIstring\fP +True if the string \fIstring\fP is not the null string. +.TP 7 +\fIs1\fP\fB\ =\ \fP \fIs2\fP +True if the strings \fIs1\fP and \fIs2\fP are identical. +.TP 7 +\fIs1\fP\fB\ !=\ \fP \fIs2\fP +True if the strings \fIs1\fP and \fIs2\fP are not identical. +.TP 7 +\fIn1\fP\fB\ -eq\ \fP \fIn2\fP +True if the integers \fIn1\fP and \fIn2\fP are algebraically equal. +.TP 7 +\fIn1\fP\fB\ -ne\ \fP \fIn2\fP +True if the integers \fIn1\fP and \fIn2\fP are not algebraically equal. +.TP 7 +\fIn1\fP\fB\ -gt\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically greater than the integer +\fIn2\fP. +.TP 7 +\fIn1\fP\fB\ -ge\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically greater than or equal +to the integer \fIn2\fP. +.TP 7 +\fIn1\fP\fB\ -lt\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically less than the integer +\fIn2\fP. +.TP 7 +\fIn1\fP\fB\ -le\ \fP \fIn2\fP +True if the integer \fIn1\fP is algebraically less than or equal to +the integer \fIn2\fP. +.TP 7 +\fIexpression1\fP\fB\ -a\ \fP \fIexpression2\fP +.sp +True if both \fIexpression1\fP and \fIexpression2\fP are true. The +\fB-a\fP binary primary is left associative. It has a higher +precedence than \fB-o\fP. +.TP 7 +\fIexpression1\fP\fB\ -o\ \fP \fIexpression2\fP +.sp +True if either \fIexpression1\fP or \fIexpression2\fP is true. The +\fB-o\fP binary primary is left associative. +.sp +.LP +With the exception of the \fB-h\fP \fIfile\fP and \fB-L\fP \fIfile\fP +primaries, if a \fIfile\fP argument is a symbolic +link, \fItest\fP shall evaluate the expression by resolving the symbolic +link and using the file referenced by the link. +.LP +These primaries can be combined with the following operators: +.TP 7 +\fB!\ \fP \fIexpression\fP +True if \fIexpression\fP is false. +.TP 7 +\fB(\ \fP \fIexpression\ \fP \fB)\fP +True if \fIexpression\fP is true. The parentheses can be used to alter +the normal precedence and associativity. +.sp +.LP +The primaries with two elements of the form: +.sp +.RS +.nf + +\fB-\fP\fIprimary_operator primary_operand\fP +.fi +.RE +.LP +are known as \fIunary primaries\fP. The primaries with three elements +in either of the two forms: +.sp +.RS +.nf + +\fIprimary_operand\fP \fB-\fP\fIprimary_operator primary_operand +.sp + +primary_operand primary_operator primary_operand\fP +.fi +.RE +.LP +are known as \fIbinary primaries\fP. Additional implementation-defined +operators and \fIprimary_operator\fPs may be provided +by implementations. They shall be of the form - \fIoperator\fP where +the first character of \fIoperator\fP is not a digit. +.LP +The algorithm for determining the precedence of the operators and +the return value that shall be generated is based on the +number of arguments presented to \fItest\fP. (However, when using +the \fB"[...]"\fP form, the right-bracket final argument +shall not be counted in this algorithm.) +.LP +In the following list, $1, $2, $3, and $4 represent the arguments +presented to \fItest\fP: +.TP 7 +0\ arguments: +Exit false (1). +.TP 7 +1\ argument: +Exit true (0) if $1 is not null; otherwise, exit false. +.TP 7 +2\ arguments: +.RS +.IP " *" 3 +If $1 is \fB'!'\fP, exit true if $2 is null, false if $2 is not null. +.LP +.IP " *" 3 +If $1 is a unary primary, exit true if the unary test is true, false +if the unary test is false. +.LP +.IP " *" 3 +Otherwise, produce unspecified results. +.LP +.RE +.TP 7 +3\ arguments: +.RS +.IP " *" 3 +If $2 is a binary primary, perform the binary test of $1 and $3. +.LP +.IP " *" 3 +If $1 is \fB'!'\fP, negate the two-argument test of $2 and $3. +.LP +.IP " *" 3 +If $1 is \fB'('\fP and $3 is \fB')'\fP, perform the unary test of +$2. +.LP +.IP " *" 3 +Otherwise, produce unspecified results. +.LP +.RE +.TP 7 +4\ arguments: +.RS +.IP " *" 3 +If $1 is \fB'!'\fP, negate the three-argument test of $2, $3, and +$4. +.LP +.IP " *" 3 +If $1 is \fB'('\fP and $4 is \fB')'\fP, perform the two-argument +test of $2 and $3. +.LP +.IP " *" 3 +Otherwise, the results are unspecified. +.LP +.RE +.TP 7 +>4\ arguments: +The results are unspecified. +.LP +On XSI-conformant systems, combinations of primaries and operators +shall be evaluated using the precedence and associativity rules +described previously. In addition, the string comparison binary primaries +\fB'='\fP and \fB"!="\fP shall have a higher +precedence than any unary primary. +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fItest\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +Not used. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +\fIexpression\fP evaluated to true. +.TP 7 +\ 1 +\fIexpression\fP evaluated to false or \fIexpression\fP was missing. +.TP 7 +>1 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +Scripts should be careful when dealing with user-supplied input that +could be confused with primaries and operators. Unless the +application writer knows all the cases that produce input to the script, +invocations like: +.sp +.RS +.nf + +\fBtest "$1" -a "$2" +\fP +.fi +.RE +.LP +should be written as: +.sp +.RS +.nf + +\fBtest "$1" && test "$2" +\fP +.fi +.RE +.LP +to avoid problems if a user supplied values such as $1 set to \fB'!'\fP +and $2 set to the null string. That is, in cases +where maximal portability is of concern, replace: +.sp +.RS +.nf + +\fBtest expr1 -a expr2 +\fP +.fi +.RE +.LP +with: +.sp +.RS +.nf + +\fBtest expr1 && test expr2 +\fP +.fi +.RE +.LP +and replace: +.sp +.RS +.nf + +\fBtest expr1 -o expr2 +\fP +.fi +.RE +.LP +with: +.sp +.RS +.nf + +\fBtest expr1 || test expr2 +\fP +.fi +.RE +.LP +but note that, in \fItest\fP, \fB-a\fP has higher precedence than +\fB-o\fP while \fB"&&"\fP and \fB"||"\fP have +equal precedence in the shell. +.LP +Parentheses or braces can be used in the shell command language to +effect grouping. +.LP +Parentheses must be escaped when using \fIsh\fP; for example: +.sp +.RS +.nf + +\fBtest \\( expr1 -a expr2 \\) -o expr3 +\fP +.fi +.RE +.LP +This command is not always portable outside XSI-conformant systems. +The following form can be used instead: +.sp +.RS +.nf + +\fB( test expr1 && test expr2 ) || test expr3 +\fP +.fi +.RE +.LP +The two commands: +.sp +.RS +.nf + +\fBtest "$1" +test ! "$1" +\fP +.fi +.RE +.LP +could not be used reliably on some historical systems. Unexpected +results would occur if such a \fIstring\fP expression were +used and $1 expanded to \fB'!'\fP, \fB'('\fP, or a known unary primary. +Better constructs are: +.sp +.RS +.nf + +\fBtest -n "$1" +test -z "$1" +\fP +.fi +.RE +respectively. +.LP +Historical systems have also been unreliable given the common construct: +.sp +.RS +.nf + +\fBtest "$response" = "expected string" +\fP +.fi +.RE +.LP +One of the following is a more reliable form: +.sp +.RS +.nf + +\fBtest "X$response" = "Xexpected string" +test "expected string" = "$response" +\fP +.fi +.RE +.LP +Note that the second form assumes that \fIexpected string\fP could +not be confused with any unary primary. If \fIexpected +string\fP starts with \fB'-'\fP, \fB'('\fP, \fB'!'\fP, or even +\fB'='\fP, the first form should be used instead. +Using the preceding rules without the XSI marked extensions, any of +the three comparison forms is reliable, given any input. +(However, note that the strings are quoted in all cases.) +.LP +Because the string comparison binary primaries, \fB'='\fP and \fB"!="\fP, +have a higher precedence than any unary primary +in the greater than 4 argument case, unexpected results can occur +if arguments are not properly prepared. For example, in: +.sp +.RS +.nf + +\fBtest -d $1 -o -d $2 +\fP +.fi +.RE +.LP +If $1 evaluates to a possible directory name of \fB'='\fP, the first +three arguments are considered a string comparison, +which shall cause a syntax error when the second \fB-d\fP is encountered. +One of the following forms prevents this; the second is +preferred: +.sp +.RS +.nf + +\fBtest \\( -d "$1" \\) -o \\( -d "$2" \\) +test -d "$1" || test -d "$2" +\fP +.fi +.RE +.LP +Also in the greater than 4 argument case: +.sp +.RS +.nf + +\fBtest "$1" = "bat" -a "$2" = "ball" +\fP +.fi +.RE +.LP +syntax errors occur if $1 evaluates to \fB'('\fP or \fB'!'\fP . One +of the following forms prevents this; the third is +preferred: +.sp +.RS +.nf + +\fBtest "X$1" = "Xbat" -a "X$2" = "Xball" +test "$1" = "bat" && test "$2" = "ball" +test "X$1" = "Xbat" && test "X$2" = "Xball" +\fP +.fi +.RE +.SH EXAMPLES +.IP " 1." 4 +Exit if there are not two or three arguments (two variations): +.sp +.RS +.nf + +\fBif [ $# -ne 2 -a $# -ne 3 ]; then exit 1; fi +if [ $# -lt 2 -o $# -gt 3 ]; then exit 1; fi +\fP +.fi +.RE +.LP +.IP " 2." 4 +Perform a \fImkdir\fP if a directory does not exist: +.sp +.RS +.nf + +\fBtest ! -d tempdir && mkdir tempdir +\fP +.fi +.RE +.LP +.IP " 3." 4 +Wait for a file to become non-readable: +.sp +.RS +.nf + +\fBwhile test -r thefile +do + sleep 30 +done +echo '"thefile" is no longer readable' +\fP +.fi +.RE +.LP +.IP " 4." 4 +Perform a command if the argument is one of three strings (two variations): +.sp +.RS +.nf + +\fBif [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ] +then + \fP \fIcommand\fP\fB +fi +.sp + +case "$1" in + pear|grape|apple)\fP \fIcommand\fP \fB;; +esac +\fP +.fi +.RE +.LP +.SH RATIONALE +.LP +The KornShell-derived conditional command (double bracket \fB[[]]\fP) +was removed from the shell command language description +in an early proposal. Objections were raised that the real problem +is misuse of the \fItest\fP command ( \fB[\fP), and putting it +into the shell is the wrong way to fix the problem. Instead, proper +documentation and a new shell reserved word ( \fB!\fP) are +sufficient. +.LP +Tests that require multiple \fItest\fP operations can be done at the +shell level using individual invocations of the +\fItest\fP command and shell logicals, rather than using the error-prone +\fB-o\fP flag of \fItest\fP. +.LP +XSI-conformant systems support more than four arguments. +.LP +XSI-conformant systems support the combining of primaries with the +following constructs: +.TP 7 +\fIexpression1\fP \fB-a\fP \fIexpression2\fP +.sp +True if both \fIexpression1\fP and \fIexpression2\fP are true. +.TP 7 +\fIexpression1\fP \fB-o\fP \fIexpression2\fP +.sp +True if at least one of \fIexpression1\fP and \fIexpression2\fP are +true. +.TP 7 +\fB(\fP \fIexpression\fP \fB)\fP +.sp +True if \fIexpression\fP is true. +.sp +.LP +In evaluating these more complex combined expressions, the following +precedence rules are used: +.IP " *" 3 +The unary primaries have higher precedence than the algebraic binary +primaries. +.LP +.IP " *" 3 +The unary primaries have lower precedence than the string binary primaries. +.LP +.IP " *" 3 +The unary and binary primaries have higher precedence than the unary +\fIstring\fP primary. +.LP +.IP " *" 3 +The \fB!\fP operator has higher precedence than the \fB-a\fP operator, +and the \fB-a\fP operator has higher precedence than +the \fB-o\fP operator. +.LP +.IP " *" 3 +The \fB-a\fP and \fB-o\fP operators are left associative. +.LP +.IP " *" 3 +The parentheses can be used to alter the normal precedence and associativity. +.LP +.LP +The BSD and System V versions of \fB-f\fP are not the same. The BSD +definition was: +.TP 7 +\fB-f\ \fP \fIfile\fP +True if \fIfile\fP exists and is not a directory. +.sp +.LP +The SVID version (true if the file exists and is a regular file) was +chosen for this volume of IEEE\ Std\ 1003.1-2001 +because its use is consistent with the \fB-b\fP, \fB-c\fP, \fB-d\fP, +and \fB-p\fP operands ( \fIfile\fP exists and is a +specific file type). +.LP +The \fB-e\fP primary, possessing similar functionality to that provided +by the C shell, was added because it provides the only +way for a shell script to find out if a file exists without trying +to open the file. Since implementations are allowed to add +additional file types, a portable script cannot use: +.sp +.RS +.nf + +\fBtest -b foo -o -c foo -o -d foo -o -f foo -o -p foo +\fP +.fi +.RE +.LP +to find out if \fBfoo\fP is an existing file. On historical BSD systems, +the existence of a file could be determined by: +.sp +.RS +.nf + +\fBtest -f foo -o -d foo +\fP +.fi +.RE +.LP +but there was no easy way to determine that an existing file was a +regular file. An early proposal used the KornShell \fB-a\fP +primary (with the same meaning), but this was changed to \fB-e\fP +because there were concerns about the high probability of humans +confusing the \fB-a\fP primary with the \fB-a\fP binary operator. +.LP +The following options were not included in this volume of IEEE\ Std\ 1003.1-2001, +although they are provided by some +implementations. These operands should not be used by new implementations +for other purposes: +.TP 7 +\fB-k\ \fP \fIfile\fP +True if \fIfile\fP exists and its sticky bit is set. +.TP 7 +\fB-C\ \fP \fIfile\fP +True if \fIfile\fP is a contiguous file. +.TP 7 +\fB-V\ \fP \fIfile\fP +True if \fIfile\fP is a version file. +.sp +.LP +The following option was not included because it was undocumented +in most implementations, has been removed from some +implementations (including System V), and the functionality is provided +by the shell (see \fIParameter Expansion\fP . +.TP 7 +\fB-l\ \fP \fIstring\fP +The length of the string \fIstring\fP. +.sp +.LP +The \fB-b\fP, \fB-c\fP, \fB-g\fP, \fB-p\fP, \fB-u\fP, and \fB-x\fP +operands are derived from the SVID; historical BSD does +not provide them. The \fB-k\fP operand is derived from System V; historical +BSD does not provide it. +.LP +On historical BSD systems, \fItest\fP \fB-w\fP \fIdirectory\fP always +returned false because \fItest\fP tried to open the +directory for writing, which always fails. +.LP +Some additional primaries newly invented or from the KornShell appeared +in an early proposal as part of the conditional command +( \fB[[]]\fP): \fIs1\fP \fB>\fP \fIs2\fP, \fIs1\fP \fB<\fP \fIs2\fP, +\fIstr\fP \fB=\fP \fIpattern\fP, \fIstr\fP +\fB!=\fP \fIpattern\fP, \fIf1\fP \fB-nt\fP \fIf2\fP, \fIf1\fP \fB-ot\fP +\fIf2\fP, and \fIf1\fP \fB-ef\fP \fIf2\fP. They +were not carried forward into the \fItest\fP utility when the conditional +command was removed from the shell because they have not +been included in the \fItest\fP utility built into historical implementations +of the \fIsh\fP +utility. +.LP +The \fB-t\fP \fIfile_descriptor\fP primary is shown with a mandatory +argument because the grammar is ambiguous if it can be +omitted. Historical implementations have allowed it to be omitted, +providing a default of 1. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIFile Read, Write, and Creation\fP, \fIfind\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |