bin/test: Sync with FreeBSD
[dragonfly.git] / bin / test / test.1
CommitLineData
b3967821 1.\"-
984263bc
MD
2.\" Copyright (c) 1991, 1993
3.\" The Regents of the University of California. All rights reserved.
4.\"
5.\" This code is derived from software contributed to Berkeley by
6.\" the Institute of Electrical and Electronics Engineers, Inc.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\" 3. All advertising materials mentioning features or use of this software
17.\" must display the following acknowledgement:
18.\" This product includes software developed by the University of
19.\" California, Berkeley and its contributors.
20.\" 4. Neither the name of the University nor the names of its contributors
21.\" may be used to endorse or promote products derived from this software
22.\" without specific prior written permission.
23.\"
24.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34.\" SUCH DAMAGE.
35.\"
36.\" @(#)test.1 8.1 (Berkeley) 5/31/93
b3967821 37.\" $FreeBSD: src/bin/test/test.1,v 1.31 2010/09/11 10:49:56 brucec Exp $
984263bc 38.\"
b3967821 39.Dd September 10, 2010
984263bc
MD
40.Dt TEST 1
41.Os
42.Sh NAME
43.Nm test ,
44.Nm \&[
45.Nd condition evaluation utility
46.Sh SYNOPSIS
47.Nm
48.Ar expression
49.Nm \&[
50.Ar expression Cm ]
1bf4b486 51.Sh DESCRIPTION
984263bc
MD
52The
53.Nm
54utility evaluates the expression and, if it evaluates
55to true, returns a zero (true) exit status; otherwise
56it returns 1 (false).
b7367ef6
SW
57If there is no expression,
58.Nm
59also returns 1 (false).
984263bc
MD
60.Pp
61All operators and flags are separate arguments to the
62.Nm
63utility.
64.Pp
65The following primaries are used to construct expression:
66.Bl -tag -width Ar
67.It Fl b Ar file
68True if
69.Ar file
70exists and is a block special
71file.
72.It Fl c Ar file
73True if
74.Ar file
75exists and is a character
76special file.
77.It Fl d Ar file
78True if
79.Ar file
80exists and is a directory.
81.It Fl e Ar file
82True if
83.Ar file
84exists (regardless of type).
85.It Fl f Ar file
86True if
87.Ar file
88exists and is a regular file.
89.It Fl g Ar file
90True if
91.Ar file
92exists and its set group ID flag
93is set.
94.It Fl h Ar file
95True if
96.Ar file
97exists and is a symbolic link.
98This operator is retained for compatibility with previous versions of
99this program.
100Do not rely on its existence; use
101.Fl L
102instead.
103.It Fl k Ar file
104True if
105.Ar file
106exists and its sticky bit is set.
107.It Fl n Ar string
108True if the length of
109.Ar string
110is nonzero.
111.It Fl p Ar file
112True if
113.Ar file
114is a named pipe
115.Pq Tn FIFO .
116.It Fl r Ar file
117True if
118.Ar file
119exists and is readable.
120.It Fl s Ar file
121True if
122.Ar file
123exists and has a size greater
124than zero.
125.It Fl t Ar file_descriptor
126True if the file whose file descriptor number
127is
128.Ar file_descriptor
129is open and is associated with a terminal.
130.It Fl u Ar file
131True if
132.Ar file
133exists and its set user ID flag
134is set.
135.It Fl w Ar file
136True if
137.Ar file
138exists and is writable.
139True
6ab72760
CP
140indicates both that the write flag is on and that
141.Ar file
142resides on a read-write file system.
143.Pp
144Note that this behaviour is specific to
145.Dx .
146When writing portable scripts, keep in mind that
147on some systems, this test may
148indicate only that the write flag is on.
984263bc
MD
149.It Fl x Ar file
150True if
151.Ar file
152exists and is executable.
153True
154indicates only that the execute flag is on.
155If
156.Ar file
157is a directory, true indicates that
158.Ar file
159can be searched.
160.It Fl z Ar string
161True if the length of
162.Ar string
163is zero.
164.It Fl L Ar file
165True if
166.Ar file
167exists and is a symbolic link.
168.It Fl O Ar file
169True if
170.Ar file
171exists and its owner matches the effective user id of this process.
172.It Fl G Ar file
173True if
174.Ar file
175exists and its group matches the effective group id of this process.
176.It Fl S Ar file
177True if
178.Ar file
179exists and is a socket.
180.It Ar file1 Fl nt Ar file2
181True if
182.Ar file1
183exists and is newer than
184.Ar file2 .
185.It Ar file1 Fl ot Ar file2
186True if
187.Ar file1
188exists and is older than
189.Ar file2 .
190.It Ar file1 Fl ef Ar file2
191True if
192.Ar file1
193and
194.Ar file2
195exist and refer to the same file.
196.It Ar string
197True if
198.Ar string
199is not the null
200string.
b3967821 201.It Ar s1 Cm = Ar s2
984263bc 202True if the strings
b3967821 203.Ar s1
984263bc 204and
b3967821 205.Ar s2
984263bc 206are identical.
b3967821 207.It Ar s1 Cm != Ar s2
984263bc 208True if the strings
b3967821 209.Ar s1
984263bc 210and
b3967821 211.Ar s2
984263bc 212are not identical.
b3967821 213.It Ar s1 Cm < Ar s2
984263bc 214True if string
b3967821 215.Ar s1
984263bc 216comes before
b3967821
PA
217.Ar s2
218based on the binary value of their characters.
219.It Ar s1 Cm > Ar s2
984263bc 220True if string
b3967821 221.Ar s1
984263bc 222comes after
b3967821
PA
223.Ar s2
224based on the binary value of their characters.
225.It Ar n1 Fl eq Ar n2
984263bc 226True if the integers
b3967821 227.Ar n1
984263bc 228and
b3967821 229.Ar n2
984263bc
MD
230are algebraically
231equal.
b3967821 232.It Ar n1 Fl ne Ar n2
984263bc 233True if the integers
b3967821 234.Ar n1
984263bc 235and
b3967821 236.Ar n2
984263bc
MD
237are not
238algebraically equal.
b3967821 239.It Ar n1 Fl gt Ar n2
984263bc 240True if the integer
b3967821 241.Ar n1
984263bc
MD
242is algebraically
243greater than the integer
b3967821
PA
244.Ar n2 .
245.It Ar n1 Fl ge Ar n2
984263bc 246True if the integer
b3967821 247.Ar n1
984263bc
MD
248is algebraically
249greater than or equal to the integer
b3967821
PA
250.Ar n2 .
251.It Ar n1 Fl lt Ar n2
984263bc 252True if the integer
b3967821 253.Ar n1
984263bc
MD
254is algebraically less
255than the integer
b3967821
PA
256.Ar n2 .
257.It Ar n1 Fl le Ar n2
984263bc 258True if the integer
b3967821 259.Ar n1
984263bc
MD
260is algebraically less
261than or equal to the integer
b3967821 262.Ar n2 .
984263bc
MD
263.El
264.Pp
b3967821
PA
265If
266.Ar file
267is a symbolic link,
268.Nm
269will fully dereference it and then evaluate the expression
270against the file referenced, except for the
271.Fl h
272and
273.Fl L
274primaries.
275.Pp
984263bc
MD
276These primaries can be combined with the following operators:
277.Bl -tag -width Ar
278.It Cm \&! Ar expression
279True if
280.Ar expression
281is false.
282.It Ar expression1 Fl a Ar expression2
283True if both
284.Ar expression1
285and
286.Ar expression2
287are true.
288.It Ar expression1 Fl o Ar expression2
289True if either
290.Ar expression1
291or
292.Ar expression2
293are true.
b3967821 294.It Cm \&( Ar expression Cm \&)
984263bc
MD
295True if expression is true.
296.El
297.Pp
298The
299.Fl a
300operator has higher precedence than the
301.Fl o
302operator.
303.Pp
304Some shells may provide a builtin
305.Nm
306command which is similar or identical to this utility.
307Consult the
308.Xr builtin 1
309manual page.
310.Sh GRAMMAR AMBIGUITY
311The
312.Nm
b3967821
PA
313grammar is inherently ambiguous.
314In order to assure a degree of consistency,
984263bc
MD
315the cases described in the
316.St -p1003.2 ,
317section D11.2/4.62.4, standard
318are evaluated consistently according to the rules specified in the
b3967821
PA
319standards document.
320All other cases are subject to the ambiguity in the
984263bc 321command semantics.
b3967821
PA
322.Pp
323In particular, only expressions containing
324.Fl a ,
325.Fl o ,
326.Cm \&(
327or
328.Cm \&)
329can be ambiguous.
330.Sh EXIT STATUS
984263bc
MD
331The
332.Nm
333utility exits with one of the following values:
b3967821 334.Bl -tag -width indent
984263bc
MD
335.It 0
336expression evaluated to true.
337.It 1
338expression evaluated to false or expression was
339missing.
340.It >1
341An error occurred.
342.El
343.Sh SEE ALSO
344.Xr builtin 1 ,
345.Xr expr 1 ,
b3967821
PA
346.Xr sh 1 ,
347.Xr symlink 7
984263bc
MD
348.Sh STANDARDS
349The
350.Nm
351utility implements a superset of the
352.St -p1003.2
353specification.
b3967821
PA
354.Sh BUGS
355Both sides are always evaluated in
356.Fl a
357and
358.Fl o .
359For instance, the writable status of
360.Pa file
361will be tested by the following command even though the former expression
362indicated false, which results in a gratuitous access to the file system:
363.Dl "[ -z abc -a -w file ]"
364To avoid this, write
365.Dl "[ -z abc ] && [ -w file ]"