diff options
Diffstat (limited to 'man2/unlink.2')
| -rw-r--r-- | man2/unlink.2 | 298 |
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) |