symlink

, symlinkat

- make a symbolic link to a file

Synopsis

#include <unistd.h>

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

int symlinkat(const char *path1,int fd,  const char *path2);

Description

The symlink() function creates a symbolic link path2 to the file path1. Either name may be an arbitrary pathname, the files need not be on the same file system, and path1 may be nonexistent.

The file to which the symbolic link points is used when an open(2) operation is performed on the link. A stat() operation performed on a symbolic link returns the linked-to file, while an lstat() operation returns information about the link itself. See stat(2). Unexpected results may occur when a symbolic link is made to a directory. To avoid confusion in applications, the readlink(2) call can be used to read the contents of a symbolic link.

The symlinkat() function is equivalent to the symlink() function except in the case where path2 specifies a relative path. In this case the symbolic link is created relative to the directory associated with the file descriptor fd instead of the current working directory. If the file descriptor was opened without O_SEARCH, the function checks whether directory searches are permitted using the current permissions of the directory underlying the file descriptor. If the file descriptor was opened with O_SEARCH, the function does not perform the check.

If symlinkat() is passed the special value AT_FDCWD in the fd parameter, the current working directory is used and the behavior is identical to a call to symlink().

Return Values

Upon successful completion, 0 is returned. Otherwise, -1 is returned, errno is set to indicate the error, and the symbolic link is not made.

Errors

The symlink() and symlinkat() functions 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.

EDQUOT

The directory where the entry for the new symbolic link is being placed cannot be extended because the user's quota of disk blocks on that file system has been exhausted; the new symbolic link cannot be created because the user's quota of disk blocks on that file system has been exhausted; or the user's quota of inodes on the file system where the file is being created has been exhausted.

EEXIST

The file referred to by path2 already exists.

EFAULT

The path1 or path2 argument points to an illegal address.

EILSEQ

The path argument includes non-UTF8 characters and the file system accepts only file names where all characters are part of the UTF-8 character codeset.

EIO

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

ELOOP

Too many symbolic links are encountered in translating path2.

ENAMETOOLONG

The length of the path2 argument exceeds PATH_MAX, or the length of a path2 component exceeds NAME_MAX while _POSIX_NO_TRUNC is in effect.

ENOENT

A component of the path prefix of path2 does not exist.

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; the new symbolic link cannot be created because no space is left on the file system which will contain the link; or there are no free inodes on the file system on which the file is being created.

ENOSYS

The file system does not support symbolic links.

ENOTDIR

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

EROFS

The file path2 would reside on a read-only file system.

The symlinkat() function will fail if:

EACCES

fd was not opened with O_SEARCH and the permissions of the directory underlying fd do not permit directory searches.

EBADF

The path2 argument does not specify an absolute path and the fd argument is neither AT_FDCWD nor a valid file descriptor open for reading or searching.

The symlink() and symlinkat() functions may fail if:

ELOOP

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

ENAMETOOLONG

The length of the path2 argument exceeds {PATH_MAX} or pathname resolution of a symbolic link in the path2 argument produced an intermediate result with a length that exceeds {PATH_MAX}.

The symlinkat() function may fail if:

ENOTDIR

The path2 argument is not an absolute path and fd is neither AT_FDCWD nor a file descriptor associated with a directory

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

cp(1), link(2), open(2), readlink(2), stat(2), unlink(2), attributes(5)