readlink or readlinkat Subroutine
Purpose
Reads the contents of a symbolic link.
Library
Standard C Library (libc.a)
Syntax
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 named by the Path parameter in the buffer 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 O_SEARCH 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 O_SEARCH open flag, the subroutine does not perform the check for that directory.
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 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:
| Item | Description |
|---|---|
| ENOENT | The file 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:
| 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:
| Item | Description |
|---|---|
| ETIMEDOUT | The connection timed out. |