man2/unlink.2

   1 .\" This manpage is Copyright (C) 1992 Drew Eckhardt;
   2 .\"             and Copyright (C) 1993 Ian Jackson
   3 .\"             and Copyright (C) 2006, 2014 Michael Kerrisk.
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
   8 .\" Modified 1996-09-08 by Arnt Gulbrandsen <agulbra@troll.no>
   9 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
  10 .\" Modified 2001-05-17 by aeb
  11 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
  12 .\"
  13 .TH unlink 2 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 unlink, unlinkat \- delete a name and possibly the file it refers to
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <unistd.h>
  22 .P
  23 .BI "int unlink(const char *" pathname );
  24 .P
  25 .BR "#include <fcntl.h>           " "/* Definition of " AT_* " constants */"
  26 .B #include <unistd.h>
  27 .P
  28 .BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags );
  29 .fi
  30 .P
  31 .RS -4
  32 Feature Test Macro Requirements for glibc (see
  33 .BR feature_test_macros (7)):
  34 .RE
  35 .P
  36 .BR unlinkat ():
  37 .nf
  38     Since glibc 2.10:
  39         _POSIX_C_SOURCE >= 200809L
  40     Before glibc 2.10:
  41         _ATFILE_SOURCE
  42 .fi
  43 .SH DESCRIPTION
  44 .BR unlink ()
  45 deletes a name from the filesystem.
  46 If that name was the
  47 last link to a file and no processes have the file open, the file is
  48 deleted and the space it was using is made available for reuse.
  49 .P
  50 If the name was the last link to a file but any processes still have
  51 the file open, the file will remain in existence until the last file
  52 descriptor referring to it is closed.
  53 .P
  54 If the name referred to a symbolic link, the link is removed.
  55 .P
  56 If the name referred to a socket, FIFO, or device, the name for it is
  57 removed but processes which have the object open may continue to use
  58 it.
  59 .SS unlinkat()
  60 The
  61 .BR unlinkat ()
  62 system call operates in exactly the same way as either
  63 .BR unlink ()
  64 or
  65 .BR rmdir (2)
  66 (depending on whether or not
  67 .I flags
  68 includes the
  69 .B AT_REMOVEDIR
  70 flag)
  71 except for the differences described here.
  72 .P
  73 If the pathname given in
  74 .I pathname
  75 is relative, then it is interpreted relative to the directory
  76 referred to by the file descriptor
  77 .I dirfd
  78 (rather than relative to the current working directory of
  79 the calling process, as is done by
  80 .BR unlink ()
  81 and
  82 .BR rmdir (2)
  83 for a relative pathname).
  84 .P
  85 If the pathname given in
  86 .I pathname
  87 is relative and
  88 .I dirfd
  89 is the special value
  90 .BR AT_FDCWD ,
  91 then
  92 .I pathname
  93 is interpreted relative to the current working
  94 directory of the calling process (like
  95 .BR unlink ()
  96 and
  97 .BR rmdir (2)).
  98 .P
  99 If the pathname given in
 100 .I pathname
 101 is absolute, then
 102 .I dirfd
 103 is ignored.
 104 .P
 105 .I flags
 106 is a bit mask that can either be specified as 0, or by ORing
 107 together flag values that control the operation of
 108 .BR unlinkat ().
 109 Currently, only one such flag is defined:
 110 .TP
 111 .B AT_REMOVEDIR
 112 By default,
 113 .BR unlinkat ()
 114 performs the equivalent of
 115 .BR unlink ()
 116 on
 117 .IR pathname .
 118 If the
 119 .B AT_REMOVEDIR
 120 flag is specified, then
 121 performs the equivalent of
 122 .BR rmdir (2)
 123 on
 124 .IR pathname .
 125 .P
 126 See
 127 .BR openat (2)
 128 for an explanation of the need for
 129 .BR unlinkat ().
 130 .SH RETURN VALUE
 131 On success, zero is returned.
 132 On error, \-1 is returned, and
 133 .I errno
 134 is set to indicate the error.
 135 .SH ERRORS
 136 .TP
 137 .B EACCES
 138 Write access to the directory containing
 139 .I pathname
 140 is not allowed for the process's effective UID, or one of the
 141 directories in
 142 .I pathname
 143 did not allow search permission.
 144 (See also
 145 .BR path_resolution (7).)
 146 .TP
 147 .B EBUSY
 148 The file
 149 .I pathname
 150 cannot be unlinked because it is being used by the system
 151 or another process;
 152 for example, it is a mount point
 153 or the NFS client software created it to represent an
 154 active but otherwise nameless inode ("NFS silly renamed").
 155 .TP
 156 .B EFAULT
 157 .I pathname
 158 points outside your accessible address space.
 159 .TP
 160 .B EIO
 161 An I/O error occurred.
 162 .TP
 163 .B EISDIR
 164 .I pathname
 165 refers to a directory.
 166 (This is the non-POSIX value returned since Linux 2.1.132.)
 167 .TP
 168 .B ELOOP
 169 Too many symbolic links were encountered in translating
 170 .IR pathname .
 171 .TP
 172 .B ENAMETOOLONG
 173 .IR pathname " was too long."
 174 .TP
 175 .B ENOENT
 176 A component in
 177 .I pathname
 178 does not exist or is a dangling symbolic link, or
 179 .I pathname
 180 is empty.
 181 .TP
 182 .B ENOMEM
 183 Insufficient kernel memory was available.
 184 .TP
 185 .B ENOTDIR
 186 A component used as a directory in
 187 .I pathname
 188 is not, in fact, a directory.
 189 .TP
 190 .B EPERM
 191 The system does not allow unlinking of directories,
 192 or unlinking of directories requires privileges that the
 193 calling process doesn't have.
 194 (This is the POSIX prescribed error return;
 195 as noted above, Linux returns
 196 .B EISDIR
 197 for this case.)
 198 .TP
 199 .BR EPERM " (Linux only)"
 200 The filesystem does not allow unlinking of files.
 201 .TP
 202 .BR EPERM " or " EACCES
 203 The directory containing
 204 .I pathname
 205 has the sticky bit
 206 .RB ( S_ISVTX )
 207 set and the process's effective UID is neither the UID of the file to
 208 be deleted nor that of the directory containing it, and
 209 the process is not privileged (Linux: does not have the
 210 .B CAP_FOWNER
 211 capability).
 212 .TP
 213 .B EPERM
 214 The file to be unlinked is marked immutable or append-only.
 215 (See
 216 .BR ioctl_iflags (2).)
 217 .TP
 218 .B EROFS
 219 .I pathname
 220 refers to a file on a read-only filesystem.
 221 .P
 222 The same errors that occur for
 223 .BR unlink ()
 224 and
 225 .BR rmdir (2)
 226 can also occur for
 227 .BR unlinkat ().
 228 The following additional errors can occur for
 229 .BR unlinkat ():
 230 .TP
 231 .B EBADF
 232 .I pathname
 233 is relative but
 234 .I dirfd
 235 is neither
 236 .B AT_FDCWD
 237 nor a valid file descriptor.
 238 .TP
 239 .B EINVAL
 240 An invalid flag value was specified in
 241 .IR flags .
 242 .TP
 243 .B EISDIR
 244 .I pathname
 245 refers to a directory, and
 246 .B AT_REMOVEDIR
 247 was not specified in
 248 .IR flags .
 249 .TP
 250 .B ENOTDIR
 251 .I pathname
 252 is relative and
 253 .I dirfd
 254 is a file descriptor referring to a file other than a directory.
 255 .SH STANDARDS
 256 POSIX.1-2008.
 257 .SH HISTORY
 258 .TP
 259 .BR unlink ()
 260 SVr4, 4.3BSD, POSIX.1-2001.
 261 .\" SVr4 documents additional error
 262 .\" conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK.
 263 .TP
 264 .BR unlinkat ()
 265 POSIX.1-2008.
 266 Linux 2.6.16,
 267 glibc 2.4.
 268 .SS glibc
 269 On older kernels where
 270 .BR unlinkat ()
 271 is unavailable, the glibc wrapper function falls back to the use of
 272 .BR unlink ()
 273 or
 274 .BR rmdir (2).
 275 When
 276 .I pathname
 277 is a relative pathname,
 278 glibc constructs a pathname based on the symbolic link in
 279 .I /proc/self/fd
 280 that corresponds to the
 281 .I dirfd
 282 argument.
 283 .SH BUGS
 284 Infelicities in the protocol underlying NFS can cause the unexpected
 285 disappearance of files which are still being used.
 286 .SH SEE ALSO
 287 .BR rm (1),
 288 .BR unlink (1),
 289 .BR chmod (2),
 290 .BR link (2),
 291 .BR mknod (2),
 292 .BR open (2),
 293 .BR rename (2),
 294 .BR rmdir (2),
 295 .BR mkfifo (3),
 296 .BR remove (3),
 297 .BR path_resolution (7),
 298 .BR symlink (7)