CAPI函数描述(G-N)
25.2.3.26. mysql_get_character_set_info() void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs) 描述 该函数提供了关于默认客户端字符集的信息。可以使用mysql_set_character_set()函数更改默认的字符集。 该函数是在MySQL 5.0.10中增
25.2.3.26. mysql_get_character_set_info()
void mysql_get_character_set_info(MYSQL *mysql, MY_CHARSET_INFO *cs)
描述
该函数提供了关于默认客户端字符集的信息。可以使用mysql_set_character_set()函数更改默认的字符集。
该函数是在MySQL 5.0.10中增加的。
示例：
if (!mysql_set_character_set(&mysql, "utf8"))
{
MY_CHARSET_INFO cs;
mysql_get_character_set_info(&mysql, &cs);
printf("character set information:\n");
printf("character set name: %s\n", cs.name);
printf("collation name: %s\n", cs.csname);
printf("comment: %s\n", cs.comment);
printf("directory: %s\n", cs.dir);
printf("multi byte character min. length: %d\n", cs.mbminlen);
printf("multi byte character max. length: %d\n", cs.mbmaxlen);
}
25.2.3.27. mysql_get_client_info()
char *mysql_get_client_info(void)
描述
返回表示客户端库版本的字符串。
返回值
表示MySQL客户端库版本的字符串。
错误
无。
25.2.3.28. mysql_get_client_version()
unsigned long mysql_get_client_version(void)
描述
返回表示客户端库版本的整数。该值的格式是XYYZZ，其中X是主版本号，YY是发布级别，ZZ是发布级别内的版本号。例如，值40102表示客户端库的版本是4.1.2。
返回值
表示MySQL客户端库版本的整数。
错误
无。
25.2.3.29. mysql_get_host_info()
char *mysql_get_host_info(MYSQL *mysql)
描述
返回描述了所使用连接类型的字符串，包括服务器主机名。
返回值
代表服务器主机名和连接类型的字符串。
错误
无。
25.2.3.30. mysql_get_proto_info()
unsigned int mysql_get_proto_info(MYSQL *mysql)
描述
返回当前连接所使用的协议版本。
返回值
代表当前连接所使用协议版本的无符号整数。
错误
无。
25.2.3.31. mysql_get_server_info()
char *mysql_get_server_info(MYSQL *mysql)
描述
返回代表服务器版本号的字符串。
返回值
代表服务器版本号的字符串。
错误
无。
25.2.3.32. mysql_get_server_version()
unsigned long mysql_get_server_version(MYSQL *mysql)
描述
以整数形式返回服务器的版本号。
返回值
表示MySQL服务器版本的数值，格式如下：
major_version*10000 + minor_version *100 + sub_version
例如，对于5.0.12，返回500012。
在客户端程序中，为了快速确定某些与版本相关的服务器功能是否存在，该函数很有用。
错误
无。
25.2.3.33. mysql_hex_string()
unsigned long mysql_hex_string(char *to, const char *from, unsigned long length)
描述
该函数用于创建可用在SQL语句中的合法SQL字符串。请参见9.1.1节，“字符串”。
该字符串从形式上编码为十六进制格式，每个字符编码为2个十六进制数。结果被置入其中，并添加1个终结Null字节。
“from”所指向的字符串必须是长度字节“long”。必须为“to”分配缓冲区，缓冲区至少为length*2+1字节长。当mysql_hex_string()返回时，“to”的内容为由Null终结的字符串。返回值是编码字符串的长度，不包括终结用Null字符。
可采用0xvalue或X'value'格式将返回值置于SQL语句中。但是，返回值不包括0x或X'...'。调用者必须提供所希望的格式是何种。
示例：
char query[1000],*end;
end = strmov(query,"INSERT INTO test_table values(");
end = strmov(end,"0x");
end += mysql_hex_string(end,"What's this",11);
end = strmov(end,",0x");
end += mysql_hex_string(end,"binary data: \0\r\n",16);
*end++ = ')';
if (mysql_real_query(&mysql,query,(unsigned int) (end - query)))
{
fprintf(stderr, "Failed to insert row, Error: %s\n",
mysql_error(&mysql));
}
示例中所使用的strmov()函数包含在mysqlclient库中，它的工作方式类似于strcpy()，但返回指向第1个参数终结Null的指针。
返回值
置于“to”中的值的长度，不包括终结用Null字符。
错误
无。
25.2.3.34. mysql_info()
char *mysql_info(MYSQL *mysql)
描述
检索字符串，该字符串提供了关于最近执行查询的信息，但仅对这里列出的语句有效。对于其他语句，mysql_info()返回NULL。字符串的格式取决于查询的类型，如本节所述。数值仅是说明性的，字符串包含与查询相适应的值。
· INSERT INTO ... SELECT ...
字符串格式：记录，100；副本，0；警告，0
· INSERT INTO ... VALUES (...),(...),(...)...
字符串格式：记录，3；副本，0；警告，0
· LOAD DATA INFILE ...
字符串格式：记录，1；删除，0；跳过，0；警告，0
· ALTER TABLE
字符串格式：记录，3；副本，0；警告，0
· UPDATE
字符串格式：匹配行，40；更改，40；警告，0
注意，mysql_info()为INSERT ... VALUES返回非NULL值，INSERT ... VALUES仅用于多行形式的语句（也就是说，仅当指定了多个值列表时）。
返回值
字符串，它表示最近所执行查询的额外信息。如果该查询无可用信息，返回NULL。
错误
无。
25.2.3.35. mysql_init()
MYSQL *mysql_init(MYSQL *mysql)
描述
分配或初始化与mysql_real_connect()相适应的MYSQL对象。如果mysql是NULL指针，该函数将分配、初始化、并返回新对象。否则，将初始化对象，并返回对象的地址。如果mysql_init()分配了新的对象，当调用mysql_close()来关闭连接时。将释放该对象。
返回值
初始化的MYSQL*句柄。如果无足够内存以分配新的对象，返回NULL。
错误
在内存不足的情况下，返回NULL。
25.2.3.36. mysql_insert_id()
my_ulonglong mysql_insert_id(MYSQL *mysql)
描述
返回由以前的INSERT或UPDATE语句为AUTO_INCREMENT列生成的值。在包含AUTO_INCREMENT字段的表中执行了INSERT语句后，应使用该函数。
更准确地讲，将在下述条件下更新mysql_insert_id()：
· 将值保存到AUTO_INCREMENT列中的INSERT语句。无论值是通过在列中存储特殊值NULL或0自动生成的，还是确切的非特殊值，都成立。
· 在有多行INSERT语句的情况下，mysql_insert_id()返回第1个自动生成的AUTO_INCREMENT值，如果未生成这类值，将返回插入在AUTO_INCREMENT列中的最后1个确切值。
· 通过将LAST_INSERT_ID(expr)插入到任意列中以生成AUTO_INCREMENT值的INSERT语句。
· 通过更新任意列至LAST_INSERT_ID(expr)以生成AUTO_INCREMENT值的INSERT语句。
· mysql_insert_id()的值不受诸如SELECT等返回结果集的语句的影响。
· 如果前面的语句返回了错误，mysql_insert_id()的值将是不确定的。
注意，如果前面的语句未使用AUTO_INCREMENT，mysql_insert_id()返回0。如果需要保存值，在生成值的语句后，务必立刻调用mysql_insert_id()。
mysql_insert_id()的值仅受在当前客户端连接内发出的语句的影响。不受由其他客户端发出的语句的影响。
请参见12.9.3节，“信息函数”。
此外还应注意，SQL LAST_INSERT_ID()函数的值总包含最近生成的AUTO_INCREMENT值，而且在语句之间不会被复位，原因在于该函数的值是在服务器中维护的。另一个区别是，如果设置了AUTO_INCREMENT列来指定非特殊值，不会更新LAST_INSERT_ID()。
LAST_INSERT_ID()不同于mysql_insert_id()的原因在于，LAST_INSERT_ID()在脚本中很容易使用，而mysql_insert_id()则试图提供关于在AUTO_INCREMENT列中出现情况的更准确信息。
返回值
在前面的讨论中予以了介绍。
错误
无。
25.2.3.37. mysql_kill()
int mysql_kill(MYSQL *mysql, unsigned long pid)
描述
请求服务器杀死由pid指定的线程。
返回值
0表示成功，非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
25.2.3.38. mysql_library_end()
void mysql_library_end(void)
描述
它是mysql_server_end()函数的同义词。
关于具体的用法，请参见25.2.2节，“C API函数概述”。
25.2.3.39. mysql_library_init()
int mysql_library_init(int argc, char **argv, char **groups)
描述
这是mysql_server_init()函数的同义词。
关于具体的用法，请参见25.2.2节，“C API函数概述”。
25.2.3.40. mysql_list_dbs()
MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)
描述
返回由服务器上的数据库名称组成的结果集，该服务器与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%”或“_”，也可以是NULL指针，以便与所有的数据库匹配。调用mysql_list_dbs()的方法类似于执行查询SHOW database [LIKE wild]。
必须用mysql_free_result()释放结果集。
返回值
成功后返回MYSQL_RES结果集。如果出现错误，返回NULL。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
25.2.3.41. mysql_list_fields()
MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)
描述
返回由给定表中的字段名称组成的结果集，给定表与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%”或“_”，也可以是NULL指针，以便与所有的字段匹配。调用mysql_list_fields()的方法类似于执行查询SHOW COLUMNS FROM tbl_name [LIKE wild]。
注意，建议使用SHOW COLUMNS FROM tbl_name，而不是mysql_list_fields()。
必须用mysql_free_result()释放结果集。
返回值
如果成功，返回MYSQL_RES结果集。如果出现错误，返回NULL。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
25.2.3.42. mysql_list_processes()
MYSQL_RES *mysql_list_processes(MYSQL *mysql)
描述
返回描述当前服务器线程的结果集。该类信息与mysqladmin processlist或SHOW PROCESSLIST查询给出的信息相同。
必须用mysql_free_result()释放结果集。
返回值
如果成功，返回MYSQL_RES结果集。如果出现错误，返回NULL。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
25.2.3.43. mysql_list_tables()
MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)
描述
返回由当前数据库内的表名组成的结果集，当前数据库与由通配符参数指定的简单正则表达式匹配。通配符参数可以包含通配符“%”或“_”，也可以是NULL指针，以便与所有的表匹配。调用mysql_list_tables()的方法类似于执行查询HOW tables [LIKE wild]。
必须用mysql_free_result()释放结果集。
返回值
如果成功，返回MYSQL_RES结果集。 如果出现错误，返回NULL。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
25.2.3.44. mysql_more_results()
my_bool mysql_more_results(MYSQL *mysql)
描述
如果当前执行的查询存在多个结果，返回“真”，而且应用程序必须调用mysql_next_result()来获取结果。
返回值
如果存在多个结果，返回“真”（1），如果不存在多个结果，返回“假”（0）。
在大多数情况下，可调用mysql_next_result()来测试是否存在多个结果，如果存在多个结果，对检索进行初始化操作。
请参见25.2.9节，“多查询执行的C API处理”。请参见25.2.3.45节，“mysql_next_result()”。
错误
无。
25.2.3.45. mysql_next_result()
int mysql_next_result(MYSQL *mysql)
描述
如果存在多个查询结果，mysql_next_result()将读取下一个查询结果，并将状态返回给应用程序。
如果前面的查询返回了结果集，必须为其调用mysql_free_result()。
调用了mysql_next_result()后，连接状态就像你已为下一查询调用了mysql_real_query()或mysql_query()时的一样。这意味着你能调用mysql_store_result()、mysql_warning_count()、mysql_affected_rows()等等。
如果mysql_next_result()返回错误，将不执行任何其他语句，也不会获取任何更多的结果，
请参见25.2.9节，“多查询执行的C API处理”。
返回值
|
返回值 |
描述 |
|
0 |
成功并有多个结果。 |
|
-1 |
成功但没有多个结果。 |
|
>0 |
出错 |
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。例如，没有为前面的结果集调用mysql_use_result()。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中，与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
25.2.3.46. mysql_num_fields()
unsigned int mysql_num_fields(MYSQL_RES *result)
要想传递MYSQL*参量取而代之，请使用无符号整数mysql_field_count(MYSQL *mysql)。
描述
返回结果集中的行数。
注意，你可以从指向结果集的指针或指向连接句柄的指针获得行数。如果mysql_store_result()或mysql_use_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_errno(&mysql))
{
fprintf(stderr, "Error: %s\n", mysql_error(&mysql));
}
else if (mysql_field_count(&mysql) == 0)
{
// query does not return data
// (it was not a SELECT)
num_rows = mysql_affected_rows(&mysql);
}
}
}
另一种可选方式是（如果你知道你的查询应返回结果集），使用检查“mysql_field_count(&mysql) is = 0”来替换mysql_errno(&mysql)调用。仅当出错时才应使用它。
25.2.3.47. mysql_num_rows()
my_ulonglong mysql_num_rows(MYSQL_RES *result)
描述
返回结果集中的行数。
mysql_num_rows()的使用取决于是否采用了mysql_store_result()或mysql_use_result()来返回结果集。如果使用了mysql_store_result()，可以立刻调用mysql_num_rows()。如果使用了mysql_use_result()，mysql_num_rows()不返回正确的值，直至检索了结果集中的所有行为止。
返回值
结果集中的行数。
错误
无。