std::filesy...read_symlink(3)

Hey bestie!! 💖 Welcome to std::filesy...read_symlink(3) — the C++ Standard Library manual page for std::filesystem::read_symlink. Lowkey one of those pages that's like “follow the link, but make it filesystem,” and we’re gonna get through it together, fr fr. 🦋

💖 NAME 💖

std::filesystem::read_symlink — std::filesystem::read_symlink (yes, it’s the same name twice, it’s giving “I contain multitudes” 💅).

✨ Synopsis ✨

Okay so, first things first: it’s defined in the header <filesystem>. Here’s the synopsis exactly as the page serves it, bestie:

          Defined in header <filesystem>
          std::filesystem::path read_symlink( const std::filesystem::path& p
       (1) (since C++17)
          );
          std::filesystem::path read_symlink( const std::filesystem::path&
          p,
       (2) (since C++17)
                                              std::error_code& ec );

So the vibe is: if the path p refers to a symbolic link, returns a new path object which refers to the target of that symbolic link. ✨

🚨 It is an error if p does not refer to a symbolic link. The non-throwing overload returns an empty path on errors.

🎀 Parameters 🎀

• p — path to a symlink. That’s the linky-link you’re asking about. 🔗
• ec — out-parameter for error reporting in the non-throwing overload. It’s where the error code goes to spill the tea. ☕

🌸 Return value 🌸

The target of the symlink (which may not necessarily exist). So like, don’t assume the target is actually there, bestie — it might be giving ghost town. 👻

💀 Exceptions 💀

Any overload not marked noexcept may throw std::bad_alloc if memory allocation fails. 😭

1. Throws std::filesystem::filesystem_error on underlying OS API errors, constructed with p as the first path argument and the OS error code as the error code argument.
2. Sets a std::error_code& parameter to the OS API error code if an OS API call fails, and executes ec.clear() if no errors occur.

🧪 Example 🧪

// Run this code

        #include <filesystem>
        #include <iostream>

        namespace fs = std::filesystem;

        int main()
        {
            for (fs::path p : {"/usr/bin/gcc", "/bin/cat", "/bin/mouse"})
            {
                std::cout << p;
                fs::exists(p) ?
                    fs::is_symlink(p) ?
                        std::cout << " -> " << fs::read_symlink(p) << '\n' :
                        std::cout << " exists but it is not a symlink\n" :
                    std::cout << " does not exist\n";
            }
        }

🌟 Possible output 🌟

        "/usr/bin/gcc" -> "gcc-5"
        "/bin/cat" exists but it is not a symlink
        "/bin/mouse" does not exist

🌈 See also 🌈

• is_symlink (C++17) — checks whether the argument refers to a symbolic link (function).
• create_symlink (C++17), create_directory_symlink (C++17) — creates a symbolic link (function).
• copy_symlink (C++17) — copies a symbolic link (function).
• status (C++17) — determines file attributes (function).
• symlink_status (C++17) — determines file attributes, checking the symlink target (function).

Source/version: http://cppreference.com · date: 2024.06.10 — bye bestie, go read those symlinks and stay iconic 💅🦋✨