Mysql C API函数详解
- mysql_init()
MYSQL *mysql_init(MYSQL *mysql)
描述
分配或初始化与mysql_real_connect()相适应的MYSQL对象。如果mysql是NULL指针，该函数将分配、初始化、并返回新对象。否则，将初始化对象，并返回对象的地址。如果mysql_init()分配了新的对象，当调用mysql_close()来关闭连接时。将释放该对象。
返回值
初始化的MYSQL*句柄。如果无足够内存以分配新的对象，返回NULL。
错误
在内存不足的情况下，返回NULL。
mysql_errno()
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”表示未出现错误。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终结的字符串。如果未出现错误，返回空字符串。
错误
无。
mysql_real_escape_string()
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字符。
- 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
- mysql_character_set_name()
const char *mysql_character_set_name(MYSQL *mysql)
描述
为当前连接返回默认的字符集。
返回值
默认字符集。
错误
无。
mysql_set_character_set()
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));
}- mysql_close()
void mysql_close(MYSQL *mysql)
描述
关闭前面打开的连接。如果句柄是由mysql_init()或mysql_connect()自动分配的，mysql_close()还将解除分配由mysql指向的连接句柄。
返回值
无。
错误
无。
- mysql_select_db()
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
出现未知错误。
- mysql_real_query()
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
出现未知错误。
- 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);
}- mysql_store_result()
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
出现未知错误。
- 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");
}- 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]);
}
}- 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()不返回正确的值，直至检索了结果集中的所有行为止。
返回值
结果集中的行数。
错误
无。
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);
}- mysql_free_result()
void mysql_free_result(MYSQL_RES *result)
描述
释放由mysql_store_result()、mysql_use_result()、mysql_list_dbs()等为结果集分配的内存。完成对结果集的操作后，必须调用mysql_free_result()释放结果集使用的内存。
释放完成后，不要尝试访问结果集。
返回值
无。
错误
无。
- 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_get_host_info()
char *mysql_get_host_info(MYSQL *mysql)
描述
返回描述了所使用连接类型的字符串，包括服务器主机名。
返回值
代表服务器主机名和连接类型的字符串。
错误
无。
- mysql_options()
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，总会读取客户端组。
返回值
成功时返回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));
}