5.4.50 mysql_options()

int
mysql_options(MYSQL *mysql,
              enum mysql_option option,
              const void *arg)

Описание

Может использоваться для установки дополнительных параметров подключения и влияния на поведение соединения. Эту функцию можно вызывать несколько раз для установки нескольких параметров. Для получения значений параметров используйте mysql_get_option().

Вызовите mysql_options() после mysql_init() и перед mysql_connect() или mysql_real_connect().

Аргумент option — это параметр, который нужно установить; аргумент arg — значение параметра. Если параметр является целым числом, укажите указатель на значение целого числа как аргумент arg.

Параметры, такие как файлы SSL-сертификата и ключа, используются для установления зашифрованного соединения, если такие соединения доступны, но не налагают требования, чтобы полученное соединение было зашифрованным. Для требования зашифрованного соединения используйте метод, описанный в разделе 3.6.1, «Поддержка зашифрованных соединений».

В приведенном ниже списке описаны возможные параметры, их влияние и то, как используется arg для каждого параметра. Для описаний параметров, где указано, что arg не используется, его значение не имеет значения; принято передавать 0. Некоторые параметры применимы только в том случае, если приложение связано с встроенной серверной библиотекой libmysqld и не используются для приложений, связанных с клиентской библиотекой libmysqlclient.

MYSQL_DEFAULT_AUTH (argument type: char *)

Имя используемого плагина аутентификации.
MYSQL_ENABLE_CLEARTEXT_PLUGIN (argument type: my_bool *)

Включить плагин аутентификации с открытым текстом mysql_clear_password. См. .
MYSQL_INIT_COMMAND (argument type: char *)

SQL-запрос для выполнения при подключении к серверу MySQL. Автоматически перевыполняется при повторном подключении.
MYSQL_OPT_BIND (argument: char *)

Сетевой интерфейс, через который следует подключаться к серверу. Используется, когда клиентский хост имеет несколько сетевых интерфейсов. Аргумент представляет собой имя хоста или IP-адрес (указанный в виде строки).
MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS (argument type: my_bool *)

Указывает, может ли клиент обрабатывать просроченные пароли. См. .
MYSQL_OPT_COMPRESS (argument: not used)

Сжимать всю информацию, отправляемую между клиентом и сервером, если это возможно. См. .
MYSQL_OPT_CONNECT_ATTR_DELETE (argument type: char *)

Учитывая имя ключа, этот параметр удаляет пару ключ-значение из текущего набора атрибутов соединения, которые нужно передать серверу во время подключения. Аргументом является указатель на строку, завершающуюся нулевым символом, которая задает имя ключа. Сравнение имени ключа с существующими ключами чувствительно к регистру.

См. также описание параметра MYSQL_OPT_CONNECT_ATTR_RESET, а также описание параметра MYSQL_OPT_CONNECT_ATTR_ADD в описании функции mysql_options4(). Описание этой функции также включает пример использования.

Performance Schema предоставляет доступ к атрибутам соединения через таблицы и . См. .
MYSQL_OPT_CONNECT_ATTR_RESET (argument not used)

Этот параметр сбрасывает (очищает) текущий набор атрибутов соединения, которые нужно передать серверу во время подключения.

См. также описание параметра MYSQL_OPT_CONNECT_ATTR_DELETE, а также описание параметра MYSQL_OPT_CONNECT_ATTR_ADD в описании функции mysql_options4(). Описание этой функции также включает пример использования.

Performance Schema предоставляет доступ к атрибутам соединения через таблицы и . См. .
MYSQL_OPT_CONNECT_TIMEOUT (argument type: unsigned int *)

Время ожидания подключения в секундах.
MYSQL_OPT_GET_SERVER_PUBLIC_KEY (argument type: my_bool *)

