add section about not using hardcoded errno values

1 files changed, 37 insertions, 0 deletions

diff --git a/hurd/porting/guidelines.mdwn b/hurd/porting/guidelines.mdwn
index bcfc8dd5..8dd27a52 100644
--- a/hurd/porting/guidelines.mdwn
+++ b/hurd/porting/guidelines.mdwn
@@ -232,3 +232,40 @@ Not implemented, not POSIX.  Try to disable the feature in the package.
 ## <a name="parport"> <linux/parport.h> <linux/ppdev.h> </a>
 
 There is no programming interface for the parallel port on GNU/Hurd yet.
+
+## <a name="errno"> `errno` values </a>
+
+When dealing with `errno`, you should always use the predefined error codes defined with the `E*` constants, instead of manually comparing/assigning/etc with their values.
+
+For example (C/C++):
+
+    /* check whether it does not exist */
+    if (errno == 2)
+      ...
+
+or Python:
+
+    # check whether it does not exist
+    try:
+      ...
+    except OSError, err:
+      err.errno == 2:
+        ...
+
+This is wrong, as [the actual values of the `E*` are unspecified (per POSIX)](http://www.opengroup.org/onlinepubs/009695399/functions/xsh_chap02_03.html#tag_02_03). You must always use the predefined constants for the possible errors.
+
+For example (C/C++):
+
+    /* check whether it does not exist */
+    if (errno == ENOENT)
+      ...
+
+With Python, you can use the [`errno` module](http://docs.python.org/library/errno.html) for the various constants:
+
+    # check whether it does not exist
+    try:
+      ...
+    except OSError, err:
+      import errno
+      err.errno == errno.ENOENT:
+        ...