xref: /freebsd/bin/test/test.1 (revision 7f3dea244c40159a41ab22da77a434d7c5b5e85a)
1.\" Copyright (c) 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the Institute of Electrical and Electronics Engineers, Inc.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\"    must display the following acknowledgement:
17.\"	This product includes software developed by the University of
18.\"	California, Berkeley and its contributors.
19.\" 4. Neither the name of the University nor the names of its contributors
20.\"    may be used to endorse or promote products derived from this software
21.\"    without specific prior written permission.
22.\"
23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33.\" SUCH DAMAGE.
34.\"
35.\"     @(#)test.1	8.1 (Berkeley) 5/31/93
36.\" $FreeBSD$
37.\"
38.Dd May 31, 1993
39.Dt TEST 1
40.Os
41.Sh NAME
42.Nm test ,
43.Nm \&[
44.Nd condition evaluation utility
45.Sh SYNOPSIS
46.Nm test
47.Ar expression
48.Nm [
49.Ar expression Cm ]
50.Sh DESCRIPTION
51The
52.Nm test
53utility evaluates the expression and, if it evaluates
54to true, returns a zero (true) exit status; otherwise
55it returns 1 (false).
56If there is no expression, test also
57returns 1 (false).
58.Pp
59All operators and flags are separate arguments to the
60.Nm test
61utility.
62.Pp
63The following primaries are used to construct expression:
64.Bl -tag -width Ar
65.It Fl b Ar file
66True if
67.Ar file
68exists and is a block special
69file.
70.It Fl c Ar file
71True if
72.Ar file
73exists and is a character
74special file.
75.It Fl d Ar file
76True if
77.Ar file
78exists and is a directory.
79.It Fl e Ar file
80True if
81.Ar file
82exists (regardless of type).
83.It Fl f Ar file
84True if
85.Ar file
86exists and is a regular file.
87.It Fl g Ar file
88True if
89.Ar file
90exists and its set group ID flag
91is set.
92.It Fl h Ar file
93True if
94.Ar file
95exists and is a symbolic link.
96This operator is retained for compatibility with previous versions of
97this program. Do 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.Po Tn FIFO Pc .
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 Op 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
173.Ar file1
174exists and is newer than
175.Ar file2 .
176.It Ar file1 Fl ot Ar file2
177True if
178.Ar file1
179exists and is older than
180.Ar file2 .
181.It Ar file1 Fl ef Ar file2
182True if
183.Ar file1
184and
185.Ar file2
186exist and refer to the same file.
187.It Ar string
188True if
189.Ar string
190is not the null
191string.
192.It Ar \&s\&1 Cm \&= Ar \&s\&2
193True if the strings
194.Ar \&s\&1
195and
196.Ar \&s\&2
197are identical.
198.It Ar \&s\&1 Cm \&!= Ar \&s\&2
199True if the strings
200.Ar \&s\&1
201and
202.Ar \&s\&2
203are not identical.
204.It Ar \&s\&1 Cm \&< Ar \&s\&2
205True if string
206.Ar \&s\&1
207comes before
208.Ar \&s\&2
209based on the ASCII value of their characters.
210.It Ar \&s\&1 Cm \&> Ar \&s\&2
211True if string
212.Ar \&s\&1
213comes after
214.Ar \&s\&2
215based on the ASCII value of their characters.
216.It Ar \&s\&1
217True if
218.Ar \&s\&1
219is not the null
220string.
221.It Ar \&n\&1 Fl \&eq Ar \&n\&2
222True if the integers
223.Ar \&n\&1
224and
225.Ar \&n\&2
226are algebraically
227equal.
228.It Ar \&n\&1 Fl \&ne Ar \&n\&2
229True if the integers
230.Ar \&n\&1
231and
232.Ar \&n\&2
233are not
234algebraically equal.
235.It Ar \&n\&1 Fl \&gt Ar \&n\&2
236True if the integer
237.Ar \&n\&1
238is algebraically
239greater than the integer
240.Ar \&n\&2 .
241.It Ar \&n\&1 Fl \&ge Ar \&n\&2
242True if the integer
243.Ar \&n\&1
244is algebraically
245greater than or equal to the integer
246.Ar \&n\&2 .
247.It Ar \&n\&1 Fl \&lt Ar \&n\&2
248True if the integer
249.Ar \&n\&1
250is algebraically less
251than the integer
252.Ar \&n\&2 .
253.It Ar \&n\&1 Fl \&le Ar \&n\&2
254True if the integer
255.Ar \&n\&1
256is algebraically less
257than or equal to the integer
258.Ar \&n\&2 .
259.El
260.Pp
261These primaries can be combined with the following operators:
262.Bl -tag -width Ar
263.It Cm \&! Ar expression
264True if
265.Ar expression
266is false.
267.It Ar expression1 Fl a Ar expression2
268True if both
269.Ar expression1
270and
271.Ar expression2
272are true.
273.It Ar expression1 Fl o Ar expression2
274True if either
275.Ar expression1
276or
277.Ar expression2
278are true.
279.It Cm \&( Ns Ar expression Ns Cm \&)
280True if expression is true.
281.El
282.Pp
283The
284.Fl a
285operator has higher precedence than the
286.Fl o
287operator.
288.Sh GRAMMAR AMBIGUITY
289The
290.Nm test
291grammar is inherently ambiguous.  In order to assure a degree of consistency,
292the cases described in the
293.St -p1003.2 ,
294section D11.2/4.62.4, standard
295are evaluated consistently according to the rules specified in the
296standards document.  All other cases are subject to the ambiguity in the
297command semantics.
298.Sh RETURN VALUES
299The
300.Nm test
301utility exits with one of the following values:
302.Bl -tag -width Ds
303.It 0
304expression evaluated to true.
305.It 1
306expression evaluated to false or expression was
307missing.
308.It >1
309An error occurred.
310.El
311.Sh SEE ALSO
312.Xr expr 1 ,
313.Xr sh 1
314.Sh STANDARDS
315The
316.Nm test
317utility implements a superset of the
318.St -p1003.2
319specification.
320