std::experi...::is_symlink(3)

🌸 std::experi...::is_symlink(3) 🌸

okay bestie, so this one lives in the C++ Standard Libary manual (yes that's how it's spelled in the manual name, we don't ask 💅) — and it's literally just "hey, is this thing a symlink?" but make it C++ filesystem TS. no cap, she's a small function with big "am I a link or not" energy. let's get into it 🫶

---

✨ NAME ✨

std::experimental::filesystem::is_symlink — yeah. that's it. that's the name. twice, actually:

std::experimental::filesystem::is_symlink std::experimental::filesystem::is_symlink

periodt 💅

---

✨ SYNOPSIS ✨

so first, where does she live? in this header, bestie:

Defined in header <experimental/filesystem>
bool is_symlink( file_status s );                 (1) (filesystem TS)
bool is_symlink( const path& p );                 (2) (filesystem TS)
bool is_symlink( const path& p, error_code& ec );

what she does: checks if the given file status or path corresponds to a symbolic link, as if determined by the POSIX S_IFLNK. like, she's doing the vibe check the same way POSIX would 🔍

1. Equivalent to s.type() == file_type::symlink.
2. Equivalent to is_symlink(status(p)) or is_symlink(status(p, ec)).

---

✨ PARAMETERS ✨

• s — file status to check. the lil status object you're interrogating 🕵️‍♀️
• p — path to examine. the thing you're pointing at 👀
• ec — out-parameter for error reporting in the non-throwing overload. she'll tuck the error in here instead of yelling at you 🙈

---

✨ RETURN VALUE ✨

true if the file indicated by p or if the type indicated s refers to a symbolic link. slay, that's it.

the non-throwing overload returns false if an error occurs. no drama, just false. 💀

---

✨ EXCEPTIONS ✨

1) noexcept specification: noexcept. she's chill, she does not throw. iconic.

2) okay so the overload that does not take an error_code& parameter throws filesystem_error on underlying OS API errors, constructed with p as the first argument and the OS error code as the error code argument. also std::bad_alloc may be thrown if memory allocation fails (allocation said "not today" 😭).

the overload taking an error_code& parameter sets it to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur. this overload has noexcept specification: noexcept. very demure, very mindful 🌸

---

✨ NOTES ✨

the info this function gives you is usually also provided as a byproduct of directory iteration. so like, if you're already iterating, you kinda have it? 👑

but listen: during directory iteration, calling is_symlink(*iterator) is less efficient than is_symlink(iterator->status()). use the cached status, bestie, your perf will thank you 🧚

---

✨ EXAMPLE ✨

// Run this code

#include <cstdio>
#include <cstring>
#include <experimental/filesystem>
#include <fstream>
#include <iostream>
#include <sys/socket.h>
#include <sys/stat.h>
#include <sys/un.h>
#include <unistd.h>

namespace fs = std::experimental::filesystem;

void demo_status(const fs::path& p, fs::file_status s)
{
    std::cout << p;
    // alternative: switch(s.type()) { case fs::file_type::regular: ... }
    if (fs::is_regular_file(s))
        std::cout << " is a regular file\n";
    if (fs::is_directory(s))
        std::cout << " is a directory\n";
    if (fs::is_block_file(s))
        std::cout << " is a block device\n";
    if (fs::is_character_file(s))
        std::cout << " is a character device\n";
    if (fs::is_fifo(s))
        std::cout << " is a named IPC pipe\n";
    if (fs::is_socket(s))
        std::cout << " is a named IPC socket\n";
    if (fs::is_symlink(s))
        std::cout << " is a symlink\n";
    if (!fs::exists(s))
        std::cout << " does not exist\n";
}

int main()
{
    // create files of different kinds
    fs::create_directory("sandbox");
    std::ofstream("sandbox/file"); // create regular file
    fs::create_directory("sandbox/dir");
    mkfifo("sandbox/pipe", 0644);
    struct sockaddr_un addr;
    addr.sun_family = AF_UNIX;
    std::strcpy(addr.sun_path, "sandbox/sock");
    int fd = socket(PF_UNIX, SOCK_STREAM, 0);
    bind(fd, (struct sockaddr*)&addr, sizeof addr);
    fs::create_symlink("file", "sandbox/symlink");

    // demo different status accessors
    for (auto it = fs::directory_iterator("sandbox"); it != fs::directory_iterator(); ++it)
        demo_status(*it, it->symlink_status()); // use cached status from directory entry
    demo_status("dev/null", fs::status("/dev/null")); // direct calls to status
    demo_status("dev/sda", fs::status("/dev/sda"));
    demo_status("sandbox/no", fs::status("/sandbox/no"));

    // cleanup
    close(fd);
    fs::remove_all("sandbox");
}

Possible output:

"sandbox/file" is a regular file
"sandbox/dir" is a directory
"sandbox/pipe" is a named IPC pipe
"sandbox/sock" is a named IPC socket
"sandbox/symlink" is a symlink
"dev/null" is a character device
"dev/sda" is a block device
"sandbox/no" does not exist

look at her go. creating every file type known to humanity and then labeling them all 😭 that's main character energy fr fr 🔥

---

✨ SEE ALSO ✨

• status — determines file attributes (function)
• symlink_status — determines file attributes, checking the symlink target (function)
• file_status — represents file type and permissions (class)
• status_known — checks whether file status is known (function)
• is_block_file — checks whether the given path refers to block device (function)
• is_character_file — checks whether the given path refers to a character device (function)
• is_directory — checks whether the given path refers to a directory (function)
• is_fifo — checks whether the given path refers to a named pipe (function)
• is_other — checks whether the argument refers to an other file (function)
• is_regular_file — checks whether the argument refers to a regular file (function)
• is_socket — checks whether the argument refers to a named IPC socket (function)
• exists — checks whether path refers to existing file system object (function)

and from std::experimental::filesystem::directory_entry (public member functions, both of 'em 🎀):

• status — cached status of the file designated by this directory entry
• symlink_status — cached symlink_status of the file designated by this directory entry

---

✨ CATEGORIES ✨

• Noindexed pages
• unconditionally noexcept

🌈 HIDDEN CATEGORIES 🌈

• Pages with unreviewed unconditional noexcept template
• Pages with unreviewed noexcept template

---

okay that's the whole page, no skipped parts, we ate and left no crumbs 🍓

so yeah — that's std::experi...::is_symlink(3) from cppreference.com, version 2024.06.10 💜 go check if something's a symlink. it's giving "one job, done well." bye bestie! ✨💅🦋