1TEST(1P)                   POSIX Programmer's Manual                  TEST(1P)
2
3
4

PROLOG

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
11

NAME

13       test — evaluate expression
14

SYNOPSIS

16       test [expression]
17
18       [ [expression] ]
19

DESCRIPTION

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
26       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

OPTIONS

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
35       No options shall be supported.
36

OPERANDS

38       The  application  shall  ensure that all operators and elements of pri‐
39       maries are presented as separate arguments to the test utility.
40
41       The following primaries can be used to construct expression:
42
43       −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
49       −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
55       −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
61       −e pathname
62                 True  if  pathname  resolves  to an existing directory entry.
63                 False if pathname cannot be resolved.
64
65       −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
71       −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
78       −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
85       −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
92       −n string True if the length of string is non-zero; otherwise, false.
93
94       −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
100       −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
108       −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
114       −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
121       −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
128       −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
135       −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
143       −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
152       −z string True  if  the  length  of  string  string is zero; otherwise,
153                 false.
154
155       string    True if the string string is not the null string;  otherwise,
156                 false.
157
158       s1 = s2   True  if  the  strings  s1  and  s2 are identical; otherwise,
159                 false.
160
161       s1 != s2  True if the strings s1 and s2 are not  identical;  otherwise,
162                 false.
163
164       n1 −eq n2 True  if the integers n1 and n2 are algebraically equal; oth‐
165                 erwise, false.
166
167       n1 −ne n2 True if the integers n1 and n2 are not  algebraically  equal;
168                 otherwise, false.
169
170       n1 −gt n2 True  if  the  integer  n1  is algebraically greater than the
171                 integer n2; otherwise, false.
172
173       n1 −ge n2 True if the integer n1 is algebraically greater than or equal
174                 to the integer n2; otherwise, false.
175
176       n1 −lt n2 True if the integer n1 is algebraically less than the integer
177                 n2; otherwise, false.
178
179       n1 −le n2 True if the integer n1 is algebraically less than or equal to
180                 the integer n2; otherwise, false.
181
182       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
187       expression1 −o expression2
188                 True if either expression1 or expression2 is true; otherwise,
189                 false. The −o binary primary is left associative.
190
191       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
196       These primaries can be combined with the following operators:
197
198       ! expression
199                 True if expression is false. False if expression is true.
200
201       ( 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
206       The primaries with two elements of the form:
207
208           primary_operator primary_operand
209
210       are  known  as  unary  primaries.  The primaries with three elements in
211       either of the two forms:
212
213           primary_operandprimary_operator primary_operand
214
215           primary_operand primary_operator primary_operand
216
217       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
222       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
228       In  the following list, $1, $2, $3, and $4 represent the arguments pre‐
229       sented to test:
230
231       0 arguments:
232                   Exit false (1).
233
234       1 argument: Exit true (0) if $1 is not null; otherwise, exit false.
235
236       2 arguments:
237                    *  If $1 is '!', exit true if $2 is null, false if  $2  is
238                       not null.
239
240                    *  If  $1  is a unary primary, exit true if the unary test
241                       is true, false if the unary test is false.
242
243                    *  Otherwise, produce unspecified results.
244
245       3 arguments:
246                    *  If $2 is a binary primary, perform the binary  test  of
247                       $1 and $3.
248
249                    *  If  $1  is  '!', negate the two-argument test of $2 and
250                       $3.
251
252                    *  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
256                    *  Otherwise, produce unspecified results.
257
258       4 arguments:
259                    *  If $1 is '!', negate the three-argument test of $2, $3,
260                       and $4.
261
262                    *  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
267                    *  Otherwise, the results are unspecified.
268
269       >4 arguments:
270                   The results are unspecified.
271
272                   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

STDIN

279       Not used.
280

INPUT FILES

282       None.
283

ENVIRONMENT VARIABLES

285       The following environment variables shall affect the execution of test:
286
287       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
293       LC_ALL    If set to a non-empty string value, override  the  values  of
294                 all the other internationalization variables.
295
296       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
300       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
305       NLSPATH   Determine the location of message catalogs for the processing
306                 of LC_MESSAGES.
307

ASYNCHRONOUS EVENTS

309       Default.
310

STDOUT

312       Not used.
313

STDERR

315       The standard error shall be used only for diagnostic messages.
316

OUTPUT FILES

318       None.
319

EXTENDED DESCRIPTION

321       None.
322

EXIT STATUS

324       The following exit values shall be returned:
325
326        0    expression evaluated to true.
327
328        1    expression evaluated to false or expression was missing.
329
330       >1    An error occurred.
331

CONSEQUENCES OF ERRORS

333       Default.
334
335       The following sections are informative.
336

APPLICATION USAGE

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
349           test "$1" −a "$2"
350
351       should be written as:
352
353           test "$1" && test "$2"
354
355       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
359           test expr1 −a expr2
360
361       with:
362
363           test expr1 && test expr2
364
365       and replace:
366
367           test expr1 −o expr2
368
369       with:
370
371           test expr1 || test expr2
372
373       but note that, in test, −a has higher precedence than −o while "&&" and
374       "||" have equal precedence in the shell.
375
376       Parentheses or braces can be used in  the  shell  command  language  to
377       effect grouping.
378
379       Parentheses must be escaped when using sh; for example:
380
381           test \( expr1 −a expr2 \) −o expr3
382
383       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
387           ( test expr1 && test expr2 ) || test expr3
388
389       The two commands:
390
391           test "$1"
392           test ! "$1"
393
394       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
398           test −n "$1"
399           test −z "$1"
400
401       respectively.
402
403       Historical  systems  have  also  been  unreliable given the common con‐
404       struct:
405
406           test "$response" = "expected string"
407
408       One of the following is a more reliable form:
409
410           test "X$response" = "Xexpected string"
411           test "expected string" = "$response"
412
413       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
420       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
425           test −d $1 −o −d $2
426
427       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
432           test \( −d "$1" \) −o \( −d "$2" \)
433           test −d "$1" || test −d "$2"
434
435       Also in the greater than 4 argument case:
436
437           test "$1" = "bat" −a "$2" = "ball"
438
439       syntax  errors occur if $1 evaluates to '(' or '!'.  One of the follow‐
440       ing forms prevents this; the third is preferred:
441
442           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

EXAMPLES

447        1. Exit if there are not two or three arguments (two variations):
448
449               if [ $# −ne 2 ] && [ $# −ne 3 ]; then exit 1; fi
450               if [ $# −lt 2 ] || [ $# −gt 3 ]; then exit 1; fi
451
452        2. Perform a mkdir if a directory does not exist:
453
454               test ! −d tempdir && mkdir tempdir
455
456        3. Wait for a file to become non-readable:
457
458               while test −r thefile
459               do
460                   sleep 30
461               done
462               echo '"thefile" is no longer readable'
463
464        4. Perform a command if the argument is  one  of  three  strings  (two
465           variations):
466
467               if [ "$1" = "pear" ] || [ "$1" = "grape" ] || [ "$1" = "apple" ]
468               then
469                   command
470               fi
471
472               case "$1" in
473                   pear|grape|apple) command ;;
474               esac
475

RATIONALE

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
484       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
488       XSI-conformant systems support more than four arguments.
489
490       XSI-conformant systems support the combining of primaries with the fol‐
491       lowing constructs:
492
493       expression1 −a expression2
494             True if both expression1 and expression2 are true.
495
496       expression1 −o expression2
497             True if at least one of expression1 and expression2 are true.
498
499       ( expression )
500             True if expression is true.
501
502       In  evaluating  these  more complex combined expressions, the following
503       precedence rules are used:
504
505        *  The unary primaries  have  higher  precedence  than  the  algebraic
506           binary primaries.
507
508        *  The  unary  primaries  have lower precedence than the string binary
509           primaries.
510
511        *  The unary and binary primaries  have  higher  precedence  than  the
512           unary string primary.
513
514        *  The !  operator has higher precedence than the −a operator, and the
515           −a operator has higher precedence than the −o operator.
516
517        *  The −a and −o operators are left associative.
518
519        *  The parentheses can be used to  alter  the  normal  precedence  and
520           associativity.
521
522       The  BSD  and System V versions of −f are not the same. The BSD defini‐
523       tion was:
524
525       −f file   True if file exists and is not a directory.
526
527       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
532       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
538           test −b foo −o −c foo −o −d foo −o −f foo −o −p foo
539
540       to  find out if foo is an existing file. On historical BSD systems, the
541       existence of a file could be determined by:
542
543           test −f foo −o −d foo
544
545       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
551       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
555       −k file   True if file exists and its sticky bit is set.
556
557       −C file   True if file is a contiguous file.
558
559       −V file   True if file is a version file.
560
561       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
566       −l string The length of the string string.
567
568       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
572       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
576       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
584       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
589       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

FUTURE DIRECTIONS

595       None.
596

SEE ALSO

598       Section 1.1.1.4, File Read, Write, and Creation, find
599
600       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
615       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 .
619
620
621
622IEEE/The Open Group                  2013                             TEST(1P)
Impressum