NAME

symlink - make a symbolic link to a file

SYNOPSIS

#include <unistd.h>

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


DESCRIPTION

The symlink() function shall create a symbolic link called path2 that contains the string pointed to by path1 ( path2 is the name of the symbolic link created, path1 is the string contained in the symbolic link).

The string pointed to by path1 shall be treated only as a character string and shall not be validated as a pathname.

If the symlink() function fails for any reason other than [EIO], any file named by path2 shall be unaffected.

RETURN VALUE

Upon successful completion, symlink() shall return 0; otherwise, it shall return -1 and set errno to indicate the error.

ERRORS

The symlink() function shall 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]

A loop exists in symbolic links encountered during resolution of the path2 argument.

[ENAMETOOLONG]

The length of the path2 argument exceeds {PATH_MAX} or a pathname component is longer than {NAME_MAX} or the length of the path1 argument is longer than {SYMLINK_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 shall 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:

[ELOOP]

More than {SYMLOOP_MAX} symbolic links were encountered during resolution of the path2 argument.

[ENAMETOOLONG]

As a result of encountering a symbolic link in resolution of the path2 argument, the length of the substituted pathname string exceeded {PATH_MAX} bytes (including the terminating null byte), or the length of the string pointed to by path1 exceeded {SYMLINK_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.

RATIONALE

Since IEEE Std 1003.1-2001 does not require any association of file times with symbolic links, there is no requirement that file times be updated by symlink().

FUTURE DIRECTIONS

None.

SEE ALSO

lchown(), link(), lstat(), open(), readlink(), unlink(), the Base Definitions volume of IEEE Std 1003.1-2001, <unistd.h>

CHANGE HISTORY

First released in Issue 4, Version 2.

Issue 5

Moved from X/OPEN UNIX extension to BASE.

Issue 6

The following changes were made to align with the IEEE P1003.1a draft standard:

• The DESCRIPTION text is updated.

• The [ELOOP] optional error condition is added.