std::experi...mlink_status(3)

🌸 NAME 🌸

okay so welcome to the C++ Standard Libary manual page (yes, the header says “Libary” and we are not fixing it, it’s iconic 💅). The main characters are std::experimental::filesystem::status and std::experimental::filesystem::symlink_status — the “what even is this filesystem object?” duo. 🫶

---

✨ Synopsis ✨

Defined in header <experimental/filesystem>:

Defined in header <experimental/filesystem>
file_status status( const path& p );                             (1)
(filesystem TS)
file_status status( const path& p, error_code& ec ) noexcept;
file_status symlink_status( const path& p );
file_status symlink_status( const path& p, error_code& ec )      (2)
(filesystem TS)
noexcept;

1. This one determines the type + attributes of the filesystem object identified by p, as if by POSIX stat — and yes, symlinks get followed to their targets. 🧚

• If p is a regular file, returns file_status(file_type::regular).
• If p is a directory, returns file_status(file_type::directory).
• If p is a block special file, returns file_status(file_type::block).
• If p is a character special file, returns file_status(file_type::character).
• If p is a fifo or pipe file, returns file_status(file_type::fifo).
• If p is a socket, returns file_status(file_type::socket).
• If p does not exist, returns file_status(file_type::not_found).
• If p exists but file attributes cannot be determined, e.g. due to lack of permissions, returns file_status(file_type::unknown).
• If errors prevent even knowing whether p exists, the non-throwing overload sets ec and returns file_status(file_type::none), and the throwing overload throws filesystem_error.
• Otherwise, returns file_status(file_type::unknown).

2. Same as (1), except the behavior is as if the POSIX lstat is used (symlinks are not followed):

• If p is a symlink, returns file_status(file_type::symlink).

---

🎀 Parameters 🎀

• p — path to examine
• ec — out-parameter for error reporting in the non-throwing overload

---

💖 Return value 💖

The file status (a file_status object). Slay.

---

🦋 Exceptions 🦋

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. std::bad_alloc may be thrown if memory allocation fails. 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.

---

⭐ Notes ⭐

The information provided by this function is usually also provided as a byproduct of directory iteration, and may be obtained by the member functions of directory_entry. During directory iteration, calling status again is unnecessary. fr fr, don’t do extra work bestie 💅

---

🌈 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

---

🌟 See also 🌟

• 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)
• is_symlink — checks whether the argument refers to a symbolic link (function)
• exists — checks whether path refers to existing file system object (function)
• status — cached status of the file designated by this directory entry
• symlink_status — cached symlink_status of the file designated by this directory entry (public member function of std::experimental::filesystem::directory_entry)

---

📚 Categories 📚

• Noindexed pages
• unconditionally noexcept

🙈 Hidden categories 🙈

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

---

source: http://cppreference.com · version/date: 2024.06.10 · page: std::experi...mlink_status(3) — ok bye bestie, go check those file types 💅✨