1.\" $OpenBSD: unlink.2,v 1.20 2011/11/06 17:22:20 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: November 6 2011 $ 34.Dt UNLINK 2 35.Os 36.Sh NAME 37.Nm unlink , 38.Nm unlinkat 39.Nd remove directory entry 40.Sh SYNOPSIS 41.Fd #include <fcntl.h> 42.Fd #include <unistd.h> 43.Ft int 44.Fn unlink "const char *path" 45.Ft int 46.Fn unlinkat "int fd" "const char *path" "int flag" 47.Sh DESCRIPTION 48The 49.Fn unlink 50function removes the link named by 51.Fa path 52from its directory and decrements the link count of the 53file which was referenced by the link. 54If that decrement reduces the link count of the file 55to zero, 56and no process has the file open, then 57all resources associated with the file are reclaimed. 58If one or more processes have the file open when the last link is removed, 59the link is removed, but the removal of the file is delayed until 60all references to it have been closed. 61.Pp 62The 63.Fn unlinkat 64function is equivalent to either the 65.Fn unlink 66or 67.Xr rmdir 2 68function depending on the value of 69.Fa flag 70(see below), except that where 71.Fa path 72specifies a relative path, 73the directory entry to be removed is determined relative to 74the directory associated with file descriptor 75.Fa fd 76instead of the current working directory. 77.Pp 78If 79.Fn unlinkat 80is passed the special value 81.Dv AT_FDCWD 82(defined in 83.In fcntl.h ) 84in the 85.Fa fd 86parameter, the current working directory is used 87and the behavior is identical to a call to 88.Fn unlink 89or 90.Xr rmdir 2 , 91depending on whether or not the 92.Dv AT_REMOVEDIR 93bit is set in 94.Fa flag . 95.Pp 96Values for 97.Fa flag 98are constructed by bitwise-inclusive 99.Tn OR Ns ing 100flags from the following list defined in 101.In fcntl.h : 102.Pp 103.Bl -tag -width AT_REMOVEDIR -offset indent -compact 104.It Dv AT_REMOVEDIR 105Remove the directory entry specified by 106.Fa path 107as a directory, not a normal file. 108.El 109.Sh RETURN VALUES 110Upon successful completion, a value of 0 is returned. 111Otherwise, a value of \-1 is returned and 112.Va errno 113is set to indicate the error. 114.Sh ERRORS 115The 116.Fn unlink 117and 118.Fn unlinkat 119functions will fail if: 120.Bl -tag -width Er 121.It Bq Er ENOTDIR 122A component of the path prefix is not a directory. 123.It Bq Er ENAMETOOLONG 124A component of a pathname exceeded 125.Dv {NAME_MAX} 126characters, or an entire path name exceeded 127.Dv {PATH_MAX} 128characters. 129.It Bq Er ENOENT 130The named file does not exist. 131.It Bq Er EACCES 132Search permission is denied for a component of the path prefix. 133.It Bq Er EACCES 134Write permission is denied on the directory containing the link 135to be removed. 136.It Bq Er ELOOP 137Too many symbolic links were encountered in translating the pathname. 138.It Bq Er EPERM 139The named file is a directory and the effective user ID 140of the process is not the superuser, or the file system 141containing the file does not permit the use of 142.Fn unlink 143on a directory. 144.It Bq Er EPERM 145The directory containing the file is marked sticky, 146and neither the containing directory nor the file to be removed 147are owned by the effective user ID. 148.It Bq Er EPERM 149The named file has its immutable or append-only flag set (see 150.Xr chflags 2 ) . 151.It Bq Er EBUSY 152The entry to be unlinked is the mount point for a 153mounted file system. 154.It Bq Er EIO 155An I/O error occurred while deleting the directory entry 156or deallocating the inode. 157.It Bq Er EROFS 158The named file resides on a read-only file system. 159.It Bq Er EFAULT 160.Fa path 161points outside the process's allocated address space. 162.El 163.Pp 164Additionally, 165.Fn unlinkat 166will fail if: 167.Bl -tag -width Er 168.It Bq Er EBADF 169The 170.Fa path 171argument does not specify an absolute path and the 172.Fa fd 173argument is neither 174.Dv AT_FDCWD 175nor a valid file descriptor open for reading. 176.It Bq Er ENOTDIR 177The 178.Dv AT_REMOVEDIR 179flag bit is set and 180.Fa path 181does not name a directory. 182.It Bq Er ENOTEMPTY 183The 184.Dv AT_REMOVEDIR 185flag bit is set and the named directory contains files other than 186.Ql \&. 187and 188.Ql \&.. 189in it. 190.El 191.Sh SEE ALSO 192.Xr rm 1 , 193.Xr close 2 , 194.Xr link 2 , 195.Xr rmdir 2 , 196.Xr symlink 7 197.Sh STANDARDS 198The 199.Fn unlink 200and 201.Fn unlinkat 202functions conform to 203.St -p1003.1-2008 . 204.Sh HISTORY 205The 206.Fn unlink 207system call first appeared in 208.At v1 . 209The 210.Fn unlinkat 211function appeared in 212.Ox 5.0 . 213