From 02154eb2c252536c0d80bec7f48602e886e1b2de Mon Sep 17 00:00:00 2001 From: aeb Date: Sat, 25 Nov 2000 01:58:34 +0000 Subject: [PATCH] Add some information about return values. git-svn-id: svn://svn.linux1394.org/libraw1394/trunk@45 53a565d1-3bb7-0310-b661-cf11e63c67ab --- README | 32 +++++++++++++++++++++++++++++--- 1 file 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