lib/libc/sys/unlink.2

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