Позволяет клиенту запрашивать у сервера открытый ключ, необходимый для обмена паролями на основе пары ключей RSA. Этот параметр применяется к клиентам, которые аутентифицируются с помощью плагина аутентификации caching_sha2_password. Для этого плагина сервер не отправляет открытый ключ, если он не запрошен. Этот параметр игнорируется для учетных записей, которые не аутентифицируются с помощью этого плагина. Он также игнорируется, если обмен паролями на основе RSA не используется, как это происходит, когда клиент подключается к серверу с использованием защищенного соединения.

Если указан MYSQL_SERVER_PUBLIC_KEY и указывает на допустимый файл открытого ключа, он имеет приоритет над MYSQL_OPT_GET_SERVER_PUBLIC_KEY.

Для получения информации о плагине caching_sha2_password см. .

Этот параметр был добавлен в MySQL 5.7.23.
MYSQL_OPT_GUESS_CONNECTION (argument: not used)

Для приложения, связанного с библиотекой встроенного сервера libmysqld, этот параметр позволяет библиотеке определить, использовать ли встроенный сервер или удаленный сервер. “Определение” означает, что если имя хоста установлено и не является localhost, используется удаленный сервер. Это поведение является значением по умолчанию. MYSQL_OPT_USE_EMBEDDED_CONNECTION и MYSQL_OPT_USE_REMOTE_CONNECTION могут быть использованы для его переопределения. Этот параметр игнорируется для приложений, связанных с клиентской библиотекой libmysqlclient.
MYSQL_OPT_LOCAL_INFILE (argument type: optional pointer to unsigned int)

Этот параметр влияет на возможности загрузки данных с локального хранилища для операций . По умолчанию возможности определяются значением по умолчанию, скомпилированным в клиентскую библиотеку MySQL. Чтобы явно управлять этой возможностью, вызовите mysql_options() для включения или отключения параметра MYSQL_OPT_LOCAL_INFILE:
- Чтобы включить загрузку данных LOCAL, установите указатель так, чтобы он указывал на unsigned int, имеющее ненулевое значение, или опустите аргумент указателя.
- Чтобы отключить загрузку данных LOCAL, установите указатель так, чтобы он указывал на unsigned int, имеющее нулевое значение.
Параметр CMake управляет значением по умолчанию клиентской библиотеки для локальной загрузки данных (см. ).

Успешное использование операций загрузки LOCAL клиентом также требует, чтобы сервер разрешал локальную загрузку; см.
MYSQL_OPT_MAX_ALLOWED_PACKET (argument: unsigned long *)

Этот параметр устанавливает размер буфера для связи клиент/сервер на стороне клиента. Если аргумент mysql не является NULL, вызов устанавливает значение параметра для этого сеанса. Если mysql является NULL, вызов устанавливает значение параметра глобально для всех последующих сеансов, для которых не указано значение, специфичное для сеанса.

Поскольку можно установить максимальный размер буфера для сеанса или глобально, в зависимости от того, является ли аргумент mysql не-NULL или NULL, mysql_get_option() аналогично возвращает значение сеанса или глобальное значение в зависимости от его аргумента mysql.
MYSQL_OPT_NAMED_PIPE (argument: not used)

Использовать именованный канал для подключения к серверу MySQL в Windows, если сервер разрешает подключения через именованные каналы.
MYSQL_OPT_NET_BUFFER_LENGTH (argument: unsigned long *)

Этот параметр устанавливает размер буфера на стороне клиента для связи TCP/IP и сокетов.
MYSQL_OPT_PROTOCOL (argument type: unsigned int *)

Транспортный протокол, используемый для соединения. Укажите одно из перечисленных значений mysql_protocol_type, определенных в mysql.h.
MYSQL_OPT_READ_TIMEOUT (argument type: unsigned int *)

Время ожидания в секундах для каждой попытки чтения с сервера. При необходимости выполняются повторные попытки, поэтому общее эффективное значение времени ожидания в три раза больше значения параметра. Вы можете установить значение так, чтобы потерянное соединение можно было обнаружить раньше, чем значение TCP/IP Close_Wait_Timeout в 10 минут.
MYSQL_OPT_RECONNECT (argument type: my_bool *)

