linkat()

Arguments:

olddirfd

A file descriptor that indicates the base directory for relative filepaths. The pathname given in oldpath is resolved by appending it to the directory associated with olddirfd. You can set this argument to AT_FDCWD to use the current working directory as the base directory.

Note:

The QNX OS implementation of the *at() functions differ from the POSIX standards. You must use a file descriptor obtained from an open() or openat() call with the O_DIRECTORY flag set, rather than the O_SEARCH flag on POSIX. Otherwise, the function fails and sets errno to ENOTDIR.

If oldpath specifies an absolute path, olddirfd has no effect.

oldpath

The path of an existing file that you're creating a hard link to. This can be absolute or relative; for details of how relative pathname resolution is done, see above.

newdirfd

A file descriptor that indicates the base directory for relative filepaths. The pathname given in newpath is resolved by appending it to the directory associated with newdirfd. You can set this argument to AT_FDCWD to use the current working directory as the base directory.

Note:

The QNX OS implementation of the *at() functions differ from the POSIX standards. You must use a file descriptor obtained from an open() or openat()call with the O_DIRECTORY flag set, rather than the O_SEARCH flag on POSIX. Otherwise, the function fails and sets errno to ENOTDIR.

If newpath specifies an absolute path, newdirfd has no effect.

newpath

The path of the new link. This can be absolute or relative; for details of how relative pathname resolution is done, see above.

flags

A bitfield of the following flags:

• AT_SYMLINK_FOLLOW — if oldpath names a symbolic link, create a new link for the target of the symbolic link.

Library:

libc

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

Description:

The linkat() function creates a new directory entry named by newpath to refer to (that is, to be a hard link to) an existing file named by oldpath. Each of the oldpath and newpath arguments can contain an absolute or a relative path. In the latter case, the corresponding file descriptor argument (olddirfd for oldpath and newdirfd for newpath) is used to resolve the pathname, as explained in the descriptions of these arguments (above).

For olddirfd and newdirfd, the function checks if directory searches are permitted using the current permissions of the directory underlying the file descriptor.

When the flags field is 0, this function is equivalent to link() when both oldpath and newpath are absolute and not relative paths. For details about other possible flags settings, see this argument's description (above).

QNX OS 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, linkat() can still be used for maintaining a per-thread current working directory, using file descriptors maintained by the application.

If it succeeds, the linkat() function atomically creates a new link for the existing file and increments the link count of the file by one. For information about which fields of the file and the directory are updated, see the link() reference.

If the link specified by newpath already exists, the function fails and an error is returned. If the function fails for this or any other reason, no link is created, and the link count of the file remains unchanged.

Returns:

0

Success.

-1

An error occurred (errno is set).

Errors:

EACCES

One of the following is true:

• A component of the path prefix in oldpath or newpath denies search permission.
• You don't have permission to search the directory underlying olddirfd or newdirfd.
• The link named by newpath is in a directory with a mode that denies write permission.
• The calling process does not have read permission for the existing file.

EBADF

One of the paths (oldpath or newpath) does not specify an absolute path and the corresponding file descriptor (olddirfd or newdirfd) is neither AT_FDCWD nor a valid file descriptor open for reading.

EEXIST

The link named by newpath already exists.

EINVAL

An invalid value was specified for flags.

ELOOP

During resolution of the oldpath or newpath argument, too many levels of symbolic links were encountered.

EMLINK

The number of links to the file named by oldpath would exceed LINK_MAX.

ENAMETOOLONG

The length of the oldpath or newpath string exceeds PATH_MAX, or the resolution of a symbolic link within one of these strings produced a result longer than PATH_MAX.

ENOENT

One of the following conditions is true:

• A component of the path prefix in oldpath or newpath doesn't exist.
• The file named by oldpath doesn't exist.
• Either oldpath or newpath points to an empty string.

ENOSPC

The directory that would contain the link can't be extended.

ENOSYS

The linkat() function isn't implemented for the filesystem underlying the path specified in oldpath or newpath.

ENOTDIR

One of the following is true:

• A component of the path prefix in oldpath or newpath names an existing file that is neither a directory nor a symbolic link to one.
• The pathname in oldpath contains at least one non-slash character, ends with at least one slash character (/), and the last component names an existing file that is neither a directory nor a symbolic link to one.
• The path in oldpath names an existing non-directory and the path in newpath names a non-existent file, contains at least one non-slash character, and ends with at least one slash character (/).
• The oldpath or newpath argument isn't an absolute path and the associated olddirfd or newdirfd file descriptor is associated with a non-directory file.
• One of the file descriptors (olddirfd or newdirfd) was created without O_DIRECTORY set.

EPERM

The file named by oldpath is a directory and the calling process doesn't have the appropriate permissions.

EROFS

The requested link requires writing in a directory on a read-only filesystem.

EXDEV

The link named by newpath and the file named by oldpath are on different filesystems and the implementation doesn't support links between filesystems. Or, oldpath refers to a named stream.

Classification:

POSIX 2008