[dragonfly.git] / bin / test / test.1

.\"-
.\" 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
.\" $FreeBSD: src/bin/test/test.1,v 1.31 2010/09/11 10:49:56 brucec Exp $
.\"
.Dd September 10, 2010
.Dt TEST 1
.Os
.Sh NAME
.Nm test ,
.Nm \&[
.Nd condition evaluation utility
.Sh SYNOPSIS
.Nm
.Ar expression
.Nm \&[
.Ar expression Cm ]
.Sh DESCRIPTION
The
.Nm
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,
.Nm
also returns 1 (false).
.Pp
All operators and flags are separate arguments to the
.Nm
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
.Pq Tn FIFO .
.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 both that the write flag is on and that
.Ar file
resides on a read-write file system.
.Pp
Note that this behaviour is specific to
.Dx .
When writing portable scripts, keep in mind that
on some systems, this test may
indicate only that the write flag is on.
.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 s1 Cm = Ar s2
True if the strings
.Ar s1
and
.Ar s2
are identical.
.It Ar s1 Cm != Ar s2
True if the strings
.Ar s1
and
.Ar s2
are not identical.
.It Ar s1 Cm < Ar s2
True if string
.Ar s1
comes before
.Ar s2
based on the binary value of their characters.
.It Ar s1 Cm > Ar s2
True if string
.Ar s1
comes after
.Ar s2
based on the binary value of their characters.
.It Ar n1 Fl eq Ar n2
True if the integers
.Ar n1
and
.Ar n2
are algebraically
equal.
.It Ar n1 Fl ne Ar n2
True if the integers
.Ar n1
and
.Ar n2
are not
algebraically equal.
.It Ar n1 Fl gt Ar n2
True if the integer
.Ar n1
is algebraically
greater than the integer
.Ar n2 .
.It Ar n1 Fl ge Ar n2
True if the integer
.Ar n1
is algebraically
greater than or equal to the integer
.Ar n2 .
.It Ar n1 Fl lt Ar n2
True if the integer
.Ar n1
is algebraically less
than the integer
.Ar n2 .
.It Ar n1 Fl le Ar n2
True if the integer
.Ar n1
is algebraically less
than or equal to the integer
.Ar n2 .
.El
.Pp
If
.Ar file
is a symbolic link,
.Nm
will fully dereference it and then evaluate the expression
against the file referenced, except for the
.Fl h
and
.Fl L
primaries.
.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 \&( Ar expression Cm \&)
True if expression is true.
.El
.Pp
The
.Fl a
operator has higher precedence than the
.Fl o
operator.
.Pp
Some shells may provide a builtin
.Nm
command which is similar or identical to this utility.
Consult the
.Xr builtin 1
manual page.
.Sh GRAMMAR AMBIGUITY
The
.Nm
grammar is inherently ambiguous.
In order to assure a degree of consistency,
the cases described in the
.St -p1003.2 ,
section D11.2/4.62.4, standard
are evaluated consistently according to the rules specified in the
standards document.
All other cases are subject to the ambiguity in the
command semantics.
.Pp
In particular, only expressions containing
.Fl a ,
.Fl o ,
.Cm \&(
or
.Cm \&)
can be ambiguous.
.Sh EXIT STATUS
The
.Nm
utility exits with one of the following values:
.Bl -tag -width indent
.It 0
expression evaluated to true.
.It 1
expression evaluated to false or expression was
missing.
.It >1
An error occurred.
.El
.Sh SEE ALSO
.Xr builtin 1 ,
.Xr expr 1 ,
.Xr sh 1 ,
.Xr symlink 7
.Sh STANDARDS
The
.Nm
utility implements a superset of the
.St -p1003.2
specification.
.Sh BUGS
Both sides are always evaluated in
.Fl a
and
.Fl o .
For instance, the writable status of
.Pa file
will be tested by the following command even though the former expression
indicated false, which results in a gratuitous access to the file system:
.Dl "[ -z abc -a -w file ]"
To avoid this, write
.Dl "[ -z abc ] && [ -w file ]"
Commit	Line	Data
b3967821	1	.\"-
984263bc MD	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. All advertising materials mentioning features or use of this software
	17	.\" must display the following acknowledgement:
	18	.\" This product includes software developed by the University of
	19	.\" California, Berkeley and its contributors.
	20	.\" 4. Neither the name of the University nor the names of its contributors
	21	.\" may be used to endorse or promote products derived from this software
	22	.\" without specific prior written permission.
	23	.\"
	24	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	25	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	26	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	27	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	28	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	29	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	30	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	31	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	32	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	33	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	34	.\" SUCH DAMAGE.
	35	.\"
	36	.\" @(#)test.1 8.1 (Berkeley) 5/31/93
b3967821	37	.\" $FreeBSD: src/bin/test/test.1,v 1.31 2010/09/11 10:49:56 brucec Exp $
984263bc	38	.\"
b3967821	39	.Dd September 10, 2010
984263bc MD	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 ]
1bf4b486	51	.Sh DESCRIPTION
984263bc MD	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).
b7367ef6 SW	57	If there is no expression,
	58	.Nm
	59	also returns 1 (false).