Включить или отключить автоматическое повторное подключение к серверу, если обнаружено, что соединение было потеряно. Повторное подключение отключено по умолчанию; этот параметр предоставляет способ явного задания поведения повторного подключения. См. Раздел 3.6.6, «Управление автоматическим повторным подключением».
MYSQL_OPT_RETRY_COUNT (argument type: unsigned int *)

Количество попыток для системных вызовов, связанных с вводом-выводом, которые прерываются при подключении к серверу или обмене данными с ним. Если этот параметр не указан, значение по умолчанию равно 1 (1 повторная попытка, если исходный вызов прерван, всего 2 попытки).

Этот параметр может использоваться только клиентами, которые связаны с C-клиентской библиотекой, скомпилированной с поддержкой NDB Cluster. Он доступен начиная с MySQL NDB Cluster 7.5.1.
MYSQL_OPT_SSL_CA (argument type: char *)

Имя файла сертификата центра сертификации (CA). Этот параметр, если используется, должен указывать на тот же сертификат, что и сервер.
MYSQL_OPT_SSL_CAPATH (argument type: char *)

Имя каталога, содержащего доверенные файлы сертификатов SSL CA.
MYSQL_OPT_SSL_CERT (argument type: char *)

Имя файла сертификата открытого ключа клиента.
MYSQL_OPT_SSL_CIPHER (argument type: char *)

Список допустимых шифров для шифрования SSL.
MYSQL_OPT_SSL_CRL (argument type: char *)

Имя файла, содержащего списки отозванных сертификатов.
MYSQL_OPT_SSL_CRLPATH (argument type: char *)

Имя каталога, содержащего файлы, содержащие списки отозванных сертификатов.
MYSQL_OPT_SSL_ENFORCE (argument type: my_bool *)

Требовать ли использование SSL для соединения. Если включено и зашифрованное соединение не может быть установлено, попытка соединения завершается неудачей.

Этот параметр устарел, начиная с MySQL 5.7.11, и удален в MySQL 8.0. Вместо этого используйте MYSQL_OPT_SSL_MODE со значением SSL_MODE_REQUIRED.
MYSQL_OPT_SSL_KEY (argument type: char *)

Имя файла закрытого ключа клиента.
MYSQL_OPT_SSL_MODE (argument type: unsigned int *)

Режим безопасности, используемый для соединения с сервером: SSL_MODE_DISABLED, SSL_MODE_PREFERRED, SSL_MODE_REQUIRED, SSL_MODE_VERIFY_CA, SSL_MODE_VERIFY_IDENTITY. Если этот параметр не указан, значение по умолчанию — SSL_MODE_PREFERRED. Эти режимы являются допустимыми значениями перечисления mysql_ssl_mode, определенного в mysql.h. Для получения дополнительной информации о режимах безопасности см. описание в .

Этот параметр был добавлен в MySQL 5.7.11.
MYSQL_OPT_SSL_VERIFY_SERVER_CERT (argument type: my_bool *)

Включить или отключить проверку идентификатора общего имени сервера в его сертификате по сравнению с именем хоста, используемым при подключении к серверу. Соединение отклоняется, если существует несоответствие. Для зашифрованных соединений эта функция может использоваться для предотвращения атак «человек посередине». Проверка идентификации отключена по умолчанию.

Этот параметр не работает с самозаверяющими сертификатами, которые не содержат имя сервера в качестве значения общего имени.

Этот параметр устарел, начиная с MySQL 5.7.11, и удален в MySQL 8.0. Вместо этого используйте MYSQL_OPT_SSL_MODE со значением SSL_MODE_VERIFY_IDENTITY.

MYSQL_OPT_TLS_VERSION (тип аргумента: char *)

