link(2)                                                         link(2)

  link()

  NAME

    link(), wcs_link - make a hard file link

  SYNOPSIS

    #include 

    int link (const char *oldname, const char *newname)
    int wcs_link (const wchar_t *oldname, const wchar_t *newname)

  DESCRIPTION

    The link(2) and wcs_link(2) functions are identical except that the
    wcs_link(2) function accepts wide characters in the oldname and newname
    arguments.

    The link(2) or wcs_link(2) function call atomically creates the specified
    directory entry (hard link) newname with the attributes of the underlying
    object pointed at by oldname If the link is successful: the link count of
    the underlying object is incremented; oldname and newname share equal
    access and rights to the underlying object.

    If oldname is removed, the file newname is not deleted and the link count
    of the underlying object is decremented.

    The file specified by oldname must exist for the hard link to succeed, and
    both oldname and newname must be in the same file system. Oldname may not
    be a directory; NTFS does not support hard-linking a directory.

  RETURN VALUES

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

  ERRORS

    The link(2) or wcs_link(2) call will fail and no link will be created if:

    [EACCES]
        A component of either path prefix denies search permission.

    [EACCES]
        The requested link requires writing in a directory with a mode that
        denies write permission.

    [EEXIST]
        The link named by newname does exist.

    [EFAULT]
        One of the pathnames specified is outside the process's allocated
        address space.

    [EINVAL]
        Either pathname contains a character with the high-order bit set, or
        the file resides on a device that does not support the link(2)
        operation.

    [EIO]
        An I/O error occurred while reading from or writing to the file system
        to make the directory entry.

    [ELOOP]
        Too many symbolic links were encountered in translating one of the
        pathnames.

    [ENAMETOOLONG]
        A component of either pathname exceeded {NAME_MAX} characters, or
        entire length of either pathname exceeded {PATH_MAX} characters.

    [ENOENT]
        A component of either path prefix does not exist.

    [ENOENT]
        The file named by oldname does not exist.

    [ENOSPC]
        The directory in which the entry for the new link is being placed
        cannot be extended because there is no space left on the file system
        containing the directory.

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

    [EPERM]
        The file named by oldname is a directory.

    [EROFS]
        The requested link requires writing in a directory on a read-only file
        system.

    [EXDEV]
        The link named by newname and the file named by oldname are on
        different file systems.

  SEE ALSO

    remove(2)

    unlink(2)

  USAGE NOTES

    All of these functions are thread safe.

    All of these functions are async-signal safe.