SYMLINK(2)

💖 SYMLINK(2) 💖 — the symlink glow-up, from your fave syscall bestie

okay so. you opened the System Calls Manual (that's the manual name, it lives in section 2, syscalls only, no cap) and you landed on symlink. bestie, you are about to make a link that is literally symbolic. not a hard link. a vibe. let's go. 🦋

---

✨ NAME ✨

symlink, symlinkat — make symbolic link to a file

📚 LIBRARY 📚

Standard C Library (libc, -lc)

---

🌸 SYNOPSIS 🌸

like, here's the whole thing, copy it exactly, don't freestyle:

#include <unistd.h>

int
symlink(const char *name1, const char *name2);

int
symlinkat(const char *name1, int fd, const char *name2);

---

💅 DESCRIPTION 💅

So. A symbolic link name2 is created to name1. And before you get confused (everyone does, it's fine, breathe): name2 is the name of the file being created, and name1 is the string used in creating the symbolic link. The way that the "new thing" is name2 and the "thing it points at" is name1? iconic. slightly chaotic. we love her. 🙈

Either name can be an arbitrary path name — go feral, no rules — and the files do not have to live on the same file system. cross-filesystem? she doesn't care. main character energy. ✨

Now. symlinkat() is the same girl as symlink() except in one specific case: when name2 specifies a relative path. In that case, the symbolic link gets created relative to the directory associated with the file descriptor fd instead of the current working directory. cute, right? 🎀

And if you pass symlinkat() the special value AT_FDCWD in the fd parameter? Then the current working directory is used and the behavior is identical to a call to symlink(). fr fr, same thing.

---

🔥 RETURN VALUES 🔥

symlink() returns the value 0 if it ate and left no crumbs (successful). Otherwise the value -1 comes back and the global variable errno is set to indicate the error. 😭 the -1 is never good news.

---

💀 ERRORS 💀

The symbolic link succeeds unless — and girl, there are so many unlesses:

• [ENOTDIR] — a component of the name2 path prefix is not a directory. rude.
• [ENAMETOOLONG] — a component of the name2 pathname exceeded 255 characters, or the entire length of either path name exceeded 1023 characters. she said too long, bestie 💀
• [ENOENT] — a component of the name2 path prefix does not exist. she's not there. ghosted.
• [EACCES] — a component of the name2 path prefix denies search permission, or write permission is denied on the parent directory of the file to be created.
• [ELOOP] — too many symbolic links were encountered in translating the name2 path name. it's giving infinite hallway 😵💫
• [EEXIST] — the path name pointed at by the name2 argument already exists. she's taken!!
• [EPERM] — the parent directory of the file named by name2 has its immutable flag set. see the chflags(2) manual page for more information. that directory is not accepting applications. 🚫
• [EIO] — an I/O error occurred while making the directory entry for name2, allocating the inode for name2, or writing out the link contents of name2.
• [EROFS] — the file name2 would reside on a read-only file system. no writes allowed, periodt.
• [ENOSPC] — the directory in which the entry for the new symbolic link is being placed cannot be extended because there is no space left on the file system containing the directory.
• [ENOSPC] — the new symbolic link cannot be created because there is no space left on the file system that will contain the symbolic link.
• [ENOSPC] — there are no free inodes on the file system on which the symbolic link is being created. (yes, three separate ENOSPC situations. she contains multitudes.)
• [EDQUOT] — the directory in which the entry for the new symbolic link is being placed cannot be extended because the user's quota of disk blocks on the file system containing the directory has been exhausted.
• [EDQUOT] — the new symbolic link cannot be created because the user's quota of disk blocks on the file system that will contain the symbolic link has been exhausted.
• [EDQUOT] — the user's quota of inodes on the file system on which the symbolic link is being created has been exhausted. quota said enough 🫶
• [EINTEGRITY] — corrupted data was detected while reading from the file system. she's not okay, and neither is the disk. 😭
• [EFAULT] — the name1 or name2 argument points outside the process's allocated address space. out of bounds, out of pocket.

On top of all the errors symlink() returns, symlinkat() may also fail if:

• [EBADF] — the name2 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 name2 argument is not an absolute path and fd is neither AT_FDCWD nor a file descriptor associated with a directory.

pro tip from your girl: errno is the group chat. read it immediately after the -1 or the messages get marked as read and you'll never know what happened. 💅

---

👀 SEE ALSO 👀

ln(1), chflags(2), link(2), lstat(2), readlink(2), unlink(2), symlink(7)

iykyk, go read them, they're all besties.

---

⭐ STANDARDS ⭐

The symlinkat() system call follows The Open Group Extended API Set 2 specification. she's certified. she's got paperwork. 📜

---

🌈 HISTORY 🌈

• The symlink() system call appeared in 4.2BSD. an elder. a legend. 👑
• The symlinkat() system call appeared in FreeBSD 8.0.

---

and that's the whole page, bestie. no cap, every flag, every errno, every vibe — all preserved. this gorgeous little page came to you via Debian and is dated March 30, 2020, and it's the SYMLINK(2) entry in the System Calls Manual. go make some links. slay. 💖✨🎀