peter
/
libraw1394
Archived
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Fix documentation of return values of raw1394_start_ family of functions 

If running on top of the raw1394 kernel driver (any kernel version) or
on top of firewire-core (kernel version <= 2.6.29), raw1394_start_*
functions will return a value > 0 on success, not == 0.  Only with
firewire-core of kernel 2.6.30 or later, == 0 is returned on success.

The exact value depends on which driver is used, on CPU architecture,
and on request payload size in case of some types of requests.  In any
case, only that the value is > or == 0 on success (but == -1 on
failure) is significant to libraw1394 client applications.

This mismatch between documentation and implementation was already
present in older libraw1394 versions, including v1.x.  For the time
being, do not change the implementation, only adjust the documentation.

Reported-by: Dr. David Alan Gilbert
Signed-off-by: Stefan Richter <stefanr@s5r6.in-berlin.de>
This commit is contained in:
Stefan Richter 2010-01-31 11:33:08 +01:00
parent cf7b3e4df0
commit f806f3d0de
1 changed files with 7 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
src/raw1394.h
View File

@ -849,7 +849,7 @@ int raw1394_phy_packet_write (raw1394handle_t handle, quadlet_t data);
*
* examples of physical requests are linkon, physicalconfigurationpacket, etc.
*
* Returns: 0 on success or -1 on failure (sets errno)
* Returns: >= 0 on success or -1 on failure (sets errno)
**/
int raw1394_start_phy_packet_write(raw1394handle_t handle,
quadlet_t data, unsigned long tag);
@ -873,7 +873,7 @@ int raw1394_start_phy_packet_write(raw1394handle_t handle,
* that uniquely identifies this transaction (e.g. a struct pointer casted to
* unsigned long).
*
* Returns: 0 on success or -1 on failure (sets errno)
* Returns: >= 0 on success or -1 on failure (sets errno)
**/
int raw1394_start_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
size_t length, quadlet_t *buffer, unsigned long tag);
@ -897,7 +897,7 @@ int raw1394_start_read(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
* that uniquely identifies this transaction (e.g. a struct pointer casted to
* unsigned long).
*
* Returns: 0 on success or -1 on failure (sets errno)
* Returns: >= 0 on success or -1 on failure (sets errno)
**/
int raw1394_start_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
size_t length, quadlet_t *data, unsigned long tag);
@ -921,7 +921,7 @@ int raw1394_start_write(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
* that uniquely identifies this transaction (e.g. a struct pointer casted to
* unsigned long).
*
* Returns: 0 on success or -1 on failure (sets errno)
* Returns: >= 0 on success or -1 on failure (sets errno)
**/
int raw1394_start_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
unsigned int extcode, quadlet_t data, quadlet_t arg,
@ -946,7 +946,7 @@ int raw1394_start_lock(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
* that uniquely identifies this transaction (e.g. a struct pointer casted to
* unsigned long).
*
* Returns: 0 on success or -1 on failure (sets errno)
* Returns: >= 0 on success or -1 on failure (sets errno)
**/
int raw1394_start_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
unsigned int extcode, octlet_t data, octlet_t arg,
@ -966,7 +966,7 @@ int raw1394_start_lock64(raw1394handle_t handle, nodeid_t node, nodeaddr_t addr,
* Passes custom tag. Use pointer to raw1394_reqhandle if you use the standard
* tag handler.
*
* Returns: 0 on success or -1 on failure (sets errno)
* Returns: >= 0 on success or -1 on failure (sets errno)
**/
int raw1394_start_async_stream(raw1394handle_t handle, unsigned int channel,
unsigned int tag, unsigned int sy,
@ -995,7 +995,7 @@ int raw1394_start_async_stream(raw1394handle_t handle, unsigned int channel,
* Do not use that function, unless you really know, what you do! Sending
* corrupt packet may lead to weird results.
*
* Returns: 0 on success or -1 on failure (sets errno)
* Returns: >= 0 on success or -1 on failure (sets errno)
**/
int raw1394_start_async_send(raw1394handle_t handle,
size_t length, size_t header_length,