man-pages/man1p/rm.1p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "RM" 1P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" rm 
.SH NAME
rm \- remove directory entries
.SH SYNOPSIS
.LP
\fBrm\fP \fB[\fP\fB-fiRr\fP\fB]\fP \fIfile\fP\fB...\fP
.SH DESCRIPTION
.LP
The \fIrm\fP utility shall remove the directory entry specified by
each \fIfile\fP argument.
.LP
If either of the files dot or dot-dot are specified as the basename
portion of an operand (that is, the final pathname
component), \fIrm\fP shall write a diagnostic message to standard
error and do nothing more with such operands.
.LP
For each \fIfile\fP the following steps shall be taken:
.IP " 1." 4
If the \fIfile\fP does not exist:
.RS
.IP " a." 4
If the \fB-f\fP option is not specified, \fIrm\fP shall write a diagnostic
message to standard error.
.LP
.IP " b." 4
Go on to any remaining \fIfiles\fP.
.LP
.RE
.LP
.IP " 2." 4
If \fIfile\fP is of type directory, the following steps shall be taken:
.RS
.IP " a." 4
If neither the \fB-R\fP option nor the \fB-r\fP option is specified,
\fIrm\fP shall write a diagnostic message to standard
error, do nothing more with \fIfile\fP, and go on to any remaining
files.
.LP
.IP " b." 4
If the \fB-f\fP option is not specified, and either the permissions
of \fIfile\fP do not permit writing and the standard input
is a terminal or the \fB-i\fP option is specified, \fIrm\fP shall
write a prompt to standard error and read a line from the
standard input. If the response is not affirmative, \fIrm\fP shall
do nothing more with the current file and go on to any
remaining files.
.LP
.IP " c." 4
For each entry contained in \fIfile\fP, other than dot or dot-dot,
the four steps listed here (1 to 4) shall be taken with the
entry as if it were a \fIfile\fP operand. The \fIrm\fP utility shall
not traverse directories by following symbolic links into
other parts of the hierarchy, but shall remove the links themselves.
.LP
.IP " d." 4
If the \fB-i\fP option is specified, \fIrm\fP shall write a prompt
to standard error and read a line from the standard input.
If the response is not affirmative, \fIrm\fP shall do nothing more
with the current file, and go on to any remaining files.
.LP
.RE
.LP
.IP " 3." 4
If \fIfile\fP is not of type directory, the \fB-f\fP option is not
specified, and either the permissions of \fIfile\fP do not
permit writing and the standard input is a terminal or the \fB-i\fP
option is specified, \fIrm\fP shall write a prompt to the
standard error and read a line from the standard input. If the response
is not affirmative, \fIrm\fP shall do nothing more with
the current file and go on to any remaining files.
.LP
.IP " 4." 4
If the current file is a directory, \fIrm\fP shall perform actions
equivalent to the \fIrmdir\fP() function defined in the System Interfaces
volume of IEEE\ Std\ 1003.1-2001
called with a pathname of the current file used as the \fIpath\fP
argument. If the current file is not a directory, \fIrm\fP
shall perform actions equivalent to the \fIunlink\fP() function defined
in the System
Interfaces volume of IEEE\ Std\ 1003.1-2001 called with a pathname
of the current file used as the \fIpath\fP
argument.
.LP
If this fails for any reason, \fIrm\fP shall write a diagnostic message
to standard error, do nothing more with the current
file, and go on to any remaining files.
.LP
.LP
The \fIrm\fP utility shall be able to descend to arbitrary depths
in a file hierarchy, and shall not fail due to path length
limitations (unless an operand specified by the user exceeds system
limitations).
.SH OPTIONS
.LP
The \fIrm\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-f\fP
Do not prompt for confirmation. Do not write diagnostic messages or
modify the exit status in the case of nonexistent operands.
Any previous occurrences of the \fB-i\fP option shall be ignored.
.TP 7
\fB-i\fP
Prompt for confirmation as described previously. Any previous occurrences
of the \fB-f\fP option shall be ignored.
.TP 7
\fB-R\fP
Remove file hierarchies. See the DESCRIPTION.
.TP 7
\fB-r\fP
Equivalent to \fB-R\fP.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
A pathname of a directory entry to be removed.
.sp
.SH STDIN
.LP
The standard input shall be used to read an input line in response
to each prompt specified in the STDOUT section. Otherwise,
the standard input shall not be used.
.SH INPUT FILES
.LP
None.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fIrm\fP:
.TP 7
\fILANG\fP
Provide a default value for the internationalization variables that
are unset or null. (See the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
for
the precedence of internationalization variables used to determine
the values of locale categories.)
.TP 7
\fILC_ALL\fP
If set to a non-empty string value, override the values of all the
other internationalization variables.
.TP 7
\fILC_COLLATE\fP
.sp
Determine the locale for the behavior of ranges, equivalence classes,
and multi-character collating elements used in the extended
regular expression defined for the \fByesexpr\fP locale keyword in
the \fILC_MESSAGES\fP category.
.TP 7
\fILC_CTYPE\fP
Determine the locale for the interpretation of sequences of bytes
of text data as characters (for example, single-byte as
opposed to multi-byte characters in arguments) and the behavior of
character classes within regular expressions used in the
extended regular expression defined for the \fByesexpr\fP locale keyword
in the \fILC_MESSAGES\fP category.
.TP 7
\fILC_MESSAGES\fP
Determine the locale for the processing of affirmative responses that
should be used to affect the format and contents of
diagnostic messages written to standard error.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
Not used.
.SH STDERR
.LP
Prompts shall be written to standard error under the conditions specified
in the DESCRIPTION and OPTIONS sections. The prompts
shall contain the \fIfile\fP pathname, but their format is otherwise
unspecified. The standard error also shall be used for
diagnostic messages.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
None.
.SH EXIT STATUS
.LP
The following exit values shall be returned:
.TP 7
\ 0
All of the named directory entries for which \fIrm\fP performed actions
equivalent to the \fIrmdir\fP() or \fIunlink\fP() functions were removed.
.TP 7
>0
An error occurred.
.sp
.SH CONSEQUENCES OF ERRORS
.LP
Default.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
The \fIrm\fP utility is forbidden to remove the names dot and dot-dot
in order to avoid the consequences of inadvertently doing
something like:
.sp
.RS
.nf

