dash/bltin/test.1

.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\" Copyright (c) 1997-2005
.\"	Herbert Xu <herbert@gondor.apana.org.au>.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the Institute of Electrical and Electronics Engineers, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)test.1	8.1 (Berkeley) 5/31/93
.\"
.Dd May 31, 1993
.Dt TEST 1
.Os
.Sh NAME
.Nm test ,
.Nm \&[
.Nd condition evaluation utility
.Sh SYNOPSIS
.Nm test
.Ar expression
.Nm \&[
.Ar expression Cm ]
.Sh DESCRIPTION
The
.Nm test
utility evaluates the expression and, if it evaluates
to true, returns a zero (true) exit status; otherwise
it returns 1 (false).
If there is no expression, test also
returns 1 (false).
.Pp
All operators and flags are separate arguments to the
.Nm test
utility.
.Pp
The following primaries are used to construct expression:
.Bl -tag -width Ar
.It Fl b Ar file
True if
.Ar file
exists and is a block special
file.
.It Fl c Ar file
True if
.Ar file
exists and is a character
special file.
.It Fl d Ar file
True if
.Ar file
exists and is a directory.
.It Fl e Ar file
True if
.Ar file
exists (regardless of type).
.It Fl f Ar file
True if
.Ar file
exists and is a regular file.
.It Fl g Ar file
True if
.Ar file
exists and its set group ID flag
is set.
.It Fl h Ar file
True if
.Ar file
exists and is a symbolic link.
.It Fl k Ar file
True if
.Ar file
exists and its sticky bit is set.
.It Fl n Ar string
True if the length of
.Ar string
is nonzero.
.It Fl p Ar file
True if
.Ar file
is a named pipe
.Po Tn FIFO Pc .
.It Fl r Ar file
True if
.Ar file
exists and is readable.
.It Fl s Ar file
True if
.Ar file
exists and has a size greater
than zero.
.It Fl t Ar file_descriptor
True if the file whose file descriptor number
is
.Ar file_descriptor
is open and is associated with a terminal.
.It Fl u Ar file
True if
.Ar file
exists and its set user ID flag
is set.
.It Fl w Ar file
True if
.Ar file
exists and is writable.
True
indicates only that the write flag is on.
The file is not writable on a read-only file
system even if this test indicates true.
.It Fl x Ar file
True if
.Ar file
exists and is executable.
True
indicates only that the execute flag is on.
If
.Ar file
is a directory, true indicates that
.Ar file
can be searched.
.It Fl z Ar string
True if the length of
.Ar string
is zero.
.It Fl L Ar file
True if
.Ar file
exists and is a symbolic link.
This operator is retained for compatibility with previous versions of
this program.
Do not rely on its existence; use
.Fl h
instead.
.It Fl O Ar file
True if
.Ar file
exists and its owner matches the effective user id of this process.
.It Fl G Ar file
True if
.Ar file
exists and its group matches the effective group id of this process.
.It Fl S Ar file
True if
.Ar file
exists and is a socket.
.It Ar file1 Fl nt Ar file2
True if
.Ar file1
exists and is newer than
.Ar file2 .
.It Ar file1 Fl ot Ar file2
True if
.Ar file1
exists and is older than
.Ar file2 .
.It Ar file1 Fl ef Ar file2
True if
.Ar file1
and
.Ar file2
exist and refer to the same file.
.It Ar string
True if
.Ar string
is not the null
string.
.It Ar \&s\&1 Cm \&= Ar \&s\&2
True if the strings
.Ar \&s\&1
and
.Ar \&s\&2
are identical.
.It Ar \&s\&1 Cm \&!= Ar \&s\&2
True if the strings
.Ar \&s\&1
and
.Ar \&s\&2
are not identical.
.It Ar \&s\&1 Cm \&\*[Lt] Ar \&s\&2
True if string
.Ar \&s\&1
comes before
.Ar \&s\&2
based on the ASCII value of their characters.
.It Ar \&s\&1 Cm \&\*[Gt] Ar \&s\&2
True if string
.Ar \&s\&1
comes after
.Ar \&s\&2
based on the ASCII value of their characters.
.It Ar \&n\&1 Fl \&eq Ar \&n\&2
True if the integers
.Ar \&n\&1
and
.Ar \&n\&2
are algebraically
equal.
.It Ar \&n\&1 Fl \&ne Ar \&n\&2
True if the integers
.Ar \&n\&1
and
.Ar \&n\&2
are not
algebraically equal.
.It Ar \&n\&1 Fl \&gt Ar \&n\&2
True if the integer
.Ar \&n\&1
is algebraically
greater than the integer
.Ar \&n\&2 .
.It Ar \&n\&1 Fl \&ge Ar \&n\&2
True if the integer
.Ar \&n\&1
is algebraically
greater than or equal to the integer
.Ar \&n\&2 .
.It Ar \&n\&1 Fl \&lt Ar \&n\&2
True if the integer
.Ar \&n\&1
is algebraically less
than the integer
.Ar \&n\&2 .
.It Ar \&n\&1 Fl \&le Ar \&n\&2
True if the integer
.Ar \&n\&1
is algebraically less
than or equal to the integer
.Ar \&n\&2 .
.El
.Pp
These primaries can be combined with the following operators:
.Bl -tag -width Ar
.It Cm \&! Ar expression
True if
.Ar expression
is false.
.It Ar expression1 Fl a Ar expression2
True if both
.Ar expression1
and
.Ar expression2
are true.
.It Ar expression1 Fl o Ar expression2
True if either
.Ar expression1
or
.Ar expression2
are true.
.It Cm \&( Ns Ar expression Ns Cm \&)
True if expression is true.
.El
.Pp
The
.Fl a
operator has higher precedence than the
.Fl o
operator.
.Sh GRAMMAR AMBIGUITY
The
.Nm test
grammar is inherently ambiguous.
In order to assure a degree of consistency, the cases described in
.St -p1003.2
section 4.62.4,
are evaluated consistently according to the rules specified in the
standards document.
All other cases are subject to the ambiguity in the command semantics.
.Sh EXIT STATUS
The
.Nm test
utility exits with one of the following values:
.Bl -tag -width Ds
.It 0
expression evaluated to true.
.It 1
expression evaluated to false or expression was
missing.
.It \*[Gt]1
An error occurred.
.El
.Sh STANDARDS
The
.Nm test
utility implements a superset of the
.St -p1003.2
specification.
1	.\" Copyright (c) 1991, 1993
2	.\" The Regents of the University of California. All rights reserved.
3	.\" Copyright (c) 1997-2005
4	.\" Herbert Xu <herbert@gondor.apana.org.au>. All rights reserved.
5	.\"
6	.\" This code is derived from software contributed to Berkeley by
7	.\" the Institute of Electrical and Electronics Engineers, Inc.
8	.\"
9	.\" Redistribution and use in source and binary forms, with or without
10	.\" modification, are permitted provided that the following conditions
11	.\" are met:
12	.\" 1. Redistributions of source code must retain the above copyright
13	.\" notice, this list of conditions and the following disclaimer.
14	.\" 2. Redistributions in binary form must reproduce the above copyright
15	.\" notice, this list of conditions and the following disclaimer in the
16	.\" documentation and/or other materials provided with the distribution.
17	.\" 3. Neither the name of the University nor the names of its contributors
18	.\" may be used to endorse or promote products derived from this software
19	.\" without specific prior written permission.
20	.\"
21	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31	.\" SUCH DAMAGE.
32	.\"
33	.\" @(#)test.1 8.1 (Berkeley) 5/31/93
34	.\"
35	.Dd May 31, 1993
36	.Dt TEST 1
37	.Os
38	.Sh NAME
39	.Nm test ,
40	.Nm \&[
41	.Nd condition evaluation utility
42	.Sh SYNOPSIS
43	.Nm test
44	.Ar expression
45	.Nm \&[
46	.Ar expression Cm ]
47	.Sh DESCRIPTION
48	The
49	.Nm test
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, test also
54	returns 1 (false).
55	.Pp
56	All operators and flags are separate arguments to the
57	.Nm test
58	utility.
59	.Pp
60	The following primaries are used to construct expression:
61	.Bl -tag -width Ar
62	.It Fl b Ar file
63	True if
64	.Ar file
65	exists and is a block special
66	file.
67	.It Fl c Ar file
68	True if
69	.Ar file
70	exists and is a character
71	special file.
72	.It Fl d Ar file
73	True if
74	.Ar file
75	exists and is a directory.
76	.It Fl e Ar file
77	True if
78	.Ar file
79	exists (regardless of type).
80	.It Fl f Ar file
81	True if
82	.Ar file
83	exists and is a regular file.
84	.It Fl g Ar file
85	True if
86	.Ar file
87	exists and its set group ID flag
88	is set.
89	.It Fl h Ar file
90	True if
91	.Ar file
92	exists and is a symbolic link.
93	.It Fl k Ar file
94	True if
95	.Ar file
96	exists and its sticky bit is set.
97	.It Fl n Ar string
98	True if the length of
99	.Ar string
100	is nonzero.
101	.It Fl p Ar file
102	True if
103	.Ar file
104	is a named pipe
105	.Po Tn FIFO Pc .
106	.It Fl r Ar file
107	True if
108	.Ar file
109	exists and is readable.
110	.It Fl s Ar file
111	True if
112	.Ar file
113	exists and has a size greater
114	than zero.
115	.It Fl t Ar file_descriptor
116	True if the file whose file descriptor number
117	is
118	.Ar file_descriptor
119	is open and is associated with a terminal.
120	.It Fl u Ar file
121	True if
122	.Ar file
123	exists and its set user ID flag
124	is set.
125	.It Fl w Ar file
126	True if
127	.Ar file
128	exists and is writable.
129	True
130	indicates only that the write flag is on.
131	The file is not writable on a read-only file
132	system even if this test indicates true.
133	.It Fl x Ar file
134	True if
135	.Ar file
136	exists and is executable.
137	True
138	indicates only that the execute flag is on.
139	If
140	.Ar file
141	is a directory, true indicates that
142	.Ar file
143	can be searched.
144	.It Fl z Ar string
145	True if the length of
146	.Ar string
147	is zero.
148	.It Fl L Ar file
149	True if
150	.Ar file
151	exists and is a symbolic link.
152	This operator is retained for compatibility with previous versions of
153	this program.
154	Do not rely on its existence; use
155	.Fl h
156	instead.
157	.It Fl O Ar file
158	True if
159	.Ar file
160	exists and its owner matches the effective user id of this process.
161	.It Fl G Ar file
162	True if
163	.Ar file
164	exists and its group matches the effective group id of this process.
165	.It Fl S Ar file
166	True if
167	.Ar file
168	exists and is a socket.
169	.It Ar file1 Fl nt Ar file2
170	True if
171	.Ar file1
172	exists and is newer than
173	.Ar file2 .
174	.It Ar file1 Fl ot Ar file2
175	True if
176	.Ar file1
177	exists and is older than
178	.Ar file2 .
179	.It Ar file1 Fl ef Ar file2
180	True if
181	.Ar file1
182	and
183	.Ar file2
184	exist and refer to the same file.
185	.It Ar string
186	True if
187	.Ar string
188	is not the null
189	string.
190	.It Ar \&s\&1 Cm \&= Ar \&s\&2
191	True if the strings
192	.Ar \&s\&1
193	and
194	.Ar \&s\&2
195	are identical.
196	.It Ar \&s\&1 Cm \&!= Ar \&s\&2
197	True if the strings
198	.Ar \&s\&1
199	and
200	.Ar \&s\&2
201	are not identical.
202	.It Ar \&s\&1 Cm \&\*[Lt] Ar \&s\&2
203	True if string
204	.Ar \&s\&1
205	comes before
206	.Ar \&s\&2
207	based on the ASCII value of their characters.
208	.It Ar \&s\&1 Cm \&\*[Gt] Ar \&s\&2
209	True if string
210	.Ar \&s\&1
211	comes after
212	.Ar \&s\&2
213	based on the ASCII value of their characters.
214	.It Ar \&n\&1 Fl \&eq Ar \&n\&2
215	True if the integers
216	.Ar \&n\&1
217	and
218	.Ar \&n\&2
219	are algebraically
220	equal.
221	.It Ar \&n\&1 Fl \&ne Ar \&n\&2
222	True if the integers
223	.Ar \&n\&1
224	and
225	.Ar \&n\&2
226	are not
227	algebraically equal.
228	.It Ar \&n\&1 Fl \&gt Ar \&n\&2
229	True if the integer
230	.Ar \&n\&1
231	is algebraically
232	greater than the integer
233	.Ar \&n\&2 .
234	.It Ar \&n\&1 Fl \&ge Ar \&n\&2
235	True if the integer
236	.Ar \&n\&1
237	is algebraically
238	greater than or equal to the integer
239	.Ar \&n\&2 .
240	.It Ar \&n\&1 Fl \&lt Ar \&n\&2
241	True if the integer
242	.Ar \&n\&1
243	is algebraically less
244	than the integer
245	.Ar \&n\&2 .
246	.It Ar \&n\&1 Fl \&le Ar \&n\&2
247	True if the integer
248	.Ar \&n\&1
249	is algebraically less
250	than or equal to the integer
251	.Ar \&n\&2 .
252	.El
253	.Pp
254	These primaries can be combined with the following operators:
255	.Bl -tag -width Ar
256	.It Cm \&! Ar expression
257	True if
258	.Ar expression
259	is false.
260	.It Ar expression1 Fl a Ar expression2
261	True if both
262	.Ar expression1
263	and
264	.Ar expression2
265	are true.
266	.It Ar expression1 Fl o Ar expression2
267	True if either
268	.Ar expression1
269	or
270	.Ar expression2
271	are true.
272	.It Cm \&( Ns Ar expression Ns Cm \&)
273	True if expression is true.
274	.El
275	.Pp
276	The
277	.Fl a
278	operator has higher precedence than the
279	.Fl o
280	operator.
281	.Sh GRAMMAR AMBIGUITY
282	The
283	.Nm test
284	grammar is inherently ambiguous.
285	In order to assure a degree of consistency, the cases described in
286	.St -p1003.2
287	section 4.62.4,
288	are evaluated consistently according to the rules specified in the
289	standards document.
290	All other cases are subject to the ambiguity in the command semantics.
291	.Sh EXIT STATUS
292	The
293	.Nm test
294	utility exits with one of the following values:
295	.Bl -tag -width Ds
296	.It 0
297	expression evaluated to true.
298	.It 1
299	expression evaluated to false or expression was
300	missing.
301	.It \*[Gt]1
302	An error occurred.
303	.El
304	.Sh STANDARDS
305	The
306	.Nm test
307	utility implements a superset of the
308	.St -p1003.2
309	specification.