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}. 

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. 

SEE ALSO

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

CHANGE HISTORY

First released in Issue 4, Version 2. 

HP−UX EXTENSIONS

ERRORS

If symlink() fails, errno is set to one of the following values. 

[EFAULT] path1 or path2 points outside the process’s allocated address space.  The reliable detection of this error is implementation-dependent. 

[EIO] An I/O error occurred while making the directory entry for path2, allocating the inode for path2, or writing out the link contents of path2.

[EIO] An I/O error occurred while making the directory entry or allocating the inode. 

AUTHOR

symlink() was developed by the University of California, Berkeley. 

SEE ALSO

cp(1), link(2), readlink(2), unlink(2), symlink(4). 

STANDARDS CONFORMANCE

symlink(): AES, SVID3

Hewlett-Packard Company  —  HP-UX Release 10.20:  July 1996