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