| .\" This manpage is Copyright (C) 1992 Drew Eckhardt; |
| .\" and Copyright (C) 1993 Ian Jackson |
| .\" and Copyright (C) 2006, 2014 Michael Kerrisk. |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> |
| .\" Modified 1996-09-08 by Arnt Gulbrandsen <agulbra@troll.no> |
| .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> |
| .\" Modified 2001-05-17 by aeb |
| .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .TH UNLINK 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| unlink, unlinkat \- delete a name and possibly the file it refers to |
| .SH SYNOPSIS |
| .nf |
| .B #include <unistd.h> |
| .PP |
| .BI "int unlink(const char *" pathname ); |
| |
| .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
| .B #include <unistd.h> |
| .PP |
| .BI "int unlinkat(int " dirfd ", const char *" pathname ", int " flags ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR unlinkat (): |
| .PD 0 |
| .ad l |
| .RS 4 |
| .TP 4 |
| Since glibc 2.10: |
| _POSIX_C_SOURCE\ >=\ 200809L |
| .TP |
| Before glibc 2.10: |
| _ATFILE_SOURCE |
| .RE |
| .ad |
| .PD |
| .SH DESCRIPTION |
| .BR unlink () |
| deletes a name from the filesystem. |
| If that name was the |
| last link to a file and no processes have the file open, the file is |
| deleted and the space it was using is made available for reuse. |
| .PP |
| If the name was the last link to a file but any processes still have |
| the file open, the file will remain in existence until the last file |
| descriptor referring to it is closed. |
| .PP |
| If the name referred to a symbolic link, the link is removed. |
| .PP |
| If the name referred to a socket, FIFO, or device, the name for it is |
| removed but processes which have the object open may continue to use |
| it. |
| .SS unlinkat() |
| The |
| .BR unlinkat () |
| system call operates in exactly the same way as either |
| .BR unlink () |
| or |
| .BR rmdir (2) |
| (depending on whether or not |
| .I flags |
| includes the |
| .B AT_REMOVEDIR |
| flag) |
| except for the differences described here. |
| .PP |
| If the pathname given in |
| .I pathname |
| is relative, then it is interpreted relative to the directory |
| referred to by the file descriptor |
| .I dirfd |
| (rather than relative to the current working directory of |
| the calling process, as is done by |
| .BR unlink () |
| and |
| .BR rmdir (2) |
| for a relative pathname). |
| .PP |
| If the pathname given in |
| .I pathname |
| is relative and |
| .I dirfd |
| is the special value |
| .BR AT_FDCWD , |
| then |
| .I pathname |
| is interpreted relative to the current working |
| directory of the calling process (like |
| .BR unlink () |
| and |
| .BR rmdir (2)). |
| .PP |
| If the pathname given in |
| .I pathname |
| is absolute, then |
| .I dirfd |
| is ignored. |
| .PP |
| .I flags |
| is a bit mask that can either be specified as 0, or by ORing |
| together flag values that control the operation of |
| .BR unlinkat (). |
| Currently, only one such flag is defined: |
| .TP |
| .B AT_REMOVEDIR |
| By default, |
| .BR unlinkat () |
| performs the equivalent of |
| .BR unlink () |
| on |
| .IR pathname . |
| If the |
| .B AT_REMOVEDIR |
| flag is specified, then |
| performs the equivalent of |
| .BR rmdir (2) |
| on |
| .IR pathname . |
| .PP |
| See |
| .BR openat (2) |
| for an explanation of the need for |
| .BR unlinkat (). |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| Write access to the directory containing |
| .I pathname |
| is not allowed for the process's effective UID, or one of the |
| directories in |
| .I pathname |
| did not allow search permission. |
| (See also |
| .BR path_resolution (7).) |
| .TP |
| .BR EBUSY |
| The file |
| .I pathname |
| cannot be unlinked because it is being used by the system |
| or another process; |
| for example, it is a mount point |
| or the NFS client software created it to represent an |
| active but otherwise nameless inode ("NFS silly renamed"). |
| .TP |
| .B EFAULT |
| .I pathname |
| points outside your accessible address space. |
| .TP |
| .B EIO |
| An I/O error occurred. |
| .TP |
| .B EISDIR |
| .I pathname |
| refers to a directory. |
| (This is the non-POSIX value returned by Linux since 2.1.132.) |
| .TP |
| .B ELOOP |
| Too many symbolic links were encountered in translating |
| .IR pathname . |
| .TP |
| .B ENAMETOOLONG |
| .IR pathname " was too long." |
| .TP |
| .B ENOENT |
| A component in |
| .I pathname |
| does not exist or is a dangling symbolic link, or |
| .I pathname |
| is empty. |
| .TP |
| .B ENOMEM |
| Insufficient kernel memory was available. |
| .TP |
| .B ENOTDIR |
| A component used as a directory in |
| .I pathname |
| is not, in fact, a directory. |
| .TP |
| .B EPERM |
| The system does not allow unlinking of directories, |
| or unlinking of directories requires privileges that the |
| calling process doesn't have. |
| (This is the POSIX prescribed error return; |
| as noted above, Linux returns |
| .B EISDIR |
| for this case.) |
| .TP |
| .BR EPERM " (Linux only)" |
| The filesystem does not allow unlinking of files. |
| .TP |
| .BR EPERM " or " EACCES |
| The directory containing |
| .I pathname |
| has the sticky bit |
| .RB ( S_ISVTX ) |
| set and the process's effective UID is neither the UID of the file to |
| be deleted nor that of the directory containing it, and |
| the process is not privileged (Linux: does not have the |
| .B CAP_FOWNER |
| capability). |
| .TP |
| .B EPERM |
| The file to be unlinked is marked immutable or append-only. |
| (See |
| .BR ioctl_iflags (2).) |
| .TP |
| .B EROFS |
| .I pathname |
| refers to a file on a read-only filesystem. |
| .PP |
| The same errors that occur for |
| .BR unlink () |
| and |
| .BR rmdir (2) |
| can also occur for |
| .BR unlinkat (). |
| The following additional errors can occur for |
| .BR unlinkat (): |
| .TP |
| .B EBADF |
| .I dirfd |
| is not a valid file descriptor. |
| .TP |
| .B EINVAL |
| An invalid flag value was specified in |
| .IR flags . |
| .TP |
| .B EISDIR |
| .I pathname |
| refers to a directory, and |
| .B AT_REMOVEDIR |
| was not specified in |
| .IR flags . |
| .TP |
| .B ENOTDIR |
| .I pathname |
| is relative and |
| .I dirfd |
| is a file descriptor referring to a file other than a directory. |
| .SH VERSIONS |
| .BR unlinkat () |
| was added to Linux in kernel 2.6.16; |
| library support was added to glibc in version 2.4. |
| .SH CONFORMING TO |
| .BR unlink (): |
| SVr4, 4.3BSD, POSIX.1-2001, POSIX.1-2008. |
| .\" SVr4 documents additional error |
| .\" conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK. |
| .PP |
| .BR unlinkat (): |
| POSIX.1-2008. |
| .SH NOTES |
| .SS Glibc notes |
| On older kernels where |
| .BR unlinkat () |
| is unavailable, the glibc wrapper function falls back to the use of |
| .BR unlink () |
| or |
| .BR rmdir (2). |
| When |
| .I pathname |
| is a relative pathname, |
| glibc constructs a pathname based on the symbolic link in |
| .IR /proc/self/fd |
| that corresponds to the |
| .IR dirfd |
| argument. |
| .SH BUGS |
| Infelicities in the protocol underlying NFS can cause the unexpected |
| disappearance of files which are still being used. |
| .SH SEE ALSO |
| .BR rm (1), |
| .BR unlink (1), |
| .BR chmod (2), |
| .BR link (2), |
| .BR mknod (2), |
| .BR open (2), |
| .BR rename (2), |
| .BR rmdir (2), |
| .BR mkfifo (3), |
| .BR remove (3), |
| .BR path_resolution (7), |
| .BR symlink (7) |