test man page on CentOS

Man page or keyword search:  
man Server   8420 pages
apropos Keyword Search (all sections)
Output format
CentOS logo
[printable version]

TEST(P)			   POSIX Programmer's Manual		       TEST(P)

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.

NAME
       test - evaluate expression

SYNOPSIS
       test [expression]

       [ [expression] ]

DESCRIPTION
       The test utility shall evaluate the expression 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.

       In  the	second	form of the utility, which uses "[]" rather than test,
       the application shall ensure that  the  square  brackets	 are  separate
       arguments.

OPTIONS
       The  test  utility  shall not recognize the "--" 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.

       No options shall be supported.

OPERANDS
       The  application	 shall	ensure that all operators and elements of pri‐
       maries are presented as separate arguments to the test utility.

       The following primaries can be used to construct expression:

       -b  file
	      True if file exists and is a block special file.

       -c  file
	      True if file exists and is a character special file.

       -d  file
	      True if file exists and is a directory.

       -e  file
	      True if file exists.

       -f  file
	      True if file exists and is a regular file.

       -g  file
	      True if file exists and its set-group-ID flag is set.

       -h  file
	      True if file exists and is a symbolic link.

       -L  file
	      True if file exists and is a symbolic link.

       -n  string
	      True if the length of string is non-zero.

       -p  file
	      True if file is a FIFO.

       -r  file
	      True if file exists and is readable. True	 shall	indicate  that
	      permission to read from file will be granted, as defined in File
	      Read, Write, and Creation .

       -S  file
	      True if file exists and is a socket.

       -s  file
	      True if file exists and has a size greater than zero.

       -t  file_descriptor

	      True if the file whose file descriptor number is file_descriptor
	      is open and is associated with a terminal.

       -u  file
	      True if file exists and its set-user-ID flag is set.

       -w  file
	      True  if	file  exists and is writable. True shall indicate that
	      permission to write from file will be  granted,  as  defined  in
	      File Read, Write, and Creation .

       -x  file
	      True  if file exists and is executable. True shall indicate that
	      permission to execute file will be granted, as defined  in  File
	      Read,  Write,  and Creation . If file is a directory, true shall
	      indicate that permission to search file will be granted.

       -z  string
	      True if the length of string string is zero.

       string True if the string string is not the null string.

       s1 =  s2
	      True if the strings s1 and s2 are identical.

       s1 !=  s2
	      True if the strings s1 and s2 are not identical.

       n1 -eq  n2
	      True if the integers n1 and n2 are algebraically equal.

       n1 -ne  n2
	      True if the integers n1 and n2 are not algebraically equal.

       n1 -gt  n2
	      True if the integer n1 is algebraically greater than the integer
	      n2.

       n1 -ge  n2
	      True if the integer n1 is algebraically greater than or equal to
	      the integer n2.

       n1 -lt  n2
	      True if the integer n1 is algebraically less  than  the  integer
	      n2.

       n1 -le  n2
	      True  if	the  integer n1 is algebraically less than or equal to
	      the integer n2.

       expression1 -a  expression2

	      True if both expression1 and expression2 are true. The -a binary
	      primary is left associative. It has a higher precedence than -o.

       expression1 -o  expression2

	      True if either expression1 or expression2 is true. The -o binary
	      primary is left associative.

       With the exception of the -h file and -L	 file  primaries,  if  a  file
       argument	 is  a	symbolic  link,	 test shall evaluate the expression by
       resolving the symbolic link and using the file referenced by the link.

       These primaries can be combined with the following operators:

       !  expression
	      True if expression is false.

       (  expression  )
	      True if expression is true. The parentheses can be used to alter
	      the normal precedence and associativity.

       The primaries with two elements of the form:

	      -primary_operator primary_operand

       are  known  as  unary  primaries.  The primaries with three elements in
       either of the two forms:

	      primary_operand -primary_operator primary_operand

	      primary_operand primary_operator primary_operand

       are known as binary primaries. Additional implementation-defined opera‐
       tors  and  primary_operators  may  be provided by implementations. They
       shall be of the form - operator where the first character  of  operator
       is not a digit.

       The  algorithm  for determining the precedence of the operators and the
       return value that shall be generated is based on the  number  of	 argu‐
       ments  presented	 to  test.  (However, when using the "[...]" form, the
       right-bracket final argument shall not be counted in this algorithm.)

       In the following list, $1, $2, $3, and $4 represent the arguments  pre‐
       sented to test:

       0 arguments:
	      Exit false (1).

       1 argument:
	      Exit true (0) if $1 is not null; otherwise, exit false.

       2 arguments:

	       * If  $1	 is  '!' , exit true if $2 is null, false if $2 is not
		 null.

	       * If $1 is a unary primary, exit true  if  the  unary  test  is
		 true, false if the unary test is false.

	       * Otherwise, produce unspecified results.

       3 arguments:

	       * If  $2 is a binary primary, perform the binary test of $1 and
		 $3.

	       * If $1 is '!' , negate the two-argument test of $2 and $3.

	       * If $1 is '(' and $3 is ')' , perform the unary test of $2.

	       * Otherwise, produce unspecified results.

       4 arguments:

	       * If $1 is '!' , negate the three-argument test of $2, $3,  and
		 $4.

	       * If $1 is '(' and $4 is ')' , perform the two-argument test of
		 $2 and $3.

	       * Otherwise, the results are unspecified.

       >4 arguments:
	      The results are unspecified.

       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  pri‐
       maries  '=' and "!=" shall have a higher precedence than any unary pri‐
       mary.

