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.\" $FreeBSD$ 30.\" 31.Dd April 6, 2019 32.Dt UNLINK 2 33.Os 34.Sh NAME 35.Nm unlink , 36.Nm unlinkat 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_BENEATH 95Only unlink files and directories which are beneath of the topping 96directory. 97See the description of the 98.Dv O_BENEATH 99flag in the 100.Xr open 2 101manual page. 102.El 103.Pp 104If 105.Fn unlinkat 106is passed the special value 107.Dv AT_FDCWD 108in the 109.Fa fd 110parameter, the current working directory is used and the behavior is 111identical to a call to 112.Fa unlink 113or 114.Fa rmdir 115respectively, depending on whether or not the 116.Dv AT_REMOVEDIR 117bit is set in flag. 118.Pp 119The 120.Fn funlinkat 121system call can be used to unlink an already-opened file, unless that 122file has been replaced since it was opened. 123It is equivalent to 124.Fn unlinkat 125in the case where 126.Fa path 127is already open as the file descriptor 128.Fa fd . 129Otherwise, the path will not be removed and an error will be returned. 130The 131.Fa fd 132can be set the 133.Dv FD_NONE . 134In that case 135.Fn funlinkat 136behaves exactly like 137.Fn unlinkat . 138.Sh RETURN VALUES 139.Rv -std unlink 140.Sh ERRORS 141The 142.Fn unlink 143succeeds unless: 144.Bl -tag -width Er 145.It Bq Er ENOTDIR 146A component of the path prefix is not a directory. 147.It Bq Er EISDIR 148The named file is a directory. 149.It Bq Er ENAMETOOLONG 150A component of a pathname exceeded 255 characters, 151or an entire path name exceeded 1023 characters. 152.It Bq Er ENOENT 153The named file does not exist. 154.It Bq Er EACCES 155Search permission is denied for a component of the path prefix. 156.It Bq Er EACCES 157Write permission is denied on the directory containing the link 158to be removed. 159.It Bq Er ELOOP 160Too many symbolic links were encountered in translating the pathname. 161.It Bq Er EPERM 162The named file is a directory. 163.It Bq Er EPERM 164The named file has its immutable, undeletable or append-only flag set, see the 165.Xr chflags 2 166manual page for more information. 167.It Bq Er EPERM 168The parent directory of the named file has its immutable or append-only flag 169set. 170.It Bq Er EPERM 171The directory containing the file is marked sticky, 172and neither the containing directory nor the file to be removed 173are owned by the effective user ID. 174.It Bq Er EIO 175An I/O error occurred while deleting the directory entry 176or deallocating the inode. 177.It Bq Er EROFS 178The named file resides on a read-only file system. 179.It Bq Er EFAULT 180The 181.Fa path 182argument 183points outside the process's allocated address space. 184.It Bq Er ENOSPC 185On file systems supporting copy-on-write or snapshots, there was not enough 186free space to record metadata for the delete operation of the file. 187.El 188.Pp 189In addition to the errors returned by the 190.Fn unlink , 191the 192.Fn unlinkat 193may fail if: 194.Bl -tag -width Er 195.It Bq Er EBADF 196The 197.Fa path 198argument does not specify an absolute path and the 199.Fa fd 200argument is neither 201.Dv AT_FDCWD 202nor a valid file descriptor open for searching. 203.It Bq Er ENOTEMPTY 204The 205.Fa flag 206parameter has the 207.Dv AT_REMOVEDIR 208bit set and the 209.Fa path 210argument names a directory that is not an empty directory, 211or there are hard links to the directory other than dot or 212a single entry in dot-dot. 213.It Bq Er ENOTDIR 214The 215.Fa flag 216parameter has the 217.Dv AT_REMOVEDIR 218bit set and 219.Fa path 220does not name a directory. 221.It Bq Er EINVAL 222The value of the 223.Fa flag 224argument is not valid. 225.It Bq Er ENOTDIR 226The 227.Fa path 228argument is not an absolute path and 229.Fa fd 230is neither 231.Dv AT_FDCWD 232nor a file descriptor associated with a directory. 233.It Bq Er ENOTCAPABLE 234.Fa path 235is an absolute path, 236or contained a ".." component leading to a 237directory outside of the directory hierarchy specified by 238.Fa fd , 239and the process is in capability mode. 240.It Bq Er ENOTCAPABLE 241The 242.Dv AT_BENEATH 243flag was provided to 244.Fn unlinkat , 245and the absolute 246.Fa path 247does not have its tail fully contained under the topping directory, 248or the relative 249.Fa path 250escapes it. 251.El 252.Pp 253In addition to the errors returned by 254.Fn unlinkat , 255.Fn funlinkat 256may fail if: 257.Bl -tag -width Er 258.It Bq Er EDEADLK 259The file descriptor is not associated with the path. 260.El 261.Sh SEE ALSO 262.Xr chflags 2 , 263.Xr close 2 , 264.Xr link 2 , 265.Xr rmdir 2 , 266.Xr symlink 7 267.Sh STANDARDS 268The 269.Fn unlinkat 270system call follows The Open Group Extended API Set 2 specification. 271.Sh HISTORY 272The 273.Fn unlink 274function appeared in 275.At v1 . 276The 277.Fn unlinkat 278system call appeared in 279.Fx 8.0 . 280The 281.Fn funlinkat 282system call appeared in 283.Fx 13.0 . 284.Pp 285The 286.Fn unlink 287system call traditionally allows the super-user to unlink directories which 288can damage the file system integrity. 289This implementation no longer permits it. 290