xref: /freebsd/bin/test/test.1 (revision ddd5b8e9b4d8957fce018c520657cdfa4ecffad3)
1.\"-
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.\" 4. Neither the name of the University nor the names of its contributors
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
33.\" $FreeBSD$
34.\"
35.Dd December 27, 2012
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 \&[
46.Ar expression Cm \&]
47.Sh DESCRIPTION
48The
49.Nm
50utility evaluates the expression and, if it evaluates
51to true, returns a zero (true) exit status; otherwise
52it returns 1 (false).
53If there is no expression,
54.Nm
55also
56returns 1 (false).
57.Pp
58All operators and flags are separate arguments to the
59.Nm
60utility.
61.Pp
62The following primaries are used to construct expression:
63.Bl -tag -width Ar
64.It Fl b Ar file
65True if
66.Ar file
67exists and is a block special
68file.
69.It Fl c Ar file
70True if
71.Ar file
72exists and is a character
73special file.
74.It Fl d Ar file
75True if
76.Ar file
77exists and is a directory.
78.It Fl e Ar file
79True if
80.Ar file
81exists (regardless of type).
82.It Fl f Ar file
83True if
84.Ar file
85exists and is a regular file.
86.It Fl g Ar file
87True if
88.Ar file
89exists and its set group ID flag
90is set.
91.It Fl h Ar file
92True if
93.Ar file
94exists and is a symbolic link.
95This operator is retained for compatibility with previous versions of
96this program.
97Do not rely on its existence; use
98.Fl L
99instead.
100.It Fl k Ar file
101True if
102.Ar file
103exists and its sticky bit is set.
104.It Fl n Ar string
105True if the length of
106.Ar string
107is nonzero.
108.It Fl p Ar file
109True if
110.Ar file
111is a named pipe
112.Pq Tn FIFO .
113.It Fl r Ar file
114True if
115.Ar file
116exists and is readable.
117.It Fl s Ar file
118True if
119.Ar file
120exists and has a size greater
121than zero.
122.It Fl t Ar file_descriptor
123True if the file whose file descriptor number
124is
125.Ar file_descriptor
126is open and is associated with a terminal.
127.It Fl u Ar file
128True if
129.Ar file
130exists and its set user ID flag
131is set.
132.It Fl w Ar file
133True if
134.Ar file
135exists and is writable.
136True
137indicates only that the write flag is on.
138The file is not writable on a read-only file
139system even if this test indicates true.
140.It Fl x Ar file
141True if
142.Ar file
143exists and is executable.
144True
145indicates only that the execute flag is on.
146If
147.Ar file
148is a directory, true indicates that
149.Ar file
150can be searched.
151.It Fl z Ar string
152True if the length of
153.Ar string
154is zero.
155.It Fl L Ar file
156True if
157.Ar file
158exists and is a symbolic link.
159.It Fl O Ar file
160True if
161.Ar file
162exists and its owner matches the effective user id of this process.
163.It Fl G Ar file
164True if
165.Ar file
166exists and its group matches the effective group id of this process.
167.It Fl S Ar file
168True if
169.Ar file
170exists and is a socket.
171.It Ar file1 Fl nt Ar file2
172True if both
173.Ar file1
174and
175.Ar file2
176exist and
177.Ar file1
178is newer than
179.Ar file2 .
180.It Ar file1 Fl nt Ns Ar X Ns Ar Y Ar file2
181True if both
182.Ar file1
183and
184.Ar file2
185exist and
186.Ar file1
187has a more recent last access time
188.Pq Ar X Ns = Ns Cm a ,
189inode creation time
190.Pq Ar X Ns = Ns Cm b ,
191change time
192.Pq Ar X Ns = Ns Cm c ,
193or modification time
194.Pq Ar X Ns = Ns Cm m
195than the last access time
196.Pq Ar Y Ns = Ns Cm a ,
197inode creation time
198.Pq Ar Y Ns = Ns Cm b ,
199change time
200.Pq Ar Y Ns = Ns Cm c ,
201or modification time
202.Pq Ar Y Ns = Ns Cm m
203of
204.Ar file2 .
205Note that
206.Ic -ntmm
207is equivalent to
208.Ic -nt .
209.It Ar file1 Fl ot Ar file2
210True if both
211.Ar file1
212and
213.Ar file2
214exist and
215.Ar file1
216is older than
217.Ar file2 .
218Note that
219.Ar file1
220.Ic -ot
221.Ar file2
222is equivalent to
223.Ar file2
224.Ic -nt
225.Ar file1
226.It Ar file1 Fl ot Ns Ar X Ns Ar Y Ar file2
227Equivalent to
228.Ar file2
229.Ic -nt Ns Ar Y Ns Ar X
230.Ar file1 .
231.It Ar file1 Fl ef Ar file2
232True if
233.Ar file1
234and
235.Ar file2
236exist and refer to the same file.
237.It Ar string
238True if
239.Ar string
240is not the null
241string.
242.It Ar s1 Cm = Ar s2
243True if the strings
244.Ar s1
245and
246.Ar s2
247are identical.
248.It Ar s1 Cm != Ar s2
249True if the strings
250.Ar s1
251and
252.Ar s2
253are not identical.
254.It Ar s1 Cm < Ar s2
255True if string
256.Ar s1
257comes before
258.Ar s2
259based on the binary value of their characters.
260.It Ar s1 Cm > Ar s2
261True if string
262.Ar s1
263comes after
264.Ar s2
265based on the binary value of their characters.
266.It Ar n1 Fl eq Ar n2
267True if the integers
268.Ar n1
269and
270.Ar n2
271are algebraically
272equal.
273.It Ar n1 Fl ne Ar n2
274True if the integers
275.Ar n1
276and
277.Ar n2
278are not
279algebraically equal.
280.It Ar n1 Fl gt Ar n2
281True if the integer
282.Ar n1
283is algebraically
284greater than the integer
285.Ar n2 .
286.It Ar n1 Fl ge Ar n2
287True if the integer
288.Ar n1
289is algebraically
290greater than or equal to the integer
291.Ar n2 .
292.It Ar n1 Fl lt Ar n2
293True if the integer
294.Ar n1
295is algebraically less
296than the integer
297.Ar n2 .
298.It Ar n1 Fl le Ar n2
299True if the integer
300.Ar n1
301is algebraically less
302than or equal to the integer
303.Ar n2 .
304.El
305.Pp
306If
307.Ar file
308is a symbolic link,
309.Nm
310will fully dereference it and then evaluate the expression
311against the file referenced, except for the
312.Fl h
313and
314.Fl L
315primaries.
316.Pp
317These primaries can be combined with the following operators:
318.Bl -tag -width Ar
319.It Cm \&! Ar expression
320True if
321.Ar expression
322is false.
323.It Ar expression1 Fl a Ar expression2
324True if both
325.Ar expression1
326and
327.Ar expression2
328are true.
329.It Ar expression1 Fl o Ar expression2
330True if either
331.Ar expression1
332or
333.Ar expression2
334are true.
335.It Cm \&( Ar expression Cm \&)
336True if expression is true.
337.El
338.Pp
339The
340.Fl a
341operator has higher precedence than the
342.Fl o
343operator.
344.Pp
345Some shells may provide a builtin
346.Nm
347command which is similar or identical to this utility.
348Consult the
349.Xr builtin 1
350manual page.
351.Sh GRAMMAR AMBIGUITY
352The
353.Nm
354grammar is inherently ambiguous.
355In order to assure a degree of consistency,
356the cases described in the
357.St -p1003.2 ,
358section D11.2/4.62.4, standard
359are evaluated consistently according to the rules specified in the
360standards document.
361All other cases are subject to the ambiguity in the
362command semantics.
363.Pp
364In particular, only expressions containing
365.Fl a ,
366.Fl o ,
367.Cm \&(
368or
369.Cm \&)
370can be ambiguous.
371.Sh EXIT STATUS
372The
373.Nm
374utility exits with one of the following values:
375.Bl -tag -width indent
376.It 0
377expression evaluated to true.
378.It 1
379expression evaluated to false or expression was
380missing.
381.It >1
382An error occurred.
383.El
384.Sh COMPATIBILITY
385For compatibility with some other implementations,
386the
387.Cm =
388primary can be substituted with
389.Cm ==
390with the same meaning.
391.Sh SEE ALSO
392.Xr builtin 1 ,
393.Xr expr 1 ,
394.Xr sh 1 ,
395.Xr symlink 7
396.Sh STANDARDS
397The
398.Nm
399utility implements a superset of the
400.St -p1003.2
401specification.
402.Sh BUGS
403Both sides are always evaluated in
404.Fl a
405and
406.Fl o .
407For instance, the writable status of
408.Pa file
409will be tested by the following command even though the former expression
410indicated false, which results in a gratuitous access to the file system:
411.Dl "[ -z abc -a -w file ]"
412To avoid this, write
413.Dl "[ -z abc ] && [ -w file ]"
414