Spec-Zone.ru › MySQL Connectors 1.0

5.4.54 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 long client_flag)

Описание

mysql_real_connect() пытается установить соединение с сервером MySQL, работающим на host. Программы-клиенты должны успешно подключиться к серверу перед выполнением любых других функций API, требующих валидного MYSQL обработчика соединения.

Укажите аргументы следующим образом:

  • Для первого аргумента укажите адрес существующей MYSQL структуры. Перед вызовом mysql_real_connect() вызовите mysql_init() для инициализации MYSQL структуры. Вы можете изменить множество параметров соединения с помощью вызова mysql_options(). См. Раздел 5.4.50, «mysql_options()».

  • Значение host может быть именем хоста или IP-адресом. Клиент пытается подключиться следующим образом:

    • Если host равно NULL или строке "localhost", предполагается подключение к локальному хосту:

      • В Windows клиент подключается с использованием общего сегмента памяти, если на сервере включены соединения с общей памятью.

      • В Unix клиент подключается с использованием файла сокета Unix. Аргумент unix_socket или переменная окружения MYSQL_UNIX_PORT могут использоваться для указания имени сокета.

    • В Windows, если host равно ".", или TCP/IP не включен и не указан или хост пуст, клиент подключается с использованием именованной трубы, если на сервере включены соединения с именованными трубами. Если соединения с именованными трубами не включены, произойдет ошибка.

    • В противном случае используется TCP/IP.

    Вы также можете повлиять на тип соединения с помощью опций MYSQL_OPT_PROTOCOL или MYSQL_OPT_NAMED_PIPE для mysql_options(). Тип соединения должен поддерживаться сервером.

  • Аргумент user содержит идентификатор пользователя MySQL. Если user равно NULL или пустой строке "", предполагается текущий пользователь. В Unix это текущее имя входа. В Windows ODBC текущее имя пользователя должно быть указано явно. См. раздел Connector/ODBC.

  • Аргумент passwd содержит пароль для user. Если passwd равно NULL, проверяются только записи в таблице user для пользователя, у которого поле пароля пустое. Это позволяет администратору базы данных настроить систему привилегий MySQL таким образом, чтобы пользователи получали разные привилегии в зависимости от того, указали ли они пароль.

    Примечание

    Не пытайтесь зашифровать пароль перед вызовом mysql_real_connect(); шифрование пароля обрабатывается автоматически API клиента.

  • Аргументы user и passwd используют кодировку символов, настроенную для объекта MYSQL. По умолчанию это latin1, но может быть изменено с помощью вызова mysql_options(mysql, MYSQL_SET_CHARSET_NAME, "charset_name") до подключения.

  • db - имя базы данных. Если db не равно NULL, соединение устанавливает базу данных по умолчанию на это значение.

  • Если port не равно 0, это значение используется в качестве номера порта для TCP/IP-соединения. Обратите внимание, что аргумент host определяет тип соединения.

  • Если unix_socket не равно NULL, строка указывает сокет или именованную трубу для использования. Обратите внимание, что аргумент host определяет тип соединения.

  • Значение client_flag обычно равно 0, но может быть установлено в комбинацию следующих флагов для включения определенных функций:

    • CAN_HANDLE_EXPIRED_PASSWORDS: Клиент может обрабатывать истекшие пароли. Для получения дополнительной информации см.

    • CLIENT_COMPRESS: Использовать сжатие в протоколе клиент-сервер.

    • CLIENT_FOUND_ROWS: Возвращает количество найденных (совпавших) строк, а не количество изменённых строк.

    • CLIENT_IGNORE_SIGPIPE: Предотвращает установку обработчика сигнала SIGPIPE библиотекой клиента. Это может быть использовано для предотвращения конфликтов с обработчиком, уже установленным приложением.

    • CLIENT_IGNORE_SPACE: Разрешить пробелы после имён функций. Делает все имена функций зарезервированными словами.

    • CLIENT_INTERACTIVE: Разрешить секунд бездействия (вместо секунд) перед закрытием соединения. Переменная сессии клиента устанавливается в значение переменной сессии.

    • CLIENT_LOCAL_FILES: Включить обработку.

    • CLIENT_MULTI_RESULTS: Сообщает серверу, что клиент может обрабатывать несколько наборов результатов из нескольких операторов или хранимых процедур. Этот флаг автоматически включается, если включен CLIENT_MULTI_STATEMENTS. См. примечание после этой таблицы для получения дополнительной информации об этом флаге.

    • CLIENT_MULTI_STATEMENTS: Сообщает серверу, что клиент может отправлять несколько операторов в одной строке (разделенных ; символами). Если этот флаг не установлен, выполнение нескольких операторов отключено. См. примечание после этой таблицы для получения дополнительной информации об этом флаге.

    • CLIENT_NO_SCHEMA: Не разрешать db_name.tbl_name.col_name синтаксис. Это для ODBC. Это заставляет парсер генерировать ошибку, если вы используете этот синтаксис, что полезно для отслеживания ошибок в некоторых программах ODBC.

    • CLIENT_ODBC: Не используется.

    • CLIENT_SSL: Использовать SSL (зашифрованный протокол). Не устанавливайте этот параметр в программе-приложении; он устанавливается внутри библиотеки клиента. Вместо этого используйте mysql_options() или mysql_ssl_set() перед вызовом mysql_real_connect().

    • CLIENT_REMEMBER_OPTIONS: Запоминать параметры, указанные вызовами mysql_options(). Без этого параметра, если mysql_real_connect() завершается неудачей, необходимо повторить вызовы mysql_options() перед повторной попыткой подключения. С этим параметром вызовы mysql_options() повторять не нужно.