Протоколы, разрешенные клиентом для шифрованных соединений. Значение представляет собой список одной или нескольких версий протоколов, разделенных запятыми. Протоколы, которые могут быть указаны для этого параметра, зависят от используемой библиотеки SSL для компиляции MySQL. Для получения подробностей см. .

Этот параметр был добавлен в MySQL 5.7.10.
MYSQL_OPT_USE_EMBEDDED_CONNECTION (аргумент: не используется)

Для приложения, связанного с библиотекой встроенного сервера libmysqld, этот параметр принудительно использует встроенный сервер для подключения. Он игнорируется для приложений, связанных с библиотекой клиента libmysqlclient.
MYSQL_OPT_USE_REMOTE_CONNECTION (аргумент: не используется)

Для приложения, связанного с библиотекой встроенного сервера libmysqld, этот параметр принудительно использует удаленный сервер для подключения. Он игнорируется для приложений, связанных с библиотекой клиента libmysqlclient.
MYSQL_OPT_USE_RESULT (аргумент: не используется)

Этот параметр не используется.
MYSQL_OPT_WRITE_TIMEOUT (тип аргумента: unsigned int *)

Таймаут в секундах для каждой попытки записи на сервер. При необходимости происходит повторная попытка, поэтому общее эффективное значение таймаута составляет дважды значение параметра.
MYSQL_PLUGIN_DIR (тип аргумента: char *)

Директория, в которой следует искать плагины клиента.
MYSQL_READ_DEFAULT_FILE (тип аргумента: char *)

Читать параметры из указанного файла параметров вместо файла my.cnf.
MYSQL_READ_DEFAULT_GROUP (тип аргумента: char *)

Считывать параметры из указанной группы из my.cnf или файла, указанного с помощью MYSQL_READ_DEFAULT_FILE.
MYSQL_REPORT_DATA_TRUNCATION (тип аргумента: my_bool *)

Включить или выключить отчет об ошибках усечения данных для подготовленных запросов, использующих член error структур MYSQL_BIND. (По умолчанию: включено.)
MYSQL_SECURE_AUTH (тип аргумента: my_bool *)

Подключаться ли к серверу, который не поддерживает хеширование паролей, используемое в MySQL 4.1.1 и более поздних версиях. Этот параметр включен по умолчанию.
MYSQL_SERVER_PUBLIC_KEY (тип аргумента: char *)

Имя файла с копией открытого ключа со стороны клиента в формате PEM, необходимой серверу для обмена паролями на основе пар ключей RSA. Этот параметр применяется к клиентам, которые аутентифицируются с помощью плагина аутентификации sha256_password. Этот параметр игнорируется для учетных записей, которые не аутентифицируются с помощью одного из этих плагинов. Он также игнорируется, если обмен паролями на основе RSA не используется, как в случае, когда клиент подключается к серверу с использованием защищенного соединения.

Если MYSQL_SERVER_PUBLIC_KEY задан и указывает на действительный файл открытого ключа, он имеет приоритет перед MYSQL_OPT_GET_SERVER_PUBLIC_KEY.

Сведения о плагинах sha256_password и caching_sha2_password см. в и .
MYSQL_SET_CHARSET_DIR (тип аргумента: char *)

Путь к каталогу, содержащему файлы определений наборов символов.
MYSQL_SET_CHARSET_NAME (тип аргумента: char *)

Имя набора символов, используемого в качестве набора символов по умолчанию. Аргумент может быть MYSQL_AUTODETECT_CHARSET_NAME, чтобы набор символов определялся автоматически на основе системных настроек (см. ).
MYSQL_SET_CLIENT_IP (тип аргумента: char *)

Для приложения, связанного с библиотекой встроенного сервера libmysqld (когда libmysqld скомпилирован с поддержкой аутентификации), этот параметр означает, что пользователь считается подключившимся с указанного IP-адреса (указанного как строка) для целей аутентификации. Он игнорируется для приложений, связанных с библиотекой клиента libmysqlclient.
MYSQL_SHARED_MEMORY_BASE_NAME (тип аргумента: char *)

