[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions , Volume 2

unlink Subroutine


Removes a directory entry.


Standard C Library (libc.a)


#include <unistd.h>

int unlink ( Path)
const char *Path;


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.


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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

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.1 General Programming Concepts: Writing and Debugging Programs.

[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]