httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Trawick <trawi...@bellsouth.net>
Subject [PATCH] update APRDesign to describe error reporting
Date Wed, 05 Apr 2000 03:04:40 GMT
comments, disagreements before I ship this change?

Index: APRDesign
===================================================================
RCS file: /cvs/apache/apache-2.0/src/lib/apr/APRDesign,v
                                                                                         
                Odiff -u -r1.7 APRDesign
--- APRDesign   2000/04/03 18:40:36     1.7
+++ APRDesign   2000/04/05 03:08:42
@@ -179,3 +179,41 @@
  */
 
 For an actual example, look at any function in the fileio/unix directory.
+
+Error Reporting in APR
+
+Most APR functions return an ap_status_t return code to the caller.  The
+value is APR_SUCCESS (zero) on success, or a specific error code otherwise.
+
+When an error occurs, one of the portable error codes from apr_errno.h will
+be returned whenever possible.  Some of these error codes, such as
+APR_ENOPOOL, have meanings which are unique to APR.  Others, such as
+APR_ENOENT, correspond to errno values which C and UNIX programmers have been
+using for years.  In fact, APR's errno-style error codes will have the value
+of the corresponding errno whenever that errno is defined on the system.
+When UNIX system calls are used by APR, simply returning errno for the
+ap_status_t return code is the proper implementation, but note that APR
+return codes should be defined for all possible errno values.
+
+When system or library calls which don't return or set errno-type error codes
+are used by APR, the error code from the system or library call should be
+mapped to an APR return code so that the application can react appropriately.
+This is similar to what happens in a C Standard Library implementation on
+platforms other than UNIX.  The native system calls are used, but error codes
+are mapped into errno values such as ENOENT, ENOMEM, ENOSPC, etc.  APR needs
+to do the same thing.  Otherwise, the application can't implement logic to
+recover from certain errors because it doesn't know what error code will be
+returned for certain conditions on different platforms.
+
+Occasionally, the operating system error code cannot be translated into an APR
+error code, either because a system-specific error occurred that doesn't have
+a portable representation or because no logic was implemented to perform the
+mapping.  In this case, the operating system error code will be returned to
+the application, but transformed via a macro in apr_errno.h so that the value
+is not confused with one of the other error codes.  It is not expected that
+the application will be able to handle it, but the application may choose to
+log the value for possible problem determination.
+
+                
-- 
Jeff Trawick | trawick@ibm.net | PGP public key at web site:
     http://www.geocities.com/SiliconValley/Park/9289/
          Born in Roswell... married an alien...

Mime
View raw message