1unlink(2) System Calls Manual unlink(2)
2
6 unlink, unlinkat - delete a name and possibly the file it refers to
7
9 Standard C library (libc, -lc)
10
12 #include <unistd.h>
13 int unlink(const char *pathname);
15 #include <fcntl.h> /* Definition of AT_* constants */
17 #include <unistd.h>
18 int unlinkat(int dirfd, const char *pathname, int flags);
20 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
22 unlinkat():
24 Since glibc 2.10:
25 _POSIX_C_SOURCE >= 200809L
26 Before glibc 2.10:
27 _ATFILE_SOURCE
28
30 unlink() deletes a name from the filesystem. If that name was the last
31 link to a file and no processes have the file open, the file is deleted
32 and the space it was using is made available for reuse.
33 If the name was the last link to a file but any processes still have
35 the file open, the file will remain in existence until the last file
36 descriptor referring to it is closed.
37 If the name referred to a symbolic link, the link is removed.
39 If the name referred to a socket, FIFO, or device, the name for it is
41 removed but processes which have the object open may continue to use
42 it.
43 unlinkat()
45 The unlinkat() system call operates in exactly the same way as either
46 unlink() or rmdir(2) (depending on whether or not flags includes the
47 AT_REMOVEDIR flag) except for the differences described here.
48 If the pathname given in pathname is relative, then it is interpreted
50 relative to the directory referred to by the file descriptor dirfd
51 (rather than relative to the current working directory of the calling
52 process, as is done by unlink() and rmdir(2) for a relative pathname).
53 If the pathname given in pathname is relative and dirfd is the special
55 value AT_FDCWD, then pathname is interpreted relative to the current
56 working directory of the calling process (like unlink() and rmdir(2)).
57 If the pathname given in pathname is absolute, then dirfd is ignored.
59 flags is a bit mask that can either be specified as 0, or by ORing to‐
61 gether flag values that control the operation of unlinkat(). Cur‐
62 rently, only one such flag is defined:
63 AT_REMOVEDIR
65 By default, unlinkat() performs the equivalent of unlink() on
66 pathname. If the AT_REMOVEDIR flag is specified, then performs
67 the equivalent of rmdir(2) on pathname.
68 See openat(2) for an explanation of the need for unlinkat().
70
72 On success, zero is returned. On error, -1 is returned, and errno is
73 set to indicate the error.
74
76 EACCES Write access to the directory containing pathname is not allowed
77 for the process's effective UID, or one of the directories in
78 pathname did not allow search permission. (See also path_reso‐
79 lution(7).)
80 EBUSY The file pathname cannot be unlinked because it is being used by
82 the system or another process; for example, it is a mount point
83 or the NFS client software created it to represent an active but
84 otherwise nameless inode ("NFS silly renamed").
85 EFAULT pathname points outside your accessible address space.
87 EIO An I/O error occurred.
89 EISDIR pathname refers to a directory. (This is the non-POSIX value
91 returned since Linux 2.1.132.)
92 ELOOP Too many symbolic links were encountered in translating path‐
94 name.
95 ENAMETOOLONG
97 pathname was too long.
98 ENOENT A component in pathname does not exist or is a dangling symbolic
100 link, or pathname is empty.
101 ENOMEM Insufficient kernel memory was available.
103 ENOTDIR
105 A component used as a directory in pathname is not, in fact, a
106 directory.
107 EPERM The system does not allow unlinking of directories, or unlinking
109 of directories requires privileges that the calling process
110 doesn't have. (This is the POSIX prescribed error return; as
111 noted above, Linux returns EISDIR for this case.)
112 EPERM (Linux only)
114 The filesystem does not allow unlinking of files.
115 EPERM or EACCES
117 The directory containing pathname has the sticky bit (S_ISVTX)
118 set and the process's effective UID is neither the UID of the
119 file to be deleted nor that of the directory containing it, and
120 the process is not privileged (Linux: does not have the
121 CAP_FOWNER capability).
122 EPERM The file to be unlinked is marked immutable or append-only.
124 (See ioctl_iflags(2).)
125 EROFS pathname refers to a file on a read-only filesystem.
127 The same errors that occur for unlink() and rmdir(2) can also occur for
129 unlinkat(). The following additional errors can occur for unlinkat():
130 EBADF pathname is relative but dirfd is neither AT_FDCWD nor a valid
132 file descriptor.
133 EINVAL An invalid flag value was specified in flags.
135 EISDIR pathname refers to a directory, and AT_REMOVEDIR was not speci‐
137 fied in flags.
138 ENOTDIR
140 pathname is relative and dirfd is a file descriptor referring to
141 a file other than a directory.
142
144 POSIX.1-2008.
145
147 unlink()
148 SVr4, 4.3BSD, POSIX.1-2001.
149 unlinkat()
151 POSIX.1-2008. Linux 2.6.16, glibc 2.4.
152 glibc
154 On older kernels where unlinkat() is unavailable, the glibc wrapper
155 function falls back to the use of unlink() or rmdir(2). When pathname
156 is a relative pathname, glibc constructs a pathname based on the sym‐
157 bolic link in /proc/self/fd that corresponds to the dirfd argument.
158
160 Infelicities in the protocol underlying NFS can cause the unexpected
161 disappearance of files which are still being used.
162
164 rm(1), unlink(1), chmod(2), link(2), mknod(2), open(2), rename(2),
165 rmdir(2), mkfifo(3), remove(3), path_resolution(7), symlink(7)
166Linux man-pages 6.05 2023-03-30 unlink(2)