symlinkat()

Create a symbolic link to a path, at a given location

Synopsis:

#include <fcntl.h>

int symlinkat( const char* const psymlink,
               int dirfd,              
               const char* const path );

Arguments:

psymlink: The path that you want to link to.
dirfd: A file descriptor that indicates the base directory for relative file paths. The symbolic link name given in path is appended to the directory associated with dirfd, to produce the full link path. You can set this argument to AT_FDCWD to use the current working directory as the base directory.
Note: You must use a file descriptor obtained from an open() call with the O_DIRECTORY flag set. Otherwise, the function fails and sets errno to ENOTDIR.

If path specifies an absolute path, dirfd has no effect.
path: The name of the symbolic link that you want to create. This can be absolute or relative; for details of how relative pathname resolution is done, see above.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The symlinkat() function creates a symbolic link named path that contains the pathname specified by psymlink (path is the name of the symbolic link created, psymlink is the pathname contained in the symbolic link). The path argument can contain an absolute or relative path. In the latter case, the dirfd argument is used to resolve the pathname, as explained in this argument's description (above).

If the access mode of the open file description associated with the dirfd file descriptor is not O_SEARCH, the function checks if directory searches are permitted using the current permissions of the directory underlying the file descriptor. If the access mode is O_SEARCH, the function doesn't perform the check.

QNX Neutrino has no concept of a path operation (open(), readlink(), etc.) that references a path relative to an already open file descriptor (for a directory), as far as the filesystem resource manager is concerned. Therefore, it's not possible to eliminate the race inherent in looking up a pathname with multiple intervening directories or symbolic links. However, symlinkat() can still be used for maintaining a per-thread current working directory, using file descriptors maintained by the application.

File access checking isn't performed on the file named by psymlink, and the file need not exist.

If symlinkat() is unsuccessful, any file named by path is unaffected.

Returns:

0: Success.
-1: An error occurred (errno is set).

Errors:

EACCES

One of the following is true:

Search permission is denied on a component of the path prefix of path.
Write permission is denied for the parent directory of the symbolic link to be created.
The access mode of the dirfd file descriptor is not O_SEARCH and the underlying directory doesn't permit directory searches.

EBADF

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

EEXIST

The file named by path already exists.

EIO

An I/O error occurred while reading from the filesystem.

ELOOP

During resolution of the path argument, a loop was found in the symbolic links or more than SYMLOOP_MAX symbolic links were encountered.

ENAMETOOLONG

One of the following is true:

The length of the psymlink string exceeds SYMLINK_MAX.
A pathname component in path exceeds NAME_MAX bytes.
The length of the path string exceeds PATH_MAX.
The resolution of a symbolic link within path produced a result longer than PATH_MAX.

ENOENT

The named file doesn't exist, or path is an empty string.

ENOSPC

One of the following is true:

There's no space left on the filesystem containing the directory into which the symbolic link is to be placed.
The symbolic link can't be created because there's no space left on the filesystem that shall contain it.
The filesystem is out of file-allocation resources.

ENOTDIR

One of the following is true:

A component of the target path prefix in path names an existing file that is neither a directory nor a symbolic link to one.
The path argument is not absolute and fd is associated with a non-directory file.
The file descriptor in dirfd was created without O_DIRECTORY set.

EROFS

The new symbolic link (path) would reside on a read-only filesystem.

Classification:

POSIX 2008

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes