[apple/shell_cmds.git] / test / test.1

.\"	$NetBSD: test.1,v 1.10 1997/11/12 00:48:21 mrg Exp $
.\"
.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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.
This operator is retained for compatibility with previous versions of
this program. Do not rely on its existence; use
.Fl L
instead.
.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.
.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 \&< 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 \&> Ar \&s\&2
True if string
.Ar \&s\&1
comes after
.Ar \&s\&2
based on the ASCII value of their characters.
.It Ar \&s\&1
True if
.Ar \&s\&1
is not the null
string.
.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 RETURN VALUES
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 >1
An error occurred.
.El
.Sh STANDARDS
The
.Nm test
utility implements a superset of the
.St -p1003.2
specification.
Commit	Line	Data
44bd5ea7 A	1	.\" $NetBSD: test.1,v 1.10 1997/11/12 00:48:21 mrg Exp $
	2	.\"
	3	.\" Copyright (c) 1991, 1993
	4	.\" The Regents of the University of California. 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. All advertising materials mentioning features or use of this software
	18	.\" must display the following acknowledgement:
	19	.\" This product includes software developed by the University of
	20	.\" California, Berkeley and its contributors.
	21	.\" 4. Neither the name of the University nor the names of its contributors
	22	.\" may be used to endorse or promote products derived from this software
	23	.\" without specific prior written permission.
	24	.\"
	25	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	26	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	27	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	28	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	29	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	30	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	31	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	32	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	33	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	34	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	35	.\" SUCH DAMAGE.
	36	.\"
	37	.\" @(#)test.1 8.1 (Berkeley) 5/31/93
	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 test
	48	.Ar expression
	49	.Nm [
	50	.Ar expression Cm ]
	51	.Sh DESCRIPTION
	52	The
	53	.Nm test
	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 test
	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. Do not rely on its existence; use
