bin/test: Sync with FreeBSD
[dragonfly.git] / bin / test / test.1
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 .\" 3. All advertising materials mentioning features or use of this software
17 .\"    must display the following acknowledgement:
18 .\"     This product includes software developed by the University of
19 .\"     California, Berkeley and its contributors.
20 .\" 4. Neither the name of the University nor the names of its contributors
21 .\"    may be used to endorse or promote products derived from this software
22 .\"    without specific prior written permission.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" SUCH DAMAGE.
35 .\"
36 .\"     @(#)test.1      8.1 (Berkeley) 5/31/93
37 .\" $FreeBSD: src/bin/test/test.1,v 1.31 2010/09/11 10:49:56 brucec Exp $
38 .\"
39 .Dd September 10, 2010
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 s1 Cm = Ar s2
202 True if the strings
203 .Ar s1
204 and
205 .Ar s2
206 are identical.
207 .It Ar s1 Cm != Ar s2
208 True if the strings
209 .Ar s1
210 and
211 .Ar s2
212 are not identical.
213 .It Ar s1 Cm < Ar s2
214 True if string
215 .Ar s1
216 comes before
217 .Ar s2
218 based on the binary value of their characters.
219 .It Ar s1 Cm > Ar s2
220 True if string
221 .Ar s1
222 comes after
223 .Ar s2
224 based on the binary value of their characters.
225 .It Ar n1 Fl eq Ar n2
226 True if the integers
227 .Ar n1
228 and
229 .Ar n2
230 are algebraically
231 equal.
232 .It Ar n1 Fl ne Ar n2
233 True if the integers
234 .Ar n1
235 and
236 .Ar n2
237 are not
238 algebraically equal.
239 .It Ar n1 Fl gt Ar n2
240 True if the integer
241 .Ar n1
242 is algebraically
243 greater than the integer
244 .Ar n2 .
245 .It Ar n1 Fl ge Ar n2
246 True if the integer
247 .Ar n1
248 is algebraically
249 greater than or equal to the integer
250 .Ar n2 .
251 .It Ar n1 Fl lt Ar n2
252 True if the integer
253 .Ar n1
254 is algebraically less
255 than the integer
256 .Ar n2 .
257 .It Ar n1 Fl le Ar n2
258 True if the integer
259 .Ar n1
260 is algebraically less
261 than or equal to the integer
262 .Ar n2 .
263 .El
264 .Pp
265 If
266 .Ar file
267 is a symbolic link,
268 .Nm
269 will fully dereference it and then evaluate the expression
270 against the file referenced, except for the
271 .Fl h
272 and
273 .Fl L
274 primaries.
275 .Pp
276 These primaries can be combined with the following operators:
277 .Bl -tag -width Ar
278 .It Cm \&! Ar expression
279 True if
280 .Ar expression
281 is false.
282 .It Ar expression1 Fl a Ar expression2
283 True if both
284 .Ar expression1
285 and
286 .Ar expression2
287 are true.
288 .It Ar expression1 Fl o Ar expression2
289 True if either
290 .Ar expression1
291 or
292 .Ar expression2
293 are true.
294 .It Cm \&( Ar expression Cm \&)
295 True if expression is true.
296 .El
297 .Pp
298 The
299 .Fl a
300 operator has higher precedence than the
301 .Fl o
302 operator.
303 .Pp
304 Some shells may provide a builtin
305 .Nm
306 command which is similar or identical to this utility.
307 Consult the
308 .Xr builtin 1
309 manual page.
310 .Sh GRAMMAR AMBIGUITY
311 The
312 .Nm
313 grammar is inherently ambiguous.
314 In order to assure a degree of consistency,
315 the cases described in the
316 .St -p1003.2 ,
317 section D11.2/4.62.4, standard
318 are evaluated consistently according to the rules specified in the
319 standards document.
320 All other cases are subject to the ambiguity in the
321 command semantics.
322 .Pp
323 In particular, only expressions containing
324 .Fl a ,
325 .Fl o ,
326 .Cm \&(
327 or
328 .Cm \&)
329 can be ambiguous.
330 .Sh EXIT STATUS
331 The
332 .Nm
333 utility exits with one of the following values:
334 .Bl -tag -width indent
335 .It 0
336 expression evaluated to true.
337 .It 1
338 expression evaluated to false or expression was
339 missing.
340 .It >1
341 An error occurred.
342 .El
343 .Sh SEE ALSO
344 .Xr builtin 1 ,
345 .Xr expr 1 ,
346 .Xr sh 1 ,
347 .Xr symlink 7
348 .Sh STANDARDS
349 The
350 .Nm
351 utility implements a superset of the
352 .St -p1003.2
353 specification.
354 .Sh BUGS
355 Both sides are always evaluated in
356 .Fl a
357 and
358 .Fl o .
359 For instance, the writable status of
360 .Pa file
361 will be tested by the following command even though the former expression
362 indicated false, which results in a gratuitous access to the file system:
363 .Dl "[ -z abc -a -w file ]"
364 To avoid this, write
365 .Dl "[ -z abc ] && [ -w file ]"