logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

rmdir.3p (7096B)


  1. '\" et
  2. .TH RMDIR "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. rmdir
  12. \(em remove a directory
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int rmdir(const char *\fIpath\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIrmdir\fR()
  23. function shall remove a directory whose name is given by
  24. .IR path .
  25. The directory shall be removed only if it is an empty directory.
  26. .P
  27. If the directory is the root directory or the current working directory
  28. of any process, it is unspecified whether the function succeeds, or
  29. whether it shall fail and set
  30. .IR errno
  31. to
  32. .BR [EBUSY] .
  33. .P
  34. If
  35. .IR path
  36. names a symbolic link, then
  37. \fIrmdir\fR()
  38. shall fail and set
  39. .IR errno
  40. to
  41. .BR [ENOTDIR] .
  42. .P
  43. If the
  44. .IR path
  45. argument refers to a path whose final component is either dot or
  46. dot-dot,
  47. \fIrmdir\fR()
  48. shall fail.
  49. .P
  50. If the directory's link count becomes 0 and no process has the
  51. directory open, the space occupied by the directory shall be freed and
  52. the directory shall no longer be accessible. If one or more processes
  53. have the directory open when the last link is removed, the dot and
  54. dot-dot entries, if present, shall be removed before
  55. \fIrmdir\fR()
  56. returns and no new entries may be created in the directory, but the
  57. directory shall not be removed until all references to the directory
  58. are closed.
  59. .P
  60. If the directory is not an empty directory,
  61. \fIrmdir\fR()
  62. shall fail and set
  63. .IR errno
  64. to
  65. .BR [EEXIST]
  66. or
  67. .BR [ENOTEMPTY] .
  68. .P
  69. Upon successful completion,
  70. \fIrmdir\fR()
  71. shall mark for update the last data modification and last file status
  72. change timestamps of the parent directory.
  73. .SH "RETURN VALUE"
  74. Upon successful completion, the function
  75. \fIrmdir\fR()
  76. shall return 0. Otherwise, \-1 shall be returned, and
  77. .IR errno
  78. set to indicate the error. If \-1 is returned, the named
  79. directory shall not be changed.
  80. .SH ERRORS
  81. The
  82. \fIrmdir\fR()
  83. function shall fail if:
  84. .TP
  85. .BR EACCES
  86. Search permission is denied on a component of the path prefix, or write
  87. permission is denied on the parent directory of the directory to be
  88. removed.
  89. .TP
  90. .BR EBUSY
  91. The directory to be removed is currently in use by the system or
  92. some process and the implementation considers this to be an error.
  93. .IP "[EEXIST]\ or\ [ENOTEMPTY]" 12
  94. .br
  95. The
  96. .IR path
  97. argument names a directory that is not an empty directory, or there are
  98. hard links to the directory other than dot or a single entry in
  99. dot-dot.
  100. .TP
  101. .BR EINVAL
  102. The
  103. .IR path
  104. argument contains a last component that is dot.
  105. .TP
  106. .BR EIO
  107. A physical I/O error has occurred.
  108. .TP
  109. .BR ELOOP
  110. A loop exists in symbolic links encountered during resolution of the
  111. .IR path
  112. argument.
  113. .TP
  114. .BR ENAMETOOLONG
  115. .br
  116. The length of a component of a pathname is longer than
  117. {NAME_MAX}.
  118. .TP
  119. .BR ENOENT
  120. A component of
  121. .IR path
  122. does not name an existing file, or the
  123. .IR path
  124. argument names a nonexistent directory or points to an empty string.
  125. .TP
  126. .BR ENOTDIR
  127. A component of
  128. .IR path
  129. names an existing file that is neither a directory nor a symbolic link
  130. to a directory.
  131. .IP "[EPERM]\ or\ [EACCES]" 12
  132. .br
  133. The S_ISVTX flag is set on the directory containing the file referred
  134. to by the
  135. .IR path
  136. argument and the process does not satisfy the criteria specified in the Base Definitions volume of POSIX.1\(hy2017,
  137. .IR "Section 4.3" ", " "Directory Protection".
  138. .TP
  139. .BR EROFS
  140. The directory entry to be removed resides on a read-only file system.
  141. .P
  142. The
  143. \fIrmdir\fR()
  144. function may fail if:
  145. .TP
  146. .BR ELOOP
  147. More than
  148. {SYMLOOP_MAX}
  149. symbolic links were encountered during resolution of the
  150. .IR path
  151. argument.
  152. .TP
  153. .BR ENAMETOOLONG
  154. .br
  155. The length of a pathname exceeds
  156. {PATH_MAX},
  157. or pathname resolution of a symbolic link produced an intermediate
  158. result with a length that exceeds
  159. {PATH_MAX}.
  160. .LP
  161. .IR "The following sections are informative."
  162. .SH EXAMPLES
  163. .SS "Removing a Directory"
  164. .P
  165. The following example shows how to remove a directory named
  166. .BR /home/cnd/mod1 .
  167. .sp
  168. .RS 4
  169. .nf
  170. #include <unistd.h>
  171. .P
  172. int status;
  173. \&...
  174. status = rmdir("/home/cnd/mod1");
  175. .fi
  176. .P
  177. .RE
  178. .SH "APPLICATION USAGE"
  179. None.
  180. .SH RATIONALE
  181. The
  182. \fIrmdir\fR()
  183. and
  184. \fIrename\fR()
  185. functions originated in 4.2 BSD, and they used
  186. .BR [ENOTEMPTY]
  187. for the condition when the directory to be removed does not exist or
  188. .IR new
  189. already exists. When the 1984 /usr/group standard was published, it contained
  190. .BR [EEXIST]
  191. instead. When these functions were adopted into System V, the
  192. 1984 /usr/group standard was used as a reference. Therefore, several existing applications
  193. and implementations support/use both forms, and no agreement could be
  194. reached on either value. All implementations are required to supply
  195. both
  196. .BR [EEXIST]
  197. and
  198. .BR [ENOTEMPTY]
  199. in
  200. .IR <errno.h>
  201. with distinct values, so that applications can use both values in
  202. C-language
  203. .BR case
  204. statements.
  205. .P
  206. The meaning of deleting
  207. .IR pathname \c
  208. .BR /dot
  209. is unclear, because the name of the file (directory) in the parent
  210. directory to be removed is not clear, particularly in the presence of
  211. multiple links to a directory.
  212. .P
  213. The POSIX.1\(hy1990 standard was silent with regard to the behavior of
  214. \fIrmdir\fR()
  215. when there are multiple hard links to the directory being removed. The
  216. requirement to set
  217. .IR errno
  218. to
  219. .BR [EEXIST]
  220. or
  221. .BR [ENOTEMPTY]
  222. clarifies the behavior in this case.
  223. .P
  224. If the current working directory of the process is being removed, that
  225. should be an allowed error.
  226. .P
  227. Virtually all existing implementations detect
  228. .BR [ENOTEMPTY]
  229. or the case of dot-dot. The text in
  230. .IR "Section 2.3" ", " "Error Numbers"
  231. about returning any one of the possible errors permits that behavior to
  232. continue. The
  233. .BR [ELOOP]
  234. error may be returned if more than
  235. {SYMLOOP_MAX}
  236. symbolic links are encountered during resolution of the
  237. .IR path
  238. argument.
  239. .SH "FUTURE DIRECTIONS"
  240. None.
  241. .SH "SEE ALSO"
  242. .IR "Section 2.3" ", " "Error Numbers",
  243. .IR "\fImkdir\fR\^(\|)",
  244. .IR "\fIremove\fR\^(\|)",
  245. .IR "\fIrename\fR\^(\|)",
  246. .IR "\fIunlink\fR\^(\|)"
  247. .P
  248. The Base Definitions volume of POSIX.1\(hy2017,
  249. .IR "Section 4.3" ", " "Directory Protection",
  250. .IR "\fB<unistd.h>\fP"
  251. .\"
  252. .SH COPYRIGHT
  253. Portions of this text are reprinted and reproduced in electronic form
  254. from IEEE Std 1003.1-2017, Standard for Information Technology
  255. -- Portable Operating System Interface (POSIX), The Open Group Base
  256. Specifications Issue 7, 2018 Edition,
  257. Copyright (C) 2018 by the Institute of
  258. Electrical and Electronics Engineers, Inc and The Open Group.
  259. In the event of any discrepancy between this version and the original IEEE and
  260. The Open Group Standard, the original IEEE and The Open Group Standard
  261. is the referee document. The original Standard can be obtained online at
  262. http://www.opengroup.org/unix/online.html .
  263. .PP
  264. Any typographical or formatting errors that appear
  265. in this page are most likely
  266. to have been introduced during the conversion of the source files to
  267. man page format. To report such errors, see
  268. https://www.kernel.org/doc/man-pages/reporting_bugs.html .