99	.Fl L
100	instead.
101	.It Fl k Ar file
102	True if
103	.Ar file
104	exists and its sticky bit is set.
105	.It Fl n Ar string
106	True if the length of
107	.Ar string
108	is nonzero.
109	.It Fl p Ar file
110	True if
111	.Ar file
112	is a named pipe
113	.Po Tn FIFO Pc .
114	.It Fl r Ar file
115	True if
116	.Ar file
117	exists and is readable.
118	.It Fl s Ar file
119	True if
120	.Ar file
121	exists and has a size greater
122	than zero.
123	.It Fl t Ar file_descriptor
124	True if the file whose file descriptor number
125	is
126	.Ar file_descriptor
127	is open and is associated with a terminal.
128	.It Fl u Ar file
129	True if
130	.Ar file
131	exists and its set user ID flag
132	is set.
133	.It Fl w Ar file
134	True if
135	.Ar file
136	exists and is writable.
137	True
138	indicates only that the write flag is on.
139	The file is not writable on a read-only file
140	system even if this test indicates true.
141	.It Fl x Ar file
142	True if
143	.Ar file
144	exists and is executable.
145	True
146	indicates only that the execute flag is on.
147	If
148	.Ar file
149	is a directory, true indicates that
150	.Ar file
151	can be searched.
152	.It Fl z Ar string
153	True if the length of
154	.Ar string
155	is zero.
156	.It Fl L Ar file
157	True if
158	.Ar file
159	exists and is a symbolic link.
160	.It Fl O Ar file
161	True if
162	.Ar file
163	exists and its owner matches the effective user id of this process.
164	.It Fl G Ar file
165	True if
166	.Ar file
167	exists and its group matches the effective group id of this process.
168	.It Fl S Ar file
169	True if
170	.Ar file
171	exists and is a socket.
172	.It Ar file1 Fl nt Ar file2
173	True if
174	.Ar file1
175	exists and is newer than
176	.Ar file2 .
177	.It Ar file1 Fl ot Ar file2
178	True if
179	.Ar file1
180	exists and is older than
181	.Ar file2 .
182	.It Ar file1 Fl ef Ar file2
183	True if
184	.Ar file1
185	and
186	.Ar file2
187	exist and refer to the same file.
188	.It Ar string
189	True if
190	.Ar string
191	is not the null
192	string.
193	.It Ar \&s\&1 Cm \&= Ar \&s\&2
194	True if the strings
195	.Ar \&s\&1
196	and
197	.Ar \&s\&2
198	are identical.
199	.It Ar \&s\&1 Cm \&!= Ar \&s\&2
200	True if the strings
201	.Ar \&s\&1
202	and
203	.Ar \&s\&2
204	are not identical.
205	.It Ar \&s\&1 Cm \&< Ar \&s\&2
206	True if string
207	.Ar \&s\&1
208	comes before
209	.Ar \&s\&2
210	based on the ASCII value of their characters.
211	.It Ar \&s\&1 Cm \&> Ar \&s\&2
212	True if string
213	.Ar \&s\&1
214	comes after
215	.Ar \&s\&2
216	based on the ASCII value of their characters.
217	.It Ar \&s\&1
218	True if
219	.Ar \&s\&1
220	is not the null
221	string.
222	.It Ar \&n\&1 Fl \&eq Ar \&n\&2
223	True if the integers
224	.Ar \&n\&1
225	and
226	.Ar \&n\&2
227	are algebraically
228	equal.
229	.It Ar \&n\&1 Fl \&ne Ar \&n\&2
230	True if the integers
231	.Ar \&n\&1
232	and
233	.Ar \&n\&2
234	are not
235	algebraically equal.
236	.It Ar \&n\&1 Fl \&gt Ar \&n\&2
237	True if the integer
238	.Ar \&n\&1
239	is algebraically
240	greater than the integer
241	.Ar \&n\&2 .
242	.It Ar \&n\&1 Fl \&ge Ar \&n\&2
243	True if the integer
244	.Ar \&n\&1
245	is algebraically
246	greater than or equal to the integer
247	.Ar \&n\&2 .
248	.It Ar \&n\&1 Fl \&lt Ar \&n\&2
249	True if the integer
250	.Ar \&n\&1
251	is algebraically less
252	than the integer
253	.Ar \&n\&2 .
254	.It Ar \&n\&1 Fl \&le Ar \&n\&2
255	True if the integer
256	.Ar \&n\&1
257	is algebraically less
258	than or equal to the integer
259	.Ar \&n\&2 .
260	.El
261	.Pp
262	These primaries can be combined with the following operators:
263	.Bl -tag -width Ar
264	.It Cm \&! Ar expression
265	True if
266	.Ar expression
267	is false.
268	.It Ar expression1 Fl a Ar expression2
269	True if both
270	.Ar expression1
271	and
272	.Ar expression2
273	are true.
274	.It Ar expression1 Fl o Ar expression2
275	True if either
276	.Ar expression1
277	or
278	.Ar expression2
279	are true.
280	.It Cm \&( Ns Ar expression Ns Cm \&)
281	True if expression is true.
282	.El
283	.Pp
284	The
285	.Fl a
286	operator has higher precedence than the
287	.Fl o
288	operator.
289	.Sh GRAMMAR AMBIGUITY
290	The
291	.Nm test
292	grammar is inherently ambiguous. In order to assure a degree of consistency,
293	the cases described in
294	.St -p1003.2
295	section 4.62.4,
296	are evaluated consistently according to the rules specified in the
297	standards document. All other cases are subject to the ambiguity in the
298	command semantics.
299	.Sh RETURN VALUES
300	The
301	.Nm test
302	utility exits with one of the following values:
303	.Bl -tag -width Ds
304	.It 0
305	expression evaluated to true.
306	.It 1
307	expression evaluated to false or expression was
308	missing.
309	.It >1
310	An error occurred.
311	.El
312	.Sh STANDARDS
313	The
314	.Nm test
315	utility implements a superset of the
316	.St -p1003.2
317	specification.