1.\" $OpenBSD: unlink.2,v 1.28 2021/06/30 18:46:49 schwarze Exp $ 2.\" $NetBSD: unlink.2,v 1.7 1995/02/27 12:39:13 cgd Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)unlink.2 8.1 (Berkeley) 6/4/93 32.\" 33.Dd $Mdocdate: June 30 2021 $ 34.Dt UNLINK 2 35.Os 36.Sh NAME 37.Nm unlink , 38.Nm unlinkat 39.Nd remove directory entry 40.Sh SYNOPSIS 41.In unistd.h 42.Ft int 43.Fn unlink "const char *path" 44.In fcntl.h 45.In unistd.h 46.Ft int 47.Fn unlinkat "int fd" "const char *path" "int flag" 48.Sh DESCRIPTION 49The 50.Fn unlink 51function removes the link named by 52.Fa path 53from its directory and decrements the link count of the 54file which was referenced by the link. 55If that decrement reduces the link count of the file 56to zero, 57and no process has the file open, then 58all resources associated with the file are reclaimed. 59If one or more processes have the file open when the last link is removed, 60the link is removed, but the removal of the file is delayed until 61all references to it have been closed. 62.Pp 63The 64.Fn unlinkat 65function is equivalent to either the 66.Fn unlink 67or 68.Xr rmdir 2 69function depending on the value of 70.Fa flag 71(see below), except that where 72.Fa path 73specifies a relative path, 74the directory entry to be removed is determined relative to 75the directory associated with file descriptor 76.Fa fd 77instead of the current working directory. 78.Pp 79If 80.Fn unlinkat 81is passed the special value 82.Dv AT_FDCWD 83(defined in 84.In fcntl.h ) 85in the 86.Fa fd 87parameter, the current working directory is used 88and the behavior is identical to a call to 89.Fn unlink 90or 91.Xr rmdir 2 , 92depending on whether or not the 93.Dv AT_REMOVEDIR 94bit is set in 95.Fa flag . 96.Pp 97The 98.Fa flag 99argument is the bitwise OR of zero or more of the following values: 100.Pp 101.Bl -tag -width AT_REMOVEDIR -offset indent -compact 102.It Dv AT_REMOVEDIR 103Remove the directory entry specified by 104.Fa path 105as a directory, not a normal file. 106.El 107.Sh RETURN VALUES 108.Rv -std 109.Sh ERRORS 110The 111.Fn unlink 112and 113.Fn unlinkat 114functions will fail if: 115.Bl -tag -width Er 116.It Bq Er ENOTDIR 117A component of the path prefix is not a directory. 118.It Bq Er ENAMETOOLONG 119A component of a pathname exceeded 120.Dv NAME_MAX 121characters, or an entire pathname (including the terminating NUL) 122exceeded 123.Dv PATH_MAX 124bytes. 125.It Bq Er ENOENT 126The named file does not exist. 127.It Bq Er EACCES 128Search permission is denied for a component of the path prefix. 129.It Bq Er EACCES 130Write permission is denied on the directory containing the link 131to be removed. 132.It Bq Er ELOOP 133Too many symbolic links were encountered in translating the pathname. 134.It Bq Er EPERM 135The named file is a directory and the effective user ID 136of the process is not the superuser, or the file system 137containing the file does not permit the use of 138.Fn unlink 139on a directory. 140.It Bq Er EPERM 141The directory containing the file is marked sticky, 142and neither the containing directory nor the file to be removed 143are owned by the effective user ID. 144.It Bq Er EPERM 145The named file or the directory containing it has its immutable or 146append-only flag set (see 147.Xr chflags 2 ) . 148.It Bq Er EBUSY 149The entry to be unlinked is the mount point for a 150mounted file system. 151.It Bq Er EIO 152An I/O error occurred while deleting the directory entry 153or deallocating the inode. 154.It Bq Er EROFS 155The named file resides on a read-only file system. 156.It Bq Er EFAULT 157.Fa path 158points outside the process's allocated address space. 159.El 160.Pp 161Additionally, 162.Fn unlinkat 163will fail if: 164.Bl -tag -width Er 165.It Bq Er ENOTDIR 166The 167.Dv AT_REMOVEDIR 168flag bit is set and 169.Fa path 170does not name a directory. 171.It Bq Er ENOTEMPTY 172The 173.Dv AT_REMOVEDIR 174flag bit is set and the named directory contains files other than 175.Ql \&. 176and 177.Ql \&.. 178in it. 179.It Bq Er EINVAL 180The value of the 181.Fa flag 182argument was neither zero nor 183.Dv AT_REMOVEDIR . 184.It Bq Er EINVAL 185The value of the 186.Fa flag 187argument was 188.Dv AT_REMOVEDIR 189and the last element of 190.Fa path 191consists of 192.Ql \&. . 193.It Bq Er EBADF 194The 195.Fa path 196argument specifies a relative path and the 197.Fa fd 198argument is neither 199.Dv AT_FDCWD 200nor a valid file descriptor. 201.It Bq Er ENOTDIR 202The 203.Fa path 204argument specifies a relative path and the 205.Fa fd 206argument is a valid file descriptor but it does not reference a directory. 207.It Bq Er EACCES 208The 209.Fa path 210argument specifies a relative path but search permission is denied 211for the directory which the 212.Fa fd 213file descriptor references. 214.El 215.Sh SEE ALSO 216.Xr rm 1 , 217.Xr chflags 2 , 218.Xr close 2 , 219.Xr link 2 , 220.Xr rmdir 2 , 221.Xr symlink 7 222.Sh STANDARDS 223The 224.Fn unlink 225and 226.Fn unlinkat 227functions conform to 228.St -p1003.1-2008 . 229.Sh HISTORY 230The 231.Fn unlink 232system call first appeared in 233.At v1 . 234The 235.Fn unlinkat 236function appeared in 237.Ox 5.0 . 238