summaryrefslogtreecommitdiffstats
path: root/man2/unlink.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/unlink.2')
-rw-r--r--man2/unlink.2298
1 files changed, 298 insertions, 0 deletions
diff --git a/man2/unlink.2 b/man2/unlink.2
new file mode 100644
index 0000000..85cb670
--- /dev/null
+++ b/man2/unlink.2
@@ -0,0 +1,298 @@
+.\" This manpage is Copyright (C) 1992 Drew Eckhardt;
+.\" and Copyright (C) 1993 Ian Jackson
+.\" and Copyright (C) 2006, 2014 Michael Kerrisk.
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 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 2023-03-30 "Linux man-pages 6.05.01"
+.SH NAME
+unlink, unlinkat \- delete a name and possibly the file it refers to
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <unistd.h>
+.PP
+.BI "int unlink(const char *" pathname );
+.PP
+.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
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.PP
+.BR unlinkat ():
+.nf
+ Since glibc 2.10:
+ _POSIX_C_SOURCE >= 200809L
+ Before glibc 2.10:
+ _ATFILE_SOURCE
+.fi
+.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 to indicate the error.
+.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
+.B 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 since Linux 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 pathname
+is relative but
+.I dirfd
+is neither
+.B AT_FDCWD
+nor 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 STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR unlink ()
+SVr4, 4.3BSD, POSIX.1-2001.
+.\" SVr4 documents additional error
+.\" conditions EINTR, EMULTIHOP, ETXTBSY, ENOLINK.
+.TP
+.BR unlinkat ()
+POSIX.1-2008.
+Linux 2.6.16,
+glibc 2.4.
+.SS glibc
+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
+.I /proc/self/fd
+that corresponds to the
+.I 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)