NAME

symlink - make symbolic link to a file

 SYNOPSIS

#include <unistd.h>

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

 DESCRIPTION

The symlink() function creates a symbolic link. Its name is the pathname pointed to by path2, which must be a pathname that does not name an existing file or symbolic link. The contents of the symbolic link are the string pointed to by path1.

 RETURN VALUE

Upon successful completion, symlink() returns 0. Otherwise, it returns -1 and sets errno to indicate the error.

 ERRORS

The symlink() function will fail if:

[EACCES]

Write permission is denied in the directory where the symbolic link is being created, or search permission is denied for a component of the path prefix of path2.

[EEXIST]

The path2 argument names an existing file or symbolic link.

[EIO]

An I/O error occurs while reading from or writing to the file system.

[ELOOP]

Too many symbolic links were encountered in resolving path2.

[ENAMETOOLONG]

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

[ENOENT]

A component of path2 does not name an existing file or path2 is an empty string.

[ENOSPC]

The directory in which the entry for the new symbolic link is being placed cannot be extended because no space is left on the file system containing the directory, or the new symbolic link cannot be created because no space is left on the file system which will contain the link, or the file system is out of file-allocation resources.

[ENOTDIR]

A component of the path prefix of path2 is not a directory.

[EROFS]

The new symbolic link would reside on a read-only file system.

The symlink() function may fail if:

[ENAMETOOLONG]

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

 EXAMPLES

None.

 APPLICATION USAGE

Like a hard link, a symbolic link allows a file to have multiple logical names. The presence of a hard link guarantees the existence of a file, even after the original name has been removed. A symbolic link provides no such assurance; in fact, the file named by the path1 argument need not exist when the link is created. A symbolic link can cross file system boundaries.

Normal permission checks are made on each component of the symbolic link pathname during its resolution.

 FUTURE DIRECTIONS

None.

 SEE ALSO

lchown(), link(), lstat(), open(), readlink(), <unistd.h>.