unlink(S)                      6 January 1993                      unlink(S)


 Name

    unlink - remove directory entry

 Syntax


    cc ... -lc


    int unlink (path)
    char *path;


 Description

    The unlink function removes the link named by the pathname pointed to by
    path and decrements the link count of the file referenced by the link.

    When the file's link count becomes zero and no process has the file open,
    the space occupied by the file is freed and the file is no longer acces-
    sible.  If one or more processes have the file open when the last link is
    removed, the link is removed before unlink returns, but the removal of
    the file contents is postponed until all references to the file have been
    closed.

    Upon successful completion, unlink 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'' and ``st_mtime'' fields of the file
    are marked for update.

    If all of the following conditions are true, a file is not unlinked:

    1.  The parent directory has the sticky bit set

    2.  The file is not writable by the user

    3.  The user does not own the parent directory

    4.  The user does not own the file

    5.  The user is not root

    When all links to a file have been removed and no process has the file
    open, the space occupied by the file is freed and the file ceases to
    exist.  If one or more processes have the file open when the last link is
    removed, the removal is postponed until all references to the file have
    been closed.

 Return value

    Upon successful completion, a value of 0 is returned.  Otherwise, a value
    of -1 is returned and errno is set to indicate the error.

 Diagnostics

    The unlink function will fail and not unlink the file if:

    [EACCES]       Search permission is denied for a component of the path
                   prefix, or 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.

    [EINTR]        A signal was caught during the unlink system call.

    [EMULTIHOP]    Components of path require hopping to multiple remote ma-
                   chines.

    [ENAMETOOLONG] The length of the path string exceeds PATHMAX or a path-
                   name component is longer than NAMEMAX while
                   POSIXNOTRUNC is in effect.

    [ENOENT]       The named file does not exist, or the path argument points
                   to an empty string.

    [ENOLINK]      path points to a remote machine and the link to that ma-
                   chine is no longer active.

    [ENOTDIR]      A component of the path prefix is not a directory.

    [EPERM]        The named file is a directory and the effective user ID of
                   the process is not super user.

    [EROFS]        The directory entry to be unlinked is part of a read-only
                   file system.

    [ETXTBSY]      The entry to be unlinked is the last link to a pure pro-
                   cedure (shared text) file that is being executed.


 See also

    close(S), link(S), open(S), rm(C), stat(S)

 Standards conformance

    unlink is conformant with:
    AT&T SVID Issue 2;
    X/Open Portability Guide, Issue 3, 1989;
    Intel386 Binary Compatibility Specification, Edition 2 (iBCSe2);
    IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C
    Language] (ISO/IEC 9945-1);
    and NIST FIPS 151-1.