1 files changed, 30 insertions, 0 deletions
diff --git a/Docs/04-errors b/Docs/04-errors
new file mode 100644
index 000000000..786c46374
--- /dev/null
+++ b/Docs/04-errors
@@ -0,0 +1,30 @@
+Error handling
+==============
+
+This section describes error handling in the code.
+
+The most common serious error is memory exhaustion. If malloc(), strdup(), etc.
+fails, clean up and free any partially complete structures leaving data in a
+consistent state, and return a value which indicates failure, eg. 0 for
+functions which return a pointer (document the value in the function
+documentation). The caller should then propagate the failure up in the same way.
+At some point, the error should stop being passed up and be reported to the user
+using
+
+  warn_user("NoMemory", 0);
+
+The other common error is one returned by a RISC OS SWI. Always use "X" SWIs,
+something like this:
+
+  os_error *error;
+  error = xwimp_get_pointer_info(&pointer);
+  if (error) {
+	LOG(("xwimp_get_pointer_info: 0x%x: %s\n",
+			error->errnum, error->errmess));
+	warn_user("WimpError", error->errmess);
+	return false;
+  }
+
+If an error occurs during initialisation, in most cases exit immediately using
+die(), since this indicates that there is already insufficient memory, or a
+resource file is corrupted, etc.