Filesystem library functions often provide two overloads, one that throws an exception to report file system errors, and another that sets an error_code. [ Note: This supports two common use cases:
Uses where file system errors are truly exceptional and indicate a serious failure. Throwing an exception is an appropriate response.
Uses where file system errors are routine and do not necessarily represent failure. Returning an error code is the most appropriate response. This allows application specific error handling, including simply ignoring the error.
— end note ]
Functions not having an argument of type error_code& handle errors as follows, unless otherwise specified:
When a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, an exception of type filesystem_error shall be thrown. For functions with a single path argument, that argument shall be passed to the filesystem_error constructor with a single path argument. For functions with two path arguments, the first of these arguments shall be passed to the filesystem_error constructor as the path1 argument, and the second shall be passed as the path2 argument. The filesystem_error constructor's error_code argument is set as appropriate for the specific operating system dependent error.
Failure to allocate storage is reported by throwing an exception as described in [res.on.exception.handling].
Destructors throw nothing.
Functions having an argument of type error_code& handle errors as follows, unless otherwise specified:
If a call by the implementation to an operating system or other underlying API results in an error that prevents the function from meeting its specifications, the error_code& argument is set as appropriate for the specific operating system dependent error. Otherwise, clear() is called on the error_code& argument.