5.4.54 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.

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

Название плагина аутентификации для использования.
MYSQL_ENABLE_CLEARTEXT_PLUGIN (тип аргумента: bool *)

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

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

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

Указать, может ли клиент обрабатывать истекшие пароли. См. .
MYSQL_OPT_COMPRESS (аргумент: не используется)

Сжать всю информацию, отправляемую между клиентом и сервером, если возможно. См. .

Начиная с MySQL 8.0.18, MYSQL_OPT_COMPRESS становится устаревшим параметром из-за введения параметра MYSQL_OPT_COMPRESSION_ALGORITHMS для более тонкого контроля сжатия соединений (см. ). Значение MYSQL_OPT_COMPRESS зависит от того, указан ли MYSQL_OPT_COMPRESSION_ALGORITHMS:
- Если MYSQL_OPT_COMPRESSION_ALGORITHMS не указан, включение MYSQL_OPT_COMPRESS эквивалентно указанию набора алгоритмов клиента zlib,uncompressed.
- Если MYSQL_OPT_COMPRESSION_ALGORITHMS указан, включение MYSQL_OPT_COMPRESS эквивалентно указанию набора алгоритмов zlib, а полный набор алгоритмов клиента является объединением zlib и алгоритмов, указанных в MYSQL_OPT_COMPRESSION_ALGORITHMS. Например, при включенном MYSQL_OPT_COMPRESS и установке MYSQL_OPT_COMPRESSION_ALGORITHMS в значение zlib,zstd, разрешённый набор алгоритмов — zlib плюс zlib,zstd; то есть, zlib,zstd. При включенном MYSQL_OPT_COMPRESS и установке MYSQL_OPT_COMPRESSION_ALGORITHMS в значение zstd,uncompressed, разрешённый набор алгоритмов — zlib плюс zstd,uncompressed; то есть, zlib,zstd,uncompressed.
Начиная с MySQL 8.0.18, MYSQL_OPT_COMPRESS устарел. Он может быть удалён в будущей версии MySQL. См. .
MYSQL_OPT_COMPRESSION_ALGORITHMS (тип аргумента: const char *)

Разрешённые алгоритмы сжатия для соединений с сервером. Доступные алгоритмы совпадают с системной переменной. Если этот параметр не указан, значение по умолчанию — uncompressed.

Для получения дополнительной информации см. .

Этот параметр добавлен в MySQL 8.0.18. Для асинхронных операций параметр не действует до MySQL 8.0.21.
MYSQL_OPT_CONNECT_ATTR_DELETE (тип аргумента: char *)

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

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

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

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

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

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

Таймаут подключения в секундах.
MYSQL_OPT_GET_SERVER_PUBLIC_KEY (тип аргумента: bool *)

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

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

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

Этот параметр влияет на возможность клиента LOCAL для операций . Он указывает каталог, в котором должны находиться файлы, указанные в операциях . Влияние параметра MYSQL_OPT_LOAD_DATA_LOCAL_DIR зависит от включения или выключения загрузки данных LOCAL:
- Если загрузка данных LOCAL включена по умолчанию в библиотеке MySQL-клиента или явно включена с помощью MYSQL_OPT_LOCAL_INFILE, параметр MYSQL_OPT_LOAD_DATA_LOCAL_DIR не оказывает никакого влияния.
- Если загрузка данных LOCAL выключена по умолчанию в библиотеке MySQL-клиента или явно выключена с помощью MYSQL_OPT_LOCAL_INFILE, параметр MYSQL_OPT_LOAD_DATA_LOCAL_DIR может использоваться для обозначения разрешённого каталога для загружаемых локально файлов. В этом случае загрузка данных LOCAL разрешена, но ограничена файлами, расположенными в указанном каталоге. Интерпретация значения MYSQL_OPT_LOAD_DATA_LOCAL_DIR следующая:
  - Если значение равно указателю на null (значение по умолчанию), каталог не задан, и файлы не разрешены для загрузки данных LOCAL.
  - Если значение — путь к каталогу, загрузка данных LOCAL разрешена, но ограничена файлами, расположенными в указанном каталоге. Сравнение имени пути каталога и имени пути загружаемых файлов регистрозависимое независимо от регистрозависимости файловой системы.
Например, чтобы явно отключить загрузку локальных данных, кроме файлов, расположенных в каталоге /my/local/data, вызовите mysql_options() следующим образом:
```
unsigned int i = 0;
mysql_options(&mysql,MYSQL_OPT_LOCAL_INFILE,&i);
mysql_options(&mysql,MYSQL_OPT_LOAD_DATA_LOCAL_DIR,"/my/local/data");
```
Параметр MYSQL_OPT_LOAD_DATA_LOCAL_DIR может быть установлен в любое время во время работы обработчика соединения mysql. После установки значение применяется ко всем последующим операциям загрузки LOCAL, пока значение не будет изменено.

Параметр CMake управляет значением по умолчанию для загрузки локальных данных в библиотеке клиента (см. ).

Успешное выполнение операций загрузки LOCAL клиентом также требует, чтобы сервер разрешал локальную загрузку; см.

Параметр MYSQL_OPT_LOAD_DATA_LOCAL_DIR был добавлен в MySQL 8.0.21.
MYSQL_OPT_LOCAL_INFILE (тип аргумента: необязательный указатель на unsigned int)

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

Параметр CMake управляет значением по умолчанию для загрузки локальных данных в библиотеке клиента (см. ).

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

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

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

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

Этот параметр устанавливает размер буфера клиента для TCP/IP и сокетного взаимодействия.

