|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH RMDIR "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
rmdir
|
|
Packit |
7cfc04 |
\(em remove a directory
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <unistd.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
int rmdir(const char *\fIpath\fP);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
function shall remove a directory whose name is given by
|
|
Packit |
7cfc04 |
.IR path .
|
|
Packit |
7cfc04 |
The directory shall be removed only if it is an empty directory.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the directory is the root directory or the current working directory
|
|
Packit |
7cfc04 |
of any process, it is unspecified whether the function succeeds, or
|
|
Packit |
7cfc04 |
whether it shall fail and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to
|
|
Packit |
7cfc04 |
.BR [EBUSY] .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
names a symbolic link, then
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
shall fail and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to
|
|
Packit |
7cfc04 |
.BR [ENOTDIR] .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument refers to a path whose final component is either dot or
|
|
Packit |
7cfc04 |
dot-dot,
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
shall fail.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the directory's link count becomes 0 and no process has the
|
|
Packit |
7cfc04 |
directory open, the space occupied by the directory shall be freed and
|
|
Packit |
7cfc04 |
the directory shall no longer be accessible. If one or more processes
|
|
Packit |
7cfc04 |
have the directory open when the last link is removed, the dot and
|
|
Packit |
7cfc04 |
dot-dot entries, if present, shall be removed before
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
returns and no new entries may be created in the directory, but the
|
|
Packit |
7cfc04 |
directory shall not be removed until all references to the directory
|
|
Packit |
7cfc04 |
are closed.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the directory is not an empty directory,
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
shall fail and set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to
|
|
Packit |
7cfc04 |
.BR [EEXIST]
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR [ENOTEMPTY] .
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Upon successful completion,
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
shall mark for update the last data modification and last file status
|
|
Packit |
7cfc04 |
change timestamps of the parent directory.
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
Upon successful completion, the function
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
shall return 0. Otherwise, \(mi1 shall be returned, and
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
set to indicate the error. If \(mi1 is returned, the named
|
|
Packit |
7cfc04 |
directory shall not be changed.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
function shall fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EACCES
|
|
Packit |
7cfc04 |
Search permission is denied on a component of the path prefix, or write
|
|
Packit |
7cfc04 |
permission is denied on the parent directory of the directory to be
|
|
Packit |
7cfc04 |
removed.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EBUSY
|
|
Packit |
7cfc04 |
The directory to be removed is currently in use by the system or
|
|
Packit |
7cfc04 |
some process and the implementation considers this to be an error.
|
|
Packit |
7cfc04 |
.IP "[EEXIST]\ or\ [ENOTEMPTY]" 12
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument names a directory that is not an empty directory, or there are
|
|
Packit |
7cfc04 |
hard links to the directory other than dot or a single entry in
|
|
Packit |
7cfc04 |
dot-dot.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EINVAL
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument contains a last component that is dot.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EIO
|
|
Packit |
7cfc04 |
A physical I/O error has occurred.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ELOOP
|
|
Packit |
7cfc04 |
A loop exists in symbolic links encountered during resolution of the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENAMETOOLONG
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The length of a component of a pathname is longer than
|
|
Packit |
7cfc04 |
{NAME_MAX}.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOENT
|
|
Packit |
7cfc04 |
A component of
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
does not name an existing file, or the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument names a nonexistent directory or points to an empty string.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENOTDIR
|
|
Packit |
7cfc04 |
A component of
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
names an existing file that is neither a directory nor a symbolic link
|
|
Packit |
7cfc04 |
to a directory.
|
|
Packit |
7cfc04 |
.IP "[EPERM]\ or\ [EACCES]" 12
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The S_ISVTX flag is set on the directory containing the file referred
|
|
Packit |
7cfc04 |
to by the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 4.2" ", " "Directory Protection".
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EROFS
|
|
Packit |
7cfc04 |
The directory entry to be removed resides on a read-only file system.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
function may fail if:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ELOOP
|
|
Packit |
7cfc04 |
More than
|
|
Packit |
7cfc04 |
{SYMLOOP_MAX}
|
|
Packit |
7cfc04 |
symbolic links were encountered during resolution of the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR ENAMETOOLONG
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
The length of a pathname exceeds
|
|
Packit |
7cfc04 |
{PATH_MAX},
|
|
Packit |
7cfc04 |
or pathname resolution of a symbolic link produced an intermediate
|
|
Packit |
7cfc04 |
result with a length that exceeds
|
|
Packit |
7cfc04 |
{PATH_MAX}.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
.SS "Removing a Directory"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The following example shows how to remove a directory named
|
|
Packit |
7cfc04 |
.BR /home/cnd/mod1 .
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
#include <unistd.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
int status;
|
|
Packit |
7cfc04 |
\&...
|
|
Packit |
7cfc04 |
status = rmdir("/home/cnd/mod1");
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIrename\fR()
|
|
Packit |
7cfc04 |
functions originated in 4.2 BSD, and they used
|
|
Packit |
7cfc04 |
.BR [ENOTEMPTY]
|
|
Packit |
7cfc04 |
for the condition when the directory to be removed does not exist or
|
|
Packit |
7cfc04 |
.IR new
|
|
Packit |
7cfc04 |
already exists. When the 1984 /usr/group standard was published, it contained
|
|
Packit |
7cfc04 |
.BR [EEXIST]
|
|
Packit |
7cfc04 |
instead. When these functions were adopted into System V, the
|
|
Packit |
7cfc04 |
1984 /usr/group standard was used as a reference. Therefore, several existing applications
|
|
Packit |
7cfc04 |
and implementations support/use both forms, and no agreement could be
|
|
Packit |
7cfc04 |
reached on either value. All implementations are required to supply
|
|
Packit |
7cfc04 |
both
|
|
Packit |
7cfc04 |
.BR [EEXIST]
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR [ENOTEMPTY]
|
|
Packit |
7cfc04 |
in
|
|
Packit |
7cfc04 |
.IR <errno.h>
|
|
Packit |
7cfc04 |
with distinct values, so that applications can use both values in
|
|
Packit |
7cfc04 |
C-language
|
|
Packit |
7cfc04 |
.BR case
|
|
Packit |
7cfc04 |
statements.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The meaning of deleting
|
|
Packit |
7cfc04 |
.IR pathname \c
|
|
Packit |
7cfc04 |
.BR /dot
|
|
Packit |
7cfc04 |
is unclear, because the name of the file (directory) in the parent
|
|
Packit |
7cfc04 |
directory to be removed is not clear, particularly in the presence of
|
|
Packit |
7cfc04 |
multiple links to a directory.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The POSIX.1\(hy1990 standard was silent with regard to the behavior of
|
|
Packit |
7cfc04 |
\fIrmdir\fR()
|
|
Packit |
7cfc04 |
when there are multiple hard links to the directory being removed. The
|
|
Packit |
7cfc04 |
requirement to set
|
|
Packit |
7cfc04 |
.IR errno
|
|
Packit |
7cfc04 |
to
|
|
Packit |
7cfc04 |
.BR [EEXIST]
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR [ENOTEMPTY]
|
|
Packit |
7cfc04 |
clarifies the behavior in this case.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
If the current working directory of the process is being removed, that
|
|
Packit |
7cfc04 |
should be an allowed error.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Virtually all existing implementations detect
|
|
Packit |
7cfc04 |
.BR [ENOTEMPTY]
|
|
Packit |
7cfc04 |
or the case of dot-dot. The text in
|
|
Packit |
7cfc04 |
.IR "Section 2.3" ", " "Error Numbers"
|
|
Packit |
7cfc04 |
about returning any one of the possible errors permits that behavior to
|
|
Packit |
7cfc04 |
continue. The
|
|
Packit |
7cfc04 |
.BR [ELOOP]
|
|
Packit |
7cfc04 |
error may be returned if more than
|
|
Packit |
7cfc04 |
{SYMLOOP_MAX}
|
|
Packit |
7cfc04 |
symbolic links are encountered during resolution of the
|
|
Packit |
7cfc04 |
.IR path
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "Section 2.3" ", " "Error Numbers",
|
|
Packit |
7cfc04 |
.IR "\fImkdir\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIremove\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIrename\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIunlink\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "Section 4.2" ", " "Directory Protection",
|
|
Packit |
7cfc04 |
.IR "\fB<unistd.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|