25.2.3.1. mysql_affected_rows()my_ulonglong mysql_affected_rows(mysql *mysql)
描述
返回上次update更改的行数，上次delete删除的行数，或上次insert语句插入的行数。对于update、delete或insert语句，可在mysql_query()后立刻调用。对于select语句，mysql_affected_rows()的工作方式与mysql_num_rows()类似。
返回值
大于0的整数表明受影响或检索的行数。“0”表示update语句未更新记录，在查询中没有与where匹配的行，或未执行查询。“-1”表示查询返回错误，或者，对于select查询，在调用mysql_store_result()之前调用了mysql_affected_rows()。由于mysql_affected_rows()返回无符号值，通过比较返回值和“(my_ulonglong)-1”或等效的“(my_ulonglong)~0”，检查是否为“-1”。
错误
无。
示例：
mysql_query(&mysql,update products set cost=cost*1.25 where group=10);
printf(%ld products updated,(long) mysql_affected_rows(&mysql));
如果在连接至mysqld时指定了标志client_found_rows，对于update语句，mysql_affected_rows()将返回where语句匹配的行数。
注意，使用replace命令时，如果新行替代了旧行，mysql_affected_rows()返回2。这是因为，在该情况下，删除了重复行后插入了1行。
如果使用“insert ... on duplicate key update”来插入行，如果行是作为新行插入的，mysql_affected_rows()返回1，如果是更新了已有的行，返回2。
25.2.3.2. mysql_autocommit()my_bool mysql_autocommit(mysql *mysql, my_bool mode)
描述
如果模式为“1”，启用autocommit模式；如果模式为“0”，禁止autocommit模式。
返回值
如果成功，返回0，如果出现错误，返回非0值。
错误
无。
25.2.3.3. mysql_change_user()my_bool mysql_change_user(mysql *mysql, const char *user, const char *password, const char *db)
描述
更改用户，并使由db指定的数据库成为由mysql指定的连接上的默认数据库（当前数据库）。在后续查询中，对于不包含显式数据库区分符的表引用，该数据库是默认数据库。
如果不能确定已连接的用户或用户不具有使用数据库的权限，mysql_change_user()将失败。在这种情况下，不会改变用户和数据库。
如果不打算拥有默认数据库，可将db参数设置为null。
该命令总是会执行活动事务的rollback操作，关闭所有的临时表，解锁所有的锁定表，并复位状态，就像进行了新连接那样。即使未更改用户，也会出现该情况。
返回值
0表示成功，非0值表示出现错误。
错误
与从mysql_real_connect()获得的相同。
· cr_commands_out_of_sync
以不恰当的顺序执行了命令。
· cr_server_gone_error
mysql服务器不可用。
· cr_server_lost
在查询过程中丢失了与服务器的连接。
· cr_unknown_error
出现未知错误。
· er_unknown_com_error
mysql服务器未实施该命令（或许是较低版本的服务器）。
· er_access_denied_error
用户或密码错误。
· er_bad_db_error
数据库不存在。
· er_dbaccess_denied_error
用户没有访问数据库的权限。
· er_wrong_db_name
数据库名称过长。
示例：
if (mysql_change_user(&mysql, user, password, new_database))
{
fprintf(stderr, failed to change user. error: %s\n,
mysql_error(&mysql));
}
25.2.3.4. mysql_character_set_name()const char *mysql_character_set_name(mysql *mysql)
描述
为当前连接返回默认的字符集。
返回值
默认字符集。
错误
无。
25.2.3.5. mysql_close()void mysql_close(mysql *mysql)
描述
关闭前面打开的连接。如果句柄是由mysql_init()或mysql_connect()自动分配的，mysql_close()还将解除分配由mysql指向的连接句柄。
返回值
无。
错误
无。
25.2.3.6. mysql_commit()my_bool mysql_commit(mysql *mysql)
描述
提交当前事务。
该函数的动作受completion_type系统变量的值控制。尤其是，如果completion_type的值为2，终结事务并关闭客户端连接后，服务器将执行释放操作。客户端程序应调用mysql_close()，从客户端一侧关闭连接。
返回值
如果成功，返回0，如果出现错误，返回非0值。
错误
无。
25.2.3.7. mysql_connect()mysql *mysql_connect(mysql *mysql, const char *host, const char *user, const char *passwd)
描述
该函数已过时。最好使用mysql_real_connect()取而代之。
mysql_connect()试图建立与运行在主机上的mysql数据库引擎的连接。在能够执行任何其他api函数之前，mysql_connect()必须成功完成，但mysql_get_client_info()例外。
这些参数的意义与mysql_real_connect()的对应参数的意义相同，差别在于连接参数可以为null。在这种情况下，c api将自动为连接结构分配内存，并当调用mysql_close()时释放分配的内存。该方法的缺点是，如果连接失败，你无法检索错误消息。要想从mysql_errno()或mysql_error()获得错误消息，必须提供有效的mysql指针。
返回值
与mysql_real_connect()的相同。
错误
与mysql_real_connect()的相同。
25.2.3.8. mysql_create_db()int mysql_create_db(mysql *mysql, const char *db)
描述
创建由db参数命名的数据库。
该函数已过时。最好使用mysql_query()来发出sqlcreate database语句。
返回值
如果数据库已成功创建，返回0，如果出现错误，返回非0值。
错误
· cr_commands_out_of_sync
以不恰当的顺序执行了命令。
· cr_server_gone_error
mysql服务器不可用。
· cr_server_lost
在查询过程中，与服务器的连接丢失。
· cr_unknown_error
出现未知错误。
示例：
if(mysql_create_db(&mysql, my_database))
{
fprintf(stderr, failed to create new database. error: %s\n,
mysql_error(&mysql));
}
25.2.3.9. mysql_data_seek()void mysql_data_seek(mysql_res *result, my_ulonglong offset)
描述
在查询结果集中寻找任意行。偏移值为行号，范围从0到mysql_num_rows(result)-1。
该函数要求结果集结构包含查询的所有结果，因此，somysql_data_seek()仅应与mysql_store_result()联合使用，而不是与mysql_use_result()。
返回值
无。
错误
无。
25.2.3.10. mysql_debug()void mysql_debug(const char *debug)
描述
用给定的字符串执行dbug_push。mysql_debug()采用fred fish调试库。要想使用该函数，必须编译客户端库，使之支持调试功能。请参见e.1节，“调试mysql服务器”。请参见e.2节，“调试mysql客户端”。
返回值
无。
错误
无。
示例：
这里给出的调用将使客户端库在客户端机器的/tmp/client.trace中生成1个跟踪文件。
mysql_debug(d:t:o,/tmp/client.trace);
25.2.3.11. mysql_drop_db()int mysql_drop_db(mysql *mysql, const char *db)
描述
撤销由db参数命名数据库。
该函数已过时。最好使用mysql_query()来发出sqldrop database语句
返回值
如果成功撤销了数据库，返回0。如果出现错误，返回非0值。
错误
· cr_commands_out_of_sync
以不恰当的顺序执行了命令。
· cr_server_gone_error
mysql服务器不可用。
· cr_server_lost
在查询过程中，与服务器的连接丢失。
· cr_unknown_error
出现未知错误。
示例：
if(mysql_drop_db(&mysql, my_database))
fprintf(stderr, failed to drop the database: error: %s\n,
mysql_error(&mysql));
25.2.3.12. mysql_dump_debug_info()int mysql_dump_debug_info(mysql *mysql)
描述
指示服务器将一些调试信息写入日志。要想使之工作，已连接的用户必须具有super权限。
返回值
如果命令成功，返回0。如果出现错误，返回非0值。
错误
· cr_commands_out_of_sync
以不恰当的顺序执行了命令。
· cr_server_gone_error
mysql服务器不可用。
· cr_server_lost
在查询过程中，与服务器的连接丢失。
· cr_unknown_error
出现未知错误。
25.2.3.13. mysql_eof()my_bool mysql_eof(mysql_res *result)
描述
该函数已过时。应使用mysql_errno()或mysql_error()取而代之。
mysql_eof()确定是否已读取了结果集的最后1行。
如果通过成功调用mysql_store_result()获得了结果集，客户端将在1次操作中收到整个结果集。在该情况下，从mysql_fetch_row()返回的null总表示已到达结果集末尾，而且没必要调用mysql_eof()。与mysql_store_result()一起使用时，mysql_eof()总返回“真”。
另一方面，如果你使用mysql_use_result()来初始化结果集检索，当重复调用mysql_fetch_row()时，将逐个地从服务器获取结果集的行。由于在该过程中，可能出现连接上的错误，从mysql_fetch_row()返回的null值不一定表示已正常地抵达结果集末尾。在该情况下，可以使用mysql_eof()来判定出现了什么情况。如果抵达结果集末尾，mysql_eof()返回非0值，如果出现错误，返回0。
从历史的角度上看，mysql_eof()在日期上早于标准的mysql错误函数mysql_errno()和mysql_error()。由于这类错误函数提供了相同的信息，它们优先于已过时的mysql_eof()。事实上，它们提供了更多信息，这是因为，mysql_eof()仅返回布尔值，错误函数能够在出现错误时指明错误的原因。
返回值
如果未出现错误，返回0。如果抵达结果集的末尾，返回非0值。
错误
无。
示例：
在下面的示例中，介绍了使用mysql_eof()的方法：
mysql_query(&mysql,select * from some_table);
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
// do something with data
}
if(!mysql_eof(result)) // mysql_fetch_row() failed due to an error
{
fprintf(stderr, error: %s\n, mysql_error(&mysql));
}
但是，你也能使用标准的mysql错误函数实现相同的结果：
mysql_query(&mysql,select * from some_table);
result = mysql_use_result(&mysql);
while((row = mysql_fetch_row(result)))
{
// do something with data
}
if(mysql_errno(&mysql)) // mysql_fetch_row() failed due to an error
{
fprintf(stderr, error: %s\n, mysql_error(&mysql));
}
25.2.3.14. mysql_errno()unsigned int mysql_errno(mysql *mysql)
描述
对于由mysql指定的连接，mysql_errno()返回最近调用的api函数的错误代码，该函数调用可能成功也可能失败。“0”返回值表示未出现错误。在mysqlerrmsg.h头文件中，列出了客户端错误消息编号。在附录b：错误代码和消息中，也列出了这些错误。
注意，如果成功，某些函数，如mysql_fetch_row()等，不会设置mysql_errno()。
经验规则是，如果成功，所有向服务器请求信息的函数均会复位mysql_errno()。
返回值
如果失败，返回上次mysql_xxx()调用的错误代码。“0”表示未出现错误。
错误
无。
25.2.3.15. mysql_error()const char *mysql_error(mysql *mysql)
描述
对于由mysql指定的连接，对于失败的最近调用的api函数，mysql_error()返回包含错误消息的、由null终结的字符串。如果该函数未失败，mysql_error()的返回值可能是以前的错误，或指明无错误的空字符串。
经验规则是，如果成功，所有向服务器请求信息的函数均会复位mysql_error()。
对于复位mysql_errno()的函数，下述两个测试是等效的：
if(mysql_errno(&mysql))
{
// an error occurred
}
if(mysql_error(&mysql)[0] != '\0')
{
// an error occurred
}
通过重新编译mysql客户端库，可以更改客户端错误消息的语言。目前，能够选择数种语言显示错误消息，请参见5.10.2节，“设置错误消息语言”。
返回值
返回描述错误的、由null终结的字符串。如果未出现错误，返回空字符串。
错误
无。
25.2.3.16. mysql_escape_string()应使用mysql_real_escape_string()取而代之！
该函数与mysql_real_escape_string()等同，但mysql_real_escape_string()会将连接处理程序作为其第1个参量，并按照当前字符集对字符串进行转义处理。mysql_escape_string()不采用连接参量，而且不考虑当前字符集设置。
25.2.3.17. mysql_fetch_field()mysql_field *mysql_fetch_field(mysql_res *result)
描述
返回采用mysql_field结构的结果集的列。重复调用该函数，以检索关于结果集中所有列的信息。未剩余字段时，mysql_fetch_field()返回null。
每次执行新的select查询时，将复位mysql_fetch_field()，以返回关于第1个字段的信息。调用mysql_field_seek()也会影响mysql_fetch_field()返回的字段。
如果调用了mysql_query()以在表上执行select，但未调用mysql_store_result()，如果调用了mysql_fetch_field()以请求blob字段的长度，mysql将返回默认的blob长度（8kb）。之所以选择8kb是因为mysql不知道blob的最大长度。应在日后使其成为可配置的。一旦检索了结果集，field->max_length将包含特定查询中该列的最大值的长度。
返回值
当前列的mysql_field结构。如果未剩余任何列，返回null。
错误
无。
示例：
mysql_field *field;
while((field = mysql_fetch_field(result)))
{
printf(field name %s\n, field->name);
}
25.2.3.18. mysql_fetch_field_direct()mysql_field *mysql_fetch_field_direct(mysql_res *result, unsigned int fieldnr)
描述
给定结果集内某1列的字段编号fieldnr，以mysql_field结构形式返回列的字段定义。可以使用该函数检索任意列的定义。fieldnr的值应在从0到mysql_num_fields(result)-1的范围内。
返回值
对于指定列，返回mysql_field结构。
错误
无。
示例：
unsigned int num_fields;
unsigned int i;
mysql_field *field;
num_fields = mysql_num_fields(result);
for(i = 0; i name);
}
25.2.3.19. mysql_fetch_fields()mysql_field *mysql_fetch_fields(mysql_res *result)
描述
对于结果集，返回所有mysql_field结构的数组。每个结构提供了结果集中1列的字段定义。
返回值
关于结果集所有列的mysql_field结构的数组。
错误
无。
示例：
unsigned int num_fields;
unsigned int i;
mysql_field *fields;
num_fields = mysql_num_fields(result);
fields = mysql_fetch_fields(result);
for(i = 0; i < num_fields; i++)
{
printf(field %u is %s\n, i, fields[i].name);
}
25.2.3.20. mysql_fetch_lengths()unsigned long *mysql_fetch_lengths(mysql_res *result)
描述
返回结果集内当前行的列的长度。如果打算复制字段值，该长度信息有助于优化，这是因为，你能避免调用strlen()。此外，如果结果集包含二进制数据，必须使用该函数来确定数据的大小，原因在于，对于包含null字符的任何字段，strlen()将返回错误的结果。
对于空列以及包含null值的列，其长度为0。要想了解区分这两类情况的方法，请参见关于mysql_fetch_row()的介绍。
返回值
无符号长整数的数组表示各列的大小（不包括任何终结null字符）。如果出现错误，返回null。
错误
mysql_fetch_lengths()仅对结果集的当前行有效。如果在调用mysql_fetch_row()之前或检索了结果集中的所有行后调用了它，将返回null。
示例：
mysql_row row;
unsigned long *lengths;
unsigned int num_fields;
unsigned int i;
row = mysql_fetch_row(result);
if (row)
{
num_fields = mysql_num_fields(result);
lengths = mysql_fetch_lengths(result);
for(i = 0; i < num_fields; i++)
{
printf(column %u is %lu bytes in length.\n, i, lengths[i]);
}
}
25.2.3.21. mysql_fetch_row()mysql_row mysql_fetch_row(mysql_res *result)
描述
检索结果集的下一行。在mysql_store_result()之后使用时，如果没有要检索的行，mysql_fetch_row()返回null。在mysql_use_result()之后使用时，如果没有要检索的行或出现了错误，mysql_fetch_row()返回null。
行内值的数目由mysql_num_fields(result)给出。如果行中保存了调用mysql_fetch_row()返回的值，将按照row[0]到row[mysql_num_fields(result)-1]，访问这些值的指针。行中的null值由null指针指明。
可以通过调用mysql_fetch_lengths()来获得行中字段值的长度。对于空字段以及包含null的字段，长度为0。通过检查字段值的指针，能够区分它们。如果指针为null，字段为null，否则字段为空。
返回值
下一行的mysql_row结构。如果没有更多要检索的行或出现了错误，返回null。
错误
注意，在对mysql_fetch_row()的两次调用之间，不会复位错误。
· cr_server_lost
在查询过程中，与服务器的连接丢失。
· cr_unknown_error
出现未知错误。
示例：
mysql_row row;
unsigned int num_fields;
unsigned int i;
num_fields = mysql_num_fields(result);
while ((row = mysql_fetch_row(result)))
{
unsigned long *lengths;
lengths = mysql_fetch_lengths(result);
for(i = 0; i < num_fields; i++)
{
printf([%.*s] , (int) lengths[i], row[i] ? row[i] : null);
}
printf(\n);
}
25.2.3.22. mysql_field_count()unsigned int mysql_field_count(mysql *mysql)
描述
返回作用在连接上的最近查询的列数。
该函数的正常使用是在mysql_store_result()返回null（因而没有结果集指针）时。在这种情况下，可调用mysql_field_count()来判定mysql_store_result()是否应生成非空结果。这样，客户端就能采取恰当的动作，而无需知道查询是否是select（或类似select的）语句。在这里给出的示例中，演示了完成它的方法。
请参见25.2.13.1节，“为什么在mysql_query()返回成功后，mysql_store_result()有时会返回null”.
返回值
表示结果集中列数的无符号整数。
错误
无。
示例：
mysql_res *result;
unsigned int num_fields;
unsigned int num_rows;
if (mysql_query(&mysql,query_string))
{
// error
}
else // query succeeded, process any data returned by it
{
result = mysql_store_result(&mysql);
if (result) // there are rows
{
num_fields = mysql_num_fields(result);
// retrieve rows, then call mysql_free_result(result)
}
else // mysql_store_result() returned nothing; should it have?
{
if(mysql_field_count(&mysql) == 0)
{
// query does not return data
// (it was not a select)
num_rows = mysql_affected_rows(&mysql);
}
else // mysql_store_result() should have returned data
{
fprintf(stderr, error: %s\n, mysql_error(&mysql));
}
}
}
另一种可选的方法是，用mysql_errno(&mysql)替换mysql_field_count(&mysql)调用。在该情况下，无论语句是否是select，你将直接从mysql_store_result()查找错误，而不是从mysql_field_count()的值进行推断。
25.2.3.23. mysql_field_seek()mysql_field_offset mysql_field_seek(mysql_res *result, mysql_field_offset offset)
描述
将字段光标设置到给定的偏移处。对mysql_fetch_field()的下一次调用将检索与该偏移相关的列定义。
要想查找行的开始，请传递值为0的偏移量。
返回值
字段光标的前一个值。
错误
无。
25.2.3.24. mysql_field_tell()mysql_field_offset mysql_field_tell(mysql_res *result)
描述
返回上一个mysql_fetch_field()所使用的字段光标的定义。该值可用作mysql_field_seek()的参量。
返回值
字段光标的当前偏移量。
错误
无。
25.2.3.25. mysql_free_result()void mysql_free_result(mysql_res *result)
描述
释放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等为结果集分配的内存。完成对结果集的操作后，必须调用mysql_free_result()释放结果集使用的内存。
释放完成后，不要尝试访问结果集。
返回值
无。
错误
无。