29 Input/output library [input.output]

29.11 File systems [filesystems]

29.11.14 Filesystem operation functions [fs.op.funcs] 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.
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().
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.
  • 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).
    : 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).
      : 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).
      : file_­type​::​directory implies that calling 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, if the attributes indicate an implementation-defined file type ([fs.enum.file.type]), returns file_­status(file_­type​::​A, prms), where A is the constant for the implementation-defined file type.
    • 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.