Имя объекта общей памяти для связи с сервером в Windows, если сервер поддерживает подключения через общую память. Укажите то же значение, что и для переменной системы. сервера mysqld, к которому вы хотите подключиться.

Группа client всегда читается, если вы используете MYSQL_READ_DEFAULT_FILE или MYSQL_READ_DEFAULT_GROUP.

Указанная группа в файле параметров может содержать следующие параметры.

Параметр	Описание
`character-sets-dir=dir_name`	Директория, в которой установлены наборы символов.
`compress`	Использовать сжатый протокол клиент/сервер.
`connect-timeout=seconds`	Таймаут подключения в секундах. В Linux этот таймаут также используется для ожидания первого ответа от сервера.
`database=db_name`	Подключиться к этой базе данных, если база данных не была указана в команде подключения.
`debug`	Параметры отладки.
`default-character-set=charset_name`	Набор символов по умолчанию.
`disable-local-infile`	Отключить использование .
`enable-cleartext-plugin`	Включить плагин аутентификации `mysql_clear_password` в режиме открытого текста.
`host=host_name`	Имя хоста по умолчанию.
`init-command=stmt`	Запрос для выполнения при подключении к серверу MySQL. Автоматически повторно выполняется при повторном подключении.
`interactive-timeout=seconds`	То же, что и указание `CLIENT_INTERACTIVE` для `mysql_real_connect()`. См. Раздел 5.4.54, «mysql_real_connect()».
`local-infile[={0\|1}]`	Если не указан аргумент или аргумент равен нулю, включить использование ; в противном случае отключить.
`max_allowed_packet=bytes`	Максимальный размер пакета, который клиент может прочитать от сервера.
`multi-queries`, `multi-results`	Включить несколько наборов результатов из многострочных запросов или хранимых процедур.
`multi-statements`	Разрешить клиенту отправлять несколько запросов в одной строке (разделенных символами `;`).
`password=password`	Пароль по умолчанию.
`pipe`	Использовать именованные каналы для подключения к серверу MySQL в Windows.
`port=port_num`	Номер порта по умолчанию.
`protocol={TCP\|SOCKET\|PIPE\|MEMORY}`	Протокол, используемый при подключении к серверу.
`return-found-rows`	Указать `mysql_info()` возвращать найденные строки вместо обновленных строк при использовании .
`shared-memory-base-name=name`	Имя общей памяти, используемое для подключения к серверу.
`socket={file_name\|pipe_name}`	Файл сокета по умолчанию.
`ssl-ca=file_name`	Файл центрального сертификационного органа (Certificate Authority).
`ssl-capath=dir_name`	Каталог центрального сертификационного органа (Certificate Authority).
`ssl-cert=file_name`	Файл сертификата.
`ssl-cipher=cipher_list`	Разрешенные шифры SSL.
`ssl-key=file_name`	Ключевой файл.
`timeout=seconds`	Аналогично `connect-timeout`.
`user`	Пользователь по умолчанию.

timeout был заменён на connect-timeout, но timeout всё ещё поддерживается для обратной совместимости.

Дополнительную информацию о файлах параметров, используемых программами MySQL, см. .

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

Ноль в случае успеха. Неноль, если вы указали неизвестный параметр.

Пример

Следующие вызовы mysql_options() запрашивают использование сжатия в протоколе клиент/сервер, заставляют читать параметры из группы [odbc] в файлах параметров и отключают автоматический режим подтверждения транзакций:

MYSQL mysql;

mysql_init(&mysql);
mysql_options(&mysql,MYSQL_OPT_COMPRESS,0);
mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"odbc");
mysql_options(&mysql,MYSQL_INIT_COMMAND,"SET autocommit=0");
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));
}