Init

cppdraft/fs/err/report.md

@@ -0,0 +1,77 @@
+[fs.err.report]
+
+# 31 Input/output library [[input.output]](./#input.output)
+
+## 31.12 File systems [[filesystems]](filesystems#fs.err.report)
+
+### 31.12.5 Error reporting [fs.err.report]
+
+[1](#1)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13501)
+
+Filesystem library functions often provide two overloads, one that
+throws an exception to report file system errors, and another that sets an error_code[.](#1.sentence-1)
+
+[*Note [1](#note-1)*:
+
+This supports two common use cases:
+
+- [(1.1)](#1.1)
+
+  Uses where file system errors are truly exceptional
+and indicate a serious failure[.](#1.1.sentence-1)
+  Throwing an exception is an appropriate response[.](#1.1.sentence-2)
+
+- [(1.2)](#1.2)
+
+  Uses where file system errors are routine
+and do not necessarily represent failure[.](#1.2.sentence-1)
+  Returning an error code is the most appropriate response[.](#1.2.sentence-2)
+  This allows application specific error handling, including simply ignoring the error[.](#1.2.sentence-3)
+
+— *end note*]
+
+[2](#2)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13519)
+
+Functions not having an argument of type error_code& handle errors as follows, unless otherwise specified:
+
+- [(2.1)](#2.1)
+
+  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 typefilesystem_error shall be thrown[.](#2.1.sentence-1)
+  For functions with a single path
+ argument, that argument shall be passed to thefilesystem_error constructor with a single path argument[.](#2.1.sentence-2)
+  For
+ functions with two path arguments, the first of these arguments shall be
+ passed to thefilesystem_error constructor as the path1 argument,
+ and the second shall be passed as the path2 argument[.](#2.1.sentence-3)
+  The filesystem_error constructor's error_code argument
+ is set as appropriate for the specific operating system dependent error[.](#2.1.sentence-4)
+
+- [(2.2)](#2.2)
+
+  Failure to allocate storage is reported by throwing an exception
+as described in [[res.on.exception.handling]](res.on.exception.handling "16.4.6.14 Restrictions on exception handling")[.](#2.2.sentence-1)
+
+- [(2.3)](#2.3)
+
+  Destructors throw nothing[.](#2.3.sentence-1)
+
+[3](#3)
+
+[#](http://github.com/Eelis/draft/tree/9adde4bc1c62ec234483e63ea3b70a59724c745a/source/iostreams.tex#L13541)
+
+Functions having an argument of type error_code& handle errors as follows, unless otherwise specified:
+
+- [(3.1)](#3.1)
+
+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[.](#3.sentence-1)
+  Otherwise, clear() is called on the error_code& argument[.](#3.1.sentence-2)