1RMDIR(P) POSIX Programmer's Manual RMDIR(P)
2
6 rmdir - remove a directory
7
9 #include <unistd.h>
10 int rmdir(const char *path);
12
15 The rmdir() function shall remove a directory whose name is given by
16 path. The directory shall be removed only if it is an empty directory.
17 If the directory is the root directory or the current working directory
19 of any process, it is unspecified whether the function succeeds, or
20 whether it shall fail and set errno to [EBUSY].
21 If path names a symbolic link, then rmdir() shall fail and set errno to
23 [ENOTDIR].
24 If the path argument refers to a path whose final component is either
26 dot or dot-dot, rmdir() shall fail.
27 If the directory's link count becomes 0 and no process has the direc‐
29 tory open, the space occupied by the directory shall be freed and the
30 directory shall no longer be accessible. If one or more processes have
31 the directory open when the last link is removed, the dot and dot-dot
32 entries, if present, shall be removed before rmdir() returns and no new
33 entries may be created in the directory, but the directory shall not be
34 removed until all references to the directory are closed.
35 If the directory is not an empty directory, rmdir() shall fail and set
37 errno to [EEXIST] or [ENOTEMPTY].
38 Upon successful completion, the rmdir() function shall mark for update
40 the st_ctime and st_mtime fields of the parent directory.
41
43 Upon successful completion, the function rmdir() shall return 0. Other‐
44 wise, -1 shall be returned, and errno set to indicate the error. If -1
45 is returned, the named directory shall not be changed.
46
48 The rmdir() function shall fail if:
49 EACCES Search permission is denied on a component of the path prefix,
51 or write permission is denied on the parent directory of the
52 directory to be removed.
53 EBUSY The directory to be removed is currently in use by the system or
55 some process and the implementation considers this to be an
56 error.
57 EEXIST or ENOTEMPTY
59 The path argument names a directory that is not an empty direc‐
60 tory, or there are hard links to the directory other than dot or
61 a single entry in dot-dot.
62 EINVAL The path argument contains a last component that is dot.
64 EIO A physical I/O error has occurred.
66 ELOOP A loop exists in symbolic links encountered during resolution of
68 the path argument.
69 ENAMETOOLONG
71 The length of the path argument exceeds {PATH_MAX} or a pathname
72 component is longer than {NAME_MAX}.
73 ENOENT A component of path does not name an existing file, or the path
75 argument names a nonexistent directory or points to an empty
76 string.
77 ENOTDIR
79 A component of path is not a directory.
80 EPERM or EACCES
82 The S_ISVTX flag is set on the parent directory of the directory
84 to be removed and the caller is not the owner of the directory
85 to be removed, nor is the caller the owner of the parent direc‐
86 tory, nor does the caller have the appropriate privileges.
87 EROFS The directory entry to be removed resides on a read-only file
89 system.
90 The rmdir() function may fail if:
93 ELOOP More than {SYMLOOP_MAX} symbolic links were encountered during
95 resolution of the path argument.
96 ENAMETOOLONG
98 As a result of encountering a symbolic link in resolution of the
99 path argument, the length of the substituted pathname string
100 exceeded {PATH_MAX}.
101 The following sections are informative.
104
106 Removing a Directory
107 The following example shows how to remove a directory named
108 /home/cnd/mod1.
109 #include <unistd.h>
112 int status;
115 ...
116 status = rmdir("/home/cnd/mod1");
117
119 None.
120
122 The rmdir() and rename() functions originated in 4.2 BSD, and they used
123 [ENOTEMPTY] for the condition when the directory to be removed does not
124 exist or new already exists. When the 1984 /usr/group standard was pub‐
125 lished, it contained [EEXIST] instead. When these functions were
126 adopted into System V, the 1984 /usr/group standard was used as a ref‐
127 erence. Therefore, several existing applications and implementations
128 support/use both forms, and no agreement could be reached on either
129 value. All implementations are required to supply both [EEXIST] and
130 [ENOTEMPTY] in <errno.h> with distinct values, so that applications can
131 use both values in C-language case statements.
132 The meaning of deleting pathname /dot is unclear, because the name of
134 the file (directory) in the parent directory to be removed is not
135 clear, particularly in the presence of multiple links to a directory.
136 The POSIX.1-1990 standard was silent with regard to the behavior of
138 rmdir() when there are multiple hard links to the directory being
139 removed. The requirement to set errno to [EEXIST] or [ENOTEMPTY] clari‐
140 fies the behavior in this case.
141 If the process' current working directory is being removed, that should
143 be an allowed error.
144 Virtually all existing implementations detect [ENOTEMPTY] or the case
146 of dot-dot. The text in Error Numbers about returning any one of the
147 possible errors permits that behavior to continue. The [ELOOP] error
148 may be returned if more than {SYMLOOP_MAX} symbolic links are encoun‐
149 tered during resolution of the path argument.
150
152 None.
153
155 Error Numbers , mkdir() , remove() , unlink() , the Base Definitions
156 volume of IEEE Std 1003.1-2001, <unistd.h>
157
159 Portions of this text are reprinted and reproduced in electronic form
160 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
161 -- Portable Operating System Interface (POSIX), The Open Group Base
162 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
163 Electrical and Electronics Engineers, Inc and The Open Group. In the
164 event of any discrepancy between this version and the original IEEE and
165 The Open Group Standard, the original IEEE and The Open Group Standard
166 is the referee document. The original Standard can be obtained online
167 at http://www.opengroup.org/unix/online.html .
168IEEE/The Open Group 2003 RMDIR(P)