unlink(2)

unlink -- remove directory entry

Synopsis

   #include <unistd.h>
   
   int unlink(const char *path);

Description

unlink removes the directory entry named by the pathname pointed to by the argument path and decrements the link count of the file referenced by the directory entry.

The effective user ID of the calling process must have write permission on the file pointed to by path; the caller must also have write permission on the parent directory of the file (or have the P_COMPAT privilege).

When all links to a file have been removed and no process has an outstanding reference to the file, the space occupied by the file is freed and the file ceases to exist. If one or more processes have outstanding references to the file when the last link is removed, space occupied by the file is not released until all references to the file have been removed.

If path is a symbolic link, the symbolic link is removed.

The path argument should not name a directory unless the calling process has the P_FILESYS privilege; portable programs should not depend on this behavior, as some implementations do not support unlink on directories. Instead, portable applications should use rmdir(2) to remove directories.

Return values

On success, unlink returns 0 and marks for update the ``st_ctime'' and ``st_mtime'' fields of the parent directory. Also, if the file's link count is not zero, the ``st_ctime'' field of the file is marked for update. On failure, unlink returns -1, sets errno to identify the error, and the file is not unlinked.

Errors

In the following conditions, unlink fails and sets errno to:

EACCES: Search permission is denied for a component of the path prefix.
EACCES: Write permission is denied on the directory containing the link to be removed and the process does not have the P_COMPAT privilege.
EACCES: The parent directory in which the file named by path resides has the sticky bit set, and the user does not own either the parent directory or the file.
EACCES: Write permission is denied on the file named by path.
EBUSY: The entry to be unlinked is the mount point for a mounted file system.
EFAULT: path points outside the process's allocated address space.
EINTR: A signal was caught during the unlink system call.
ELOOP: Too many symbolic links were encountered in translating path.
EMULTIHOP: Components of path require hopping to multiple remote machines and the file system does not allow it.
ENAMETOOLONG: The length of the path argument exceeds {PATH_MAX}, or the length of a path component exceeds {NAME_MAX} while _POSIX_NO_TRUNC is in effect.
ENOENT: The named file does not exist or is a null pathname. The user is not a super-user.
ENOTDIR: A component of the path prefix is not a directory.
EPERM: The named file is a directory and the calling process does not have the P_FILESYS privilege.
EROFS: The directory entry to be unlinked is part of a read-only file system.
ENOLINK: path points to a remote machine and the link to that machine is no longer active.

References

close(2), link(2), open(2), rm(1), rmdir(2)