Removes a directory entry.
Standard C Library (libc.a)
#include <unistd.h>int unlink (Path)
const char *Path;
int unlinkat (DirFileDescriptor,
Path, Flag)
int DirFileDescriptor;
const char * Path;
int Flag;
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.
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.
| 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. |
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.
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. |