b743068203c911dece5dc98eed1e021c818d73a5
[dragonfly.git] / bin / test / test.1
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: src/bin/test/test.1,v 1.11.2.5 2001/12/14 14:22:09 ru Exp $
37 .\" $DragonFly: src/bin/test/test.1,v 1.7 2007/10/20 17:56:46 swildner Exp $
38 .\"
39 .Dd May 31, 1993
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 ]
51 .Sh DESCRIPTION
52 The
53 .Nm
54 utility evaluates the expression and, if it evaluates
55 to true, returns a zero (true) exit status; otherwise
56 it returns 1 (false).
57 If there is no expression,
58 .Nm
59 also returns 1 (false).
60 .Pp
61 All operators and flags are separate arguments to the
62 .Nm
63 utility.
64 .Pp
65 The following primaries are used to construct expression:
66 .Bl -tag -width Ar
67 .It Fl b Ar file
68 True if
69 .Ar file
70 exists and is a block special
71 file.
72 .It Fl c Ar file
73 True if
74 .Ar file
75 exists and is a character
76 special file.
77 .It Fl d Ar file
78 True if
79 .Ar file
80 exists and is a directory.
81 .It Fl e Ar file
82 True if
83 .Ar file
84 exists (regardless of type).
85 .It Fl f Ar file
86 True if
87 .Ar file
88 exists and is a regular file.
89 .It Fl g Ar file
90 True if
91 .Ar file
92 exists and its set group ID flag
93 is set.
94 .It Fl h Ar file
95 True if
96 .Ar file
97 exists and is a symbolic link.
98 This operator is retained for compatibility with previous versions of
99 this program.
100 Do not rely on its existence; use
101 .Fl L
102 instead.
103 .It Fl k Ar file
104 True if
105 .Ar file
106 exists and its sticky bit is set.
107 .It Fl n Ar string
108 True if the length of
109 .Ar string
110 is nonzero.
111 .It Fl p Ar file
112 True if
113 .Ar file
114 is a named pipe
115 .Pq Tn FIFO .
116 .It Fl r Ar file
117 True if
118 .Ar file
119 exists and is readable.
120 .It Fl s Ar file
121 True if
122 .Ar file
123 exists and has a size greater
124 than zero.
125 .It Fl t Ar file_descriptor
126 True if the file whose file descriptor number
127 is
128 .Ar file_descriptor
129 is open and is associated with a terminal.
130 .It Fl u Ar file
131 True if
132 .Ar file
133 exists and its set user ID flag
134 is set.
135 .It Fl w Ar file
136 True if
137 .Ar file
138 exists and is writable.
139 True
140 indicates both that the write flag is on and that
141 .Ar file
142 resides on a read-write file system.
143 .Pp
144 Note that this behaviour is specific to
145 .Dx .
146 When writing portable scripts, keep in mind that
147 on some systems, this test may
148 indicate only that the write flag is on.
149 .It Fl x Ar file
150 True if
151 .Ar file
152 exists and is executable.
153 True
154 indicates only that the execute flag is on.
155 If
156 .Ar file
157 is a directory, true indicates that
158 .Ar file
159 can be searched.
160 .It Fl z Ar string
161 True if the length of
162 .Ar string
163 is zero.
164 .It Fl L Ar file
165 True if
166 .Ar file
167 exists and is a symbolic link.
168 .It Fl O Ar file
169 True if
170 .Ar file
171 exists and its owner matches the effective user id of this process.
172 .It Fl G Ar file
173 True if
174 .Ar file
175 exists and its group matches the effective group id of this process.
176 .It Fl S Ar file
177 True if
178 .Ar file
179 exists and is a socket.
180 .It Ar file1 Fl nt Ar file2
181 True if
182 .Ar file1
183 exists and is newer than
184 .Ar file2 .
185 .It Ar file1 Fl ot Ar file2
186 True if
187 .Ar file1
188 exists and is older than
189 .Ar file2 .
190 .It Ar file1 Fl ef Ar file2
191 True if
192 .Ar file1
193 and
194 .Ar file2
195 exist and refer to the same file.
196 .It Ar string
197 True if
198 .Ar string
199 is not the null
200 string.
201 .It Ar \&s\&1 Cm \&= Ar \&s\&2
202 True if the strings
203 .Ar \&s\&1
204 and
205 .Ar \&s\&2
206 are identical.
207 .It Ar \&s\&1 Cm \&!= Ar \&s\&2
208 True if the strings
209 .Ar \&s\&1
210 and
211 .Ar \&s\&2
212 are not identical.
213 .It Ar \&s\&1 Cm \&< Ar \&s\&2
214 True if string
215 .Ar \&s\&1
216 comes before
217 .Ar \&s\&2
218 based on the ASCII value of their characters.
219 .It Ar \&s\&1 Cm \&> Ar \&s\&2
220 True if string
221 .Ar \&s\&1
222 comes after
223 .Ar \&s\&2
224 based on the ASCII value of their characters.
225 .It Ar \&s\&1
226 True if
227 .Ar \&s\&1
228 is not the null
229 string.
230 .It Ar \&n\&1 Fl \&eq Ar \&n\&2
231 True if the integers
232 .Ar \&n\&1
233 and
234 .Ar \&n\&2
235 are algebraically
236 equal.
237 .It Ar \&n\&1 Fl \&ne Ar \&n\&2
238 True if the integers
239 .Ar \&n\&1
240 and
241 .Ar \&n\&2
242 are not
243 algebraically equal.
244 .It Ar \&n\&1 Fl \&gt Ar \&n\&2
245 True if the integer
246 .Ar \&n\&1
247 is algebraically
248 greater than the integer
249 .Ar \&n\&2 .
250 .It Ar \&n\&1 Fl \&ge Ar \&n\&2
251 True if the integer
252 .Ar \&n\&1
253 is algebraically
254 greater than or equal to the integer
255 .Ar \&n\&2 .
256 .It Ar \&n\&1 Fl \&lt Ar \&n\&2
257 True if the integer
258 .Ar \&n\&1
259 is algebraically less
260 than the integer
261 .Ar \&n\&2 .
262 .It Ar \&n\&1 Fl \&le Ar \&n\&2
263 True if the integer
264 .Ar \&n\&1
265 is algebraically less
266 than or equal to the integer
267 .Ar \&n\&2 .
268 .El
269 .Pp
270 These primaries can be combined with the following operators:
271 .Bl -tag -width Ar
272 .It Cm \&! Ar expression
273 True if
274 .Ar expression
275 is false.
276 .It Ar expression1 Fl a Ar expression2
277 True if both
278 .Ar expression1
279 and
280 .Ar expression2
281 are true.
282 .It Ar expression1 Fl o Ar expression2
283 True if either
284 .Ar expression1
285 or
286 .Ar expression2
287 are true.
288 .It Cm \&( Ns Ar expression Ns Cm \&)
289 True if expression is true.
290 .El
291 .Pp
292 The
293 .Fl a
294 operator has higher precedence than the
295 .Fl o
296 operator.
297 .Pp
298 Some shells may provide a builtin
299 .Nm
300 command which is similar or identical to this utility.
301 Consult the
302 .Xr builtin 1
303 manual page.
304 .Sh GRAMMAR AMBIGUITY
305 The
306 .Nm
307 grammar is inherently ambiguous.  In order to assure a degree of consistency,
308 the cases described in the
309 .St -p1003.2 ,
310 section D11.2/4.62.4, standard
311 are evaluated consistently according to the rules specified in the
312 standards document.  All other cases are subject to the ambiguity in the
313 command semantics.
314 .Sh DIAGNOSTICS
315 The
316 .Nm
317 utility exits with one of the following values:
318 .Bl -tag -width Ds
319 .It 0
320 expression evaluated to true.
321 .It 1
322 expression evaluated to false or expression was
323 missing.
324 .It >1
325 An error occurred.
326 .El
327 .Sh SEE ALSO
328 .Xr builtin 1 ,
329 .Xr expr 1 ,
330 .Xr sh 1
331 .Sh STANDARDS
332 The
333 .Nm
334 utility implements a superset of the
335 .St -p1003.2
336 specification.