RETURN VALUES is for function return values only. FreeBSD has an own
[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.6 2006/03/01 08:08:44 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, 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 both that the write flag is on and that
140 .Ar file
141 resides on a read-write file system.
142 .Pp
143 Note that this behaviour is specific to
144 .Dx .
145 When writing portable scripts, keep in mind that
146 on some systems, this test may
147 indicate only that the write flag is on.
148 .It Fl x Ar file
149 True if
150 .Ar file
151 exists and is executable.
152 True
153 indicates only that the execute flag is on.
154 If
155 .Ar file
156 is a directory, true indicates that
157 .Ar file
158 can be searched.
159 .It Fl z Ar string
160 True if the length of
161 .Ar string
162 is zero.
163 .It Fl L Ar file
164 True if
165 .Ar file
166 exists and is a symbolic link.
167 .It Fl O Ar file
168 True if
169 .Ar file
170 exists and its owner matches the effective user id of this process.
171 .It Fl G Ar file
172 True if
173 .Ar file
174 exists and its group matches the effective group id of this process.
175 .It Fl S Ar file
176 True if
177 .Ar file
178 exists and is a socket.
179 .It Ar file1 Fl nt Ar file2
180 True if
181 .Ar file1
182 exists and is newer than
183 .Ar file2 .
184 .It Ar file1 Fl ot Ar file2
185 True if
186 .Ar file1
187 exists and is older than
188 .Ar file2 .
189 .It Ar file1 Fl ef Ar file2
190 True if
191 .Ar file1
192 and
193 .Ar file2
194 exist and refer to the same file.
195 .It Ar string
196 True if
197 .Ar string
198 is not the null
199 string.
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 identical.
206 .It Ar \&s\&1 Cm \&!= Ar \&s\&2
207 True if the strings
208 .Ar \&s\&1
209 and
210 .Ar \&s\&2
211 are not identical.
212 .It Ar \&s\&1 Cm \&< Ar \&s\&2
213 True if string
214 .Ar \&s\&1
215 comes before
216 .Ar \&s\&2
217 based on the ASCII value of their characters.
218 .It Ar \&s\&1 Cm \&> Ar \&s\&2
219 True if string
220 .Ar \&s\&1
221 comes after
222 .Ar \&s\&2
223 based on the ASCII value of their characters.
224 .It Ar \&s\&1
225 True if
226 .Ar \&s\&1
227 is not the null
228 string.
229 .It Ar \&n\&1 Fl \&eq Ar \&n\&2
230 True if the integers
231 .Ar \&n\&1
232 and
233 .Ar \&n\&2
234 are algebraically
235 equal.
236 .It Ar \&n\&1 Fl \&ne Ar \&n\&2
237 True if the integers
238 .Ar \&n\&1
239 and
240 .Ar \&n\&2
241 are not
242 algebraically equal.
243 .It Ar \&n\&1 Fl \&gt Ar \&n\&2
244 True if the integer
245 .Ar \&n\&1
246 is algebraically
247 greater than the integer
248 .Ar \&n\&2 .
249 .It Ar \&n\&1 Fl \&ge Ar \&n\&2
250 True if the integer
251 .Ar \&n\&1
252 is algebraically
253 greater than or equal to the integer
254 .Ar \&n\&2 .
255 .It Ar \&n\&1 Fl \&lt Ar \&n\&2
256 True if the integer
257 .Ar \&n\&1
258 is algebraically less
259 than the integer
260 .Ar \&n\&2 .
261 .It Ar \&n\&1 Fl \&le Ar \&n\&2
262 True if the integer
263 .Ar \&n\&1
264 is algebraically less
265 than or equal to the integer
266 .Ar \&n\&2 .
267 .El
268 .Pp
269 These primaries can be combined with the following operators:
270 .Bl -tag -width Ar
271 .It Cm \&! Ar expression
272 True if
273 .Ar expression
274 is false.
275 .It Ar expression1 Fl a Ar expression2
276 True if both
277 .Ar expression1
278 and
279 .Ar expression2
280 are true.
281 .It Ar expression1 Fl o Ar expression2
282 True if either
283 .Ar expression1
284 or
285 .Ar expression2
286 are true.
287 .It Cm \&( Ns Ar expression Ns Cm \&)
288 True if expression is true.
289 .El
290 .Pp
291 The
292 .Fl a
293 operator has higher precedence than the
294 .Fl o
295 operator.
296 .Pp
297 Some shells may provide a builtin
298 .Nm
299 command which is similar or identical to this utility.
300 Consult the
301 .Xr builtin 1
302 manual page.
303 .Sh GRAMMAR AMBIGUITY
304 The
305 .Nm
306 grammar is inherently ambiguous.  In order to assure a degree of consistency,
307 the cases described in the
308 .St -p1003.2 ,
309 section D11.2/4.62.4, standard
310 are evaluated consistently according to the rules specified in the
311 standards document.  All other cases are subject to the ambiguity in the
312 command semantics.
313 .Sh DIAGNOSTICS
314 The
315 .Nm
316 utility exits with one of the following values:
317 .Bl -tag -width Ds
318 .It 0
319 expression evaluated to true.
320 .It 1
321 expression evaluated to false or expression was
322 missing.
323 .It >1
324 An error occurred.
325 .El
326 .Sh SEE ALSO
327 .Xr builtin 1 ,
328 .Xr expr 1 ,
329 .Xr sh 1
330 .Sh STANDARDS
331 The
332 .Nm
333 utility implements a superset of the
334 .St -p1003.2
335 specification.