NAME

link - link to a file

 SYNOPSIS

#include <unistd.h>

int link(const char *path1, const char *path2);

 DESCRIPTION

The link() function creates a new link (directory entry) for the existing file, path1.

The path1 argument points to a pathname naming an existing file. The path2 argument points to a pathname naming the new directory entry to be created. The link() function will atomically create a new link for the existing file and the link count of the file is incremented by one.

If path1 names a directory, link() will fail unless the process has appropriate privileges and the implementation supports using link() on directories.

Upon successful completion, link() will mark for update the st_ctime field of the file. Also, the st_ctime and st_mtime fields of the directory that contains the new entry are marked for update.

If link() fails, no link is created and the link count of the file will remain unchanged.

The implementation may require that the calling process has permission to access the existing file.

 RETURN VALUE

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

 ERRORS

The link() function will fail if:

[EACCES]

A component of either path prefix denies search permission, or the requested link requires writing in a directory with a mode that denies write permission, or the calling process does not have permission to access the existing file and this is required by the implementation.

[EEXIST]

The link named by path2 exists.

[ELOOP]

Too many symbolic links were encountered in resolving path1 or path2.

[EMLINK]

The number of links to the file named by path1 would exceed {LINK_MAX}.

[ENAMETOOLONG]

The length of path1 or path2 exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX}.

[ENOENT]

A component of either path prefix does not exist; the file named by path1 does not exist; or path1 or path2 points to an empty string.

[ENOSPC]

The directory to contain the link cannot be extended.

[ENOTDIR]

A component of either path prefix is not a directory.

[EPERM]

The file named by path1 is a directory and either the calling process does not have appropriate privileges or the implementation prohibits using link() on directories.

[EROFS]

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

[EXDEV]

The link named by path2 and the file named by path1 are on different file systems and the implementation does not support links between file systems, or path1 refers to a named STREAM.

The link() function may fail if:

[ENAMETOOLONG]

Pathname resolution of a symbolic link produced an intermediate result whose length exceeds {PATH_MAX}.

 EXAMPLES

None.

 APPLICATION USAGE

Some implementations do allow links between file systems.

 FUTURE DIRECTIONS

None.

 SEE ALSO

symlink(), unlink(), <unistd.h>.

DERIVATION

Derived from Issue 1 of the SVID.