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));

}

const char *mysql_character_set_name(MYSQL *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);

}

char *mysql_get_client_info(void)

描述

返回資料表示客戶端庫版本的字串。

返回值

資料表示MySQL客戶端庫版本的字串。

錯誤

無。

unsigned long mysql_get_client_version(void)

描述

返回資料表示客戶端庫版本的整數。該值的格式是XYYZZ，其中X是主版本號，YY是發佈級別，ZZ是發佈級別內的版本號。例如，值40102資料表示客戶端庫的版本是4.1.2。

返回值

資料表示MySQL客戶端庫版本的整數。

錯誤

無。

char *mysql_get_host_info(MYSQL *mysql)

描述

返回描述了所使用連接類型的字串，包括伺服器主機名。

返回值

代資料表伺服器主機名和連接類型的字串。

錯誤

無。

unsigned int mysql_get_proto_info(MYSQL *mysql)

描述

返回當前連接所使用的協議版本。

返回值

代資料表當前連接所使用協議版本的無符號整數。

錯誤

無。

char *mysql_get_server_info(MYSQL *mysql)

描述

返回代資料表伺服器版本號的字串。

返回值

代資料表伺服器版本號的字串。