STDIN
       Not used.

INPUT FILES
       None.

ENVIRONMENT VARIABLES
       The following environment variables shall affect the execution of test:

       LANG   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	 Vari‐
	      ables  for the precedence of internationalization variables used
	      to determine the values of locale categories.)

       LC_ALL If set to a non-empty string value, override the values  of  all
	      the other internationalization variables.

       LC_CTYPE
	      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).

       LC_MESSAGES
	      Determine	 the  locale  that should be used to affect the format
	      and contents of diagnostic messages written to standard error.

       NLSPATH
	      Determine the location of message catalogs for the processing of
	      LC_MESSAGES .

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

STDERR
       The standard error shall be used only for diagnostic messages.

OUTPUT FILES
       None.

EXTENDED DESCRIPTION
       None.

EXIT STATUS
       The following exit values shall be returned:

	0     expression evaluated to true.

	1     expression evaluated to false or expression was missing.

       >1     An error occurred.

CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       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, invoca‐
       tions like:

	      test "$1" -a "$2"

       should be written as:

	      test "$1" && test "$2"

       to avoid problems if a user supplied values such as $1 set to '!'   and
       $2  set to the null string. That is, in cases where maximal portability
       is of concern, replace:

	      test expr1 -a expr2

       with:

	      test expr1 && test expr2

       and replace:

	      test expr1 -o expr2

       with:

	      test expr1 || test expr2

       but note that, in test, -a has higher precedence than -o while "&&" and
       "||" have equal precedence in the shell.

       Parentheses  or	braces	can  be	 used in the shell command language to
       effect grouping.

       Parentheses must be escaped when using sh; for example:

	      test \( expr1 -a expr2 \) -o expr3

       This command is not always  portable  outside  XSI-conformant  systems.
       The following form can be used instead:

	      ( test expr1 && test expr2 ) || test expr3

       The two commands:

	      test "$1"
	      test ! "$1"

       could  not  be  used  reliably  on  some historical systems. Unexpected
       results would occur if such  a  string  expression  were	 used  and  $1
       expanded	 to  '!'  , '(' , or a known unary primary.  Better constructs
       are:

	      test -n "$1"
	      test -z "$1"
       respectively.

       Historical systems have also been  unreliable  given  the  common  con‐
       struct:

	      test "$response" = "expected string"

       One of the following is a more reliable form:

	      test "X$response" = "Xexpected string"
	      test "expected string" = "$response"

       Note  that  the	second	form assumes that expected string could not be
       confused with any unary primary. If expected string starts with	'-'  ,
       '(' , '!' , or even '=' , 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.)

       Because the string comparison binary primaries, '=' and "!=" ,  have  a
       higher precedence than any unary primary in the greater than 4 argument
       case, unexpected results can occur if arguments are not	properly  pre‐
       pared. For example, in:

	      test -d $1 -o -d $2

       If  $1  evaluates to a possible directory name of '=' , the first three
       arguments are considered a string comparison, which shall cause a  syn‐
       tax  error  when	 the  second  -d is encountered.  One of the following
       forms prevents this; the second is preferred:

	      test \( -d "$1" \) -o \( -d "$2" \)
	      test -d "$1" || test -d "$2"

       Also in the greater than 4 argument case:

	      test "$1" = "bat" -a "$2" = "ball"

       syntax errors occur if $1 evaluates to '(' or '!' . One of the  follow‐
       ing forms prevents this; the third is preferred:

	      test "X$1" = "Xbat" -a "X$2" = "Xball"
	      test "$1" = "bat" && test "$2" = "ball"
	      test "X$1" = "Xbat" && test "X$2" = "Xball"

