readlink or readlinkat Subroutine

Purpose

Reads the contents of a symbolic link.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>

int readlink ( Path,  Buffer,  BufferSize)
const char * Path;
char * Buffer;
size_t BufferSize;

int readlinkat ( DirFileDescriptor, Path, Buffer, BufferSize )
int DirFileDescriptor;
const char * Path;
char * Buffer;
size_t BufferSize;

Description

The readlink and readlinkat subroutines copy the contents of the symbolic link that is named by the Path parameter in the buffer that is specified in the Buffer parameter. The BufferSize parameter indicates the size of the buffer in bytes. If the actual length of the symbolic link is less than the number of bytes specified in the BufferSize parameter, the string copied into the buffer will be null-terminated. If the actual length of the symbolic link is greater than the number of bytes specified in the Buffersize parameter, an error is returned. The length of a symbolic link cannot exceed 1023 characters or the value of the PATH_MAX constant. PATH_MAX is defined in the limits.h file.

The readlinkat subroutine is equivalent to the readlink subroutine if the DirFileDescriptor parameter is AT_FDCWD or Path is an absolute path name. If DirFileDescriptor is a valid file descriptor of an open directory and Path is a relative path name, Path is considered to be relative to the directory that is associated with the DirFileDescriptor parameter instead of the current working directory.

If DirFileDescriptor was opened without the PATH_MAX open flag, the subroutine checks to determine whether directory searches are permitted for that directory by using the current permissions of the directory. If the directory was opened with the PATH_MAX open flag, the subroutine does not perform the check for that directory.

Parameters

Table 1. Parameters
Item	Description
`DirFileDescriptor`	Specifies the file descriptor of an open directory.
`Path`	Specifies the path name of the destination file or directory. If `DirFileDescriptor` is specified and `Path` is a relative path name, then `Path` is considered relative to the directory specified by `DirFileDescriptor`.
`Buffer`	Points to the user buffer. The buffer should be at least as large as the `BufferSize` parameter.
`BufferSize`	Indicates the size of the buffer. The contents of the link are null-terminated, provided there is room in the buffer.

Return Values

Upon successful completion, the readlink and readlinkat subroutines return a count of the number of characters that are placed in the buffer (not including any terminating null character). If the readlink or readlinkat subroutine is unsuccessful, the buffer is not modified, a value of -1 is returned, and the errno global variable is set to indicate the error.

Error Codes

The readlink and readlinkat subroutines fail if one or both of the following are true:

Table 2. Error Codes for readlink and readlinkat
Item	Description
`ENOENT`	The file that is named by the `Path` parameter does not exist, or the path points to an empty string.
`EINVAL`	The file named by the `Path` parameter is not a symbolic link.
`ERANGE`	The path name in the symbolic link is longer than the `BufferSize` value.

The readlinkat subroutine is unsuccessful if one or more of the following is true:

Table 3. Error codes for readlinkat
Item	Description
`EBADF`	The `Path` parameter does not specify an absolute path and the `DirFileDescriptor` parameter is neither `AT_FDCWD` not a valid file descriptor.
`ENOTDIR`	The `Path` parameter does not specify an absolute path and the `DirFileDescriptor` parameter is neither `AT_FDCWD` nor a file descriptor associated with a directory.

The readlink and readlinkat subroutines can also fail due to additional errors.

If Network File System (NFS) is installed on the system, the readlink and readlinkat subroutines can also fail if the following is true:

Table 4. Error code for NFS
Item	Description
`ETIMEDOUT`	The connection timed out.