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 February 23, 2021 32.Dt UNLINK 2 33.Os 34.Sh NAME 35.Nm unlink , 36.Nm unlinkat , 37.Nm funlinkat 38.Nd remove directory entry 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft int 44.Fn unlink "const char *path" 45.Ft int 46.Fn unlinkat "int dfd" "const char *path" "int flag" 47.Ft int 48.Fn funlinkat "int dfd" "const char *path" "int fd" "int flag" 49.Sh DESCRIPTION 50The 51.Fn unlink 52system call 53removes the link named by 54.Fa path 55from its directory and decrements the link count of the 56file which was referenced by the link. 57If that decrement reduces the link count of the file 58to zero, 59and no process has the file open, then 60all resources associated with the file are reclaimed. 61If one or more process have the file open when the last link is removed, 62the link is removed, but the removal of the file is delayed until 63all references to it have been closed. 64The 65.Fa path 66argument 67may not be a directory. 68.Pp 69The 70.Fn unlinkat 71system call is equivalent to 72.Fn unlink 73or 74.Fn rmdir 75except in the case where 76.Fa path 77specifies a relative path. 78In this case the directory entry to be removed is determined 79relative to the directory associated with the file descriptor 80.Fa dfd 81instead of the current working directory. 82.Pp 83The values for 84.Fa flag 85are constructed by a bitwise-inclusive OR of flags from the following list, 86defined in 87.In fcntl.h : 88.Bl -tag -width indent 89.It Dv AT_REMOVEDIR 90Remove the directory entry specified by 91.Fa fd 92and 93.Fa path 94as a directory, not a normal file. 95.It Dv AT_RESOLVE_BENEATH 96Only walk paths below the directory specified by the 97.Ar fd 98descriptor. 99See the description of the 100.Dv O_RESOLVE_BENEATH 101flag in the 102.Xr open 2 103manual page. 104.El 105.Pp 106If 107.Fn unlinkat 108is passed the special value 109.Dv AT_FDCWD 110in the 111.Fa fd 112parameter, the current working directory is used and the behavior is 113identical to a call to 114.Fa unlink 115or 116.Fa rmdir 117respectively, depending on whether or not the 118.Dv AT_REMOVEDIR 119bit is set in flag. 120.Pp 121The 122.Fn funlinkat 123system call can be used to unlink an already-opened file, unless that 124file has been replaced since it was opened. 125It is equivalent to 126.Fn unlinkat 127in the case where 128.Fa path 129is already open as the file descriptor 130.Fa fd . 131Otherwise, the path will not be removed and an error will be returned. 132The 133.Fa fd 134can be set the 135.Dv FD_NONE . 136In that case 137.Fn funlinkat 138behaves exactly like 139.Fn unlinkat . 140.Sh RETURN VALUES 141.Rv -std unlink 142.Sh ERRORS 143The 144.Fn unlink 145succeeds unless: 146.Bl -tag -width Er 147.It Bq Er ENOTDIR 148A component of the path prefix is not a directory. 149.It Bq Er EISDIR 150The named file is a directory. 151.It Bq Er ENAMETOOLONG 152A component of a pathname exceeded 255 characters, 153or an entire path name exceeded 1023 characters. 154.It Bq Er ENOENT 155The named file does not exist. 156.It Bq Er EACCES 157Search permission is denied for a component of the path prefix. 158.It Bq Er EACCES 159Write permission is denied on the directory containing the link 160to be removed. 161.It Bq Er ELOOP 162Too many symbolic links were encountered in translating the pathname. 163.It Bq Er EPERM 164The named file is a directory. 165.It Bq Er EPERM 166The named file has its immutable, undeletable or append-only flag set, see the 167.Xr chflags 2 168manual page for more information. 169.It Bq Er EPERM 170The parent directory of the named file has its immutable or append-only flag 171set. 172.It Bq Er EPERM 173The directory containing the file is marked sticky, 174and neither the containing directory nor the file to be removed 175are owned by the effective user ID. 176.It Bq Er EIO 177An I/O error occurred while deleting the directory entry 178or deallocating the inode. 179.It Bq Er EINTEGRITY 180Corrupted data was detected while reading from the file system. 181.It Bq Er EROFS 182The named file resides on a read-only file system. 183.It Bq Er EFAULT 184The 185.Fa path 186argument 187points outside the process's allocated address space. 188.It Bq Er ENOSPC 189On file systems supporting copy-on-write or snapshots, there was not enough 190free space to record metadata for the delete operation of the file. 191.El 192.Pp 193In addition to the errors returned by the 194.Fn unlink , 195the 196.Fn unlinkat 197may fail if: 198.Bl -tag -width Er 199.It Bq Er EBADF 200The 201.Fa path 202argument does not specify an absolute path and the 203.Fa fd 204argument is neither 205.Dv AT_FDCWD 206nor a valid file descriptor open for searching. 207.It Bq Er ENOTEMPTY 208The 209.Fa flag 210parameter has the 211.Dv AT_REMOVEDIR 212bit set and the 213.Fa path 214argument names a directory that is not an empty directory, 215or there are hard links to the directory other than dot or 216a single entry in dot-dot. 217.It Bq Er ENOTDIR 218The 219.Fa flag 220parameter has the 221.Dv AT_REMOVEDIR 222bit set and 223.Fa path 224does not name a directory. 225.It Bq Er EINVAL 226The value of the 227.Fa flag 228argument is not valid. 229.It Bq Er ENOTDIR 230The 231.Fa path 232argument is not an absolute path and 233.Fa fd 234is neither 235.Dv AT_FDCWD 236nor a file descriptor associated with a directory. 237.It Bq Er ENOTCAPABLE 238.Fa path 239is an absolute path, 240or contained a ".." component leading to a 241directory outside of the directory hierarchy specified by 242.Fa fd , 243and the process is in capability mode or the 244.Dv AT_RESOLVE_BENEATH 245flag was specified. 246.El 247.Pp 248In addition to the errors returned by 249.Fn unlinkat , 250.Fn funlinkat 251may fail if: 252.Bl -tag -width Er 253.It Bq Er EDEADLK 254The file descriptor is not associated with the path. 255.El 256.Sh SEE ALSO 257.Xr chflags 2 , 258.Xr close 2 , 259.Xr link 2 , 260.Xr rmdir 2 , 261.Xr symlink 7 262.Sh STANDARDS 263The 264.Fn unlinkat 265system call follows The Open Group Extended API Set 2 specification. 266.Sh HISTORY 267The 268.Fn unlink 269function appeared in 270.At v1 . 271The 272.Fn unlinkat 273system call appeared in 274.Fx 8.0 . 275The 276.Fn funlinkat 277system call appeared in 278.Fx 13.0 . 279.Pp 280The 281.Fn unlink 282system call traditionally allows the super-user to unlink directories which 283can damage the file system integrity. 284This implementation no longer permits it. 285