[apple/file_cmds.git] / rm / rm.1

.\" Copyright (c) 1990, 1993, 1994
.\"	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.
.\"
.\"	@(#)rm.1	8.5 (Berkeley) 12/5/94
.\" $FreeBSD: src/bin/rm/rm.1,v 1.23 2001/07/15 07:49:05 dd Exp $
.\"
.Dd January 28, 1999
.Dt RM 1
.Os
.Sh NAME
.Nm rm ,
.Nm unlink
.Nd remove directory entries
.Sh SYNOPSIS
.Nm
.Op Fl dfiPRrvW
.Ar
.Nm unlink
.Ar file
.Sh DESCRIPTION
The
.Nm
utility attempts to remove the non-directory type files specified on the
command line.
If the permissions of the file do not permit writing, and the standard
input device is a terminal, the user is prompted (on the standard error
output) for confirmation.
.Pp
The options are as follows:
.Bl -tag -width Fl
.It Fl d
Attempt to remove directories as well as other types of files.
.It Fl f
Attempt to remove the files without prompting for confirmation,
regardless of the file's permissions.
If the file does not exist, do not display a diagnostic message or modify
the exit status to reflect an error.
The
.Fl f
option overrides any previous
.Fl i
options.
.It Fl i
Request confirmation before attempting to remove each file, regardless of
the file's permissions, or whether or not the standard input device is a
terminal.
The
.Fl i
option overrides any previous
.Fl f
options.
.It Fl P
Overwrite regular files before deleting them.
Files are overwritten three times, first with the byte pattern 0xff,
then 0x00, and then 0xff again, before they are deleted.
.It Fl R
Attempt to remove the file hierarchy rooted in each file argument.
The
.Fl R
option implies the
.Fl d
option.
If the
.Fl i
option is specified, the user is prompted for confirmation before
each directory's contents are processed (as well as before the attempt
is made to remove the directory).
If the user does not respond affirmatively, the file hierarchy rooted in
that directory is skipped.
.Pp
.It Fl r
Equivalent to
.Fl R .
.It Fl v
Be verbose when deleting files, showing them as they are removed.
.It Fl W
Attempt to undelete the named files.
Currently, this option can only be used to recover
files covered by whiteouts.
.El
.Pp
The
.Nm
utility removes symbolic links, not the files referenced by the links.
.Pp
It is an error to attempt to remove the files
.Dq .\&
or
.Dq .. .
.Pp
When the utility is called as
.Nm unlink ,
only one argument,
which must not be a directory,
may be supplied.
No options may be supplied in this simple mode of operation,
which performs an
.Xr unlink 2
operation on the passed argument.
.Pp
The
.Nm
utility exits 0 if all of the named files or file hierarchies were removed,
or if the
.Fl f
option was specified and all of the existing files or file hierarchies were
removed.
If an error occurs,
.Nm
exits with a value >0.
.Sh NOTE
The
.Nm
command uses
.Xr getopt 3
to parse its arguments, which allows it to accept
the
.Sq Li --
option which will cause it to stop processing flag options at that
point.  This will allow the removal of file names that begin
with a dash
.Pq Sq - .
For example:
.Dl rm -- -filename
The same behavior can be obtained by using an absolute or relative
path reference.  For example:
.Dl rm /home/user/-filename
.Dl rm ./-filename
.Sh SEE ALSO
.Xr rmdir 1 ,
.Xr undelete 2 ,
.Xr unlink 2 ,
.Xr fts 3 ,
.Xr getopt 3 ,
.Xr symlink 7
.Sh BUGS
The
.Fl P
option assumes that the underlying file system is a fixed-block file
system.  In addition, only regular files are overwritten, other types of files
are not.
.Sh COMPATIBILITY
The
.Nm
utility differs from historical implementations in that the
.Fl f
option only masks attempts to remove non-existent files instead of
masking a large variety of errors.
The
.Fl v
option is non-standard and its use in scripts is not recommended.
.Pp
Also, historical
.Bx
implementations prompted on the standard output,
not the standard error output.
.Sh STANDARDS
The
.Nm
command is almost
.St -p1003.2
compatible, except that
.Tn POSIX
requires
.Nm
to act like
.Xr rmdir 1
when the
.Ar file
specified is a directory.  This implementation requires the
.Fl d
option if such behavior is desired.  This follows the historical
behavior of
.Nm
with respect to directories.
.Pp
The simplified
.Nm unlink
command conforms to
.St -susv2 .
.Sh HISTORY
A
.Nm
command appeared in
.At v1 .
Commit	Line	Data
44a7a5ab A	1	.\" Copyright (c) 1990, 1993, 1994
	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	.\" @(#)rm.1 8.5 (Berkeley) 12/5/94
440bd198	36	.\" $FreeBSD: src/bin/rm/rm.1,v 1.23 2001/07/15 07:49:05 dd Exp $
44a7a5ab	37	.\"
440bd198	38	.Dd January 28, 1999
44a7a5ab A	39	.Dt RM 1
	40	.Os
	41	.Sh NAME
440bd198 A	42	.Nm rm ,
440bd198 A	43	.Nm unlink
44a7a5ab A	44	.Nd remove directory entries
	45	.Sh SYNOPSIS
	46	.Nm
440bd198 A	47	.Op Fl dfiPRrvW
	48	.Ar
	49	.Nm unlink
	50	.Ar file
