symlink, symlinkat - make symbolic link to file

Syntax	#include <unistd.h> int symlink(const char *path1,, const char *path2); int symlinkat(const char *path1, int fd, const char *path2);
Description	symlink() creates a symbolic link. Its name is the pathname referenced by path2. This pathname must not be the same as the name of an existing file or a symbolic link. The content of the symbolic link is the string referenced by path1. A symbolic link can refer to another file system. The file identified by path1 need not be present. The file to which the symbolic link points is used when an open() operation is performed on the link. A stat() on a symbolic link returns the referenced file, whereas an lstat() returns information about the link itself. This can lead to surprising results when a symbolic link is made to a directory. To avoid undesirable side effects in programs, the readlink() call can be used to read the contents of a symbolic link. The symlinkat() function is equivalent to the symlink() function except when the path2 parameter specifies a relative path. In this case the symbolic link is not created in the current directory, but in the directory connected with the file descriptor fd. If the 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 is transferred to the symlinkat() function for the fd parameter, the current directory is used.
Return val.	0	if successful.
	-1	if an error occurs; errno is set to indicate the error.
Errors	symlink() and symlinkat() will fail if:
	EACCES	Search permission is denied for the directory in which the symbolic link was created. Search permission is denied for a component of the path prefix of path2.
	EEXIST	The file or symbolic link specified using path2 already exists.
	ENOTDIR	A component of the path prefix of path2 is not a directory.
	EIO	An I/O error occurred while reading from or writing to the file system.
	ELOOP	Too many symbolic links were encountered in resolving path2.
	ENAMETOOLONG
		The length of the path1 or path2 argument exceeds {PATH_MAX} or a component of path1 or path2 is longer than {NAME_MAX}. symlink() could also fail if the resolving of a symbolic link produces a result whose length exceeds {PATH_MAX}.
	ENOENT	A component of the pathname prefix of path2 does not exist or path2 is an empty string.
	ENOSPC	The directory in which the entry for the new symbolic link is to be created cannot be extended because there is no space left on the file system containing the directory. The new symbolic link cannot be created because there is no space left on the file system which will contain the link. There are no free inodes on the file system on which the file is to be created.
	EROFS	The new symbolic link would reside on a read-only file system.
	Extension
	EDQUOT	The directory in which the entry for the new symbolic link is to be placed cannot be extended because the maximum number of disk blocks allocated to the user (i.e. the user’s quota) on the file system was exceeded. The new symbolic link cannot be created because the user's quota of disk blocks on the file system that is to contain the link was exceeded. The user's quota of inodes on the file system on which the file is to be created was exceeded.
	EFAULT	path1 or path2 points outside the allocated address space for the process.
	ENOSYS	The file system does not support symbolic links. (End)
	In addition, symlinkat() fails if the following applies:
	EACCES	The file descriptor fd was not opened with O_SEARCH, and the authorizations applicable for the directory do not permit the directory to be searched.
	EBADF	The path2 parameter does not specify an absolute pathname, and the fd parameter does not have the value AT_FDCWD, nor does it contain a valid file descriptor opened for reading or searching.
	ENOTDIR	The path2 parameter does not specify an absolute pathname, and the file descriptor fd is not connected with a directory.
Notes	symlink() and symlinkat() are executed for POSIX files only.
See also	lchown(), link(), lstat(), open(), readlink(), fcntl.h, unistd.h, command cp in the manual "POSIX Commands".