Если ваша программа использует операторы для выполнения хранимых процедур, флаг CLIENT_MULTI_RESULTS должен быть включён. Это связано с тем, что каждый оператор возвращает результат, указывающий статус вызова, в дополнение к любым наборам результатов, которые могут быть возвращены операторами, выполняемыми внутри процедуры. Так как операторы могут возвращать несколько результатов, обработайте их с помощью цикла, вызывающего mysql_next_result() для определения наличия дополнительных результатов.

CLIENT_MULTI_RESULTS может быть включено при вызове mysql_real_connect(), либо явно, передав флаг CLIENT_MULTI_RESULTS, либо неявно, передав CLIENT_MULTI_STATEMENTS (что также включает CLIENT_MULTI_RESULTS). В MySQL 5.7 CLIENT_MULTI_RESULTS включено по умолчанию.

Если вы включите CLIENT_MULTI_STATEMENTS или CLIENT_MULTI_RESULTS, обработайте результат для каждого вызова mysql_real_query() или mysql_query() с помощью цикла, вызывающего mysql_next_result() для определения наличия дополнительных результатов. Пример см. в Разделе 3.6.2, «Поддержка выполнения нескольких операторов».

Для некоторых аргументов возможно, что значение берется из файла настроек, а не из явного значения в вызове mysql_real_connect(). Для этого вызовите mysql_options() с опцией MYSQL_READ_DEFAULT_FILE или MYSQL_READ_DEFAULT_GROUP перед вызовом mysql_real_connect(). Затем в вызове mysql_real_connect() укажите значение “no-value” для каждого аргумента, который должен быть прочитан из файла настроек.

  • Для host, укажите значение NULL или пустую строку ("").

  • Для user, укажите значение NULL или пустую строку.

  • Для passwd, укажите значение NULL. (Для пароля, значение пустой строки в вызове mysql_real_connect() не может быть переопределено в файле опций, так как пустая строка явно указывает, что у учётной записи MySQL должен быть пустой пароль.)

  • Для db, укажите значение NULL или пустую строку.

  • Для port, укажите значение 0.

  • Для unix_socket, укажите значение NULL.

Если в файле опций не найдено значения для аргумента, используется его значение по умолчанию, указанное в описаниях ранее в этом разделе.

Значения возврата

Обработчик соединения MYSQL*, если соединение было успешным, NULL, если соединение не удалось. При успешном соединении значение возврата совпадает со значением первого аргумента.

Ошибки

  • Не удалось подключиться к серверу MySQL.

  • Не удалось подключиться к локальному серверу MySQL.

  • Не удалось создать сокет IP.

  • Недостаточно памяти.

  • Не удалось создать Unix-сокет.

  • Не удалось найти IP-адрес для имени хоста.

  • Произошло несоответствие протокола при попытке подключения к серверу с помощью библиотеки клиента, использующей другую версию протокола.

  • Не удалось создать именованную трубу в Windows.

  • Не удалось дождаться именованной трубы в Windows.

  • Не удалось получить обработчик трубы в Windows.

  • Если > 0 и подключение к серверу заняло более секунд или сервер завершился во время выполнения init-command.

  • Обработчик соединения MYSQL уже подключен.

Пример

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. Это позволяет добавлять опции в секцию [your_prog_name], чтобы обеспечить работу вашей программы, даже если MySQL настроен каким-то нестандартным способом.

© 2025 Oracle
Licensed under the GPLv2 License.
https://docs.oracle.com/cd/E17952_01/c-api-5.7-en/mysql-real-connect.html

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API