44a7a5ab A	51	.Sh DESCRIPTION
	52	The
	53	.Nm
	54	utility attempts to remove the non-directory type files specified on the
	55	command line.
	56	If the permissions of the file do not permit writing, and the standard
	57	input device is a terminal, the user is prompted (on the standard error
	58	output) for confirmation.
	59	.Pp
	60	The options are as follows:
440bd198	61	.Bl -tag -width Fl
44a7a5ab A	62	.It Fl d
	63	Attempt to remove directories as well as other types of files.
	64	.It Fl f
	65	Attempt to remove the files without prompting for confirmation,
	66	regardless of the file's permissions.
	67	If the file does not exist, do not display a diagnostic message or modify
	68	the exit status to reflect an error.
	69	The
	70	.Fl f
	71	option overrides any previous
440bd198	72	.Fl i
44a7a5ab A	73	options.
	74	.It Fl i
	75	Request confirmation before attempting to remove each file, regardless of
	76	the file's permissions, or whether or not the standard input device is a
	77	terminal.
	78	The
	79	.Fl i
	80	option overrides any previous
440bd198	81	.Fl f
44a7a5ab A	82	options.
	83	.It Fl P
	84	Overwrite regular files before deleting them.
	85	Files are overwritten three times, first with the byte pattern 0xff,
	86	then 0x00, and then 0xff again, before they are deleted.
	87	.It Fl R
	88	Attempt to remove the file hierarchy rooted in each file argument.
440bd198	89	The
44a7a5ab A	90	.Fl R
	91	option implies the
	92	.Fl d
	93	option.
	94	If the
	95	.Fl i
440bd198	96	option is specified, the user is prompted for confirmation before
44a7a5ab A	97	each directory's contents are processed (as well as before the attempt
	98	is made to remove the directory).
	99	If the user does not respond affirmatively, the file hierarchy rooted in
	100	that directory is skipped.
	101	.Pp
	102	.It Fl r
	103	Equivalent to
	104	.Fl R .
440bd198 A	105	.It Fl v
440bd198 A	106	Be verbose when deleting files, showing them as they are removed.
44a7a5ab	107	.It Fl W
440bd198	108	Attempt to undelete the named files.
44a7a5ab A	109	Currently, this option can only be used to recover
	110	files covered by whiteouts.
	111	.El
	112	.Pp
	113	The
	114	.Nm
	115	utility removes symbolic links, not the files referenced by the links.
	116	.Pp
440bd198 A	117	It is an error to attempt to remove the files
	118	.Dq .\&
	119	or
	120	.Dq .. .
	121	.Pp
	122	When the utility is called as
	123	.Nm unlink ,
	124	only one argument,
	125	which must not be a directory,
	126	may be supplied.
	127	No options may be supplied in this simple mode of operation,
	128	which performs an
	129	.Xr unlink 2
	130	operation on the passed argument.
44a7a5ab A	131	.Pp
	132	The
	133	.Nm
	134	utility exits 0 if all of the named files or file hierarchies were removed,
	135	or if the
	136	.Fl f
	137	option was specified and all of the existing files or file hierarchies were
	138	removed.
	139	If an error occurs,
	140	.Nm
	141	exits with a value >0.
440bd198 A	142	.Sh NOTE
	143	The
	144	.Nm
	145	command uses
	146	.Xr getopt 3
	147	to parse its arguments, which allows it to accept
	148	the
	149	.Sq Li --
	150	option which will cause it to stop processing flag options at that
	151	point. This will allow the removal of file names that begin
	152	with a dash
	153	.Pq Sq - .
	154	For example:
	155	.Dl rm -- -filename
	156	The same behavior can be obtained by using an absolute or relative
	157	path reference. For example:
	158	.Dl rm /home/user/-filename
	159	.Dl rm ./-filename
44a7a5ab A	160	.Sh SEE ALSO
	161	.Xr rmdir 1 ,
	162	.Xr undelete 2 ,
	163	.Xr unlink 2 ,
	164	.Xr fts 3 ,
440bd198	165	.Xr getopt 3 ,
44a7a5ab A	166	.Xr symlink 7
	167	.Sh BUGS
	168	The
	169	.Fl P
	170	option assumes that the underlying file system is a fixed-block file
6c780a1f	171	system. In addition, only regular files are overwritten, other types of files
44a7a5ab A	172	are not.
	173	.Sh COMPATIBILITY
	174	The
	175	.Nm
	176	utility differs from historical implementations in that the
	177	.Fl f
	178	option only masks attempts to remove non-existent files instead of
	179	masking a large variety of errors.
440bd198 A	180	The
	181	.Fl v
	182	option is non-standard and its use in scripts is not recommended.
44a7a5ab A	183	.Pp
	184	Also, historical
	185	.Bx
	186	implementations prompted on the standard output,
	187	not the standard error output.
	188	.Sh STANDARDS
	189	The
	190	.Nm
440bd198	191	command is almost
44a7a5ab	192	.St -p1003.2
440bd198 A	193	compatible, except that
	194	.Tn POSIX
	195	requires
	196	.Nm
	197	to act like
	198	.Xr rmdir 1
	199	when the
	200	.Ar file
	201	specified is a directory. This implementation requires the
	202	.Fl d
	203	option if such behavior is desired. This follows the historical
	204	behavior of
	205	.Nm
	206	with respect to directories.
	207	.Pp
	208	The simplified
	209	.Nm unlink
	210	command conforms to
	211	.St -susv2 .
	212	.Sh HISTORY
	213	A
	214	.Nm
	215	command appeared in
	216	.At v1 .