\fBrm -r .*
\fP
.fi
.RE
.LP
Some implementations do not permit the removal of the last link to
an executable binary file that is being executed; see the
[EBUSY] error in the \fIunlink\fP() function defined in the System
Interfaces volume of
IEEE\ Std\ 1003.1-2001. Thus, the \fIrm\fP utility can fail to remove
such files.
.LP
The \fB-i\fP option causes \fIrm\fP to prompt and read the standard
input even if the standard input is not a terminal, but in
the absence of \fB-i\fP the mode prompting is not done when the standard
input is not a terminal.
.SH EXAMPLES
.IP " 1." 4
The following command:
.sp
.RS
.nf

\fBrm a.out core
\fP
.fi
.RE
.LP
removes the directory entries: \fBa.out\fP and \fBcore\fP.
.LP
.IP " 2." 4
The following command:
.sp
.RS
.nf

\fBrm -Rf junk
\fP
.fi
.RE
.LP
removes the directory \fBjunk\fP and all its contents, without prompting.
.LP
.SH RATIONALE
.LP
For absolute clarity, paragraphs (2b) and (3) in the DESCRIPTION of
\fIrm\fP describing the behavior when prompting for
confirmation, should be interpreted in the following manner:
.sp
.RS
.nf

\fBif ((NOT f_option) AND
    ((not_writable AND input_is_terminal) OR i_option))
\fP
.fi
.RE
.LP
The exact format of the interactive prompts is unspecified. Only the
general nature of the contents of prompts are specified
because implementations may desire more descriptive prompts than those
used on historical implementations. Therefore, an
application not using the \fB-f\fP option, or using the \fB-i\fP option,
relies on the system to provide the most suitable dialog
directly with the user, based on the behavior specified.
.LP
The \fB-r\fP option is historical practice on all known systems. The
synonym \fB-R\fP option is provided for consistency with
the other utilities in this volume of IEEE\ Std\ 1003.1-2001 that
provide options requesting recursive descent through the
file hierarchy.
.LP
The behavior of the \fB-f\fP option in historical versions of \fIrm\fP
is inconsistent. In general, along with "forcing" the
unlink without prompting for permission, it always causes diagnostic
messages to be suppressed and the exit status to be unmodified
for nonexistent operands and files that cannot be unlinked. In some
versions, however, the \fB-f\fP option suppresses usage
messages and system errors as well. Suppressing such messages is not
a service to either shell scripts or users.
.LP
It is less clear that error messages regarding files that cannot be
unlinked (removed) should be suppressed. Although this is
historical practice, this volume of IEEE\ Std\ 1003.1-2001 does not
permit the \fB-f\fP option to suppress such
messages.
.LP
When given the \fB-r\fP and \fB-i\fP options, historical versions
of \fIrm\fP prompt the user twice for each directory, once
before removing its contents and once before actually attempting to
delete the directory entry that names it. This allows the user
to "prune" the file hierarchy walk. Historical versions of \fIrm\fP
were inconsistent in that some did not do the former prompt
for directories named on the command line and others had obscure prompting
behavior when the \fB-i\fP option was specified and the
permissions of the file did not permit writing. The POSIX Shell and
Utilities \fIrm\fP differs little from historic practice, but
does require that prompts be consistent. Historical versions of \fIrm\fP
were also inconsistent in that prompts were done to both
standard output and standard error. This volume of IEEE\ Std\ 1003.1-2001
requires that prompts be done to standard error,
for consistency with \fIcp\fP and \fImv\fP, and to allow
historical extensions to \fIrm\fP that provide an option to list deleted
files on standard output.
.LP
The \fIrm\fP utility is required to descend to arbitrary depths so
that any file hierarchy may be deleted. This means, for
example, that the \fIrm\fP utility cannot run out of file descriptors
during its descent (that is, if the number of file
descriptors is limited, \fIrm\fP cannot be implemented in the historical
fashion where one file descriptor is used per directory
level). Also, \fIrm\fP is not permitted to fail because of path length
restrictions, unless an operand specified by the user is
longer than {PATH_MAX}.
.LP
The \fIrm\fP utility removes symbolic links themselves, not the files
they refer to, as a consequence of the dependence on the
\fIunlink\fP() functionality, per the DESCRIPTION. When removing hierarchies
with \fB-r\fP
or \fB-R\fP, the prohibition on following symbolic links has to be
made explicit.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIrmdir\fP() , the System Interfaces volume of IEEE\ Std\ 1003.1-2001,
\fIremove\fP(), \fIrmdir\fP(), \fIunlink\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .