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