gpfs_linkat() subroutine

Creates a file link relative to directory file descriptors.

Library

GPFS Library (libgpfs.so for Linux®)

Synopsis

#include <gpfs.h>
int gpfs_linkat(gpfs_file_t olddirfd, const char *oldpath,
                gpfs_file_t newdirfd, const char *newpath, int flags);

Description

The gpfs_linkat() subroutine creates a file link relative to directory file descriptors. If the file name already exists, the gpfs_linkat() subroutine replaces the destination automatically. This API call uses the same arguments as the Linux linkat() system call. This API call can be used to link files that are opened with O_TMPFILE to a directory.

The gpfs_linkat() subroutine is not supported on AIX®. Attempting to use this call on AIX might result in errno of ENOSYS.

Parameters

oldpath

The relative path of the file or directory that needs to be linked to a file or directory. If the pathname given in oldpath is relative, then it is interpreted relative to the directory referred to by the file descriptor olddirfd.

If oldpath is relative and olddirfd is the special value AT_FDCWD, then oldpath is interpreted relative to the current working directory of the calling process.

If oldpath is absolute, then olddirfd is ignored.

AT_EMPTY_PATH: If oldpath is an empty string, create a link to the file referenced by olddirfd. In this case, olddirfd can refer to any type of file except a directory. This will generally not work if the file has a link count of zero (files that are created with O_TMPFILE and without O_EXCL are an exception). The caller must have the CAP_DAC_READ_SEARCH capability in order to use this flag.

AT_SYMLINK_FOLLOW: By default, linkat() does not dereference oldpath if it is a symbolic link. The flag AT_SYMLINK_FOLLOW can be specified in flags to cause oldpath to be dereferenced if it is a symbolic link.

newpath

The relative path of the file or directory to which the file or directory is linked. The interpretation of newpath is as for oldpath, except that a relative pathname is interpreted relative to the directory referred to by the file descriptor newdirfd.

When newpath specifies an existing file, it is automatically replaced and EEXIST is never returned. Unlike the Linux) linkat() call, specifying the AT_EMPTY_PATH flag does not require the CAP_DAC_READ_SEARCH capability.

Exit status

If the gpfs_linkat() subroutine is successful, it returns a value of 0 and links a file to a directory name.

If the gpfs_linkat() subroutine is unsuccessful, it returns a value of -1 and sets the global error variable errno to indicate the nature of the error.

Exceptions

None.

Error status

Error codes include but are not limited to the following:

EBADF: The file descriptor is not valid.
EINVAL: The source or destination does not refer to a regular file or a GPFS file system.
EISDIR: The specified path name is a directory.
ENOMEM: Unable to allocate memory for the request.
ENOSYS: The gpfs_linkat() subroutine is not available.
ESTALE: The cached file system information was not valid.

Location

/usr/lpp/mmfs/lib/libgpfs.so for Linux