EXAMPLES
	1. Exit if there are not two or three arguments (two variations):

	   if [ $# -ne 2 -a $# -ne 3 ]; then exit 1; fi
	   if [ $# -lt 2 -o $# -gt 3 ]; then exit 1; fi

	2. Perform a mkdir if a directory does not exist:

	   test ! -d tempdir && mkdir tempdir

	3. Wait for a file to become non-readable:

	   while test -r thefile
	   do
	       sleep 30
	   done
	   echo '"thefile" is no longer readable'

	4. Perform  a  command	if  the	 argument is one of three strings (two
	   variations):

	   if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
	   then
	       command
	   fi

	   case "$1" in
	       pear|grape|apple) command ;;
	   esac

RATIONALE
       The KornShell-derived conditional command  (double  bracket  [[]])  was
       removed	from  the  shell command language description in an early pro‐
       posal. Objections were raised that the real problem is  misuse  of  the
       test  command  (	 [), and putting it into the shell is the wrong way to
       fix the problem. Instead, proper documentation and a new shell reserved
       word ( !) are sufficient.

       Tests  that  require  multiple test operations can be done at the shell
       level using individual invocations of the test command and shell	 logi‐
       cals, rather than using the error-prone -o flag of test.

       XSI-conformant systems support more than four arguments.

       XSI-conformant systems support the combining of primaries with the fol‐
       lowing constructs:

       expression1 -a expression2

	      True if both expression1 and expression2 are true.

       expression1 -o expression2

	      True if at least one of expression1 and expression2 are true.

       ( expression )

	      True if expression is true.

       In evaluating these more complex combined  expressions,	the  following
       precedence rules are used:

	* The unary primaries have higher precedence than the algebraic binary
	  primaries.

	* The unary primaries have lower precedence  than  the	string	binary
	  primaries.

	* The unary and binary primaries have higher precedence than the unary
	  string primary.

	* The ! operator has higher precedence than the -a operator,  and  the
	  -a operator has higher precedence than the -o operator.

	* The -a and -o operators are left associative.

	* The parentheses can be used to alter the normal precedence and asso‐
	  ciativity.

       The BSD and System V versions of -f are not the same. The  BSD  defini‐
       tion was:

       -f  file
	      True if file exists and is not a directory.

       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  con‐
       sistent	with  the  -b,	-c, -d, and -p operands ( file exists and is a
       specific file type).

       The -e 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 por‐
       table script cannot use:

	      test -b foo -o -c foo -o -d foo -o -f foo -o -p foo

       to find out if foo is an existing file. On historical BSD systems,  the
       existence of a file could be determined by:

	      test -f foo -o -d foo

       but there was no easy way to determine that an existing file was a reg‐
       ular file. An early proposal used the KornShell -a  primary  (with  the
       same  meaning),	but this was changed to -e because there were concerns
       about the high probability of humans confusing the -a primary with  the
       -a binary operator.

       The   following	 options   were	  not	included  in  this  volume  of
       IEEE Std 1003.1-2001, although they are provided	 by  some  implementa‐
       tions.  These  operands	should	not be used by new implementations for
       other purposes:

       -k  file
	      True if file exists and its sticky bit is set.

       -C  file
	      True if file is a contiguous file.

       -V  file
	      True if file is a version file.

       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 Parameter Expansion .

       -l  string
	      The length of the string string.

       The -b, -c, -g, -p, -u, and -x operands are derived from the SVID; his‐
       torical BSD does not provide them. The -k operand is derived from  Sys‐
       tem V; historical BSD does not provide it.

       On  historical  BSD  systems,  test  -w directory always returned false
       because test tried to open the  directory  for  writing,	 which	always
       fails.

       Some additional primaries newly invented or from the KornShell appeared
       in an early proposal as part of the conditional command ( [[]]):	 s1  >
       s2,  s1	< s2, str = pattern, str != pattern, f1 -nt f2, f1 -ot f2, and
       f1 -ef f2. They were not carried forward into the test utility when the
       conditional  command  was  removed from the shell because they have not
       been included in the test utility built into historical implementations
       of the sh utility.

       The  -t	file_descriptor	 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.

FUTURE DIRECTIONS
       None.

SEE ALSO
       File Read, Write, and Creation , find

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 .

IEEE/The Open Group		     2003			       TEST(P)
[top]

List of man pages available for CentOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net