path: root/documentation/errors.mdwn
diff options
Diffstat (limited to 'documentation/errors.mdwn')
1 files changed, 36 insertions, 0 deletions
diff --git a/documentation/errors.mdwn b/documentation/errors.mdwn
new file mode 100644
index 0000000..2e818ab
--- /dev/null
+++ b/documentation/errors.mdwn
@@ -0,0 +1,36 @@
+[[!meta title="Documentation/Errors"]]
+[[!meta author="James Bursa"]]
+[[!meta date="2010-03-01T02:55:53Z"]]
+[[!toc]] 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.
+[[!inline raw=yes pages="Documentation"]]