1.\" Copyright (c) 1980, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93 29.\" 30.Dd February 23, 2021 31.Dt UNLINK 2 32.Os 33.Sh NAME 34.Nm unlink , 35.Nm unlinkat , 36.Nm funlinkat 37.Nd remove directory entry 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn unlink "const char *path" 44.Ft int 45.Fn unlinkat "int dfd" "const char *path" "int flag" 46.Ft int 47.Fn funlinkat "int dfd" "const char *path" "int fd" "int flag" 48.Sh DESCRIPTION 49The 50.Fn unlink 51system call 52removes the link named by 53.Fa path 54from its directory and decrements the link count of the 55file which was referenced by the link. 56If that decrement reduces the link count of the file 57to zero, 58and no process has the file open, then 59all resources associated with the file are reclaimed. 60If one or more process have the file open when the last link is removed, 61the link is removed, but the removal of the file is delayed until 62all references to it have been closed. 63The 64.Fa path 65argument 66may not be a directory. 67.Pp 68The 69.Fn unlinkat 70system call is equivalent to 71.Fn unlink 72or 73.Fn rmdir 74except in the case where 75.Fa path 76specifies a relative path. 77In this case the directory entry to be removed is determined 78relative to the directory associated with the file descriptor 79.Fa dfd 80instead of the current working directory. 81.Pp 82The values for 83.Fa flag 84are constructed by a bitwise-inclusive OR of flags from the following list, 85defined in 86.In fcntl.h : 87.Bl -tag -width indent 88.It Dv AT_REMOVEDIR 89Remove the directory entry specified by 90.Fa fd 91and 92.Fa path 93as a directory, not a normal file. 94.It Dv AT_RESOLVE_BENEATH 95Only walk paths below the directory specified by the 96.Ar fd 97descriptor. 98See the description of the 99.Dv O_RESOLVE_BENEATH 100flag in the 101.Xr open 2 102manual page. 103.El 104.Pp 105If 106.Fn unlinkat 107is passed the special value 108.Dv AT_FDCWD 109in the 110.Fa fd 111parameter, the current working directory is used and the behavior is 112identical to a call to 113.Fa unlink 114or 115.Fa rmdir 116respectively, depending on whether or not the 117.Dv AT_REMOVEDIR 118bit is set in flag. 119.Pp 120The 121.Fn funlinkat 122system call can be used to unlink an already-opened file, unless that 123file has been replaced since it was opened. 124It is equivalent to 125.Fn unlinkat 126in the case where 127.Fa path 128is already open as the file descriptor 129.Fa fd . 130Otherwise, the path will not be removed and an error will be returned. 131The 132.Fa fd 133can be set the 134.Dv FD_NONE . 135In that case 136.Fn funlinkat 137behaves exactly like 138.Fn unlinkat . 139.Sh RETURN VALUES 140.Rv -std unlink 141.Sh ERRORS 142The 143.Fn unlink 144succeeds unless: 145.Bl -tag -width Er 146.It Bq Er ENOTDIR 147A component of the path prefix is not a directory. 148.It Bq Er EISDIR 149The named file is a directory. 150.It Bq Er ENAMETOOLONG 151A component of a pathname exceeded 255 characters, 152or an entire path name exceeded 1023 characters. 153.It Bq Er ENOENT 154The named file does not exist. 155.It Bq Er EACCES 156Search permission is denied for a component of the path prefix. 157.It Bq Er EACCES 158Write permission is denied on the directory containing the link 159to be removed. 160.It Bq Er ELOOP 161Too many symbolic links were encountered in translating the pathname. 162.It Bq Er EPERM 163The named file is a directory. 164.It Bq Er EPERM 165The named file has its immutable, undeletable or append-only flag set, see the 166.Xr chflags 2 167manual page for more information. 168.It Bq Er EPERM 169The parent directory of the named file has its immutable or append-only flag 170set. 171.It Bq Er EPERM 172The directory containing the file is marked sticky, 173and neither the containing directory nor the file to be removed 174are owned by the effective user ID. 175.It Bq Er EIO 176An I/O error occurred while deleting the directory entry 177or deallocating the inode. 178.It Bq Er EINTEGRITY 179Corrupted data was detected while reading from the file system. 180.It Bq Er EROFS 181The named file resides on a read-only file system. 182.It Bq Er EFAULT 183The 184.Fa path 185argument 186points outside the process's allocated address space. 187.It Bq Er ENOSPC 188On file systems supporting copy-on-write or snapshots, there was not enough 189free space to record metadata for the delete operation of the file. 190.El 191.Pp 192In addition to the errors returned by the 193.Fn unlink , 194the 195.Fn unlinkat 196may fail if: 197.Bl -tag -width Er 198.It Bq Er EBADF 199The 200.Fa path 201argument does not specify an absolute path and the 202.Fa fd 203argument is neither 204.Dv AT_FDCWD 205nor a valid file descriptor open for searching. 206.It Bq Er ENOTEMPTY 207The 208.Fa flag 209parameter has the 210.Dv AT_REMOVEDIR 211bit set and the 212.Fa path 213argument names a directory that is not an empty directory, 214or there are hard links to the directory other than dot or 215a single entry in dot-dot. 216.It Bq Er ENOTDIR 217The 218.Fa flag 219parameter has the 220.Dv AT_REMOVEDIR 221bit set and 222.Fa path 223does not name a directory. 224.It Bq Er EINVAL 225The value of the 226.Fa flag 227argument is not valid. 228.It Bq Er ENOTDIR 229The 230.Fa path 231argument is not an absolute path and 232.Fa fd 233is neither 234.Dv AT_FDCWD 235nor a file descriptor associated with a directory. 236.It Bq Er ENOTCAPABLE 237.Fa path 238is an absolute path, 239or contained a ".." component leading to a 240directory outside of the directory hierarchy specified by 241.Fa fd , 242and the process is in capability mode or the 243.Dv AT_RESOLVE_BENEATH 244flag was specified. 245.El 246.Pp 247In addition to the errors returned by 248.Fn unlinkat , 249.Fn funlinkat 250may fail if: 251.Bl -tag -width Er 252.It Bq Er EDEADLK 253The file descriptor is not associated with the path. 254.El 255.Sh SEE ALSO 256.Xr chflags 2 , 257.Xr close 2 , 258.Xr link 2 , 259.Xr rmdir 2 , 260.Xr symlink 7 261.Sh STANDARDS 262The 263.Fn unlinkat 264system call follows The Open Group Extended API Set 2 specification. 265.Sh HISTORY 266The 267.Fn unlink 268function appeared in 269.At v1 . 270The 271.Fn unlinkat 272system call appeared in 273.Fx 8.0 . 274The 275.Fn funlinkat 276system call appeared in 277.Fx 13.0 . 278.Pp 279The 280.Fn unlink 281system call traditionally allows the super-user to unlink directories which 282can damage the file system integrity. 283This implementation no longer permits it. 284