31 Input/output library [input.output]

31.12 File systems [filesystems]

31.12.13 Filesystem operation functions [fs.op.funcs] Status [fs.op.status]

file_status filesystem::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 1:
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 filesystem::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 2:
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).
    [Note 3:
    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 4:
      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 5:
      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.