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