27 Input/output library [input.output]

27.10 File systems [filesystems]

27.10.15 Filesystem operation functions [fs.op.funcs]

27.10.15.35 Status [fs.op.status]

file_status status(const path& p);

Effects: As if:

error_code ec;
file_status result = status(p, ec);
if (result.type() == file_type::none)
  throw filesystem_error(implementation-supplied-message, p, ec);
return result;

Returns: See above.

Throws: filesystem_error. [ Note: result values of file_status(file_type::not_found) and file_status(file_type::unknown) are not considered failures and do not cause an exception to be thrown. — end note ]

file_status status(const path& p, error_code& ec) noexcept;

Effects: If possible, determines the attributes of the file p resolves to, as if by using POSIX stat() to obtain a POSIX struct stat. If, during attribute determination, the underlying file system API reports an error, sets ec to indicate the specific error reported. Otherwise, ec.clear(). [ Note: This allows users to inspect the specifics of underlying API errors even when the value returned by status() is not file_status(file_type::none).  — end note ]

Let prms denote the result of (m & perms::mask), where m is determined as if by converting the st_mode member of the obtained struct stat to the type perms.

Returns:

  • If ec != error_code():

    • If the specific error indicates that p cannot be resolved because some element of the path does not exist, returns file_status(file_type::not_found).

    • Otherwise, if the specific error indicates that p can be resolved but the attributes cannot be determined, returns file_status(file_type::unknown).

    • Otherwise, returns file_status(file_type::none).

    Note: These semantics distinguish between p being known not to exist, p existing but not being able to determine its attributes, and there being an error that prevents even knowing if p exists. These distinctions are important to some use cases.  — end note ]

  • Otherwise,

    • If the attributes indicate a regular file, as if by POSIX S_ISREG, returns file_status(file_type::regular, prms). [ Note: file_type::regular implies appropriate <fstream> operations would succeed, assuming no hardware, permission, access, or file system race errors. Lack of file_type::regular does not necessarily imply <fstream> operations would fail on a directory.  — end note ]

    • Otherwise, if the attributes indicate a directory, as if by POSIX S_ISDIR, returns file_status(file_type::directory, prms). [ Note: file_type::directory implies directory_iterator(p) would succeed.  — end note ]

    • Otherwise, if the attributes indicate a block special file, as if by POSIX S_ISBLK, returns file_status(file_type::block, prms).

    • Otherwise, if the attributes indicate a character special file, as if by POSIX S_ISCHR, returns file_status(file_type::character, prms).

    • Otherwise, if the attributes indicate a fifo or pipe file, as if by POSIX S_ISFIFO, returns file_status(file_type::fifo, prms).

    • Otherwise, if the attributes indicate a socket, as if by POSIX S_ISSOCK, returns file_status(file_type::socket, prms).

    • Otherwise, returns file_status(file_type::unknown, prms).

Remarks: If a symbolic link is encountered during pathname resolution, pathname resolution continues using the contents of the symbolic link.