Debian Codegraph @

upstream/debian-unstable/man2/unlink.2

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