bsd/man/man2/unlink.2

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