Add some information about return values.

git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@45 53a565d1-3bb7-0310-b661-cf11e63c67ab

1 files changed, 29 insertions, 3 deletions

diff --git a/README b/README
index da26227..e25db84 100644
--- a/README
+++ b/README
@@ -28,8 +28,34 @@ files.
 
 3. API documentation
 
-	There is currently no external document describing the library functions,
-but you can find documentation for all functions in the header file raw1394.h.
+	There is currently no external document describing the library
+functions, but you can find documentation for all functions in the header file
+raw1394.h.  Some real documentation will come Real Soon Now.
+
+	To clear up some confusion (it wasn't documented before, what was I
+thinking), here is a description of the return values of the
+raw1394_(read|write|lock) functions and also the errcode parameter of
+tag_handler_t or reeqhandler_t:
+
+	If it is negative it signals an error in handling the request locally
+(1394 target node not reached) and errno contains a Unix error code just like
+with other library functions.  If it is positive it still does not signal
+success of the request itself, just that it was properly communicated to the
+1394 target node.  To know whether it succeeded the lower 32 bits have to be
+further decoded.
+
+	The upper 16 bits contain the acknowledge code from the other node, the
+lower 16 bits the response code.  Both of these codes are the standard codes
+from the 1394 standard with the exception of 0x10 for the ack which is set on an
+access to the local node (there is no 1394 bus involved and therefore no ack
+exists).  Most of the acks completely determine the success of the request
+(ack_complete or one of the error codes).  The response code has to be
+interpreted if the ack is ack_pending or the dummy ack 0x10.  Only in this case
+is the response code valid.
+
+	This way of reporting errors will be replaced by a more sensible
+approach with (one of the, but hopefully) the next version of libraw.
+Documented here only for those who can't wait.
 
 
 4. Multithreading
@@ -51,4 +77,4 @@ http://sourceforge.net/project/?group_id=2514 for more information.  You can
 also submit bugs through this page.
 
 
-2000-03-18  Andreas Bombe
+2000-11-25  Andreas Bombe