Technical Reference: Base Operating System and Extensions, Volume 2

unlink Subroutine

Purpose

Removes a directory entry.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

int unlink ( Path) const char *Path;

Description

The unlink subroutine removes the directory entry specified by the Path parameter and decreases 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 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 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 to remove a directory. If the Path parameter names a symbolic link, the link itself is removed.

Parameters

Path	Specifies the directory entry to be 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 subroutine fails and the named file is not unlinked if one of the following is true:

ENOENT	The named file does not exist.
EACCES	Write permission is denied on the directory containing the link to be removed.
EPERM	The named file is a directory, and the calling process does not have root user authority.
EBUSY	The entry to be unlinked is the mount point for a mounted filesystem, 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.
EROFS	The entry to be unlinked is part of a read-only file system.

The unlink subroutine can be unsuccessful for other reasons. For a list of additional errors, see Appendix A, "Base Operating System Error Codes for Service That Require Path-Name Resolution"

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

ETIMEDOUT

The connection timed out.

Related Information

The close subroutine, link subroutine, open subroutine, remove (remove Subroutine) subroutine, rmdir (rmdir Subroutine) subroutine.

The rm command.

Files, Directories, and File Systems for Programmers in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.