984263bc MD	60	.Pp
	61	All operators and flags are separate arguments to the
	62	.Nm
	63	utility.
	64	.Pp
	65	The following primaries are used to construct expression:
	66	.Bl -tag -width Ar
	67	.It Fl b Ar file
	68	True if
	69	.Ar file
	70	exists and is a block special
	71	file.
	72	.It Fl c Ar file
	73	True if
	74	.Ar file
	75	exists and is a character
	76	special file.
	77	.It Fl d Ar file
	78	True if
	79	.Ar file
	80	exists and is a directory.
	81	.It Fl e Ar file
	82	True if
	83	.Ar file
	84	exists (regardless of type).
	85	.It Fl f Ar file
	86	True if
	87	.Ar file
	88	exists and is a regular file.
	89	.It Fl g Ar file
	90	True if
	91	.Ar file
	92	exists and its set group ID flag
	93	is set.
	94	.It Fl h Ar file
	95	True if
	96	.Ar file
	97	exists and is a symbolic link.
	98	This operator is retained for compatibility with previous versions of
	99	this program.
	100	Do not rely on its existence; use
	101	.Fl L
	102	instead.
	103	.It Fl k Ar file
	104	True if
	105	.Ar file
	106	exists and its sticky bit is set.
	107	.It Fl n Ar string
	108	True if the length of
	109	.Ar string
	110	is nonzero.
	111	.It Fl p Ar file
	112	True if
	113	.Ar file
	114	is a named pipe
	115	.Pq Tn FIFO .
	116	.It Fl r Ar file
	117	True if
	118	.Ar file
	119	exists and is readable.
	120	.It Fl s Ar file
	121	True if
	122	.Ar file
	123	exists and has a size greater
124	than zero.
125	.It Fl t Ar file_descriptor
126	True if the file whose file descriptor number
127	is
128	.Ar file_descriptor
129	is open and is associated with a terminal.
130	.It Fl u Ar file
131	True if
132	.Ar file
133	exists and its set user ID flag
134	is set.
135	.It Fl w Ar file
136	True if
137	.Ar file
138	exists and is writable.
139	True
6ab72760 CP	140	indicates both that the write flag is on and that
	141	.Ar file
	142	resides on a read-write file system.
	143	.Pp
	144	Note that this behaviour is specific to
	145	.Dx .
	146	When writing portable scripts, keep in mind that
	147	on some systems, this test may
	148	indicate only that the write flag is on.
984263bc MD	149	.It Fl x Ar file
	150	True if
	151	.Ar file
	152	exists and is executable.
	153	True
	154	indicates only that the execute flag is on.
	155	If
	156	.Ar file
	157	is a directory, true indicates that
	158	.Ar file
	159	can be searched.
	160	.It Fl z Ar string
	161	True if the length of
	162	.Ar string
	163	is zero.
	164	.It Fl L Ar file
	165	True if
	166	.Ar file
	167	exists and is a symbolic link.
	168	.It Fl O Ar file
	169	True if
	170	.Ar file
	171	exists and its owner matches the effective user id of this process.
	172	.It Fl G Ar file
	173	True if
	174	.Ar file
	175	exists and its group matches the effective group id of this process.
	176	.It Fl S Ar file
	177	True if
	178	.Ar file
	179	exists and is a socket.
	180	.It Ar file1 Fl nt Ar file2
	181	True if
	182	.Ar file1
	183	exists and is newer than
	184	.Ar file2 .
	185	.It Ar file1 Fl ot Ar file2
	186	True if
	187	.Ar file1
	188	exists and is older than
	189	.Ar file2 .
	190	.It Ar file1 Fl ef Ar file2
	191	True if
	192	.Ar file1
	193	and
	194	.Ar file2
	195	exist and refer to the same file.
	196	.It Ar string
	197	True if
	198	.Ar string
	199	is not the null
	200	string.
b3967821	201	.It Ar s1 Cm = Ar s2
984263bc	202	True if the strings
b3967821	203	.Ar s1
984263bc	204	and
b3967821	205	.Ar s2
984263bc	206	are identical.
b3967821	207	.It Ar s1 Cm != Ar s2
984263bc	208	True if the strings
b3967821	209	.Ar s1
984263bc	210	and
b3967821	211	.Ar s2
984263bc	212	are not identical.
b3967821	213	.It Ar s1 Cm < Ar s2
984263bc	214	True if string
b3967821	215	.Ar s1
984263bc	216	comes before
b3967821 PA	217	.Ar s2
	218	based on the binary value of their characters.
	219	.It Ar s1 Cm > Ar s2
984263bc	220	True if string
b3967821	221	.Ar s1
984263bc	222	comes after
b3967821 PA	223	.Ar s2
	224	based on the binary value of their characters.
	225	.It Ar n1 Fl eq Ar n2
