- 25.2.3.1. mysql_affected_rows()
- 25.2.3.2. mysql_autocommit()
- 25.2.3.3. mysql_change_user()
- 25.2.3.4. mysql_character_set_name()
- 25.2.3.5. mysql_close()
- 25.2.3.6. mysql_commit()
- 25.2.3.7. mysql_connect()
- 25.2.3.8. mysql_create_db()
- 25.2.3.9. mysql_data_seek()
- 25.2.3.10. mysql_debug()
- 25.2.3.11. mysql_drop_db()
- 25.2.3.12. mysql_dump_debug_info()
- 25.2.3.13. mysql_eof()
- 25.2.3.14. mysql_errno()
- 25.2.3.15. mysql_error()
- 25.2.3.16. mysql_escape_string()
- 25.2.3.17. mysql_fetch_field()
- 25.2.3.18. mysql_fetch_field_direct()
- 25.2.3.19. mysql_fetch_fields()
- 25.2.3.20. mysql_fetch_lengths()
- 25.2.3.21. mysql_fetch_row()
- 25.2.3.22. mysql_field_count()
- 25.2.3.23. mysql_field_seek()
- 25.2.3.24. mysql_field_tell()
- 25.2.3.25. mysql_free_result()
- 25.2.3.26. mysql_get_character_set_info()
- 25.2.3.27. mysql_get_client_info()
- 25.2.3.28. mysql_get_client_version()
- 25.2.3.29. mysql_get_host_info()
- 25.2.3.30. mysql_get_proto_info()
- 25.2.3.31. mysql_get_server_info()
- 25.2.3.32. mysql_get_server_version()
- 25.2.3.33. mysql_hex_string()
- 25.2.3.34. mysql_info()
- 25.2.3.35. mysql_init()
- 25.2.3.36. mysql_insert_id()
- 25.2.3.37. mysql_kill()
- 25.2.3.38. mysql_library_end()
- 25.2.3.39. mysql_library_init()
- 25.2.3.40. mysql_list_dbs()
- 25.2.3.41. mysql_list_fields()
- 25.2.3.42. mysql_list_processes()
- 25.2.3.43. mysql_list_tables()
- 25.2.3.44. mysql_more_results()
- 25.2.3.45. mysql_next_result()
- 25.2.3.46. mysql_num_fields()
- 25.2.3.47. mysql_num_rows()
- 25.2.3.48. mysql_options()
- 25.2.3.49. mysql_ping()
- 25.2.3.50. mysql_query()
- 25.2.3.51. mysql_real_connect()
- 25.2.3.52. mysql_real_escape_string()
- 25.2.3.53. mysql_real_query()
- 25.2.3.54. mysql_refresh()
- 25.2.3.55. mysql_reload()
- 25.2.3.56. mysql_rollback()
- 25.2.3.57. mysql_row_seek()
- 25.2.3.58. mysql_row_tell()
- 25.2.3.59. mysql_select_db()
- 25.2.3.60. mysql_set_character_set()
- 25.2.3.61. mysql_set_server_option()
- 25.2.3.62. mysql_shutdown()
- 25.2.3.63. mysql_sqlstate()
- 25.2.3.64. mysql_ssl_set()
- 25.2.3.65. mysql_stat()
- 25.2.3.66. mysql_store_result()
- 25.2.3.67. mysql_thread_id()
- 25.2.3.68. mysql_use_result()
- 25.2.3.69. mysql_warning_count()
在本节所作的介绍中,按照C编程语言,为NULL的参数或返回值表示NULL,而不是MySQL Null值。
返回值的函数通常会返回指针或整数。除非作了其他规定,返回指针的函数将返回非Null值,以指明成功,或返回NULL值以指明出错。返回整数的函数将返回0以指明成功,或返回非0值以指明出错。注意,非0值仅表明这点。除非在函数描述中作了其他说明,不要对非0值进行测试:
if (result) /* correct */
... error ...
if (result < 0) /* incorrect */
... error ...
if (result == -1) /* incorrect */
... error ...
当函数返回错误时,在函数描述的“错误”部分将列出可能的错误类型。通过调用mysql_errno()可发现出现的错误是什么。通过调用mysql_error(),可获得错误的字符串表示。
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。
my_bool mysql_autocommit(MYSQL *mysql, my_bool mode)
描述
如果模式为“1”,启用autocommit模式;如果模式为“0”,禁止autocommit模式。
返回值
如果成功,返回0,如果出现错误,返回非0值。
错误
无。
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));
}
void mysql_close(MYSQL *mysql)
描述
关闭前面打开的连接。如果句柄是由mysql_init()或mysql_connect()自动分配的,mysql_close()还将解除分配由mysql指向的连接句柄。
返回值
无。
错误
无。
my_bool mysql_commit(MYSQL *mysql)
描述
提交当前事务。
该函数的动作受completion_type系统变量的值控制。尤其是,如果completion_type的值为2,终结事务并关闭客户端连接后,服务器将执行释放操作。客户端程序应调用mysql_close(),从客户端一侧关闭连接。
返回值
如果成功,返回0,如果出现错误,返回非0值。
错误
无。
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()的相同。
int mysql_create_db(MYSQL *mysql, const char *db)
描述
创建由db参数命名的数据库。
该函数已过时。最好使用mysql_query()来发出SQL CREATE 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));
}
void mysql_data_seek(MYSQL_RES *result, my_ulonglong offset)
描述
在查询结果集中寻找任意行。偏移值为行号,范围从0到mysql_num_rows(result)-1。
该函数要求结果集结构包含查询的所有结果,因此,so mysql_data_seek()仅应与mysql_store_result()联合使用,而不是与mysql_use_result()。
返回值
无。
错误
无。
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");
int mysql_drop_db(MYSQL *mysql, const char *db)
描述
撤销由db参数命名数据库。
该函数已过时。最好使用mysql_query()来发出SQL DROP 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));
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
出现未知错误。
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));
}
unsigned int mysql_errno(MYSQL *mysql)
描述
对于由mysql指定的连接,mysql_errno()返回最近调用的API函数的错误代码,该函数调用可能成功也可能失败。“0”返回值表示未出现错误。在MySQL errmsg.h头文件中,列出了客户端错误消息编号。在附录B:错误代码和消息中,也列出了这些错误。
注意,如果成功,某些函数,如mysql_fetch_row()等,不会设置mysql_errno()。
经验规则是,如果成功,所有向服务器请求信息的函数均会复位mysql_errno()。
返回值
如果失败,返回上次mysql_xxx()调用的错误代码。“0”表示未出现错误。
错误
无。
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终结的字符串。如果未出现错误,返回空字符串。
错误
无。
应使用mysql_real_escape_string()取而代之!
该函数与mysql_real_escape_string()等同,但mysql_real_escape_string()会将连接处理程序作为其第1个参量,并按照当前字符集对字符串进行转义处理。mysql_escape_string()不采用连接参量,而且不考虑当前字符集设置。
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);
}
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 < num_fields; i++)
{
field = mysql_fetch_field_direct(result, i);
printf("Field %u is %s\n", i, field->name);
}
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);
}
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]);
}
}
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");
}
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()的值进行推断。
MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)
描述
将字段光标设置到给定的偏移处。对mysql_fetch_field()的下一次调用将检索与该偏移相关的列定义。
要想查找行的开始,请传递值为0的偏移量。
返回值
字段光标的前一个值。
错误
无。
MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)
描述
返回上一个mysql_fetch_field()所使用的字段光标的定义。该值可用作mysql_field_seek()的参量。
返回值
字段光标的当前偏移量。
错误
无。
void mysql_free_result(MYSQL_RES *result)
描述
释放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等为结果集分配的内存。完成对结果集的操作后,必须调用mysql_free_result()释放结果集使用的内存。
释放完成后,不要尝试访问结果集。
返回值
无。
错误
无。
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);
}
unsigned long mysql_get_client_version(void)
描述
返回表示客户端库版本的整数。该值的格式是XYYZZ,其中X是主版本号,YY是发布级别,ZZ是发布级别内的版本号。例如,值40102表示客户端库的版本是4.1.2。
返回值
表示MySQL客户端库版本的整数。
错误
无。
unsigned long mysql_get_server_version(MYSQL *mysql)
描述
以整数形式返回服务器的版本号。
返回值
表示MySQL服务器版本的数值,格式如下:
major_version*10000 + minor_version *100 + sub_version
例如,对于5.0.12,返回500012。
在客户端程序中,为了快速确定某些与版本相关的服务器功能是否存在,该函数很有用。
错误
无。
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字符。
错误
无。
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。
错误
无。
MYSQL *mysql_init(MYSQL *mysql)
描述
分配或初始化与mysql_real_connect()相适应的MYSQL对象。如果mysql是NULL指针,该函数将分配、初始化、并返回新对象。否则,将初始化对象,并返回对象的地址。如果mysql_init()分配了新的对象,当调用mysql_close()来关闭连接时。将释放该对象。
返回值
初始化的MYSQL*句柄。如果无足够内存以分配新的对象,返回NULL。
错误
在内存不足的情况下,返回NULL。
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列中出现情况的更准确信息。
返回值
在前面的讨论中予以了介绍。
错误
无。
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
出现未知错误。
int mysql_library_init(int argc, char **argv, char **groups)
描述
这是mysql_server_init()函数的同义词。
关于具体的用法,请参见25.2.2节,“C API函数概述”。
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
出现未知错误。
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
出现未知错误。
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
出现未知错误。
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
出现未知错误。
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()”。
错误
无。
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()返回错误,将不执行任何其他语句,也不会获取任何更多的结果,
返回值
返回值 |
描述 |
0 |
成功并有多个结果。 |
-1 |
成功但没有多个结果。 |
>0 |
出错 |
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。例如,没有为前面的结果集调用mysql_use_result()。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
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)调用。仅当出错时才应使用它。
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()不返回正确的值,直至检索了结果集中的所有行为止。
返回值
结果集中的行数。
错误
无。
int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)
描述
可用于设置额外的连接选项,并影响连接的行为。可多次调用该函数来设置数个选项。
应在mysql_init()之后、以及mysql_connect()或mysql_real_connect()之前调用mysql_options()。
选项参量指的是你打算设置的选项。Arg参量是选项的值。如果选项是整数,那么arg应指向整数的值。
可能的选项值:
选项 |
参量类型 |
功能 |
MYSQL_INIT_COMMAND |
char * |
连接到MySQL服务器时将执行的命令。再次连接时将自动地再次执行。 |
MYSQL_OPT_COMPRESS |
未使用 |
使用压缩客户端/服务器协议 |
MYSQL_OPT_CONNECT_TIMEOUT |
unsigned int * |
以秒为单位的连接超时。 |
MYSQL_OPT_GUESS_CONNECTION |
未使用 |
对于与libmysqld链接的应用程序,允许库“猜测”是否使用嵌入式服务器或远程服务器。“猜测”表示,如果设置了主机名但不是本地主机,将使用远程服务器。该行为是默认行为。 可使用MYSQL_OPT_USE_EMBEDDED_CONNECTION 和MYSQL_OPT_USE_REMOTE_CONNECTION覆盖它。对于与libmysqlclient链接的应用程序,该选项将被忽略。 |
MYSQL_OPT_LOCAL_INFILE |
指向单元的可选指针 |
如果未给定指针,或指针指向“unsigned int != 0”,将允许命令LOAD LOCAL INFILE。 |
MYSQL_OPT_NAMED_PIPE |
未使用 |
使用命名管道连接到NT平台上的MySQL服务器。 |
MYSQL_OPT_PROTOCOL |
unsigned int * |
要使用的协议类型。应是mysql.h中定义的mysql_protocol_type的枚举值之一。 |
MYSQL_OPT_READ_TIMEOUT |
unsigned int * |
从服务器读取信息的超时(目前仅在Windows平台的TCP/IP连接上有效)。 |
MYSQL_OPT_RECONNECT |
my_bool * |
如果发现连接丢失,启动或禁止与服务器的自动再连接。从MySQL 5.0.3开始,默认情况下禁止再连接,这是5.0.13中的新选项,提供了一种以显式方式设置再连接行为的方法。 |
MYSQL_OPT_SET_CLIENT_IP |
char * |
对于与libmysqld链接的应用程序(具备鉴定支持特性的已编译libmysqld),它意味着,出于鉴定目的,用户将被视为从指定的IP地址(指定为字符串)进行连接。对于与libmysqlclient链接的应用程序,,该选项将被忽略。 |
MYSQL_OPT_USE_EMBEDDED_CONNECTION |
未使用 |
对于与libmysqld链接的应用程序,对于连接来说,它将强制使用嵌入式服务器。对于与libmysqlclient链接的应用程序,,该选项将被忽略。 |
MYSQL_OPT_USE_REMOTE_CONNECTION |
未使用 |
对于与libmysqld链接的应用程序,对于连接来说,它将强制使用远程服务器。对于与libmysqlclient链接的应用程序,,该选项将被忽略。 |
MYSQL_OPT_USE_RESULT |
未使用 |
不使用该选项。 |
MYSQL_OPT_WRITE_TIMEOUT |
unsigned int * |
写入服务器的超时(目前仅在Windows平台的TCP/IP连接上有效)。 |
MYSQL_READ_DEFAULT_FILE |
char * |
从命名选项文件而不是从my.cnf读取选项。 |
MYSQL_READ_DEFAULT_GROUP |
char * |
从my.cnf或用MYSQL_READ_DEFAULT_FILE指定的文件中的命名组读取选项。 |
MYSQL_REPORT_DATA_TRUNCATION |
my_bool * |
通过MYSQL_BIND.error,对于预处理语句,允许或禁止通报数据截断错误(默认为禁止)。 |
MYSQL_SECURE_AUTH |
my_bool* |
是否连接到不支持密码混编功能的服务器,在MySQL 4.1.1和更高版本中,使用了密码混编功能。 |
MYSQL_SET_CHARSET_DIR |
char* |
指向包含字符集定义文件的目录的路径名。 |
MYSQL_SET_CHARSET_NAME |
char* |
用作默认字符集的字符集的名称。 |
MYSQL_SHARED_MEMORY_BASE_NAME |
char* |
命名为与服务器进行通信的共享内存对象。应与你打算连接的mysqld服务器使用的选项“-shared-memory-base-name”相同。 |
注意,如果使用了MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP,总会读取客户端组。
选项文件中指定的组可能包含下述选项:
选项 |
描述 |
connect-timeout |
以秒为单位的连接超时。在Linux平台上,该超时也用作等待服务器首次回应的时间。 |
compress |
使用压缩客户端/服务器协议。 |
database |
如果在连接命令中未指定数据库,连接到该数据库。 |
debug |
调试选项。 |
disable-local-infile |
禁止使用LOAD DATA LOCAL。 |
host |
默认主机名。 |
init-command |
连接到MySQL服务器时将执行的命令。再次连接时将自动地再次执行。 |
interactive-timeout |
等同于将CLIENT_INTERACTIVE指定为mysql_real_connect()。请参见25.2.3.51节,“mysql_real_connect()”。 |
local-infile[=(0|1)] |
如果无参量或参量!= 0,那么将允许使用LOAD DATA LOCAL。 |
max_allowed_packet |
客户端能够从服务器读取的最大信息包。 |
multi-results |
允许多语句执行或存储程序的多个结果集。 |
multi-statements |
允许客户端在1个字符串内发送多条语句。(由“;”隔开)。 |
password |
默认密码。 |
pipe |
使用命名管道连接到NT平台上的MySQL服务器。 |
protocol={TCP | SOCKET | PIPE | MEMORY} |
连接到服务器时将使用的协议。 |
port |
默认端口号。 |
return-found-rows |
通知mysql_info()返回发现的行,而不是使用UPDATE时更新的行。 |
shared-memory-base-name=name |
共享内存名称,用于连接到服务器(默认为"MYSQL")。 |
socket |
默认的套接字文件。 |
user |
默认用户。 |
注意,“timeout”(超时)已被“connect-timeout”(连接超时)取代,但为了保持向后兼容,在MySQL 5.1.2-alpha中仍支持“timeout”(超时)。
关于选项文件的更多信息,请参见4.3.2节,“使用选项文件”。
返回值
成功时返回0。如果使用了未知选项,返回非0值。
示例:
MYSQL mysql;
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database: Error: %s\n",
mysql_error(&mysql));
}
该代码请求客户端使用压缩客户端/服务器协议,并从my.cnf文件的obdc部分读取额外选项。
int mysql_ping(MYSQL *mysql)
描述
检查与服务器的连接是否工作。如果连接丢失,将自动尝试再连接。
该函数可被闲置了较长时间的客户端使用,用以检查服务器是否已关闭了连接,并在必要时再次连接。
返回值
如果与服务器的连接有效返回0。如果出现错误,返回非0值。返回的非0值不表示MySQL服务器本身是否已关闭,连接可能因其他原因终端,如网络问题等。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_UNKNOWN_ERROR
出现未知错误。
int mysql_query(MYSQL *mysql, const char *query)
描述
执行由“Null终结的字符串”查询指向的SQL查询。正常情况下,字符串必须包含1条SQL语句,而且不应为语句添加终结分号(‘;’)或“\g”。如果允许多语句执行,字符串可包含多条由分号隔开的语句。请参见25.2.9节,“多查询执行的C API处理”。
mysql_query()不能用于包含二进制数据的查询,应使用mysql_real_query()取而代之(二进制数据可能包含字符‘\0’,mysql_query()会将该字符解释为查询字符串结束)。
如果希望了解查询是否应返回结果集,可使用mysql_field_count()进行检查。请参见25.2.3.22节,“mysql_field_count()”。
返回值
如果查询成功,返回0。如果出现错误,返回非0值。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
MYSQL *mysql_real_connect(MYSQL *mysql, const char *host, const char *user, const char *passwd, const char *db, unsigned int port, const char *unix_socket, unsigned long client_flag)
描述
mysql_real_connect()尝试与运行在主机上的MySQL数据库引擎建立连接。在你能够执行需要有效MySQL连接句柄结构的任何其他API函数之前,mysql_real_connect()必须成功完成。
参数的指定方式如下:
· 第1个参数应是已有MYSQL结构的地址。调用mysql_real_connect()之前,必须调用mysql_init()来初始化MYSQL结构。通过mysql_options()调用,可更改多种连接选项。请参见25.2.3.48节,“mysql_options()”。
· “host”的值必须是主机名或IP地址。如果“host”是NULL或字符串"localhost",连接将被视为与本地主机的连接。如果操作系统支持套接字(Unix)或命名管道(Windows),将使用它们而不是TCP/IP连接到服务器。
· “user”参数包含用户的MySQL登录ID。如果“user”是NULL或空字符串"",用户将被视为当前用户。在UNIX环境下,它是当前的登录名。在Windows ODBC下,必须明确指定当前用户名。请参见26.1.9.2节,“在Windows上配置MyODBC DSN”。
· “passwd”参数包含用户的密码。如果“passwd”是NULL,仅会对该用户的(拥有1个空密码字段的)用户表中的条目进行匹配检查。这样,数据库管理员就能按特定的方式设置MySQL权限系统,根据用户是否拥有指定的密码,用户将获得不同的权限。
注释:调用mysql_real_connect()之前,不要尝试加密密码,密码加密将由客户端API自动处理。
· “db”是数据库名称。如果db为NULL,连接会将默认的数据库设为该值。
· 如果“port”不是0,其值将用作TCP/IP连接的端口号。注意,“host”参数决定了连接的类型。
· 如果unix_socket不是NULL,该字符串描述了应使用的套接字或命名管道。注意,“host”参数决定了连接的类型。
· client_flag的值通常为0,但是,也能将其设置为下述标志的组合,以允许特定功能:
标志名称 |
标志描述 |
CLIENT_COMPRESS |
使用压缩协议。 |
CLIENT_FOUND_ROWS |
返回发现的行数(匹配的),而不是受影响的行数。 |
CLIENT_IGNORE_SPACE |
允许在函数名后使用空格。使所有的函数名成为保留字。 |
CLIENT_INTERACTIVE |
关闭连接之前,允许interactive_timeout(取代了wait_timeout)秒的不活动时间。客户端的会话wait_timeout变量被设为会话interactive_timeout变量的值。 |
CLIENT_LOCAL_FILES |
允许LOAD DATA LOCAL处理功能。 |
CLIENT_MULTI_STATEMENTS |
通知服务器,客户端可能在单个字符串内发送多条语句(由‘;’隔开)。如果未设置该标志,将禁止多语句执行。 |
CLIENT_MULTI_RESULTS |
通知服务器,客户端能够处理来自多语句执行或存储程序的多个结果集。如果设置了CLIENT_MULTI_STATEMENTS,将自动设置它。 |
CLIENT_NO_SCHEMA |
禁止db_name.tbl_name.col_name语法。它用于ODBC。如果使用了该语法,它会使分析程序生成错误,在捕获某些ODBC程序中的缺陷时,它很有用。 |
CLIENT_ODBC |
客户端是ODBC客户端。它将mysqld变得更为ODBC友好。 |
CLIENT_SSL |
使用SSL(加密协议)。该选项不应由应用程序设置,它是在客户端库内部设置的。 |
对于某些参数,能够从选项文件获得取值,而不是取得mysql_real_connect()调用中的确切值。为此,在调用mysql_real_connect()之前,应与MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP选项一起调用mysql_options()。随后,在mysql_real_connect()调用中,为准备从选项文件读取值的每个参数指定“无值”值:
· 对于host,指定NULL值或空字符串("")。
· 对于user,指定NULL值或空字符串。
· 对于passwd,指定NULL值。(对于密码,mysql_real_connect()调用中的空字符串的值不能被选项文件中的字符串覆盖,这是因为,空字符串明确指明MySQL账户必须有空密码)。
· 对于db,指定NULL值或空字符串
· 对于port,指定“0”值。
· 对于unix_socket,指定NULL值。
对于某一参数,如果在选项文件中未发现值,将使用它的默认值,如本节前面介绍的那样。
返回值
如果连接成功,返回MYSQL*连接句柄。如果连接失败,返回NULL。对于成功的连接,返回值与第1个参数的值相同。
错误
· CR_CONN_HOST_ERROR
无法连接到MySQL服务器。
· CR_CONNECTION_ERROR
无法连接到本地MySQL服务器。
· CR_IPSOCK_ERROR
无法创建IP套接字。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_SOCKET_CREATE_ERROR
无法创建Unix套接字。
· CR_UNKNOWN_HOST
无法找到主机名的IP地址。
· CR_VERSION_ERROR
协议不匹配,起因于:试图连接到具有特定客户端库(该客户端库使用了不同的协议版本)的服务器。如果使用很早的客户端库来建立与较新的服务器(未使用“--old-protocol”选项开始的)的连接,就会出现该情况。
· CR_NAMEDPIPEOPEN_ERROR
无法在Windows平台下创建命名管道。
· CR_NAMEDPIPEWAIT_ERROR
在Windows平台下等待命名管道失败。
· CR_NAMEDPIPESETSTATE_ERROR
在Windows平台下获取管道处理程序失败。
· CR_SERVER_LOST
如果connect_timeout > 0,而且在连接服务器时所用时间长于connect_timeout秒,或在执行init-command时服务器消失。
示例:
MYSQL mysql;
mysql_init(&mysql);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name");
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database: Error: %s\n",
mysql_error(&mysql));
}
通过使用mysql_options(),MySQL库将读取my.cnf文件的[client]和[your_prog_name]部分,以确保程序工作,即使某人以某种非标准的方式设置MySQL也同样。
注意,一旦建立了连接,mysql_real_connect()将设置再连接标志(MYSQL结构的组成部份)的值,在低于5.0.3版的API中,将其设为“1”,在较新的版本中,将其设为“0”。对于该标志,值“1”表示,如果因连接丢失而无法执行语句,放弃前,将尝试再次连接到服务器。从MySQL 5.0.13开始,可以对mysql_options()使用MYSQL_OPT_RECONNECT选项,对再连接行为进行控制。
unsigned long mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned long length)
注意,mysql必须是有效的开放式连接。之所以需要它是因为,转义功能取决于服务器使用的字符集。
描述
该函数用于创建可在SQL语句中使用的合法SQL字符串。请参见9.1.1节,“字符串”。
按照连接的当前字符集,将“from”中的字符串编码为转义SQL字符串。将结果置于“to”中,并添加1个终结用NULL字节。编码的字符为NUL (ASCII 0)、‘\n’、‘\r’、‘\’、‘'’、‘"’、以及Control-Z(请参见9.1节,“文字值”)。(严格地讲,MySQL仅需要反斜杠和引号字符,用于引用转义查询中的字符串。该函数能引用其他字符,从而使得它们在日志文件中具有更好的可读性)。
“from”指向的字符串必须是长度字节“long”。必须为“to”缓冲区分配至少length*2+1字节。在最坏的情况下,每个字符或许需要使用2个字节进行编码,而且还需要终结Null字节。当mysql_real_escape_string()返回时,“to”的内容是由Null终结的字符串。返回值是编码字符串的长度,不包括终结用Null字符。
如果需要更改连接的字符集,应使用mysql_set_character_set()函数,而不是执行SET NAMES (或SET CHARACTER SET)语句。mysql_set_character_set()的工作方式类似于SET NAMES,但它还能影响mysql_real_escape_string()所使用的字符集,而SET NAMES则不能。
示例:
char query[1000],*end;
end = strmov(query,"INSERT INTO test_table values(");
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"What's this",11);
*end++ = '\'';
*end++ = ',';
*end++ = '\'';
end += mysql_real_escape_string(&mysql, end,"binary data: \0\r\n",16);
*end++ = '\'';
*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字符。
错误
无。
int mysql_real_query(MYSQL *mysql, const char *query, unsigned long length)
描述
执行由“query”指向的SQL查询,它应是字符串长度字节“long”。正常情况下,字符串必须包含1条SQL语句,而且不应为语句添加终结分号(‘;’)或“\g”。如果允许多语句执行,字符串可包含由分号隔开的多条语句。请参见25.2.9节,“多查询执行的C API处理”。
对于包含二进制数据的查询,必须使用mysql_real_query()而不是mysql_query(),这是因为,二进制数据可能会包含‘\0’字符。此外,mysql_real_query()比mysql_query()快,这是因为它不会在查询字符串上调用strlen()。
如果希望知道查询是否应返回结果集,可使用mysql_field_count()进行检查25.2.3.22节,“mysql_field_count()”。
返回值
如果查询成功,返回0。如果出现错误,返回非0值。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
int mysql_refresh(MYSQL *mysql, unsigned int options)
描述
该函数用于刷新表或高速缓冲,或复位复制服务器信息。连接的用户必须具有RELOAD权限。
“options”参量是一种位掩码,由下述值的任意组合构成。能够以“Or”(或)方式将多个值组合在一起,用一次调用执行多项操作。
· REFRESH_GRANT
刷新授权表,与FLUSH PRIVILEGES类似。
· REFRESH_LOG
刷新日志,与FLUSH LOGS类似。
· REFRESH_TABLES
刷新表高速缓冲,与FLUSH TABLES类似。
· REFRESH_HOSTS
刷新主机高速缓冲,与FLUSH HOSTS类似。
· REFRESH_STATUS
复位状态变量,与FLUSH STATUS类似。
· REFRESH_THREADS
刷新线程高速缓冲。
· REFRESH_SLAVE
在从复制服务器上,复位主服务器信息,并重新启动从服务器,与RESET SLAVE类似。
· REFRESH_MASTER
在主复制服务器上,删除二进制日志索引中列出的二进制日志文件,并截短索引文件,与RESET MASTER类似。
返回值
0表示成功,非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
int mysql_reload(MYSQL *mysql)
描述
请求MySQL服务器重新加载授权表。连接的用户必须具有RELOAD权限。
该函数已过时。最好使用mysql_query()来发出SQL FLUSH PRIVILEGES语句。
返回值
0表示成功,非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
my_bool mysql_rollback(MYSQL *mysql)
描述
回滚当前事务。
该函数的动作取决于completion_type系统变量的值。尤其是,如果completion_type的值为“2”,终结事务后,服务器将执行释放操作,并关闭客户端连接。客户端程序应调用mysql_close(),从客户端一侧关闭连接。
返回值
如果成功,返回0,如果出现错误,返回非0值。
错误
无。
MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)
描述
将行光标置于查询结果集中的任意行。“offset”值是行偏移量,它应是从mysql_row_tell()或mysql_row_seek()返回的值。该值不是行编号,如果你打算按编号查找结果集中的行,请使用mysql_data_seek()。
该函数要求在结果集的结构中包含查询的全部结果,因此,mysql_row_seek()仅应与mysql_store_result()一起使用,而不是与mysql_use_result()。
返回值
行光标的前一个值。该值可传递给对mysql_row_seek()的后续调用。
错误
无。
MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)
描述
对于上一个mysql_fetch_row(),返回行光标的当前位置。该值可用作mysql_row_seek()的参量。
仅应在mysql_store_result()之后,而不是mysql_use_result()之后使用mysql_row_tell()。
返回值
行光标的当前偏移量。
错误
无。
int mysql_select_db(MYSQL *mysql, const char *db)
描述
使由db指定的数据库成为由mysql指定的连接上的默认数据库(当前数据库)。在后续查询中,该数据库将是未包含明确数据库区分符的表引用的默认数据库。
除非已连接的用户具有使用数据库的权限,否则mysql_select_db()将失败。
返回值
0表示成功,非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
int mysql_set_character_set(MYSQL *mysql, char *csname)
描述
该函数用于为当前连接设置默认的字符集。字符串csname指定了1个有效的字符集名称。连接校对成为字符集的默认校对。该函数的工作方式与SET NAMES语句类似,但它还能设置mysql->charset的值,从而影响了由mysql_real_escape_string()设置的字符集。
该函数是在MySQL 5.0.7中增加的。
返回值
0表示成功,非0值表示出现错误。
示例:
MYSQL mysql;
mysql_init(&mysql);
if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0))
{
fprintf(stderr, "Failed to connect to database: Error: %s\n",
mysql_error(&mysql));
}
if (!mysql_set_charset_name(&mysql, "utf8"))
{
printf("New client character set: %s\n", mysql_character_set_name(&mysql));
}
int mysql_set_server_option(MYSQL *mysql, enum enum_mysql_set_option option)
描述
允许或禁止连接的选项。选项可以取下述值之一:
MYSQL_OPTION_MULTI_STATEMENTS_ON |
允许多语句支持。 |
MYSQL_OPTION_MULTI_STATEMENTS_OFF |
禁止多语句支持。 |
返回值
0表示成功,非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· ER_UNKNOWN_COM_ERROR
服务器不支持mysql_set_server_option()(当服务器版本低于4.1.1时),或服务器不支持试图设置的选项。
int mysql_shutdown(MYSQL *mysql, enum enum_shutdown_level shutdown_level)
描述
请求数据库服务器关闭。已连接的用户必须具有SHUTDOWN权限。MySQL 5.1服务器仅支持1种关闭类型,shutdown_level必须等效于SHUTDOWN_DEFAULT。设计规划了额外的关闭级别,以便能够选择所需的级别。对于用旧版本libmysqlclient头文件编译并调用mysql_shutdown()的动态链接可执行程序,需要与旧版的libmysqlclient动态库一起使用。
在5.5节,“MySQL服务器关机进程”中,介绍了关机进程。
返回值
0表示成功,非0值表示出现错误。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
const char *mysql_sqlstate(MYSQL *mysql)
描述
返回由Null终结的字符串,该字符串包含关于上次错误的SQLSTATE错误代码。错误代码包含5个字符。'00000'表示无错误。其值由ANSI SQL和ODBC指定。关于可能取值的列表,请参见附录B:错误代码和消息。
注意,并非所有的MySQL错误均会被映射到SQLSTATE错误代码。值'HY000'(一般错误)用于未映射的错误。
返回值
包含SQLSTATE错误码的、由Null终结的字符串。
另请参见:
请参见25.2.3.14节,“mysql_errno()”。请参见25.2.3.15节,“mysql_error()”。请参见25.2.7.26节,“mysql_stmt_sqlstate()”。
int mysql_ssl_set(MYSQL *mysql, const char *key, const char *cert, const char *ca, const char *capath, const char *cipher)
描述
使用mysql_ssl_set(),可采用SSL建立安全连接。必须在mysql_real_connect()之前调用它。
除非在客户端库中允许了OpenSSL支持,否则mysql_ssl_set()不作任何事。
Mysql是从mysql_init()返回的连接处理程序。其他参数的指定如下:
· key是key文件的路径名。
· cert是证书文件的路径名。
· ca是证书授权文件的路径名。
· capath是指向目录的路径名,该目录中包含以pem格式给出的受信任SSL CA证书。
· cipher是允许密码的列表,用于SSL加密。
对于任何未使用的SSL参数,可为其给定NULL。
返回值
该函数总返回0。如果SSL设置不正确,当你尝试连接时,mysql_real_connect()将返回错误。
char *mysql_stat(MYSQL *mysql)
描述
返回包含特定信息的字符串,该信息与mysqladmin status命令提供的信息类似。包括以秒为单位的正常运行时间,以及运行线程的数目,问题数,再加载次数,以及打开的表数目。
返回值
描述服务器状态的字符集。如果出现错误,返回NULL。
错误
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
MYSQL_RES *mysql_store_result(MYSQL *mysql)
描述
对于成功检索了数据的每个查询(SELECT、SHOW、DESCRIBE、EXPLAIN、CHECK TABLE等),必须调用mysql_store_result()或mysql_use_result() 。
对于其他查询,不需要调用mysql_store_result()或mysql_use_result(),但是如果在任何情况下均调用了mysql_store_result(),它也不会导致任何伤害或性能降低。通过检查mysql_store_result()是否返回0,可检测查询是否没有结果集(以后会更多)。
如果希望了解查询是否应返回结果集,可使用mysql_field_count()进行检查。请参见25.2.3.22节,“mysql_field_count()”。
mysql_store_result()将查询的全部结果读取到客户端,分配1个MYSQL_RES结构,并将结果置于该结构中。
如果查询未返回结果集,mysql_store_result()将返回Null指针(例如,如果查询是INSERT语句)。
如果读取结果集失败,mysql_store_result()还会返回Null指针。通过检查mysql_error()是否返回非空字符串,mysql_errno()是否返回非0值,或mysql_field_count()是否返回0,可以检查是否出现了错误。
如果未返回行,将返回空的结果集。(空结果集设置不同于作为返回值的空指针)。
一旦调用了mysql_store_result()并获得了不是Null指针的结果,可调用mysql_num_rows()来找出结果集中的行数。
可以调用mysql_fetch_row()来获取结果集中的行,或调用mysql_row_seek()和mysql_row_tell()来获取或设置结果集中的当前行位置。
一旦完成了对结果集的操作,必须调用mysql_free_result()。
请参见25.2.13.1节,“为什么在mysql_query()返回成功后,mysql_store_result()有时会返回NULL”.
返回值
具有多个结果的MYSQL_RES结果集合。如果出现错误,返回NULL。
错误
如果成功,mysql_store_result()将复位mysql_error()和mysql_errno()。
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
unsigned long mysql_thread_id(MYSQL *mysql)
描述
返回当前连接的线程ID。该值可用作mysql_kill()的参量以杀死线程。
如果连接丢失,并使用mysql_ping()进行了再连接,线程ID将改变。这意味着你不应获取线程ID并保存它供以后使用。应在需要时获取它。
返回值
当前连接的线程ID。
错误
无。
MYSQL_RES *mysql_use_result(MYSQL *mysql)
描述
对于成功检索数据的每个查询(SELECT、SHOW、DESCRIBE、EXPLAIN),必须调用mysql_store_result()或mysql_use_result()。
mysql_use_result()将初始化结果集检索,但并不像mysql_store_result()那样将结果集实际读取到客户端。它必须通过对mysql_fetch_row()的调用,对每一行分别进行检索。这将直接从服务器读取结果,而不会将其保存在临时表或本地缓冲区内,与mysql_store_result()相比,速度更快而且使用的内存也更少。客户端仅为当前行和通信缓冲区分配内存,分配的内存可增加到max_allowed_packet字节。
另一方面,如果你正在客户端一侧为各行进行大量的处理操作,或者将输出发送到了用户可能会键入“^S”(停止滚动)的屏幕,就不应使用mysql_use_result()。这会绑定服务器,并阻止其他线程更新任何表(数据从这类表获得)。
使用mysql_use_result()时,必须执行mysql_fetch_row(),直至返回NULL值,否则,未获取的行将作为下一个检索的一部分返回。C API给出命令不同步错误,如果忘记了执行该操作,将不能运行该命令。
不应与从mysql_use_result()返回的结果一起使用mysql_data_seek()、mysql_row_seek()、mysql_row_tell()、mysql_num_rows()或mysql_affected_rows(),也不应发出其他查询,直至mysql_use_result()完成为止。(但是,提取了所有行后,mysql_num_rows()将准确返回提取的行数)。
一旦完成了对结果集的操作,必须调用mysql_free_result()。
使用libmysqld嵌入式服务器时,由于在调用mysql_free_result()之前,内存使用将随着每个检索的行增加,内存效益将基本丧失。
返回值
MYSQL_RES结果结构。如果出现错误,返回NULL。
错误
如果成功,mysql_use_result()将复位mysql_error()和mysql_errno()。
· CR_COMMANDS_OUT_OF_SYNC
以不恰当的顺序执行了命令。
· CR_OUT_OF_MEMORY
内存溢出。
· CR_SERVER_GONE_ERROR
MySQL服务器不可用。
· CR_SERVER_LOST
在查询过程中,与服务器的连接丢失。
· CR_UNKNOWN_ERROR
出现未知错误。
错误
返回执行前一个SQL语句期间生成的告警数目。
返回值
告警计数。
错误
无。