xref: /freebsd/bin/test/test.1 (revision 6990ffd8a95caaba6858ad44ff1b3157d1efba8f)
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
47.Ar expression
48.Nm \&[
49.Ar expression Cm ]
50.Sh DESCRIPTION
51The
52.Nm
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
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.
98Do not rely on its existence; use
99.Fl L
100instead.
101.It Fl k Ar file
102True if
103.Ar file
104exists and its sticky bit is set.
105.It Fl n Ar string
106True if the length of
107.Ar string
108is nonzero.
109.It Fl p Ar file
110True if
111.Ar file
112is a named pipe
113.Pq Tn FIFO .
114.It Fl r Ar file
115True if
116.Ar file
117exists and is readable.
118.It Fl s Ar file
119True if
120.Ar file
121exists and has a size greater
122than zero.
123.It Fl t Ar file_descriptor
124True if the file whose file descriptor number
125is
126.Ar file_descriptor
127is open and is associated with a terminal.
128.It Fl u Ar file
129True if
130.Ar file
131exists and its set user ID flag
132is set.
133.It Fl w Ar file
134True if
135.Ar file
136exists and is writable.
137True
138indicates only that the write flag is on.
139The file is not writable on a read-only file
140system even if this test indicates true.
141.It Fl x Ar file
142True if
143.Ar file
144exists and is executable.
145True
146indicates only that the execute flag is on.
147If
148.Ar file
149is a directory, true indicates that
150.Ar file
151can be searched.
152.It Fl z Ar string
153True if the length of
154.Ar string
155is zero.
156.It Fl L Ar file
157True if
158.Ar file
159exists and is a symbolic link.
160.It Fl O Ar file
161True if
162.Ar file
163exists and its owner matches the effective user id of this process.
164.It Fl G Ar file
165True if
166.Ar file
167exists and its group matches the effective group id of this process.
168.It Fl S Ar file
169True if
170.Ar file
171exists and is a socket.
172.It Ar file1 Fl nt Ar file2
173True if
174.Ar file1
175exists and is newer than
176.Ar file2 .
177.It Ar file1 Fl ot Ar file2
178True if
179.Ar file1
180exists and is older than
181.Ar file2 .
182.It Ar file1 Fl ef Ar file2
183True if
184.Ar file1
185and
186.Ar file2
187exist and refer to the same file.
188.It Ar string
189True if
190.Ar string
191is not the null
192string.
193.It Ar \&s\&1 Cm \&= Ar \&s\&2
194True if the strings
195.Ar \&s\&1
196and
197.Ar \&s\&2
198are identical.
199.It Ar \&s\&1 Cm \&!= Ar \&s\&2
200True if the strings
201.Ar \&s\&1
202and
203.Ar \&s\&2
204are not identical.
205.It Ar \&s\&1 Cm \&< Ar \&s\&2
206True if string
207.Ar \&s\&1
208comes before
209.Ar \&s\&2
210based on the ASCII value of their characters.
211.It Ar \&s\&1 Cm \&> Ar \&s\&2
212True if string
213.Ar \&s\&1
214comes after
215.Ar \&s\&2
216based on the ASCII value of their characters.
217.It Ar \&s\&1
218True if
219.Ar \&s\&1
220is not the null
221string.
222.It Ar \&n\&1 Fl \&eq Ar \&n\&2
223True if the integers
224.Ar \&n\&1
225and
226.Ar \&n\&2
227are algebraically
228equal.
229.It Ar \&n\&1 Fl \&ne Ar \&n\&2
230True if the integers
231.Ar \&n\&1
232and
233.Ar \&n\&2
234are not
235algebraically equal.
236.It Ar \&n\&1 Fl \&gt Ar \&n\&2
237True if the integer
238.Ar \&n\&1
239is algebraically
240greater than the integer
241.Ar \&n\&2 .
242.It Ar \&n\&1 Fl \&ge Ar \&n\&2
243True if the integer
244.Ar \&n\&1
245is algebraically
246greater than or equal to the integer
247.Ar \&n\&2 .
248.It Ar \&n\&1 Fl \&lt Ar \&n\&2
249True if the integer
250.Ar \&n\&1
251is algebraically less
252than the integer
253.Ar \&n\&2 .
254.It Ar \&n\&1 Fl \&le Ar \&n\&2
255True if the integer
256.Ar \&n\&1
257is algebraically less
258than or equal to the integer
259.Ar \&n\&2 .
260.El
261.Pp
262These primaries can be combined with the following operators:
263.Bl -tag -width Ar
264.It Cm \&! Ar expression
265True if
266.Ar expression
267is false.
268.It Ar expression1 Fl a Ar expression2
269True if both
270.Ar expression1
271and
272.Ar expression2
273are true.
274.It Ar expression1 Fl o Ar expression2
275True if either
276.Ar expression1
277or
278.Ar expression2
279are true.
280.It Cm \&( Ns Ar expression Ns Cm \&)
281True if expression is true.
282.El
283.Pp
284The
285.Fl a
286operator has higher precedence than the
287.Fl o
288operator.
289.Sh GRAMMAR AMBIGUITY
290The
291.Nm
292grammar is inherently ambiguous.  In order to assure a degree of consistency,
293the cases described in the
294.St -p1003.2 ,
295section D11.2/4.62.4, standard
296are evaluated consistently according to the rules specified in the
297standards document.  All other cases are subject to the ambiguity in the
298command semantics.
299.Sh RETURN VALUES
300The
301.Nm
302utility exits with one of the following values:
303.Bl -tag -width Ds
304.It 0
305expression evaluated to true.
306.It 1
307expression evaluated to false or expression was
308missing.
309.It >1
310An error occurred.
311.El
312.Sh SEE ALSO
313.Xr expr 1 ,
314.Xr sh 1
315.Sh STANDARDS
316The
317.Nm
318utility implements a superset of the
319.St -p1003.2
320specification.
321