Spec-Zone.ru › MySQL Connectors 1.0

5.4.58 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_real_connect_nonblocking(), предназначенный для применений, требующих асинхронного взаимодействия с сервером. Смотрите Главу 7, C API Asynchronous Interface.

Для подключения с использованием записи DNS SRV используйте mysql_real_connect_dns_srv(). Смотрите Раздел 5.4.59, «mysql_real_connect_dns_srv()».

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

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

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

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

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

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

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

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

    • В противном случае используется 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. По умолчанию это utf8mb4, но может быть изменено вызовом 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.

      Начиная с MySQL 8.0.32, флаг CLIENT_NO_SCHEMA устарел. Программы-клиенты могут опустить этот флаг и аргумент db, чтобы подключение устанавливало значение базы данных на текущую (или по умолчанию) базу данных.

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

    • CLIENT_OPTIONAL_RESULTSET_METADATA: Этот флаг делает метаданные набора результатов необязательными. Подавление передачи метаданных может повысить производительность, особенно для сессий, выполняющих много запросов, каждый из которых возвращает мало строк. Для получения подробностей о управлении передачей метаданных набора результатов, смотрите Раздел 3.6.7, «Необязательные метаданные набора результатов».

    • CLIENT_SSL: Использовать SSL (шифрованный протокол). Не устанавливайте этот параметр внутри программы-приложения; он устанавливается внутри библиотеки клиента. Вместо этого используйте mysql_options() перед вызовом 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). CLIENT_MULTI_RESULTS включён по умолчанию.

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

Для некоторых аргументов возможно использование значения из файла параметров вместо явного значения в вызове 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-8.4-en/mysql-real-connect.html

Spec-Zone.ru

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