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 SSL.
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 8.0.34 и может быть удалён в будущих версиях 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 Module недоступен, единственное разрешённое значение для 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_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` в открытом тексте.
`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));
}