| |
Код C API распространяется в комплекте с MySQL. Он включен в библиотеку
mysqlclient
и позволяет программам на C обращаться к базе данных.
Многие клиенты в дистрибутиве исходного кода MySQL написаны на C. Если Вы
ищете примеры, которые показывают, как использовать C API, посмотрите код
этих клиентов. Их можно найти в каталоге clients
дистрибутива
исходного кода MySQL.
Большинство других клиентских API (кроме поддержки Java) использует
библиотеку mysqlclient
, чтобы связаться с сервером MySQL. Это
означает, что, например, Вы можете воспользоваться большинством системных
переменных, которые используются другими программами потому, что реально они
вызваны из библиотеки.
Пользователь имеет максимальный размер буфера связи. Размер буфера, который распределен первоначально (16 килобайт), автоматически увеличивается до максимального размера (максимум 16 мегабайт). Поскольку размеры буфера растут только по запросу, просто увеличивая заданное по умолчанию максимальное ограничение, Вы не заставите большее количество ресурсов использоваться. Эта проверка размера обычно применяется в сложных ситуациях.
Буфер связи должен быть достаточно большим, чтобы хранить одиночную
инструкцию SQL (для трафика "клиент-на сервер") и одну строку возвращенных
данных (для трафика "сервер-на-клиент"). Буфер связи каждого потока будет
динамически расширен до максимального ограничения, чтобы обработать любой
запрос или строку. Например, если Вы имеете значения BLOB
,
которые содержат до 16M данных, Вы должны иметь ограничение буфера связи
по крайней мере в 16M (на клиенте и на сервере сразу). Заданный по умолчанию
максимум пользователя равен 16M, но заданный по умолчанию максимум сервера
равен всего 1M. Вы можете увеличивать это, меняя значение параметра
max_allowed_packet
при запуске сервера.
Сервер MySQL сокращает каждый буфер связи до
net_buffer_length
байт после каждого запроса. Для клиентуры
размер буфера, связанного с подключением, не будет уменьшен, пока подключение
не будет закрыто.
Для программирования с потоками, обратитесь к разделу "2.8 Как делать поточные клиенты". Для создания автономной прикладной программы, которая включает клиент и сервер в той же самой программе (и не связывается с внешним сервером MySQL) обратитесь к разделу "2.9 libmysqld, библиотека встроенного сервера MySQL".
MYSQL
MYSQL_RES
SELECT
, SHOW
, DESCRIBE
,
EXPLAIN
). Информация, возвращенная из запроса, названа набором
результатов в остатках от этого раздела.
MYSQL_ROW
mysql_fetch_row()
.
MYSQL_FIELD
MYSQL_FIELD
для каждого поля, неоднократно вызывая
mysql_fetch_field()
. Значения полей не являются частью этой
структуры, они содержатся в структуре MYSQL_ROW
.
MYSQL_FIELD_OFFSET
mysql_field_seek()
. Смещения представляют
собой номера полей внутри строки, начиная с нуля.
my_ulonglong
mysql_affected_rows()
, mysql_num_rows()
и
mysql_insert_id()
. Этот тип обеспечивает диапазон от
0
до 1.84e19
. На некоторых системах попытка
печатать значение типа my_ulonglong
не будет работать. Чтобы
отпечатать такое значение, преобразуйте его к типу unsigned long
и используйте формат вывода %lu
. Например:
printf (Number of rows: %lu\n", (unsigned long) mysql_num_rows(result));
Структура MYSQL_FIELD
содержит члены, перечисленные ниже:
char * name
char * table
table
представлено пустой строкой.
char * def
mysql_list_fields()
.
enum enum_field_types type
type
может быть один из следующего:
Значение Type | Используемый тип |
FIELD_TYPE_TINY | TINYINT |
FIELD_TYPE_SHORT | SMALLINT |
FIELD_TYPE_LONG | INTEGER |
FIELD_TYPE_INT24 | MEDIUMINT |
FIELD_TYPE_LONGLONG | BIGINT |
FIELD_TYPE_DECIMAL | DECIMAL или
NUMERIC |
FIELD_TYPE_FLOAT | FLOAT |
FIELD_TYPE_DOUBLE | DOUBLE или
REAL |
FIELD_TYPE_TIMESTAMP | TIMESTAMP |
FIELD_TYPE_DATE | DATE |
FIELD_TYPE_TIME | TIME |
FIELD_TYPE_DATETIME | DATETIME |
FIELD_TYPE_YEAR | YEAR |
FIELD_TYPE_STRING | Строка (CHAR или
VARCHAR ) |
FIELD_TYPE_BLOB | BLOB или
TEXT (используйте max_length , чтобы определить
максимальную длину поля) |
FIELD_TYPE_SET | SET |
FIELD_TYPE_ENUM | ENUM |
FIELD_TYPE_NULL | NULL |
FIELD_TYPE_CHAR | Не рекомендуется: используйте
FIELD_TYPE_TINY |
IS_NUM()
, чтобы проверить имеет
или нет поле числовой тип. Передайте значение type
в
IS_NUM()
. Вернется TRUE, если поле числовое:
if (IS_NUM(field->type)) printf("Field is numeric\n");
unsigned int length
unsigned int max_length
mysql_store_result()
или mysql_list_fields()
, это
содержит максимальную длину поля. Если Вы используете
mysql_use_result()
, значение этой переменной нулевое.
unsigned int flags
flags
может иметь ноль или большее количество из следующего набора битов:
Значение Flag | Что это значит |
NOT_NULL_FLAG | Поле не может быть
NULL |
PRI_KEY_FLAG | Поле часть первичного ключа |
UNIQUE_KEY_FLAG | Поле часть уникального ключа |
MULTIPLE_KEY_FLAG | Поле часть неуникального ключа |
UNSIGNED_FLAG | Поле имеет атрибут
UNSIGNED |
ZEROFILL_FLAG | Поле имеет атрибут
ZEROFILL |
BINARY_FLAG | Поле имеет атрибут
BINARY |
AUTO_INCREMENT_FLAG | Поле имеет атрибут
AUTO_INCREMENT |
ENUM_FLAG | Поле имеет тип ENUM |
BLOB_FLAG | Поле имеет тип BLOB или
TEXT |
TIMESTAMP_FLAG | Поле имеет тип
TIMESTAMP |
BLOB_FLAG
, ENUM_FLAG
и
TIMESTAMP_FLAG
не рекомендуется потому, что они указывают тип
поля, а не атрибут типа. Предпочтительно проверить
field->type
вместо FIELD_TYPE_BLOB
,
FIELD_TYPE_ENUM
или FIELD_TYPE_TIMESTAMP
. Пример
ниже иллюстрирует типичное использование flags
:
if (field->flags & NOT_NULL_FLAG) printf("Field can't be null\n");Вы можете использовать следующие макрокоманды, чтобы определить булево состояние значения
flags
:
IS_NOT_NULL(flags) | Истина, если это поле
определено как NOT NULL |
IS_PRI_KEY(flags) | Истина, если это поле первичный ключ |
IS_BLOB(flags) | Истина, если это поле
BLOB или TEXT |
unsigned int decimals
Функции, доступные в C API, перечислены ниже и описаны более подробно в следующем разделе. Подробности в разделе "2.3 Описание функций C API".
mysql_affected_rows() |
Возвращает число строк измененных последним запросом UPDATE ,
DELETE или INSERT . |
mysql_close() | Закрывает подключение к серверу. |
mysql_connect() | Соединяется с сервером. |
mysql_change_user() | Меняет пользователя и базу данных на открытом подключении. |
mysql_character_set_name() | Возвращает имя заданного по умолчанию набора символов для подключения. |
mysql_create_db() | Создает базу данных.
Аналог команды SQL CREATE DATABASE . |
mysql_data_seek() | Ищет произвольную строку в наборе результатов запросов. |
mysql_debug() | Делает DBUG_PUSH
для заданной строки. |
mysql_drop_db() | Удаляет базу данных. Эта
функция аналогична команде SQL DROP DATABASE . |
mysql_dump_debug_info() | Заставляет сервер писать информацию отладки в файл регистрации. |
mysql_eof() | Определяет, читалась или нет последняя строка набора результатов. |
mysql_errno() | Возвращает код ошибки для вызванной недавно функции MySQL. |
mysql_error() | Возвращает текстовое сообщение об ошибке для вызванной недавно функции MySQL. |
mysql_real_escape_string() | Выходит из специальных символов в строке для использования в инструкции SQL, принимающей во внимание текущий набор символов данного подключения. |
mysql_escape_string() | Выходит из специальных символов в строке для использования в обычной инструкции SQL. |
mysql_fetch_field() | Возвращает тип следующего поля таблицы. |
mysql_fetch_field_direct() | Возвращает тип поля таблицы, по номеру поля. |
mysql_fetch_fields() | Возвращает массив всех структур поля. |
mysql_fetch_lengths() | Возвращает длины всех столбцов в текущей (актуальной) строке. |
mysql_fetch_row() | Выбирает следующую строку из набора результатов. |
mysql_field_seek() | Помещает курсор столбца в определенный параметром столбец. |
mysql_field_count() | Возвращает число столбцов результата для последнего запроса. |
mysql_field_tell() | Возвращает позицию
курсора поля, используемого для последнего вызова
mysql_fetch_field() . |
mysql_free_result() | Освобождает память, используемую набором результатов. |
mysql_get_client_info() | Возвращает информацию о версии программы-клиента. |
mysql_get_host_info() | Возвращает строку, описывающую подключение. |
mysql_get_proto_info() | Возвращает версию протокола, используемую подключением. |
mysql_get_server_info() | Возвращает номер версии сервера. |
mysql_info() | Возвращает информацию относительно недавно выполненного запроса. |
mysql_init() | Получает или инициализирует
структуру MYSQL . |
mysql_insert_id() | Возвращает ID,
сгенерированный для столбца с поддержкой AUTO_INCREMENT
предыдущим запросом. |
mysql_kill() | Уничтожает заданный поток. |
mysql_list_dbs() | Возвращает имена баз данных, соответствующие простому регулярному выражению. |
mysql_list_fields() | Возвращает имена полей, соответствующие простому регулярному выражению. |
mysql_list_processes() | Возвращает список текущих потоков сервера. |
mysql_list_tables() | Возвращает имена таблиц, соответствующие простому регулярному выражению. |
mysql_num_fields() | Возвращает число столбцов в наборе результатов. |
mysql_num_rows() | Возвращает число строк в наборе результатов. |
mysql_options() | Устанавливает опции связи
для вызова mysql_connect() . |
mysql_ping() | Проверяет работает или нет подключение с сервером, повторно соединяется по мере необходимости. |
mysql_query() | Выполняет запрос SQL, определенный как строка с нулевым символом в конце. |
mysql_real_connect() | Соединяется с сервером. |
mysql_real_query() | Выполняет запрос SQL, определенный как рассчитанная строка. |
mysql_reload() | Сообщает, чтобы сервер перезагрузил таблицы предоставления привилегий. |
mysql_row_seek() | Переходит к строке в наборе
результатов, используя значение, возвращенное из
mysql_row_tell() . |
mysql_row_tell() | Возвращает позицию курсора строки. |
mysql_select_db() | Выбирает базу данных. |
mysql_shutdown() | Закрывает сервер. |
mysql_stat() | Возвращает состояние сервера. |
mysql_store_result() | Возвращает полный набор результатов пользователю. |
mysql_thread_id() | Возвращает ID потока. |
mysql_thread_safe() | Возвращает 1, если клиент компилируется как поточно-безопасный. |
mysql_use_result() | Инициализирует копию результата строка в строку. |
Чтобы соединиться с сервером, вызовите mysql_init()
, чтобы
инициализировать драйвер подключения, затем вызовите
mysql_real_connect()
с этим драйвером (наряду с другой
информацией типа hostname, имени пользователя и пароля). При подключении
mysql_real_connect()
устанавливает флажок reconnect
(часть структуры MYSQL) в значение 1
. Этот флажок указывает, что
когда запрос не может выполняться из-за потерянного подключения, надо
попробовать повторно соединиться с сервером перед отказом. Когда Вы закончите
работу с подключением, вызовите mysql_close()
для его закрытия.
В то время как подключение активно, пользователь может посылать запросы
SQL серверу, применяя функции mysql_query()
или
mysql_real_query()
. Различие между ними в том, что
mysql_query()
ожидает, что запрос будет определен как строка с
нулевым символом в конце, в то время как mysql_real_query()
ожидает рассчитанную строку. Если несет в себе двоичные данные (которые сами
по себе могут включать нулевые байты), Вы должны использовать только
mysql_real_query()
.
Для каждого запроса не-SELECT
(например, INSERT
,
UPDATE
, DELETE
), Вы можете выяснить, сколько строк
были изменены, вызывая mysql_affected_rows()
.
Для запросов SELECT
Вы получаете выбранные строки в наборе
результатов. Обратите внимание, что некоторые инструкции подобны
SELECT
в том плане, что они возвращают строки. Сюда входят
SHOW
, DESCRIBE
и EXPLAIN
. Они должны
обработаться тем же самым методом, что и обычный SELECT
.
Имеются два пути для пользователя, чтобы обработать наборы результатов.
Один путь состоит в том, чтобы получить весь набор результатов, вызывая
mysql_store_result()
. Эта функция получает с сервера все строки,
возвращенные запросом и сохраняет их на клиенте. Второй путь инициализировать
построчный набор результатов, вызывая mysql_use_result()
. Эта
функция инициализирует поиск, но фактически не получает никаких строк.
В обоих случаях Вы обращаетесь к строкам, вызывая
mysql_fetch_row()
. В случае mysql_store_result()
mysql_fetch_row()
обращается к строкам, которые уже были выбраны
из сервера. В случае же mysql_use_result()
mysql_fetch_row()
фактически получает строку с сервера
самостоятельно. Информация относительно размера данных в каждой строке
доступна через вызов mysql_fetch_lengths()
.
После того, как Вы закончите работу с набором результатов, вызовите
mysql_free_result()
, чтобы освободить используемую память.
Два механизма поиска дополняют друг друга. Программы пользователя должны
выбрать подход, который является наиболее подходящим для их требований.
Практически же, клиентура имеет тенденцию обычно использовать
mysql_store_result()
.
Преимущество mysql_store_result()
в том, что, поскольку все
строки были переданы пользователю, Вы не только можете обращаться к строкам
последовательно, Вы можете также двигаться обратно в наборе результатов,
используя mysql_data_seek()
или mysql_row_seek()
,
чтобы изменить текущую (актуальную) позицию строки внутри набора результатов.
Вы можете также выяснять, сколько там строк, вызывая
mysql_num_rows()
. С другой стороны, требования к памяти для
mysql_store_result()
могут быть очень высоки для больших наборов
результатов, и Вы, вероятно, столкнетесь с проблемами нехватки памяти.
Преимущество mysql_use_result()
в том, что пользователь
требует меньшего количества памяти для набора результатов потому, что это
поддерживает только одну строку одновременно (и потому, что имеется меньшее
количество дополнительных распределений для заголовков, так что
mysql_use_result()
может быть быстрее). Недостаток: Вы должны
обработать каждую строку быстро, чтобы не держать занятым сервер. Вы не
имеете произвольного доступа к строкам внутри набора результатов (Вы можете
только обращаться к строкам последовательно), и Вы не знаете, сколько строк
находится в наборе результатов, пока Вы не получите их все. Кроме того, Вы
должны принять все строки, даже если Вы определяете в середине поиска, что
уже нашли ту информацию, которую Вы искали.
API позволяет клиентам ответить соответственно на запросы (получая строки
только по мере необходимости) без того, чтобы знать, является или нет запрос
SELECT
. Вы можете делать это, вызывая
mysql_store_result()
после каждого mysql_query()
(или mysql_real_query()
). Если обращение к набору результатов
прошло успешно, запросом был SELECT
, и Вы можете читать строки.
Если произошел сбой, вызовите mysql_field_count()
, чтобы
определить, должен или нет фактически ожидаться результат. Если
mysql_field_count()
возвращает ноль, запрос не возвратил никаких
данных (это показывает, что это был INSERT
, UPDATE
,
DELETE
или что-то в этом роде) и не возвратит строки. Если
mysql_field_count()
отличен от нуля, запрос должен был
возвратить строки, но не сделал этого. Это указывает, что запросом был
SELECT
, который потерпел неудачу.
Вызовы mysql_store_result()
и mysql_use_result()
позволяют Вам получать информацию относительно полей, которые составляют
набор результатов (число полей, их имена, типы и т.п.). Вы можете обращаться
к информации поля последовательно внутри строки, вызывая
mysql_fetch_field()
неоднократно, или по номеру поля внутри
строки, вызывая mysql_fetch_field_direct()
напрямую. Текущая
(актуальная) позиция курсора поля может быть изменена вызовом
mysql_field_seek()
. Установка курсора поля воздействует на
последующие обращения к mysql_fetch_field()
. Вы можете также
получать информацию для полей в любой момент, вызывая
mysql_fetch_fields()
.
Для обнаружения и сообщения об ошибках MySQL обеспечивает доступ к
информации ошибки посредством функций mysql_errno()
и
mysql_error()
. Они возвращают код ошибки или сообщение об ошибке
для последней вызванной функции, позволяя Вам определить, когда ошибка
произошла, и что это было.
В описаниях ниже параметр или значение возврата NULL
означает
NULL
в смысле языка программирования C, а не MySQL-значение
NULL
.
Функции, которые возвращают значение, возвращают указатель или целое
число. Если не определено иное, функции, возвращающие указатель, возвращают
значение не-NULL
, чтобы указать успех, или значение
NULL
, чтобы указать ошибку, а функции, возвращающие число,
возвращают целочисленный ноль, чтобы указать успех, или отличное от нуля
значение, чтобы указать ошибку. Обратите внимание, что "отличное от нуля"
означает только это. Если функциональное описание не говорит иного, не надо
проверять результат на соответствие каким-либл числам, кроме нуля.
if (result) /* правильно */ ... error ... if (result < 0) /* неправильно */ ... error ... if (result == -1) /* неправильно */ ... error ...
Когда функция возвращает ошибку, подраздел Ошибки
описания функции вносит в список возможные типы ошибок. Вы можете выяснить,
который из них произошел, вызывая mysql_errno()
. Представление
строки ошибки может быть получено, вызывая mysql_error()
.
mysql_affected_rows()
my_ulonglong mysql_affected_rows(MYSQL *mysql)
Возвращает число строк, измененных последним UPDATE
,
удаленных последним DELETE
или вставленных последней инструкцией
INSERT
. Может быть вызвана немедленно после
mysql_query()
для UPDATE
, DELETE
или
INSERT
. Для инструкции SELECT
mysql_affected_rows()
работает подобно
mysql_num_rows()
.
Целое число, большее, чем ноль, указывает количество обработанных строк.
Ноль указывает, что никакие записи обработаны не были. -1 указывает, что
запрос возвратил ошибку или то, что для запроса SELECT
mysql_affected_rows()
был вызван до вызова
mysql_store_result()
.
Нет.
mysql_query(&mysql,"UPDATE products SET cost=cost*1.25 WHERE group=10"); printf("%ld products updated",(long) mysql_affected_rows(&mysql));
Если определен флажок CLIENT_FOUND_ROWS
, при соединение с
mysqld
mysql_affected_rows()
возвратит число строк,
согласованных инструкцией WHERE
для UPDATE
.
Обратите внимание, что, когда использована команда REPLACE
,
mysql_affected_rows()
вернет 2 потому, что в этом случае одна
строка была вставлена, а затем дубликат был удален.
mysql_close()
void mysql_close(MYSQL *mysql)
Закрывает предварительно открытое подключение. mysql_close()
также освободит дескриптор подключения, указанный в mysql
, если
дескриптор был распределен автоматически mysql_init()
или
mysql_connect()
.
Нет.
Нет.
mysql_connect()
MYSQL *mysql_connect(MYSQL *mysql, const char *host, const
char *user, const char *passwd)
пытается устанавливать подключение с сервером MySQL на компьютере
host
. mysql_connect()
должна завершиться успешно
прежде, чем Вы сможете выполнить любую из функций API, за исключением
mysql_get_client_info()
.
Значения параметров такие же, как для соответствующих параметров
mysql_real_connect()
с тем различием, что параметр подключения
может быть NULL
. В этом случае C API распределяет память для
структуры подключения автоматически и освобождает ее, когда Вы вызываете
mysql_close()
. Недостаток этого подхода в том, что Вы не можете
получить сообщение об ошибке, если подключение терпит неудачу. Чтобы получать
информацию об ошибке из mysql_errno()
или
mysql_error()
, Вы должны обеспечить имеющий силу указатель
на структуру MYSQL
.
Аналогично mysql_real_connect()
.
Аналогично mysql_real_connect()
.
mysql_change_user()
my_bool mysql_change_user(MYSQL *mysql, const char *user, const
char *password, const char *db)
Меняет пользователя и заставляет базу данных, определенную как
db
, стать заданной по умолчанию (текущей) базой данных на
подключении, определенном mysql
. В последующих запросах эта база
данных будет значением по умолчанию для ссылок на таблицы, которые не
включают явный спецификатор базы данных.
Эта функция представлена в MySQL Version 3.23.3.
mysql_change_user()
терпит неудачу, если указанный
пользователь не может быть использован, или если он не имеет разрешения
использовать эту базу данных. В этом случае пользователь и база данных не
будут изменены вообще.
Параметр db
может быть установлен в NULL
, если
Вы не хотите иметь заданную по умолчанию базу данных.
Ноль для успеха. Отличное от нуля, если произошла ошибка.
Аналогично mysql_real_connect()
.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
ER_UNKNOWN_COM_ERROR
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)); }
mysql_character_set_name()
const char *mysql_character_set_name(MYSQL *mysql)
Возвращает заданный по умолчанию набор символов для текущего (актуального) подключения.
Заданный по умолчанию набор символов
Нет.
mysql_create_db()
int mysql_create_db(MYSQL *mysql, const char *db)
Создает базу данных с именем db
.
Ноль, если база данных была создана успешно. Отличное от нуля, если в процессе произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
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)); }
mysql_data_seek()
void mysql_data_seek(MYSQL_RES *result, unsigned long long offset)
Переходит к произвольной строке в наборе результатов запроса. Это требует,
чтобы структура набора результата содержала весь результат запроса, так что
mysql_data_seek()
может использоваться только в конъюнкции с
mysql_store_result()
, но никак не с
mysql_use_result()
.
Смещение должно быть значением в диапазоне от 0 до
mysql_num_rows(result)-1
.
Нет.
Нет.
mysql_debug()
void mysql_debug(char *debug)
Делает DBUG_PUSH
с заданной строкой. Вызов
mysql_debug()
использует библиотеку отладки Fred Fish. Чтобы
использовать эту функцию, Вы должны компилировать библиотеку клиентов так,
чтобы поддерживать отладку.
Нет.
Нет.
Обращение, показанное ниже, заставляет библиотеку клиентов генерировать файл трассировки /tmp/client.trace на машине пользователя:
mysql_debug("d:t:O,/tmp/client.trace");
mysql_drop_db()
int mysql_drop_db(MYSQL *mysql, const char *db)
Удвляет базу данных, упомянутую как параметр db
.
Ноль, если база данных была удалена успешно. Отличное от нуля, если в процессе произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
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));
mysql_dump_debug_info()
int mysql_dump_debug_info(MYSQL *mysql)
Инструктирует сервер, чтобы писать некоторую информацию отладки в файл регистрации. Отдавший команду пользователь должен иметь привилегию process, чтобы работать.
Ноль, если команда была успешно выполнена. Отличное от нуля, если в процессе произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_eof()
my_bool mysql_eof(MYSQL_RES *result)
mysql_eof()
определяет, читалась или нет последняя
строка набора результатов.
Если Вы приобретаете результат из успешного обращения к
mysql_store_result()
, клиент получает весь набор в одной
операции. В этом случае возврат NULL
из
mysql_fetch_row()
всегда означает, что конец набора результатов
был достигнут и не нужно вызвать mysql_eof()
.
С другой стороны, если Вы используете mysql_use_result()
,
чтобы инициализировать поиск набора результата, строки набора получены с
сервера по одной, поскольку Вы вызываете mysql_fetch_row()
неоднократно. Потому что ошибка может происходить на подключении в течение
этого процесса, значение NULL
из функции
mysql_fetch_row()
не обязательно означает, что конец набора
результатов был достигнут. В этом случае, Вы можете использовать
mysql_eof()
, чтобы определить, что там случилось. Функция
mysql_eof()
возвращает значение, отличное от нуля, если конец
набора результатов был достигнут и ноль, если произошла ошибка.
Исторически mysql_eof()
предшествует стандартной функции
MySQL mysql_errno()
и mysql_error()
. Так как те
функции ошибки обеспечивают ту же самую информацию, их использование
предпочтительнее mysql_eof()
. Фактически, они обеспечивают
большее количество информации потому, что mysql_eof()
возвращает
только булево значение, в то время как функции ошибки указывают причину.
Функция mysql_eof()
возвращает значение, отличное от нуля,
если конец набора результатов был достигнут и ноль, если произошла ошибка.
Нет.
Следующий пример показывает, как Вы могли бы использовать
mysql_eof()
:
mysql_query(&mysql,"SELECT * FROM some_table"); result = mysql_use_result(&mysql); while((row = mysql_fetch_row(result))) { // Что-то делается с данными } if (!mysql_eof(result)) // mysql_fetch_row() потерпел неудачу из-за ошибки { 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))) { // Что-то делается с данными } if (mysql_errno(&mysql)) // mysql_fetch_row() потерпел неудачу из-за ошибки { fprintf(stderr, "Error: %s\n", mysql_error(&mysql)); }
mysql_errno()
unsigned int mysql_errno(MYSQL *mysql)
Для подключения, определенного в mysql
,
mysql_errno()
возвращает код ошибки для вызванной функции
API, которая может сработать нормально или потерпеть неудачу. Значение
возврата 0 означает, что никакой ошибки не произошло. Числа сообщений об
ошибках клиента перечислены в файле заголовка MySQL errmsg.h.
Серверные ошибки перечислены в mysqld_error.h. В дистрибутиве
исходного кода MySQL Вы можете найти полный список сообщений об ошибках и их
кодов в файле Docs/mysqld_error.txt.
Значение кода ошибки. 0, если никакая ошибка не произошла.
Нет.
mysql_error()
char *mysql_error(MYSQL *mysql)
Для подключения, определенного в mysql
,
mysql_error()
возвращает сообщение об ошибках для вызванной
функции API, которая может сработать нормально или потерпеть неудачу. Пустая
строка (""
) вернется, если никакой ошибки не произошло. Это
означает, что следующие тесты эквивалентны:
if (mysql_errno(&mysql)) { // an error occurred } if (mysql_error(&mysql)[0] != '\0') { // an error occurred }
Язык сообщений об ошибках пользователя может быть изменен перекомпиляцией библиотеки клиента MySQL. В настоящее время Вы можете выбирать сообщения об ошибках на нескольких различных языках.
Символьная строка, которая описывает ошибку. Пустая строка, если никакой ошибки не произошло.
Нет.
mysql_escape_string()
Это идентично mysql_real_escape_string()
за исключением того,
что требуется подключение как первый параметр.
mysql_real_escape_string()
обработает строку согласно текущему
(актуальному) набору символов, в то время как
mysql_escape_string()
игнорирует установку charset.
mysql_fetch_field()
MYSQL_FIELD *mysql_fetch_field(MYSQL_RES *result)
Возвращает определение одного столбца набора результатов как структуру
MYSQL_FIELD
. Вызовите эту функцию неоднократно, чтобы собрать
информацию относительно всех столбцов в наборе результатов.
mysql_fetch_field()
возвращает NULL
, когда все поля
уже обработаны или их не было вовсе.
mysql_fetch_field()
будет сброшен так, чтобы возвратить
информацию относительно первого поля каждый раз, когда Вы выполняете новый
запрос SELECT
. На поле, возвращенное
mysql_fetch_field()
также воздействуют обращения к
mysql_field_seek()
.
Если Вы вызвали mysql_query()
чтобы выполнить
SELECT
на таблице, но не вызвали
mysql_store_result()
, MySQL возвращает заданную по умолчанию
длину blob (8K), если Вы вызываете mysql_fetch_field()
, чтобы
спросить о длине поля типа BLOB
. Размер в 8K выбран потому, что
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_fetch_fields()
MYSQL_FIELD *mysql_fetch_fields(MYSQL_RES *result)
Возвращает массив всех структур MYSQL_FIELD
для набора
результатов. Каждая структура обеспечивает определение поля для одного
столбца набора результатов.
Массив структур 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_fetch_field_direct()
MYSQL_FIELD *mysql_fetch_field_direct(MYSQL_RES *result,
unsigned int fieldnr)
Получает код поля 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_fetch_lengths()
unsigned long *mysql_fetch_lengths(MYSQL_RES *result)
Возвращает длины столбцов текущей (актуальной) строки внутри набора
результатов. Если Вы планируете копировать значения поля, эта информация
также полезна для оптимизации потому, что Вы можете избежать вызова
strlen()
. Кроме того, если набор результатов содержит двоичные
данные, Вы должны использовать эту функцию, чтобы определить размер
данных потому, что функция strlen()
возвращает неправильные
результаты для любого поля, содержащего символы пробела.
Длина для пустых столбцов и для столбцов, содержащих значения
NULL
, равна нулю. Чтобы видеть, как отличить эти два случая,
обратитесь к описанию mysql_fetch_row()
.
Массив длинных целых чисел без знака, представляющих размер каждого
столбца (не включая любые символы пробелов в хвосте). NULL
, если
что-то пошло не так.
mysql_fetch_lengths()
имеет силу только для текущей строки
набора результатов. Этот вызов возвращает NULL
, если Вы
вызываете его перед mysql_fetch_row()
или после получения
всех строк в результате.
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_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)
. Если
row
хранит значение возврата от обращения к
mysql_fetch_row()
, указатели на значения меняются с
row[0]
на row[mysql_num_fields(result)-1]
. Значения
NULL
в строке обозначены указателями NULL
.
Длины значений полей в строке могут быть получены, вызывая
mysql_fetch_lengths()
. Пустые поля и поля, содержащие
NULL
имеют длину 0. Вы можете отличать их, проверяя указатель
для значения поля. Если указатель равен NULL
, поле
NULL
, иначе поле пустое.
Структура MYSQL_ROW
для следующей строки. NULL
,
если не имеется больше строк, чтобы получить, или произошла ошибка.
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_field_count()
unsigned int mysql_field_count(MYSQL *mysql)
Если Вы используете версию MySQL ранее, чем Version 3.22.24, Вы должны
вместо этого использовать unsigned int
mysql_num_fields(MYSQL *mysql)
.
Возвращает число столбцов для самого последнего запроса на подключении.
Нормальное использование этой функции: когда
mysql_store_result()
возвращает NULL
(и таким
образом Вы не имеете никакого указателя на набор результатов). В этом случае
Вы можете вызывать mysql_field_count()
, чтобы определить, должен
или нет mysql_store_result()
произвести не пустой результат. Это
позволяет программе пользователя выбрать соответствующее действие без того,
чтобы знать, был или нет запрос SELECT
(или
SELECT
-подобным). Пример, показанный ниже иллюстрирует, как это
может быть выполнено.
Целое число без знака, представляющее число полей в наборе результатов.
Нет.
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_field_count(&mysql)
на
mysql_errno(&mysql)
. В этом случае Вы проверяете
непосредственно для ошибки из mysql_store_result()
вместо
анализа значения mysql_field_count()
на предмет того, является
или нет оператор SELECT
.
mysql_field_seek()
MYSQL_FIELD_OFFSET mysql_field_seek(MYSQL_RES *result,
MYSQL_FIELD_OFFSET offset)
Устанавливает курсор поля к данному смещению. Следующее обращение к
mysql_fetch_field()
получит определение поля столбца, связанного
именно с этим смещением.
Чтобы перейти к началу строки, передайте 0 как значение
offset
.
Предыдущее значение курсора поля.
Нет.
mysql_field_tell()
MYSQL_FIELD_OFFSET mysql_field_tell(MYSQL_RES *result)
Возвращает позицию курсора поля, используемого для последнего
mysql_fetch_field()
. Это значение может использоваться как
параметр для mysql_field_seek()
.
Текущее смещение курсора поля.
Нет.
mysql_free_result()
void mysql_free_result(MYSQL_RES *result)
Освобождает память, распределенную для набора результатов
mysql_store_result()
, mysql_use_result()
,
mysql_list_dbs()
и другими подобными функциями. Когда Вы
закончили работу с набором результатов, Вы должны освободить память, которую
он использует, вызывая mysql_free_result()
.
Нет.
Нет.
mysql_get_client_info()
char *mysql_get_client_info(void)
Возвращает строку, которая представляет версию клиентской библиотеки.
Символьная строка, которая представляет версию клиентской библиотеки MySQL.
Нет.
mysql_get_host_info()
char *mysql_get_host_info(MYSQL *mysql)
Возвращает строку, описывающую тип используемого подключения, включая имя главного компьютера сервера.
Символьная строка, представляющая имя компьютера и тип подключения.
Нет.
mysql_get_proto_info()
unsigned int mysql_get_proto_info(MYSQL *mysql)
Возвращает код версии протокола, используемой текущим подключением.
Целое число без знака, представляющее версию протокола, используемую текущим (актуальным) подключением.
Нет.
mysql_get_server_info()
char *mysql_get_server_info(MYSQL *mysql)
Возвращает строку, которая представляет номер версии сервера.
Символьная строка, которая представляет номер версии станции.
Нет.
mysql_info()
char *mysql_info(MYSQL *mysql)
Возвращает строку, обеспечивающую информацию относительно недавно
выполненного запроса, но только для инструкций, перечисленных ниже. Для
других инструкций mysql_info()
всегда возвращает
NULL
. Формат строки изменяется в зависимости от типа запроса,
как описано ниже. Числа только иллюстративны: строка будет содержать
значения, соответствующие запросу.
INSERT INTO ... SELECT ...
Records: 100 Duplicates: 0 Warnings: 0
INSERT INTO ... VALUES (...),(...),(...)...
Records: 3 Duplicates: 0 Warnings: 0
LOAD DATA INFILE ...
Records: 1 Deleted: 0 Skipped: 0 Warnings: 0
ALTER TABLE
Records: 3 Duplicates: 0 Warnings: 0
UPDATE
Rows matched: 40 Changed: 40 Warnings: 0
Обратите внимание, что mysql_info()
возвращает значение
не-NULL
для инструкции INSERT ... VALUES
только,
если много списков значений было определено в инструкции.
Символьная строка, представляющая дополнительную информацию относительно
последнего выполненного запроса. NULL
, если никакая информация
не доступна для запроса.
Нет.
mysql_init()
MYSQL *mysql_init(MYSQL *mysql)
Распределяет или инициализирует объект MYSQL
, подходящий для
mysql_real_connect()
. Если mysql
является
указателем NULL
, функция распределяет память, инициализирует и
возвращает новый объект. Иначе объект будет просто инициализирован, и адрес
объекта возвращен. Если mysql_init()
распределяет новый объект,
место будет освобождено, когда будет вызвана mysql_close()
.
Инициализированный дескриптор MYSQL*
. NULL
, если
недостаточно памяти, чтобы распределить и инициализировать новый объект.
В случае недостаточной памяти вернется NULL
.
mysql_insert_id()
my_ulonglong mysql_insert_id(MYSQL *mysql)
Возвращает ID, сгенерированный предыдущим запросом для столбца с
поддержкой AUTO_INCREMENT
. Используйте эту функцию после того,
как Вы выполнили запрос INSERT
для таблицы, которая содержит
поле AUTO_INCREMENT
.
Обратите внимание, что mysql_insert_id()
возвращает
0
, если предыдущий запрос не генерирует значение
AUTO_INCREMENT
. Если Вы должны сохранить значение для
последующего неспешного потребления убедитесь, что вызвали
mysql_insert_id()
немедленно после того запроса,
который генерирует значение.
mysql_insert_id()
модифицируется после инструкций
INSERT
и UPDATE
, которые генерируют значение
AUTO_INCREMENT
, или установки значения столбца с помощью
LAST_INSERT_ID(expr)
.
Также обратите внимание, что значение функции SQL
LAST_INSERT_ID()
всегда содержит самое последнее сгенерированное
значение AUTO_INCREMENT
, и оно не будет сброшено между запросами
потому, что значение этой функции поддерживается сервером.
Значение поля AUTO_INCREMENT
, которое модифицировалось
предыдущим запросом. 0, если не имелось никакого предыдущего запроса на
подключении, или если запрос не модифицировал AUTO_INCREMENT
.
Нет.
mysql_kill()
int mysql_kill(MYSQL *mysql, unsigned long pid)
Просит, чтобы сервер уничтожил поток, определенный как pid
.
Ноль для успеха. Отличное от нуля, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_list_dbs()
MYSQL_RES *mysql_list_dbs(MYSQL *mysql, const char *wild)
Возвращает набор результатов, состоящий из имен баз данных на сервере,
которые соответствуют простому регулярному выражению, определенному
параметром wild
. Здесь wild
может содержать
групповые символы % или _, или может быть
NULL
, чтобы соответствовать всем базам данных. Вызов
mysql_list_dbs()
подобен выполнению запроса SHOW
databases [LIKE wild]
.
Вы должны освободить набор результатов с помощью
mysql_free_result()
.
Набор результатов MYSQL_RES
для успеха, NULL
,
если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_OUT_OF_MEMORY
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_list_fields()
MYSQL_RES *mysql_list_fields(MYSQL *mysql, const char *table,
const char *wild)
Возвращает набор результатов, состоящий из имен полей в данной таблице,
которые соответствуют простому регулярному выражению, определенному
параметром wild
. Здесь 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
CR_SERVER_LOST
CR_UNKNOWN_ERROR
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
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_list_tables()
MYSQL_RES *mysql_list_tables(MYSQL *mysql, const char *wild)
Возвращает набор результатов, состоящий из имен таблиц в текущей базе
данных, которые соответствуют простому регулярному выражению, определенному
параметром wild
. Здесь wild
может содержать
групповые символы % или _, или может быть
NULL
, чтобы соответствовать всем таблицам. Вызов
mysql_list_tables()
подобен выполнению запроса SHOW
tables [LIKE wild]
.
Вы должны освободить набор результатов с помощью
mysql_free_result()
.
Набор результатов MYSQL_RES
для успеха. NULL
,
если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_num_fields()
unsigned int mysql_num_fields(MYSQL_RES *result)
или
unsigned int mysql_num_fields(MYSQL *mysql)
Вторая форма не работает в MySQL Version 3.22.24 или выше. Чтобы
передавать параметр MYSQL*
, Вы должны использовать
unsigned int mysql_field_count(MYSQL *mysql)
.
Возвращает число столбцов в наборе результатов.
Обратите внимание, что Вы можете получать число столбцов из указателя
набора результатов или от дескриптора подключения. Вы используете дескриптор
подключения, если mysql_store_result()
или
mysql_use_result()
возвращает NULL
(и таким образом
Вы не имеете никакого указателя набора результата). В этом случае Вы можете
вызывать mysql_field_count()
чтобы определить, должен или нет
mysql_store_result()
произвести непустой результат. Это
позволяет программе пользователя выбрать соответствующее действие без того,
чтобы знать, был или нет запрос SELECT
(или
SELECT
-подобным). Пример, показанный ниже иллюстрирует, как это
может быть выполнено.
Целое число без знака, представляющее число полей в наборе результатов.
Нет.
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_errno(&mysql)
на
проверку mysql_field_count(&mysql)
=0.
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_options()
int mysql_options(MYSQL *mysql, enum mysql_option option,
const char *arg)
Может использоваться, чтобы установить дополнительные параметры связи и действует на поведение подключения. Эта функция может быть вызвана несколько раз, чтобы установить несколько параметров.
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 | Не используется | Использовать именованные каналы, чтобы соединиться с сервером MySQL под NT. |
MYSQL_INIT_COMMAND | char * | Команда, чтобы выполнить при соединении с сервером MySQL. Будет автоматически выполнена при повторном соединении. |
MYSQL_READ_DEFAULT_FILE | char * |
Читать параметры из указанного файла опций вместо my.cnf. |
MYSQL_READ_DEFAULT_GROUP | char *
| Читать параметры из именованной группы из файла опций
my.cnf или файла, определенного в
MYSQL_READ_DEFAULT_FILE . |
Обратите внимание, что группа client
всегда читается, если Вы
используете MYSQL_READ_DEFAULT_FILE
или
MYSQL_READ_DEFAULT_GROUP
.
Определенная группа в файле опций может содержать следующие параметры:
connect_timeout | Время ожидания в секундах. В Linux это время ожидания также используется для ожидания первого ответа. |
compress | Использовать сжатый протокол клиент-сервер. |
database | Соединиться с этой базой данных, если никакая база данных не была определена в команде подключения. |
debug | Опции для отладки. |
host | Имя сервера по умолчанию. |
init-command | Команда, чтобы выполнить при соединении с сервером MySQL. Будет автоматически заново выполнена при повторном соединении, если связь прервалась. |
interactive-timeout | Аналогично указанию опции
CLIENT_INTERACTIVE в mysql_real_connect() .
Подробности в разделе "2.3.171 mysql_real_connect() ". |
password | Пароль по умолчанию. |
pipe | Использовать именованные каналы, чтобы соединиться с сервером MySQL, работая под NT. |
port | Порт по умолчанию. |
return-found-rows | Сообщить
mysql_info() о том, что нужно возвратить найденные строки вместо
модифицируемых строк при использовании UPDATE . |
socket | Сокет по умолчанию. |
user | Пользователь по умолчанию. |
Обратите внимание, что timeout
был заменен на
connect_timeout
, но timeout
будет все еще работать
некоторое время для совместимости.
Ноль для успеха. Отличное от нуля, если Вы использовали неизвестную опцию.
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)); }
Вышеупомянутое запрашивает использовать сжатый протокол клиент-сервер и
читать дополнительные параметры из группы odbc
в файле опций
my.cnf
.
mysql_ping()
int mysql_ping(MYSQL *mysql)
Проверяет работает или нет подключение. В случае неработоспособности будет предпринято автоматическое переподключение.
Эта функция может использоваться клиентом, который долго простаивает, чтобы определить, закрыл или нет сервер подключение, и повторно соединиться с ним в случае необходимости.
Ноль, если подключение работает. Отличное от нуля, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_UNKNOWN_ERROR
mysql_query()
int mysql_query(MYSQL *mysql, const char *query)
Выполняет запрос SQL, указанный строкой с нулевым символом в конце. Запрос
должен состоять из одиночной инструкции SQL. Вы не должны добавлять точку с
запятой (;) или \g
для завершения запроса.
mysql_query()
не может использоваться для запросов, которые
содержат двоичные данные, взамен Вы должны использовать
mysql_real_query()
. Двоичные данные могут содержать в себе
символ \0, который mysql_query()
интерпретирует как
конец строки запроса.
Если Вы хотите знать, возвратил ли запрос набор результатов или нет, Вы
можете использовать mysql_field_count()
, чтобы проверить это.
Подробности в разделе "2.3.85 mysql_field_count()
".
Ноль, если запрос был успешен. Отличное от нуля, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
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)
mysql_real_connect()
пытается установить подключение с
сервером MySQL, запущенным на машине host
.
mysql_real_connect()
должен завершиться успешно прежде, чем Вы
сможете выполнить любую из других функций API, за исключением
mysql_get_client_info()
.
Параметры определены следующим образом:
MYSQL
. Перед вызовом mysql_real_connect()
Вы должны
вызвать mysql_init()
, чтобы инициализировать структуру
MYSQL
. Вы можете изменять много параметров подключения через
вызов mysql_options()
. Подробности в
разделе "2.3.159 mysql_options()
".
host
может быть имя или адрес IP. Если это
NULL
или строка localhost
, выполняется подключение
к локальной системе. Если OS поддерживает сокеты (Unix) или именованные
каналы (Windows), именно они используются вместо стека протоколов TCP/IP,
чтобы соединиться с сервером.
user
содержит ID пользователя MySQL. Если
user
равен NULL
, предполагается текущий
пользователь. Под Unix это текущее (актуальное) имя входа в систему. Под
Windows ODBC имя пользователя должно быть определено явно.
passwd
содержит пароль для user
. Если
passwd
равен NULL
, только записи в таблице
user
, которые имеют пустое поле пароля, будут проверены на
соответствие. Это позволяет администратору базы данных устанавливать систему
привилегий MySQL таким способом, которым пользователи получают различные
привилегии в зависимости от того, определили или нет они пароль. ОБРАТИТЕ
ВНИМАНИЕ: Не пытайтесь шифровать пароль перед вызовом
mysql_real_connect()
: шифрование пароля обработано автоматически.
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
секунд) бездеятельности перед закрытием подключения. |
CLIENT_NO_SCHEMA | Не позволять синтаксис
db_name.tbl_name.col_name . Это сделано для ODBC. Это заставляет
синтаксический анализатор генерировать ошибку, если Вы используете тот
синтаксис, который является полезным для заманивания в ловушку ошибок в
некоторых программах ODBC. |
CLIENT_ODBC | Работает клиент ODBC. |
CLIENT_SSL | Использовать шифрованный протокол SSL. |
Дескриптор MYSQL*
, если подключение было успешно,
NULL
, если подключение было неудачно. Для успешного подключения,
значение возврата: такое же, как значение первого параметра, если Вы не
передаете NULL
для этого параметра.
CR_CONN_HOST_ERROR
CR_CONNECTION_ERROR
CR_IPSOCK_ERROR
CR_OUT_OF_MEMORY
CR_SOCKET_CREATE_ERROR
CR_UNKNOWN_HOST
CR_VERSION_ERROR
--old-protocol
.
CR_NAMEDPIPEOPEN_ERROR
CR_NAMEDPIPEWAIT_ERROR
CR_NAMEDPIPESETSTATE_ERROR
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 будет
читать группы [client]
и your_prog_name
в файле
my.cnf
, что гарантирует, что Ваша программа будет работать, даже
если кто-то установил MySQL некоторым ненормативным способом.
Обратите внимание, что на подключение mysql_real_connect()
устанавливает флажок reconnect
(часть структуры MYSQL) в
значение 1
. Этот флажок указывает, что когда запрос не может
выполниться из-за потерянного подключения, надо попробовать повторно
соединиться с сервером перед отказом.
mysql_real_escape_string()
unsigned int mysql_real_escape_string(MYSQL *mysql, char *to,
const char *from,
unsigned int length)
Эта функция используется, чтобы создать допустимую строку, которую Вы можете использовать в инструкции SQL.
Строка в from
бужет закодирована до экранированной строки
SQL, принимая во внимание текущий (актуальный) набор символов подключения.
Результат будет помещен в to
и завершающий байт пустого
указателя допишется автоматически. Символы NUL
(ASCII 0),
\n, \r, \, ',
", а также Control-Z, будуь экранированы.
Строка, указанная в from
должна быть length
байтов длины. Вы должны распределить буфер по крайней мере
length*2+1
байт. В худшем случае каждый символ должен быть
закодирован как использование двух байтов, и Вы нуждаетесь в участке памяти
для завершающего байта пустого указателя. Когда
mysql_escape_string()
завершится, в to
будет
строка с нулевым байтом в конце. Значение возврата: длина закодированной
строки, не включая символ завершения.
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()
,
но возвращает указатель на завершающий символ первого параметра.
Длина значения, помещенного в to
, не включая
нулевой символ завершения.
Нет.
mysql_real_query()
int mysql_real_query(MYSQL *mysql, const char *query,
unsigned int length)
Выполняет запрос SQL, указанный в query
, который должен быть
строкой длиной в length
байт. Запрос должен состоять из
одиночной инструкции SQL. Вы не должны добавлять точку с запятой
(`;') или \g
для завершения запроса.
Вы должны использовать mysql_real_query()
вместо
mysql_query()
для запросов, которые содержат двоичные данные,
потому, что двоичные данные могут сами содержать символ \0.
Кроме того, mysql_real_query()
быстрее, чем
mysql_query()
потому, что не вызывает strlen()
.
Если Вы хотите знать, возвратил ли запрос набор результатов или нет, Вы
можете использовать mysql_field_count()
, чтобы проверить это.
Подробности в разделе "2.3.85 mysql_field_count()
".
Ноль, если запрос был успешным. Отличное от нуля, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_reload()
int mysql_reload(MYSQL *mysql)
Просит, чтобы сервер MySQL перезагрузил таблицы предоставления привилегий. Пользователь должен иметь привилегию reload.
Ноль для успеха. Отличное от нуля, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_row_seek()
MYSQL_ROW_OFFSET mysql_row_seek(MYSQL_RES *result,
MYSQL_ROW_OFFSET offset)
Устанавливает курсор строки на произвольную строку в наборе результатов
запросов. Это требует, чтобы структура набора результата содержала весь
результат запроса, так что mysql_row_seek()
может использоваться
в конъюнкции только с mysql_store_result()
, но не с
mysql_use_result()
.
Смещение должно быть значением, возвращенным из
mysql_row_tell()
для mysql_row_seek()
. Это значение
не просто номер строки, если Вы хотите перейти к строке внутри набора
результатов, используйте mysql_data_seek()
.
Предыдущее значение курсора строки. Это значение может быть передано
последующему обращению к mysql_row_seek()
.
Нет.
mysql_row_tell()
MYSQL_ROW_OFFSET mysql_row_tell(MYSQL_RES *result)
Возвращает текущую (актуальную) позицию курсора строки для последнего
вызова mysql_fetch_row()
. Это значение может использоваться как
параметр для mysql_row_seek()
.
Вы должны использовать mysql_row_tell()
только после
mysql_store_result()
, но не после
mysql_use_result()
.
Текущее (актуальное) смещение курсора строки.
Нет.
mysql_select_db()
int mysql_select_db(MYSQL *mysql, const char *db)
Заставляет базу данных, определенную через db
, стать заданной
по умолчанию базой данных на подключении, определенном в mysql
.
В последующих запросах эта база данных будет значением по умолчанию для
ссылок на таблицы, которые не включают явный спецификатор базы данных.
mysql_select_db()
терпит неудачу, если связанный пользователь
не имеет прав доступа, чтобы использовать базу данных.
Ноль для успеха. Отличное от нуля, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_shutdown()
int mysql_shutdown(MYSQL *mysql)
Выключает сервер. Связанный пользователь должен иметь привилегии закрытия системы (shutdown).
Ноль для успеха. Отличное от нуля, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_stat()
char *mysql_stat(MYSQL *mysql)
Возвращает символьную строку, содержащую информацию, подобную
обеспечиваемой командой mysqladmin status
. Это включает
uptime в секундах, число работающих потоков, количество запросов,
перезагрузок и открытых таблиц.
Символьная строка, описывающая состояние сервера. NULL
,
если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_store_result()
MYSQL_RES *mysql_store_result(MYSQL *mysql)
Вы должны вызвать mysql_store_result()
или
mysql_use_result()
для каждого запроса, который успешно получает
данные (SELECT
, SHOW
, DESCRIBE
,
EXPLAIN
).
Вы не должны вызывать mysql_store_result()
или
mysql_use_result()
для других запросов, но это не причинит
вреда, если Вы вызываете mysql_store_result()
во всех случаях.
Правда, и эффективности не прибавится... Вы могли обнаружить, что запрос не
имеет набора результатов, проверяя равенство нулю возврата
mysql_store_result()
.
Если Вы хотите знать, возвратил ли запрос набор результатов или нет, Вы
можете использовать mysql_field_count()
, чтобы проверить это.
Подробности в разделе "2.3.85 mysql_field_count()
".
mysql_store_result()
читает весь результат запроса,
распределяет структуру MYSQL_RES
и помещает
результат в эту структуру.
mysql_store_results()
вернет пустой указатель, если запрос не
возвращал набор результатов вообще (если запрос был, например, инструкцией
INSERT
).
mysql_store_results()
также возвращает пустой указатель, если
чтение набора результатов потерпело неудачу. Вы можете проверить, получили
ли Вы ошибку, проверяя возвращает ли mysql_error()
пустой
указатель. Если mysql_errno()
<> 0, или если
mysql_field_count()
<> 0, значит, ошибочка.
Пустой набор результатов будет возвращен, если не имеется никаких возвращенных строк. Пустой набор результатов отличается от пустого указателя как значение возврата.
Как только Вы вызвали mysql_store_result()
и получили
результат, который не пустой указатель, Вы можете вызывать
mysql_num_rows()
, чтобы выяснить, сколько строк
находится в наборе результатов.
Вы можете вызвать mysql_fetch_row()
, чтобы выбрать строки из
набора результатов, или mysql_row_seek()
и
mysql_row_tell()
, чтобы получить или установить текущую позицию
строки внутри набора результатов.
Вы должны вызвать mysql_free_result()
как только Вы закончите
работу с данным набором результатов.
Структура MYSQL_RES
с результатами. NULL
,
если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_OUT_OF_MEMORY
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
mysql_thread_id()
unsigned long mysql_thread_id(MYSQL *mysql)
Возвращает ID потока текущего (актуального) подключения. Это значение
может использоваться как параметр для mysql_kill()
, чтобы
уничтожить этот поток.
Если подключение потеряно, и Вы повторно соединяетесь через
mysql_ping()
, ID потока изменится. Это означает, что Вы не
должны получить ID потока и хранить его. Надо получать ID по мере надобности.
ID потока текущего (актуального) подключения.
Нет.
mysql_use_result()
MYSQL_RES *mysql_use_result(MYSQL *mysql)
Вы должны вызвать mysql_store_result()
или
mysql_use_result()
для каждого запроса, который успешно получает
данные (SELECT
, SHOW
, DESCRIBE
,
EXPLAIN
).
mysql_use_result()
инициализирует поиск набора результата, но
фактически не читает набор результатов подобно
mysql_store_result()
. Вместо этого, каждая строка должна быть
получена индивидуально, делая обращения к mysql_fetch_row()
. Это
читает результат запроса непосредственно с сервера без того, чтобы сохранить
его во временной таблице или локальном буфере, что несколько быстрее и
использует намного меньше памяти, чем mysql_store_result()
.
Пользователь распределит память только для текущей (актуальной) строки и
буфера связей, который может сам вырасти до max_allowed_packet
.
С другой стороны, Вы не должны использовать
mysql_use_result()
если Вы делаете много обработки для каждой
строки на стороне пользователя, или если вывод послан экрану, на котором
пользователь может напечатать ^S
(приостановить показ данных).
Это свяжет сервер и не даст другим потокам модифицировать любые таблицы, из
которых выбираются данные.
При использовании mysql_use_result()
Вы должны выполнять
mysql_fetch_row()
до тех пор, пока значение не вернется значение
NULL
, иначе невыбранные строки будут возвращены как часть набора
результатов для Вашего следующего запроса. C API выдает ошибку
"Commands out of sync; You can't run this command now
", если Вы
забываете про это!
Вы не можете использовать mysql_data_seek()
,
mysql_row_seek()
, mysql_row_tell()
,
mysql_num_rows()
или mysql_affected_rows()
с
результатом, возвращенным из mysql_use_result()
, и при этом Вы
не можете выдавать другие запросы, пока не закончится
mysql_use_result()
. Однако, после того, как Вы выбрали все
строки, mysql_num_rows()
точно возвратит число выбранных строк.
Вы должны вызвать mysql_free_result()
как только Вы закончили
с этим набором результатов.
Структура MYSQL_RES
. NULL
, если произошла ошибка.
CR_COMMANDS_OUT_OF_SYNC
CR_OUT_OF_MEMORY
CR_SERVER_GONE_ERROR
CR_SERVER_LOST
CR_UNKNOWN_ERROR
Вы должны использовать следующие функции, когда Вы хотите создавать поточного клиента. Подробности в разделе "2.8 Как делать поточного клиента".
my_init()
Эта функция должна быть вызвана однажды в программе перед вызовом любой
функции MySQL. Это инициализирует некоторые глобальные переменные. Если Вы
используете поточно-безопасную библиотеку клиентов, это также вызовет для
этого потока функцию mysql_thread_init()
.
Это автоматически вызвано функциями mysql_init()
,
mysql_server_init()
и mysql_connect()
.
Нет.
mysql_thread_init()
Эту функцию должен запрашивать каждый созданный поток, чтобы инициализировать специфические переменные.
Это автоматически вызвано my_init()
и
mysql_connect()
.
Нет.
mysql_thread_end()
Эта функция должна быть вызвана перед вызовом pthread_exit()
,
чтобы освободить память, распределенную в mysql_thread_init()
.
Обратите внимание, что эта функция не вызывается автоматически библиотекой. Это должно быть вызвано явно, чтобы избежать утечки памяти.
Нет.
Вы должны использовать следующие функции, если Вы хотите, чтобы в Вашей прикладной программе была функциональность встроенного сервера MySQL. Подробности в разделе "2.9 libmysqld, библиотека встроенного сервера MySQL ".
Если программа скомпонована с -lmysqlclient
вместо
-lmysqld
, эти функции не делают ничего. Это делает возможным
выбирать между использованием встроенного и автономного сервера без изменения
какого-либо кода.
mysql_server_init()
void mysql_server_init(int argc, const char **argv,
const char **groups)
Эта функция должна быть вызвана в программе перед вызовом
любой другой функции MySQL. Она запускает сервер и инициализирует все
подсистемы (mysys
, InnoDB и т.д.), используемые сервером. Если
эта функция не была вызвана, программа разрушится.
Параметры argc
и argv
аналогичны параметрам
main()
. Первый элемент argv
игнорируется (он обычно
содержит имя программы). Для удобства argc
может быть
0
, если не имеется никаких параметров командной строки сервера.
Завершаемый символом NULL
список строк в groups
задает то, какие группы в файле опций будут активны. Для удобства
groups
может быть NULL
, тогда будет активна группа
[server]
.
#include <mysql.h> #include <stdlib.h> static char *server_args[] = { "this_program", /* this string is not used */ "--datadir=.", "--set-variable=key_buffer_size=32M" }; static char *server_groups[] = { "server", "this_program_SERVER", (char *)NULL }; int main(void) { mysql_server_init(sizeof(server_args) / sizeof(char *), server_args, server_groups); /* Use any MySQL API functions here */ mysql_server_end(); return EXIT_SUCCESS; }
Нет.
mysql_server_end()
Эта функция должна быть вызвана в программе, в конце. Она завершает сервер.
Нет.
mysql_query()
вызов mysql_store_result()
иногда возвращает NULL?
Когда это случается, это означает, что одно из следующего произошло:
malloc()
(например, если набор результатов
был слишком большой).
INSERT
, UPDATE
или DELETE
).Вы можете всегда проверить, должна или нет инструкция произвести непустой
результат, вызывая mysql_field_count()
. Если
mysql_field_count()
вернет ноль, результат пуст, и последний
запрос был инструкцией, которая не возвращает значения (например,
INSERT
или DELETE
). Если
mysql_field_count()
вернет не ноль, инструкция должна была
произвести не пустой результат.
Вы можете проверить наличие ошибки вызовом mysql_error()
или
mysql_errno()
.
В дополнение к набору результатов, возвращенному запросом, Вы можете также получать следующую информацию:
mysql_affected_rows()
возвращает число строк, на которые
воздействует последний запрос при выполнении INSERT
,
UPDATE
или DELETE
. Исключительная ситуация:
DELETE
используется без предложения WHERE
, таблица
будет пересоздана пустой, что намного быстрее! В этом случае
mysql_affected_rows()
возвращает ноль для числа записей.
mysql_num_rows()
возвращает число строк в наборе
результатов. При использовании mysql_store_result()
mysql_num_rows()
может быть вызван, как только отработает
mysql_store_result()
. При использовании
mysql_use_result()
mysql_num_rows()
может быть
вызван только после того, как Вы выбрали все строки с помощью
mysql_fetch_row()
.
mysql_insert_id()
возвращает ID, сгенерированный последним
запросом, который вставил строку в таблицу с индексом
AUTO_INCREMENT
. Подробности в разделе "2.3.126
mysql_insert_id()
".
LOAD DATA INFILE ...
, INSERT INTO
... SELECT ...
, UPDATE
) возвращают дополнительную
информацию. Результат возвращен через mysql_info()
.
mysql_info()
вернет NULL
если не имеется
никакой дополнительной информации.Если Вы вставляете запись в таблицу, содержащую столбец, который имеет
атрибут AUTO_INCREMENT
, Вы можете получать последнее значение
ID вызовом mysql_insert_id()
.
Вы можете также получать ID, используя функцию
LAST_INSERT_ID()
в строке запроса, которую Вы передаете
mysql_query()
.
Вы можете проверять, используется ли индекс AUTO_INCREMENT
,
выполняя следующий код. Это также проверит, был ли запрос INSERT
с индексом AUTO_INCREMENT
:
if (mysql_error(&mysql)[0] == 0 && mysql_num_fields(result) == 0 && mysql_insert_id(&mysql) != 0) { used_id = mysql_insert_id(&mysql); }
Недавно сгенерированный ID хранится на сервере с привязкой к подключению.
Это не будет изменено другим пользователем. Это не будет даже изменено, если
Вы модифицируете другой столбец AUTO_INCREMENT
не со специальным
значением (то есть значением, которое не NULL
и не
0
).
Если Вы хотите использовать ID, который был сгенерирован для одной таблицы и вставлять его во вторую таблицу, Вы можете использовать инструкции SQL подобно этому:
INSERT INTO foo (auto,text) VALUES(NULL,'text'); # generate ID by inserting NULL INSERT INTO foo2 (id,text) VALUES(LAST_INSERT_ID(),'text'); # use ID in second table
При компоновке с C API следующие ошибки могут происходить на некоторых системах:
gcc -g -o client test.o -L/usr/local/lib/mysql -lmysqlclient -lsocket -lnsl Undefined first referenced symbol in file floor /usr/local/lib/mysql/libmysqlclient.a(password.o) ld: fatal: Symbol referencing errors. No output written to client
Если это случается на Вашей системе, Вы должны включить математическую
библиотеку, добавляя -lm
к концу строки для компоновки.
Если Вы компилируете MySQL клиентуру, которую вы написали самостоятельно
или получили от третьего лица, программы должны быть скомпонованы, используя
опцию -lmysqlclient -lz
. Вы также должны определить опцию
-L
, чтобы сообщить компоновщику, где найти библиотеку. Например,
если библиотека установлена в /usr/local/mysql/lib, используйте
-L/usr/local/mysql/lib -lmysqlclient -lz
на строке компоновки.
Для клиентуры, которая использует файлы заголовков MySQL, Вы должны
определить опцию -I
, когда Вы компилируете их (например,
-I/usr/local/mysql/include
), чтобы транслятор смог найти файлы.
Самая большая проблема состоит в том, что подпрограммы в net.c,
которые читают из сокетов, не безопасны для прерываний. Это было выполнено с
мыслью о том, что Вы могли бы иметь Вашу собственную функцию, которая может
разорвать длинное чтение на сервер. Если Вы устанавливаете программы
обработки прерывания для SIGPIPE
, обработка сокета должна
быть поточно-безопасной.
В старом двоичном коде библиотеки пользователей обычно не компилируются с опциями для поддержки поточной безопасности (код для Windows по умолчанию компилируются как поточно-безопасный). Более новые двоичные дистрибутивы имеют оба варианта библиотек.
Чтобы сделать поточный клиент, где Вы можете прерывать пользователя
из других потоков и устанавливать времена ожидания при обмене данными с
сервером MySQL, Вы должны использовать библиотеки -lmysys
,
-lstring
и -ldbug
, а также код
net_serv.o
, который использует сервер.
Если Вы не нуждаетесь в прерываниях или временах ожидания, Вы можете
только скомпилировать поточно-безопасную библиотеку пользователей
(mysqlclient_r)
и использовать ее. В этом случае Вы не должны
волноваться относительно объектного файла net_serv.o
или других
библиотек для MySQL.
При использовании поточного клиента, и если Вы хотите использовать времена
ожидания и прерывания, Вы можете использовать код из файла
thr_alarm.c. Если Вы используете подпрограммы из библиотеки
mysys
, Вы должны помнить, что нужно сначала вызвать
my_init()
! Подробности в разделе "2.4
Описание поточных функций C".
Все функции за исключением mysql_real_connect()
по умолчанию
безопасны для потоков. Следующие замечания описывают, как компилировать
безопасную библиотеку клиентов и использовать ее соответственно. Замечания
для mysql_real_connect()
фактически применимы и для
mysql_connect()
.
Чтобы сделать mysql_real_connect()
поточно-безопасной, Вы
должны перетранслировать библиотеку этой командой:
shell> ./configure --enable-thread-safe-client
Это создаст поточно-безопасную библиотеку libmysqlclient_r
.
Вы можете позволять двум потокам совместно использовать то же самое
подключение, пока Вы делаете следующее:
mysql_query()
и mysql_store_result()
другой поток
никогда не использует то же самое подключение.
mysql_store_result()
.
mysql_use_result
, Вы должны
гарантировать, что никакой другой поток не спрашивает что-нибудь относительно
того же самого подключения, пока набор результатов не закрыт.
mysql_query()
и mysql_store_result()
. Когда
mysql_store_result()
готов, блокировка может быть снята, и
другие потоки смогут сделать запрос с того же самого подключения.
pthread_mutex_lock()
и pthread_mutex_unlock()
,
чтобы устанавливать и снимать блокировку mutex.Вы должны знать следующее, если Вы имеете поток, который вызывает функции MySQL, но не создал подключение к базе данных MySQL:
Когда Вы вызываете mysql_init()
или
mysql_connect()
, MySQL создаст специфические переменные для
потока, которые используются библиотекой отладки.
Если Вы имеете в потоке вызов функции MySQL прежде, чем поток вызвал
mysql_init()
или mysql_connect()
, поток не будет
иметь необходимых специфических переменных, и Вы, вероятно, свалите программу
в дамп рано или поздно (скорее рано, чем поздно). Чтобы работать спокойно,
надо предпринять следующее:
my_init()
в начале Вашей программы, если она
вызывает любую другую функцию MySQL, перед вызовом
mysql_real_connect()
.
mysql_thread_init()
в драйвере потока перед вызовом
любой функции MySQL.
mysql_thread_end()
перед вызовом
pthread_exit()
. Это освободит память, используемую
специфическими переменными MySQL.Вы можете получать некоторые ошибки из-за неопределенных символов при
компоновке Вашего клиента с mysqlclient_r
. В большинстве случаев
это потому, что Вы не включили библиотеки потоков в строку компоновки.
Библиотека встроенного сервера MySQL делает возможным выполнить полнофункциональный сервер MySQL внутри прикладной программы. Основные выгоды: увеличивается быстродействие и упрощается управление.
libmysqld
В настоящее время, все библиотеки должны быть явно перечислены при
компоновке с -lmysqld
. В будущем mysql_config
--libmysqld-libs
назовет библиотеки, чтобы делать этот проще. Также,
все библиотеки будут, вероятно, включены в libmysqld, чтобы упростить этот
процесс еще сильнее.
Правильные флажки для компиляции и компоновки поточной программы должны использоваться, даже если Вы непосредственно не вызываете никакие функции потоков в Вашем коде.
Эта программа должна работать без любых изменений на Linux или FreeBSD системе. Для других операционных систем будут необходимы маленькие изменения. Этот пример разработан, чтобы дать общее представление о том, как все делать.
Чтобы испытать пример, создайте каталог example в том же самом уровне, где лежит каталог с исходными текстами mysql-4.0. Сохраните в нем файлы example.c и GNUmakefile, после чего выполните GNU make из каталога example.
Файл example.c:
/* * A simple example client, using the embedded MySQL server library */ #include <mysql.h> #include <stdarg.h> #include <stdio.h> #include <stdlib.h> enum on_error {E_okay, E_warn, E_fail}; static void die(MYSQL *db, char *fmt, ...); MYSQL *db_connect(const char *dbname); void db_disconnect(MYSQL *db); void db_do_query(MYSQL *db, const char *query, enum on_error on_error); const char *server_groups[] = { "test_client_SERVER", "server", NULL }; int main(int argc, char **argv) { MYSQL *one, *two; /* This must be called before any other mysql functions. * * You can use mysql_server_init(0, NULL, NULL), and it will * initialize the server using groups = { "server", NULL }. * * In your $HOME/.my.cnf file, you probably want to put: [test_client_SERVER] language = /path/to/source/of/mysql/sql/share/english * You could, of course, modify argc and argv before passing * them to this function. Or you could create new ones in any * way you like. But all of the arguments in argv (except for * argv[0], which is the program name) should be valid options * for the MySQL server. * * If you link this client against the normal mysqlclient * library, this function is just a stub that does nothing. */ mysql_server_init(argc, argv, server_groups); one = db_connect("test"); two = db_connect(NULL); db_do_query(one, "show table status", E_fail); db_do_query(two, "show databases", E_fail); mysql_close(two); mysql_close(one); /* This must be called after all other mysql functions */ mysql_server_end(); exit(EXIT_SUCCESS); } void die(MYSQL *db, char *fmt, ...) { va_list ap; va_start(ap, fmt); vfprintf(stderr, fmt, ap); va_end(ap); putc('\n', stderr); if (db) db_disconnect(db); exit(EXIT_FAILURE); } MYSQL * db_connect(const char *dbname) { MYSQL *db = mysql_init(NULL); if (!db) die(db, "mysql_init failed: no memory"); mysql_options(db, MYSQL_READ_DEFAULT_GROUP, "simple"); if (!mysql_real_connect(db, NULL, NULL, NULL, dbname, 0, NULL, 0)) die(db, "mysql_real_connect failed: %s", mysql_error(db)); return db; } void db_disconnect(MYSQL *db) { mysql_close(db); } /* * show_query: this code is snagged from mysql.cc; this function * is intended to be used internally to db_do_query() */ static char * show_query(MYSQL *db) { MYSQL_RES *res; MYSQL_FIELD *field; MYSQL_ROW row; char sep[256], *psep = sep; char *is_num = 0; char *err = 0; unsigned int length = 1; /* initial "|" */ unsigned int off; if (!(res = mysql_store_result(db))) return mysql_error(db); if (!(is_num = malloc(mysql_num_fields(res)))) { err = "Не хватило памяти"; goto err; } /* set up */ *psep++ = '+'; while ((field = mysql_fetch_field(res))) { unsigned int len = strlen(field->name); if (len < field->max_length) len = field->max_length; if (len < 2 && !IS_NOT_NULL(field->flags)) len = 2; /* \N */ field->max_length = len + 1; /* bending the API... */ len += 2; length += len + 1; /* " " before, " |" after */ if (length >= 255) { err = "row too long"; goto err; } memset(psep, '-', len); psep += len; *psep++ = '+'; *psep = '\0'; } /* column headings */ puts(sep); mysql_field_seek(res,0); fputc('|',stdout); for (off=0; (field = mysql_fetch_field(res)) ; off++) { printf(" %-*s|",field->max_length, field->name); is_num[off]= IS_NUM(field->type); } fputc('\n',stdout); puts(sep); /* rows */ while ((row = mysql_fetch_row(res))) { (void) fputs("|",stdout); mysql_field_seek(res,0); for (off=0; off < mysql_num_fields(res); off++) { field = mysql_fetch_field(res); printf(is_num[off] ? "%*s |" : " %-*s|", field->max_length, row[off] ? (char*) row[off] : "NULL"); } (void) fputc('\n',stdout); } puts(sep); err: if (is_num) free(is_num); mysql_free_result(res); return err; } void db_do_query(MYSQL *db, const char *query, enum on_error on_error) { char *err = 0; if (mysql_query(db, query) != 0) goto err; if (mysql_field_count(db) > 0) { if ((err = show_query(db))) goto err; } else if (mysql_affected_rows(db)) printf("Affected rows: %lld [%s]\n", mysql_affected_rows(db),query); return; err: switch (on_error) { case E_okay: break; case E_warn: fprintf(stderr, "db_do_query failed: %s [%s]\n", err ? err : mysql_error(db), query); break; case E_fail: die(db, "db_do_query failed: %s [%s]", err ? err : mysql_error(db), query); break; } }
Файл GNUmakefile:
# Set this to your mysql source directory m := ../mysql-4.0 CC := cc CPPFLAGS := -I$m/include -D_THREAD_SAFE -D_REENTRANT CFLAGS := -g -W -Wall LDFLAGS := -static LDLIBS = $(embed_libs) -lz -lm -lcrypt ifneq (,$(shell grep FreeBSD /COPYRIGHT 2>/dev/null)) # FreeBSD LDFLAGS += -pthread else # Assume Linux LDLIBS += -lpthread endif # Standard libraries embed_libs := \ $m/libmysqld/.libs/libmysqld.a \ $m/isam/libnisam.a \ $m/myisam/libmyisam.a \ $m/heap/libheap.a \ $m/merge/libmerge.a \ $m/myisammrg/libmyisammrg.a # Optionally-built libraries ifneq (,$(shell test -r $m/innobase/usr/libusr.a && echo "yes")) embed_libs += \ $m/innobase/usr/libusr.a \ $m/innobase/odbc/libodbc.a \ $m/innobase/srv/libsrv.a \ $m/innobase/que/libque.a \ $m/innobase/srv/libsrv.a \ $m/innobase/dict/libdict.a \ $m/innobase/ibuf/libibuf.a \ $m/innobase/row/librow.a \ $m/innobase/pars/libpars.a \ $m/innobase/btr/libbtr.a \ $m/innobase/trx/libtrx.a \ $m/innobase/read/libread.a \ $m/innobase/usr/libusr.a \ $m/innobase/buf/libbuf.a \ $m/innobase/ibuf/libibuf.a \ $m/innobase/eval/libeval.a \ $m/innobase/log/liblog.a \ $m/innobase/fsp/libfsp.a \ $m/innobase/fut/libfut.a \ $m/innobase/fil/libfil.a \ $m/innobase/lock/liblock.a \ $m/innobase/mtr/libmtr.a \ $m/innobase/page/libpage.a \ $m/innobase/rem/librem.a \ $m/innobase/thr/libthr.a \ $m/innobase/com/libcom.a \ $m/innobase/sync/libsync.a \ $m/innobase/data/libdata.a \ $m/innobase/mach/libmach.a \ $m/innobase/ha/libha.a \ $m/innobase/dyn/libdyn.a \ $m/innobase/mem/libmem.a \ $m/innobase/sync/libsync.a \ $m/innobase/ut/libut.a \ $m/innobase/os/libos.a \ $m/innobase/ut/libut.a endif ifneq (,$(shell test -r $m/bdb/build_unix/libdb.a && echo "yes")) embed_libs += $m/bdb/build_unix/libdb.a endif # Support libraries embed_libs += \ $m/mysys/libmysys.a \ $m/strings/libmystrings.a \ $m/dbug/libdbug.a \ $m/regex/libregex.a # Optionally built support libraries ifneq (,$(shell test -r $m/readline/libreadline.a && echo "yes")) embed_libs += $m/readline/libreadline.a endif # This works for simple one-file test programs sources := $(wildcard *.c) objects := $(patsubst %c,%o,$(sources)) targets := $(basename $(sources)) all: $(targets) clean: rm -f $(targets) $(objects) *.core
Исходный текст MySQL охвачен GNU GPL. Один результат этого: любая
программа, которая компонуется с libmysqld
и с исходным текстом
MySQL, должна быть выпущена как свободное программное обеспечение (согласно
лицензии, совместимой с GPL).
Авторы поощряют каждого поддерживать свободное программное обеспечение, выпуская код под GPL или совместимой лицензией. Для тех, кто не способен делать это, есть другой вариант: они должны приобрести MySQL у MySQL AB согласно более свободной лицензии.
Закладки на сайте Проследить за страницей |
Created 1996-2024 by Maxim Chirkov Добавить, Поддержать, Вебмастеру |