984263bc	226	True if the integers
b3967821	227	.Ar n1
984263bc	228	and
b3967821	229	.Ar n2
984263bc MD	230	are algebraically
984263bc MD	231	equal.
b3967821	232	.It Ar n1 Fl ne Ar n2
984263bc	233	True if the integers
b3967821	234	.Ar n1
984263bc	235	and
b3967821	236	.Ar n2
984263bc MD	237	are not
984263bc MD	238	algebraically equal.
b3967821	239	.It Ar n1 Fl gt Ar n2
984263bc	240	True if the integer
b3967821	241	.Ar n1
984263bc MD	242	is algebraically
984263bc MD	243	greater than the integer
b3967821 PA	244	.Ar n2 .
b3967821 PA	245	.It Ar n1 Fl ge Ar n2
984263bc	246	True if the integer
b3967821	247	.Ar n1
984263bc MD	248	is algebraically
984263bc MD	249	greater than or equal to the integer
b3967821 PA	250	.Ar n2 .
b3967821 PA	251	.It Ar n1 Fl lt Ar n2
984263bc	252	True if the integer
b3967821	253	.Ar n1
984263bc MD	254	is algebraically less
984263bc MD	255	than the integer
b3967821 PA	256	.Ar n2 .
b3967821 PA	257	.It Ar n1 Fl le Ar n2
984263bc	258	True if the integer
b3967821	259	.Ar n1
984263bc MD	260	is algebraically less
984263bc MD	261	than or equal to the integer
b3967821	262	.Ar n2 .
984263bc MD	263	.El
984263bc MD	264	.Pp
b3967821 PA	265	If
	266	.Ar file
	267	is a symbolic link,
	268	.Nm
	269	will fully dereference it and then evaluate the expression
	270	against the file referenced, except for the
	271	.Fl h
	272	and
	273	.Fl L
	274	primaries.
	275	.Pp
984263bc MD	276	These primaries can be combined with the following operators:
	277	.Bl -tag -width Ar
	278	.It Cm \&! Ar expression
	279	True if
	280	.Ar expression
	281	is false.
	282	.It Ar expression1 Fl a Ar expression2
	283	True if both
	284	.Ar expression1
	285	and
	286	.Ar expression2
	287	are true.
	288	.It Ar expression1 Fl o Ar expression2
	289	True if either
	290	.Ar expression1
	291	or
	292	.Ar expression2
	293	are true.
b3967821	294	.It Cm \&( Ar expression Cm \&)
984263bc MD	295	True if expression is true.
	296	.El
	297	.Pp
	298	The
	299	.Fl a
	300	operator has higher precedence than the
	301	.Fl o
	302	operator.
	303	.Pp
	304	Some shells may provide a builtin
	305	.Nm
	306	command which is similar or identical to this utility.
	307	Consult the
	308	.Xr builtin 1
	309	manual page.
	310	.Sh GRAMMAR AMBIGUITY
	311	The
	312	.Nm
b3967821 PA	313	grammar is inherently ambiguous.
b3967821 PA	314	In order to assure a degree of consistency,
984263bc MD	315	the cases described in the
	316	.St -p1003.2 ,
	317	section D11.2/4.62.4, standard
	318	are evaluated consistently according to the rules specified in the
b3967821 PA	319	standards document.
b3967821 PA	320	All other cases are subject to the ambiguity in the
984263bc	321	command semantics.
b3967821 PA	322	.Pp
	323	In particular, only expressions containing
	324	.Fl a ,
	325	.Fl o ,
	326	.Cm \&(
	327	or
	328	.Cm \&)
	329	can be ambiguous.
	330	.Sh EXIT STATUS
984263bc MD	331	The
	332	.Nm
	333	utility exits with one of the following values:
b3967821	334	.Bl -tag -width indent
984263bc MD	335	.It 0
	336	expression evaluated to true.
	337	.It 1
	338	expression evaluated to false or expression was
	339	missing.
	340	.It >1
	341	An error occurred.
	342	.El
	343	.Sh SEE ALSO
	344	.Xr builtin 1 ,
	345	.Xr expr 1 ,
b3967821 PA	346	.Xr sh 1 ,
b3967821 PA	347	.Xr symlink 7
984263bc MD	348	.Sh STANDARDS
	349	The
	350	.Nm
	351	utility implements a superset of the
	352	.St -p1003.2
	353	specification.
b3967821 PA	354	.Sh BUGS
	355	Both sides are always evaluated in
	356	.Fl a
	357	and
	358	.Fl o .
	359	For instance, the writable status of
	360	.Pa file
	361	will be tested by the following command even though the former expression
	362	indicated false, which results in a gratuitous access to the file system:
	363	.Dl "[ -z abc -a -w file ]"
	364	To avoid this, write
	365	.Dl "[ -z abc ] && [ -w file ]"