8.4.3.171 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)
8.4.3.172 Описание
Функция mysql_real_connect()
пытается установить соединение с сервером баз
данных MySQL, работающим на хосте host
. До успешного завершения функции
mysql_real_connect()
нельзя выполнять никакие другие функции интерфейса, за
исключением mysql_get_client_info()
.
Параметры этой функции указываются следующим образом:
-
Первым параметром должен быть указатель существующей структуры
MYSQL
.
До вызова функции mysql_real_connect
() необходимо вызвать функцию
mysql_init()
для инициализации данной структуры MYSQL
. Вызов функции
mysql_options()
позволяет изменить многие опции данного соединения.
See section 8.4.3.159 mysql_options()
.
-
host
может быть как именем хоста, так и IP-адресом. Если host равен
NULL
или строке "localhost"
, то подразумевается соединение с локальным
хостом. Если операционная система поддерживает сокеты (Unix) или
именованные каналы (Windows), то они используются вместо протокола
TCP/IP для соединения с сервером.
-
Параметр user содержит имя данного пользователя MySQL. Если параметр
user равен
NULL
, то подразумевается текущий пользователь. Под
операционной системой Unix, это будет текущее имя входа в систему. Под
Windows ODBC имя пользователя должно быть указано явным образом. См.
раздел See section 8.3.2 Как заполнять различные поля в Администраторе 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. Настраивает mysqld для большей совместимости с ODBC.
|
CLIENT_SSL | Использовать SSL (протокол шифрования).
|
8.4.3.173 Возвращаемые значения
Дескриптор соединения MYSQL*
, если соединение было успешным, NULL
если
соединение было неудачным. Для успешного соединения возвращаемая величина
та же, что и величина первого параметра.
8.4.3.174 Ошибки
CR_CONN_HOST_ERROR
-
Не удалось соединиться с сервером MySQL.
CR_CONNECTION_ERROR
-
Не удалось соединиться с локальным сервером MySQL.
CR_IPSOCK_ERROR
-
Не удалось создать IP-сокет.
CR_OUT_OF_MEMORY
-
Недостаток памяти.
CR_SOCKET_CREATE_ERROR
-
Не удалось создать Unix сокет.
CR_UNKNOWN_HOST
-
Не удалось найти IP-адрес для данного имени хоста.
CR_VERSION_ERROR
-
Несоответствие протокола, что явилось результатом попытки соединения с
сервером с клиентской библиотекой, использующей иную версию протокола. Это
может произойти при использовании очень старой клиентской библиотеки для
подключения к новому серверу, при запуске которого не была установлена
опция
--old-protocol
.
CR_NAMEDPIPEOPEN_ERROR
-
Не удалось создать именованный канал на Windows.
CR_NAMEDPIPEWAIT_ERROR
-
Не удалось дождаться именованного канала на Windows.
CR_NAMEDPIPESETSTATE_ERROR
-
Не удалось получить обработчик канала на Windows.
CR_SERVER_LOST
-
Если connect_timeout > 0 и требовалось больше, чем connect_timeout секунд
для соединения с сервером или если сервер прекратил работу во время
выполнения init-command.
8.4.3.175 Пример
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. Этот флаг показывает, что в случае, если запрос не может быть
выполнен из-за потери соединения, то следует попытаться восстановить
соединение прежде, чем отказаться от него.