Bug #76409 Documentation state that my_ulonglong mysql_affected_rows() returns -1
Submitted: 20 Mar 2015 15:16 Modified: 31 Mar 2015 15:37
Reporter: Richard Haven Email Updates:
Status: Closed Impact on me:
None 
Category:Connector / C Documentation Severity:S3 (Non-critical)
Version: OS:Any
Assigned to: Paul DuBois CPU Architecture:Any
Tags: documentation, my_ulonglong, mysql_affected_rows

[20 Mar 2015 15:16] Richard Haven 
Description:
my_ulonglong mysql_affected_rows(MYSQL *mysql)

"Return Values

An integer greater than zero indicates the number of rows affected or retrieved. Zero indicates that no records were updated ... -1 indicates that the query returned an error or that, ..."

"my_ulonglong

The type used for the number of rows and for mysql_affected_rows(), mysql_num_rows(), and mysql_insert_id(). This type provides a range of 0 to 1.84e19."

Exactly how does something return -1 if it cannot have the value -1?

How to repeat:
Read the documentation at

http://dev.mysql.com/doc/refman/5.0/en/c-api-data-structures.html

and 

http://dev.mysql.com/doc/refman/5.6/en/mysql-affected-rows.html

Suggested fix:
Make up your mind
[31 Mar 2015 15:22] Paul DuBois 
I will add this to the discussion at
http://dev.mysql.com/doc/refman/5.0/en/c-api-data-structures.html:

Some functions that return a row count using this type return -1 as
an unsigned value to indicate an error or exceptional condition. You
can check for -1 by comparing the return value to (my_ulonglong)-1
(or to (my_ulonglong)~0, which is equivalent).
[31 Mar 2015 15:28] Paul DuBois 
That's basically the same language as is found in the mysql_affected_rows() page, which also indicated how that function can return -1 even though the return type is unsigned. It returns -1 as an unsigned number.
[31 Mar 2015 15:31] Richard Haven 
With all due respect, an "unsigned" -1 is sloppy. 

Give the actual value rather than depending on an unintuitive side-effect of how compilers evaluate bits.
[31 Mar 2015 15:37] Paul DuBois 
From mysql.cc:

    else if (mysql_affected_rows(&mysql) == ~(ulonglong) 0)

which is equivalent to (my_ulonglong)-1. The expressions as stated in the docs are what is intended for use.