link, linkat - create link to file

Syntax	#include <unistd.h> int link(const char *path1, const char *path2); int linkat(int fd1, const char *path1, int fd2, const char *path2, int flag);
Description	link() creates a new link (directory entry) for the existing file, path1. path1 points to a pathname naming an existing file. path2 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. Upon successful completion, link() will mark for update the st_ctime structure component of the file. The st_ctime and st_mtime fields of the directory that contains the new entry are also marked for update. If the link() function fails, no link is created, and the link count of the file remains unchanged. The calling process must have permission to access the existing file. link() is not executed between files of different file systems. If link( *path1 , *path2 ) is called successfully, and both path1 and path2 point to files of the POSIX file system, an internal link count is incremented by 1. Similarly, any successful call to unlink( *path ) or remove( *path ) decreases this link count by 1. If the count = 0 and the file is no longer open for any process, the file is deleted. The linkat() function is equivalent to the link() function except when symbolic links are to be handled in accordance with the value transferred in the flag parameter (see below), or when the path1 or path2 parameter specifies a relative path. If path1 specifies a relative pathname, this is interpreted as a path relative to the directory connected with the file descriptor fd1. If path2 specifies a relative pathname, this is interpreted as a path relative to the directory connected with the file descriptor fd2. If a file descriptor was opened without O_SEARCH, the function checks whether a search is permitted in the connected file descriptor with the authorizations applicable for the directory. If the file descriptor was opened with O_SEARCH, the check is not performed. When the value AT_FDCWD was transferred to the linkat() function for the fd1 or fd2 parameter, the current directory for determining the file of the corresponding path is used. In the flag parameter, the value AT_SYMLINK_FOLLOW, which is defined in the fnctl.h header, can be transferred. If path1 specifies a symbolic link, a new symbolic link is generated for the destination.
Return val.	0	if successful
	-1	if an error occurs; errno is set to indicate the error.
Errors	link() and linkat() will fail if:
	EACCES	Search permission is denied for a component of either path prefix, 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.
	EEXIST	The link named by path2 exists.
	Extension
	EFAULT	path1 or path2 points outside the allocated address space.
	EINTR	A signal was caught during the link() system call.
	EINVAL	An attempt was made to access a BS2000 file.
	ELOOP	Too many symbolic links were encountered in resolving path1 or path2. (End)
	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 one of the paths is not a directory.
	EPERM	The file named by path1 is a directory, and the process does not have appropriate privileges.
	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.
	In addition, linkat() fails if the following applies:
	EACCES	The file descriptor fd1 or fd2 was not opened with O_SEARCH, and the authorizations applicable for the directory do not permit the directory to be searched.
	EBADF	The path1 parameter does not specify an absolute pathname, and the fd1 parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor opened for reading or searching, or the path2 parameter does not specify an absolute pathname, and the fd2 parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor for reading or searching.
	ENOTDIR	The path1 or path2 parameter does not specify an absolute pathname, and the corresponding file descriptor fd1 / fd2 is not connected with a directory.
	EINVAL	The value of the flag parameter is invalid.
Notes	link() and linkat() are executed only for POSIX files.
See also	readlink(), remove(), symlink(), unlink(), fcntl.h, unistd.h.