MYSQL_OPT_OPTIONAL_RESULTSET_METADATA (тип аргумента: bool *)

Этот флаг делает метаданные набора результатов необязательными. Это альтернатива установке флага соединения CLIENT_OPTIONAL_RESULTSET_METADATA для функции mysql_real_connect(). Подробности по управлению передачей метаданных набора результатов см. в разделе 3.6.7 «Необязательные метаданные набора результатов».
MYSQL_OPT_PROTOCOL (тип аргумента: unsigned int *)

Протокол передачи для подключения. Укажите одно из значений перечисления mysql_protocol_type, определённого в mysql.h.
MYSQL_OPT_READ_TIMEOUT (тип аргумента: unsigned int *)

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

Примечание

Параметр MYSQL_OPT_RECONNECT всё ещё доступен, но устарел; ожидается его удаление в будущей версии MySQL.

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

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

Этот параметр может использоваться только клиентами, которые связываются с библиотекой C-клиента, скомпилированной с поддержкой кластера NDB.
MYSQL_OPT_SSL_CA (тип аргумента: char *)

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

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

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

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

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

Имя пути каталога, содержащего файлы со списками отзыва сертификатов.
MYSQL_OPT_SSL_FIPS_MODE (тип аргумента: unsigned int *)

Параметр MYSQL_OPT_SSL_FIPS_MODE устарел и может быть удалён в будущей версии MySQL.

Управляет включением режима FIPS на стороне клиента. Параметр MYSQL_OPT_SSL_FIPS_MODE отличается от других параметров MYSQL_OPT_SSL_xxx тем, что он не используется для установления зашифрованных соединений, а скорее для управления разрешёнными криптографическими операциями. См. .

Разрешённые значения параметра: SSL_FIPS_MODE_OFF, SSL_FIPS_MODE_ON и SSL_FIPS_MODE_STRICT.

Примечание

Если модуль OpenSSL FIPS Object не доступен, единственно разрешённым значением для MYSQL_OPT_SSL_FIPS_MODE является SSL_FIPS_MODE_OFF. В этом случае установка MYSQL_OPT_SSL_FIPS_MODE в SSL_FIPS_MODE_ON или SSL_FIPS_MODE_STRICT приводит к появлению предупреждения при запуске клиента и работе в режиме без FIPS.
MYSQL_OPT_SSL_KEY (тип аргумента: char *)

Имя пути файла закрытого ключа клиента.
MYSQL_OPT_SSL_MODE (тип аргумента: 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_OPT_SSL_SESSION_DATA (тип аргумента: void *)

Данные сессии для повторного использования сессии при установлении следующего зашифрованного соединения. Следует установить перед mysql_real_connect() и после mysql_init(). Ожидает данные сессии PEM, возвращённые функцией mysql_get_ssl_session_data(), и копирует результат в обработчик MYSQL. Сбрасывается в nullptr (значение по умолчанию) после mysql_real_connect(), если не указано иначе через флаг CLIENT_REMEMBER_OPTIONS.

При указании выполняется попытка повторного использования сессии во время установления TLS. mysql_get_option() возвращает обработчик, установленный функцией mysql_options(), если таковой имеется, и не увеличивает количество ссылок.

Этот параметр был добавлен в MySQL 8.0.29.
MYSQL_OPT_TLS_CIPHERSUITES (тип аргумента: char *)

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

Этот параметр был добавлен в MySQL 8.0.16.
MYSQL_OPT_TLS_SNI_SERVERNAME (тип аргумента: char *)

Сервер, к которому клиент пытается подключиться в начале рукопожатия TLS. Этот параметр должен быть установлен до подключения к серверу. Имя сервера содержит полное доменное имя хоста сервера, как понимает его клиент. Имя сервера представлено строкой байтов с использованием кодировки ASCII без заключительной точки и нечувствительно к регистру.

Указание имени сервера (SNI) — это расширение протокола TLS (OpenSSL должен быть скомпилирован с расширениями TLS для работы этого параметра). Реализация SNI в MySQL представляет только клиентскую сторону.
MYSQL_OPT_TLS_VERSION (тип аргумента: char *)

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

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

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

Уровень сжатия для соединений с сервером, использующих алгоритм сжатия zstd. Разрешённые уровни — от 1 до 22, где большие значения означают увеличение уровня сжатия. Если этот параметр не указан, значение по умолчанию — уровень сжатия zstd, равный 3. Настройка уровня сжатия не влияет на соединения, которые не используют сжатие zstd.

Дополнительную информацию см. в .

Этот параметр был добавлен в MySQL 8.0.18. Для асинхронных операций параметр не имеет эффекта до MySQL 8.0.21.
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 (тип аргумента: bool *)

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

Имя пути к файлу в формате PEM, содержащему клиентскую копию открытого ключа, необходимую серверу для обмена паролями на основе пар ключей RSA. Этот параметр применяется к клиентам, которые аутентифицируются с помощью плагина аутентификации sha256_password или caching_sha2_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_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` cleartext.
`host=host_name`	Имя хоста по умолчанию.
`init-command=stmt`	Запрос для выполнения при подключении к серверу MySQL. Автоматически повторно выполняется при повторном подключении.
`interactive-timeout=seconds`	То же самое, что и указание `CLIENT_INTERACTIVE` для `mysql_real_connect()`. См. Раздел 5.4.58, «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`	Файл файла центра сертификации.
`ssl-capath=dir_name`	Директория файла центра сертификации.
`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));
}