READLINK(2)

💖 READLINK(2) — System Calls Manual 💖

okay bestie, pull up a chair, we're talking about readlink, readlinkat, and the whole "read value of a symbolic link" situation. this is page 2 of the System Calls Manual and it is, lowkey, iconic. 🦋

---

✨ NAME ✨

readlink, readlinkat — read value of a symbolic link

📚 LIBRARY 📚

Standard C Library (libc, -lc) — yeah she lives in libc, no cap.

🌸 SYNOPSIS 🌸

#include <unistd.h>

ssize_t
readlink(const char *restrict path, char *restrict buf, size_t bufsiz);

ssize_t
readlinkat(int fd, const char *restrict path, char *restrict buf,
    size_t bufsize);

---

💅 DESCRIPTION 💅

so. the readlink() system call takes the contents of the symbolic link path and drops them into the buffer buf, which has size bufsiz. that's it, that's the whole vibe. but — and this is the part people always get wrong — readlink() does not append a NUL character to buf. not even one. so don't be out here treating buf like a string, because it is not one, periodt. 😭

now for readlinkat(): she's literally equivalent to readlink() except when path is a relative path. in that case, the symbolic link content gets read relative to the directory associated with the file descriptor fd, instead of relative to the current working directory. main character behaviour fr fr. and if you pass the special value AT_FDCWD in the fd parameter, then the current working directory is used and the behaviour is identical to a plain old call to readlink(). same energy, same result. 🫶

🎀 RETURN VALUES 🎀

if it succeeds, the call returns the count of characters placed in the buffer. if an error happens, you get a -1 and the error code goes into the global variable errno. classic. count on success, -1 on sadness.

🔥 ERRORS 🔥

the readlink() system call will fail if:

• [ENOTDIR] — a component of the path prefix is not a directory.
• [ENAMETOOLONG] — a component of a pathname exceeded 255 characters, or an entire path name exceeded 1023 characters. (numbers matter, bestie, don't round them.)
• [ENOENT] — the named file does not exist. 💀
• [EACCES] — search permission is denied for a component of the path prefix.
• [ELOOP] — too many symbolic links were encountered in translating the pathname. (the links were linking, bestie.)
• [EINVAL] — the named file is not a symbolic link.
• [EIO] — an I/O error occurred while reading from the file system.
• [EINTEGRITY] — corrupted data was detected while reading from the file system.
• [EFAULT] — the buf argument extends outside the process's allocated address space.

and on top of all the errors readlink() returns, readlinkat() may also fail if:

• [EBADF] — the path argument does not specify an absolute path and the fd argument is neither AT_FDCWD nor a valid file descriptor open for searching.
• [ENOTDIR] — the path argument is not an absolute path and fd is neither AT_FDCWD nor a file descriptor associated with a directory.

⚠️ heads up: [ENOTDIR] shows up in both lists. that's not a typo, that's just the lore.

👀 SEE ALSO 👀

lstat(2), stat(2), symlink(2), symlink(7)

🌈 STANDARDS 🌈

the readlinkat() system call follows The Open Group Extended API Set 2 specification. she's certified. 👑

⭐ HISTORY ⭐

the readlink() system call appeared in 4.2BSD. the readlinkat() system call appeared in FreeBSD 8.0. glow-up timeline, honestly. ✨

---

and that's the whole page, bestie — go read some symlinks responsibly 💜

this was brought to you by the Debian crew, dated March 30, 2020, on page READLINK(2). mwah. 🎀💖