mysql c api详解(三)...
时间：2010-08-18 来源：jsufcz
转自 http://hi.baidu.com/lovevc2008/blog/item/bdf8f73c9dbfffcd9e3d620a.html
int mysql_kill(MYSQL *mysql, unsigned long pid)
20.4.30.1 说明
要求服务器杀死由pid指定的线程。
20.4.30.2 返回值
成功，零。如果出现一个错误，非零。
20.4.30.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。20.4.31 mysql_list_dbs()
MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)
20.4.31.1 说明
返回一个结果集合，它用在服务器上的匹配wild参数指定的简单正则表达式的数据库名组成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有的数据库的一个NULL指针。调用mysql_list_dbs()类似于执行查询SHOW databases [LIKE wild]。
你必须用mysql_free_result()释放结果集合。
20.4.31.2 返回值
成功，一个MYSQL_RES结果集合。如果出现一个错误，NULL。
20.4.31.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_OUT_OF_MEMORY 内存溢出。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。20.4.32 mysql_list_fields()
MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table, const char *wild)
20.4.32.1 说明
返回一个结果集合，它用在给定表中的匹配wild参数指定的简单正则表达式的列名组成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有列的一个NULL指针。调用mysql_list_fields()类似于执行查询SHOW COLUMNS FROM tbl_name [LIKE wild]。
注意，建议你使用SHOW COLUMNS FROM tbl_name而不是mysql_list_fields()。
你必须用mysql_free_result()释放结果集合。
20.4.32.2 返回值
成功，一个MYSQL_RES的结果集合。如果出线一个错误，NULL。
20.4.32.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务者关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。20.4.33 mysql_list_processes()
MYSQL_RES *mysql_list_processes(MYSQL *mysql)
20.4.33.1 说明
返回一个描述当前服务器线程的结果集合。这是与mysqladmin processlist或SHOW PROCESSLIST查询报告的相同信息。
你必须用mysql_free_result()释放结果集合。
20.4.33.2 返回值
成功，一个MYSQL_RES结果集合。如果发生一个错误，NULL。
20.4.33.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务者关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。20.4.34 mysql_list_tables()
MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)
20.4.34.1 说明
返回一个结果集合，它用在当前数据库中的匹配wild参数指定的简单正则表达式的表名组成。wild可以包含通配符字符“%”或“_”，或可以是匹配所有表的一个NULL指针。调用mysql_list_tables()类似于执行询问SHOW tables [LIKE wild]。
你必须用mysql_free_result()释放结果集合。
20.4.34.2 返回值
成功，一个MYSQL_RES结果集合。如果出现一个错误，NULL。
20.4.34.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不正确的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。20.4.35 mysql_num_fields()
unsigned int mysql_num_fields(MYSQL_RES *result)
或
unsigned int mysql_num_fields(MYSQL *mysql)
第二中形式在MySQL 3.22.24或更新版本上不能工作。为了传递一个MYSQL* 参数，你必须使用unsigned int mysql_field_count(MYSQL *mysql)。
20.4.35.1 说明
在结果集合中返回列的数量。
注意，你也可以通过一个指向一个结果集合或一个连接句柄的指针获得列的数量。如果mysql_store_result()或mysql_user_result()返回NULL，你将使用连接句柄（而这样你没有结果集合指针)。在这种情况下，你可以调用mysql_field_count()确定mysql_store_result()是否应该产生非空的结果。这允许客户程序采取成正确的行动，不必知道查询是否是一个SELECT（或类SELECT)语句。下面被显示出的例子说明这怎么可以被做。
见20.4.51 为什么在mysql_query()返回成功后，mysql_store_result()有时返回NULL?。
20.4.35.2 返回值
表示一个结果集合中字段数量的一个无符号整数。
20.4.35.3 错误
无。
20.4.35.4 范例
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) = 0的一个检查来代替mysql_errno(&mysql)。这只会发生在出错了的情形。
20.4.36 mysql_num_rows()
my_ulonglong mysql_num_rows(MYSQL_RES *result)
20.4.36.1 说明
在结果集合中返回行的数量。
mysql_num_rows()的使用取决于你是否使用mysql_store_result()或mysql_use_result()返回一个结果集合。如果你使用mysql_store_result()，mysql_num_rows()可以马上被调用。如果你使用mysql_use_result()，mysql_num_rows()将不会返回正确的值，直到在结果集合中的所有行均被检索了。
20.4.36.2 返回值
在结果集合中行的数量。
20.4.36.3 错误
无。
20.4.37 mysql_options()
int mysql_options(MYSQL *mysql, enum mysql_option option, const char *arg)
20.4.37.1 说明
能用于设置额外连接选项并且影响一个连接的行为。这个函数可以被多次调用来设置多个选项。
mysql_options()应该在mysql_init()之后和mysql_connect()或mysql_real_connect()之前调用。
option参数是你想要设置的选项；arg参数是选项的值。如果选项是一个整数，那么arg应该指向整数值。
可能的选项值：
| 选项 | 参数类型 | 功能 |
| MYSQL_OPT_CONNECT_TIMEOUT | unsigned int * | 以秒计的连接超时。 |
| MYSQL_OPT_COMPRESS | 不使用 | 使用压缩的客户机/服务器协议。 |
| MYSQL_OPT_NAMED_PIPE | 不使用 | 使用命名管道连接一个在NT上的MySQL服务器。 |
| MYSQL_INIT_COMMAND | char * | 当连接MySQL服务器时执行的命令。当重新连接时，将自动重新执行。 |
| MYSQL_READ_DEFAULT_FILE | char * | 从命名的选项文件而不是从“my.cnf”读取选项。 |
| MYSQL_READ_DEFAULT_GROUP | char * | 从“my.cnf”或用MYSQL_READ_DEFAULT_FILE指定的文件中的命名组中读取选项。 |
注意，如果你使用MYSQL_READ_DEFAULT_FILE或MYSQL_READ_DEFAULT_GROUP，总是读取client。
在选项文件中指定的组可能包含下列选项：
| compress | 使用压缩的客户机/服务器协议。 |
| database | 如果在连接命令中没有指定数据库，使用这个数据库。 |
| debug | 调试选项 |
| host | 缺省主机名 |
| init-command | 在连接MySQL服务器时，执行的命令。当重新连接时，将自动重新执行。 |
| password | 缺省口令 |
| pipe | 使用命名管道连接一个在NT上的MySQL服务器。 |
| port | 缺省端口号 |
| return-found-rows | 告诉mysql_info()返回找到的行，而不是在使用UPDATE时，返回更新的行。 |
| socket | 缺省套接字号 |
| timeout | 以秒计的连接超时。 |
| user | 缺省用户 |
对于选项文件的更多信息，见4.15.4 选项文件。
20.4.37.2 返回值
成功，零。如果你使用了未知的选项，非零。
20.4.37.3 范例
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文件的odbc小节读取额外的选项。
20.4.38 mysql_ping()
int mysql_ping(MYSQL *mysql)
20.4.38.1 说明
检查到服务器的连接是否正在工作。如果它关闭了，自动尝试一个再连接。
这个函数可被已经空闲很长时间的客户使用，来检查服务器是否关闭了连接并且如有必要重新连接。
20.4.38.2 返回值
如果服务器活着，零。如果出现一个错误，非零。
20.4.38.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_UNKNOWN_ERROR 发生一个未知的错误。
20.4.39 mysql_query()
int mysql_query(MYSQL *mysql, const char *query)
20.4.39.1 说明
执行指向空终止的字符串query的SQL查询，查询必须由一个单个的SQL语句组成。你不应该在语句后加上一个终止的分号(“；”)或\g。
mysql_query()不能被用于包含二进制数据的查询；相反你应该使用mysql_real_query()。（二进制数据可能包含“\0”字符，而mysql_query()将解释为查询字符串的结束。）
20.4.39.2 返回值
如果查询成功，零。如果出现一个错误，非零。
20.4.39.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 到服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。
20.4.40 mysql_real_connect()
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 int client_flag)
20.4.40.1 说明
mysql_real_connect()试图建立到运行host的一个MySQL数据库引擎的一个连接。 mysql_real_connect()在你可以执行任何其他API函数之前必须成功地完成，除了mysql_get_client_info()。
参数指定如下：
- 第一个参数应该是一个现存MYSQL结构的地址。在调用mysql_real_connect()之前，你必须调用mysql_init()初始化MYSQL结构。见下面的例子。
- host值可以是一个主机名或一个IP地址。如果host是NULL或字符串"localhost"，假定是到本地主机的一个连接。如果OS支持套接字(Unix)或命名管道(Win32)，使用他们而不是TCP/IP与服务器连接。
- user参数包含用户的MySQL登录ID。如果user是NULL，假定是当前用户。在Unix下，它是当前登录名。在Windows ODBC下，必须明确地指定当前用户名字。见16.4 怎样填写ODBC管理程序中各种域。
- passwd参数为user包含口令。如果passwd是NULL，只有在user表中对于有一个空白口令字段的用户的条目将被检查一个匹配。这允许数据库主管设置MySQL权限，使用户获得不同的口令，取决于他们是否已经指定一个口令。注意：不要试图在调用mysql_real_connect()前加密口令；口令加密自动被客户API处理。
- db是数据库名。如果db不是NULL，连接将缺省数据库设置为这个值。
- 如果port不是0，值对于TCP/IP连接将用作端口号。注意host参数决定连接的类型。
- 如果unix_socket不是NULL，字符串指定套接字或应该被使用的命名管道。注意host参数决定连接的类型。
- client_flag值通常是0，但是在很特殊的情况下可以被设置为下列标志的组合：
标志名字 意味着的标志 CLIENT_FOUND_ROWS 返回找到的(匹配的)行数，不是受到影响的行数。 CLIENT_NO_SCHEMA 不允许db_name.tbl_name.col_name语法。这是为了ODBC；如果你使用该语法，导致语法分析器产生一个错误，它是为在一些ODBC程序捕捉错误是有用的。 CLIENT_COMPRESS 使用压缩协议。 CLIENT_ODBC 客户是一个ODBC客户。这使mysqld变得对ODBC更友好。
20.4.40.2 返回值
如果连接成功，一个 MYSQL*连接句柄。如果连接失败，NULL。对一个成功的连接，返回值与第一个参数值相同，除非你传递NULL给该参数。
20.4.40.3 错误
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; 不能在 Win32 上创建一个命名管道。 CR_NAMEDPIPEWAIT_ERROR; 不能在 Win32 上等待一个命名管道。 CR_NAMEDPIPESETSTATE_ERROR; 不能在 Win32 上得到一个管道处理器。20.4.40.4 范例
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));
}
20.4.41 mysql_real_query()
int mysql_real_query(MYSQL *mysql, const char *query, unsigned int length)
20.4.41.1 说明
执行由query指向的SQL查询，它应该是一个length个字节的字符串。查询必须由一个单个的SQL语句组成。你不应该在语句后增加一个终止的分号(“;”)或\g。
对于包含二进制数据的查询，你必须使用mysql_real_query()而不是mysql_query()，因为二进制代码数据可能包含“\0”字符，而且，mysql_real_query()比mysql_query()更快，因为它对查询字符串调用strlen()。
20.4.41.2 返回值
如果查询成功，零。如果发生一个错误，非零。
20.4.41.3 错误
CR_COMMANDS_OUT_OF_SYNC 命令以一个不适当的次序被执行。 CR_SERVER_GONE_ERROR MySQL服务器关闭了。 CR_SERVER_LOST 对服务器的连接在查询期间失去。 CR_UNKNOWN_ERROR 发生一个未知的错误。 相关阅读 更多 +
