link(S)                        6 January 1993                        link(S)


 Name

    link - link to a file

 Syntax


    cc ... -lc


    int link (path, newpath)
    char *path, *newpath;


 Description

    The path argument points to a path name naming an existing file.  The
    newpath argument points to a path name naming the new directory entry to
    be created.  The link system call creates a new link (directory entry)
    for the existing file.

    Upon successful completion, link marks for update the ``st_ctime'' and
    ``st_mtime'' fields of the parent directory.  Also, the ``st_ctime'' and
    ``st_mtime'' fields of the file are marked for update.

    The link system call fails and no link is created if one or more of the
    following is true:

    [EACCES]       1. A component of either path prefix denies search permis-
                   sion.
                   2. The requested link requires writing in a directory with
                   a mode that denies write permission.

    [EEXIST]       The link named by newpath exists.

    [EFAULT]       path points outside the allocated address space of the
                   process.

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

    [EMLINK]       The maximum number of links to a file would be exceeded.

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

    [ENOENT]       1. A component of either path prefix does not exist.
                   2. The file named by path does not exist.
                   3. newpath points to a null path name.

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

    [ENOSPC]       The directory containing the link cannot be extended.

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

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

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

    [EXDEV]        The link named by newpath and the file named by path are
                   on different logical devices (file systems).


 Diagnostics

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

 See also

    stat(S), unlink(S)

 Standards conformance

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