unlink or unlinkat Subroutine

Purpose

Removes a directory entry.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

int unlink (Path) const char *Path; int unlinkat (DirFileDescriptor, Path, Flag) int DirFileDescriptor; const char * Path; int Flag;

Description

The unlink and unlinkat subroutines remove the directory entry specified by the Path parameter and decrease the link count of the file referenced by the link. If Network File System (NFS) is installed on your system, this path can cross into another node.

Attention: Removing a link to a directory requires root user authority. Unlinking of directories is strongly discouraged since erroneous directory structures can result. The rmdir subroutine, or the unlinkat subroutine with the Flag parameter set to AT_REMOVEDIR, should be used to remove empty directories.

When all links to a file are removed and no process has the file open, all resources associated with the file are reclaimed, and the file is no longer accessible. If one or more processes have the file open when the last link is removed, the directory entry disappears. However, the removal of the file contents is postponed until all references to the file are closed.

If the parent directory of Path has the sticky attribute (described in the mode.h file), the calling process must have root user authority or an effective user ID equal to the owner ID of Path or the owner ID of the parent directory of Path.

The st_ctime and st_mtime fields of the parent directory are marked for update if the unlink or unlinkat subroutine is successful. In addition, if the file's link count is not 0, the st_ctime field of the file will be marked for update.

Applications should use the rmdir subroutine, or the unlinkat subroutine with the Flag parameter having the AT_REMOVEDIR bit on, to remove a directory. If the Path parameter names a symbolic link, the link itself is removed.

The unlinkat subroutine is equivalent to the unlink subroutine if the Flag parameter does not have the AT_REMOVEDIR bit set, and if the DirFileDescriptor is AT_FDCWD or Path is an absolute path name. If DirFileDescriptor is a valid file descriptor of an open directory and Path is a relative path name, Path is considered to be relative to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory.

If the DirFileDescriptor in the unlinkat subroutine was opened without the O_SEARCH open flag, the subroutine checks to determine whether directory searches are permitted for that directory by using the current permissions of the directory. If the directory was opened with the O_SEARCH open flag, the subroutine does not perform the check for that directory.

If the Flag parameter of the unlinkat subroutine has the AT_REMOVEDIR bit set, the unlinkat subroutine is equivalent to the rmdir subroutine.

Parameters

Item	Description
DirFileDescriptor	Specifies the file descriptor of an open directory.
Path	Specifies the directory entry to be removed. If DirFileDescriptor is specified and Path is a relative path name, then Path is considered relative to the directory specified by DirFileDescriptor.
Flag	Specifies a bit field. If it contains the AT_REMOVEDIR bit and Path points to a directory, then the directory specified by Path is removed.

Return Values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned, the errno global variable is set to indicate the error, and the specified file is not changed.

Error Codes

The unlink and unlinkat subroutines fail and the named file is not unlinked if one of the following is true:

Item	Description
ENOENT	The named file does not exist.
EACCES	Write permission is denied on the directory containing the link to be removed.
EBUSY	The entry to be unlinked is the mount point for a mounted file system, or the file named by Path is a named STREAM.
EPERM	The file specified by the Path parameter is a directory, and the calling process does not have root user authority. EPERM is also returned if the file named by the Path parameter is a directory in a JFS2 file system. Note that JFS allows you to unlink a directory.
EROFS	The entry to be unlinked is part of a read-only file system.

The unlinkat subroutine is unsuccessful if one or more of the following is true:

Item	Description
EBADF	The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a valid file descriptor.
ENOTDIR	The Path parameter does not specify an absolute path and the DirFileDescriptor parameter is neither AT_FDCWD nor a file descriptor associated with a directory.
EINVAL	The value of the Flag parameter is not valid.

The unlink and unlinkat subroutines can be unsuccessful for other reasons. For a list of additional errors, see Base Operating System error codes for services that require path-name resolution.

If NFS is installed on the system, the unlink and unlinkat subroutines can also fail if the following is true:

Item	Description
ETIMEDOUT	The connection timed out.