mysql\_optionsv(3) MariaDB Connector/C mysql\_optionsv(3) ## [Name](#Name) mysql\_optionsv - Used to set extra connect options and affect behavior of a connection ## [Synopsis](#Synopsis) ``` #include int mysql_optionsv(MYSQL * mysql, enum mysql_option, const void * arg, ...); ``` ## [Description](#Description) Used to set extra connect options and affect behavior for a connection. This function may be called multiple times to set several options. mysql\_optionsv() should be called after [**mysql\_init(3)**](/man/os/mariadb-12.2/mysql_init.3). ## [Options](#Options) The following table shows which variable type to use for each option. Variable Type Values my\_bool MYSQL\_OPT\_RECONNECT, MYSQL\_SECURE\_AUTH, MYSQL\_REPORT\_DATA\_TRUNCATION, MYSQL\_OPT\_SSL\_ENFORCE, MYSQL\_OPT\_SSL\_VERIFY\_SERVER\_CERT, MARIADB\_OPT\_SKIP\_READ\_RESPONSE unsigned int MYSQL\_OPT\_PORT, MYSQL\_OPT\_LOCAL\_INFILE, MYSQL\_OPT\_CONNECT\_TIMEOUT, MYSQL\_OPT\_PROTOCOL, MYSQL\_OPT\_READ\_TIMEOUT, MYSQL\_OPT\_WRITE\_TIMEOUT unsigned long MYSQL\_OPT\_NET\_BUFFER\_LENGTH, MYSQL\_OPT\_MAX\_ALLOWED\_PACKET const char * MYSQL\_INIT\_COMMAND, MARIADB\_OPT\_UNIXSOCKET, MARIADB\_OPT\_PASSWORD , MARIADB\_OPT\_USER, MARIADB\_OPT\_HOST, MARIADB\_OPT\_SCHEMA, MYSQL\_OPT\_SSL\_KEY, MYSQL\_OPT\_SSL\_CERT, MYSQL\_OPT\_SSL\_CA, MYSQL\_OPT\_SSL\_CAPATH, MYSQL\_SET\_CHARSET\_NAME, MYSQL\_SET\_CHARSET\_DIR, MYSQL\_OPT\_SSL\_CIPHER, MYSQL\_SHARED\_MEMORY\_BASE\_NAME, MYSQL\_PLUGIN\_DIR, MYSQL\_DEFAULT\_AUTH, MARIADB\_OPT\_SSL\_FP, MARIADB\_OPT\_SSL\_FP\_LIST, MARIADB\_OPT\_TLS\_PASSPHRASE, MARIADB\_OPT\_TLS\_VERSION, MYSQL\_OPT\_BIND, MYSQL\_OPT\_CONNECT\_ATTR\_DELETE, MYSQL\_OPT\_CONNECT\_ATTR\_ADD, MARIADB\_OPT\_CONNECTION\_HANDLER, MYSQL\_SERVER\_PUBLIC\_KEY, MARIADB\_OPT\_RESTRICTED\_AUTH const char\*, unsigned int MARIADB\_OPT\_RPL\_REGISTER\_REPLICA - MYSQL\_OPT\_CONNECT\_ATTR\_RESET void * MARIADB\_OPT\_PROXY\_HEADER • MYSQL\_OPT\_SSL\_ENFORCE Enable or disable TLS. This option can be used to enable TLS without having to provide TLS certificates, keys or CAs. **Note**: currenty this does not enforce TLS like the option name would suggest. If the server does not support TLS, the protocol will fall back to unencrypted communication. To enforce the use of TLS, use MYSQL\_OPT\_SSL\_VERIFY\_SERVER\_CERT instead. • MYSQL\_INIT\_COMMAND Command(s) which will be executed when connecting and reconnecting to the server. • MYSQL\_OPT\_COMPRESS Use the compressed protocol for client server communication. If the server doesn’t support compressed protocol, the default protocol will be used. • MYSQL\_OPT\_CONNECT\_TIMEOUT Connect timeout in seconds. This value will be passed as an unsigned ##int## parameter. • MYSQL\_OPT\_LOCAL\_INFILE Enable or disable the use of LOAD DATA LOCAL INFILE • MYSQL\_OPT\_NAMED\_PIPE For Windows operating systems only: Use named pipes for client/server communication. • MYSQL\_PROGRESS\_CALLBACK Specifies a callback function which will be able to visualize the progress of certain long running statements (i.e. LOAD DATA LOCAL INFILE or ALTER TABLE). The callback function must be defined as followed: ``` static void report_progress(const MYSQL *mysql __attribute__((unused)), uint stage, uint max_stage, double progress __attribute__((unused)), const char *proc_info __attribute__((unused)), uint proc_info_length __attribute__((unused))) ``` • MYSQL\_OPT\_PROTOCOL Specify the type of client/server protocol. Possible values are: MYSQL\_PROTOCOL\_TCP, MYSQL\_PROTOCOL\_SOCKET, MYSQL\_PROTOCOL\_PIPE and MYSQL\_PROTOCOL\_MEMORY. • MYSQL\_OPT\_RECONNECT Enable or disable automatic reconnect. • MYSQL\_OPT\_READ\_TIMEOUT Specifies the timeout in seconds for reading packets from the server. • MYSQL\_OPT\_WRITE\_TIMEOUT Specifies the timeout in seconds for sending packets to the server. • MYSQL\_READ\_DEFAULT\_FILE Read options from the specified configuration file. If an empty string is passed, the default configuration files (such as /etc/my.cnf, /etc/mysql/my.cnf) will be read. By default, configuration files are not processed unless this option is specified. • MYSQL\_READ\_DEFAULT\_GROUP Read options from the specified group within the default configuration file or the file specified by MYSQL\_READ\_DEFAULT\_FILE. Passing an empty string will result in all sections being processed. If no specific file is provided via MYSQL\_READ\_DEFAULT\_FILE, all available default configuration files will be considered. **Note:** In addition to a specified group the following groups will be always processed: • \[client] • \[client-server] • \[client-mariadb] • MYSQL\_REPORT\_DATA\_TRUNCATION Enable or disable reporting data truncation errors for prepared statements. • MYSQL\_OPT\_BIND Specify the network interface from which to connect to MariaDB Server. • MYSQL\_PLUGIN\_DIR Specify the location of client plugins. • MYSQL\_OPT\_NONBLOCK Specify stack size for non blocking operations. The argument for MYSQL\_OPT\_NONBLOCK is the size of the stack used to save the state of a non-blocking operation while it is waiting for I/O and the application is doing other processing. Normally, applications will not have to change this, and it can be passed as zero to use the default value. • MYSQL\_OPT\_NET\_BUFFER\_LENGTH Initial network buffer size in bytes. The default value is 16777216 (16MiB). • MYSQL\_OPT\_MAX\_ALLOWED\_PACKET Maximum allowed packet length. The default value is 1073741824 (1GiB) on the client side. If the limit is exceeded by a packet sent by the server, an error is generated. • MARIADB\_OPT\_CONNECTION\_HANDLER Specify the name of a connection handler plugin. • MARIADB\_OPT\_USERDATA Bundle user data to the current connection, e.g. for use in connection handler plugins. This option requires 4 parameters: connection, option, key and value: ``` mysql_optionsv(mysql, MARIADB_OPT_USERDATA, (void *)"my_key", (void *)value); ``` • MARIADB\_OPT\_CONNECTION\_READ\_ONLY This option is used by connection handler plugins and indicates that the current connection will be used for read operations only. • MYSQL\_OPT\_CAN\_HANDLE\_EXPIRED\_PASSWORDS If this option is set, the client indicates that it will be able to handle expired passwords by setting the CLIENT\_CAN\_HANDLE\_EXPIRED\_PASSWORDS capability flag. If the password has expired and CLIENT\_CAN\_HANDLE\_EXPIRED\_PASSWORDS is set, the server will not return an error when connecting, but put the connection in sandbox mode, where all commands will return error 1820 (ER\_MUST\_CHANGE\_PASSWORD) unless a new password was set. This option was added in MariaDB Connector/C 3.0.4 • MARIADB\_OPT\_STATUS\_CALLBACK Specifies a callback function which will be called whenever the server status changes or the server sent session\_track information to the client: ``` mysql_optionsv(mysql, MARIADB_OPT_STATUS_CALLBACK, function, data) ``` The callback function must be defined as follows: ``` void status_callback(void *data, enum enum_mariadb_status_info type, ..) ``` Parameters: ``` - data Pointer passed with registration of callback function (usually a connection handle) - type Information type STATUS_TYPE or SESSION_TRACK_TYPE ``` Variadic Parameters: ``` if (type == STATUS_TYPE): - server status (unsigned int) if (type == SESSION_TRACK_TYPE) - enum enum_session_state_type track_type - session track type if (track_type == SESSION_TRACK_SYSTEM_VARIABLES) - MARIADB_CONST_STRING *key - MARIADB_CONST_STRING *value else - MARIADB_CONST_STRING *value ``` \` Note: Specifying a callback function overwrites the internal session tracking function, so API functions mysql\_session\_track\_get\_first()/next() can’t be used. An example can be found in unittest/libmariadb/connection.c (test\_status\_callback) Addid in version 3.3.2 • MARIADB\_OPT\_SKIP\_READ\_RESPONSE Don’t read response packets in binary protocol. Added in version 3.1.13 ## [Replication/Binlog API options](#Replication/Binlog_API_options) • MARIADB\_OPT\_RPL\_REGISTER\_REPLICA Specifies host name and port for Binlog/API. When this option was set, rpl\_open() will register replica with server\_id, host and port to the connected server. This information can be retrieved by SHOW SLAVE STATUS command. This option was added in version 3.3.1 ## [TLS/SSL and Security options](#TLS/SSL_and_Security_options) • MYSQL\_OPT\_SSL\_KEY Specify the name of a key for a secure connection. If the key is protected with a passphrase, the passphrase needs to be specified with MARIADB\_OPT\_PASSPHRASE option. • MYSQL\_OPT\_SSL\_CERT Specify the name of a certificate for a secure connection. • MYSQL\_OPT\_SSL\_CA Specify the name of a file which contains one or more trusted CAs. • MYSQL\_OPT\_SSL\_CAPATH Specify the path which contains trusted CAs. • MYSQL\_OPT\_SSL\_CIPHER Specify one or more (SSLv3, TLSv1.0 or TLSv1.2) cipher suites for TLS encryption. Even if Connector/C supports TLSv1.3 protocol, it is not possible yet to specify TLSv1.3 cipher suites. • MYSQL\_OPT\_SSL\_CRL Specify a file with a certificate revocation list. • MYSQL\_OPT\_SSL\_CRLPATH Specify a directory with contains files with certificate revocation lists. • MARIADB\_OPT\_SSL\_FP Specify the fingerprint hash of a server certificate for validation during the TLS handshake. For versions prior to 3.4.0 the hash is a SHA1 hash, for versions 3.4.0 and newer SHA256,SHA384 or SHA512. • MARIADB\_OPT\_SSL\_FP\_LIST Specify a file which contains one or more fingerprint hashes of server certificates for validation during the TLS handshake. For versions prior to 3.4.0 the hash is a SHA1 hash, for versions 3.4.0 and newer SHA256,SHA384 or SHA512. • MARIADB\_OPT\_SSL\_PASPHRASE Specify a passphrase for a passphrase protected client key. • MYSQL\_OPT\_SSL\_VERIFY\_SERVER\_CERT Enable (or disable) the verification of the host name against common name (CN) of the server’s host certificate. • MYSQL\_SERVER\_PUBLIC\_KEY Specifies the name of the file which contains the RSA public key of the database server. The format of this file must be in PEM format. This option is used by the caching\_sha2\_password plugin and was added in Connector/C 3.1.0 • MARIADB\_OPT\_TLS\_CIPHER\_STRENGTH This option is not in use anymore. • MARIADB\_OPT\_RESTRICTED\_AUTH Specifies one or more comma separated authentication plugins which are allowed for authentication. If the database server asks for an authentication plugin not listed in this option, MariaDB Connector/C will return an error. This option was added in MariaDB Connector/C 3.3.0 ## [Proxy settings](#Proxy_settings) As per the proxy protocol specification, the connecting client can prefix its first packet with a proxy protocol header. The server will parse the header and assume the client’s IP address is the one set in the proxy header. * MARIADB\_OPT\_PROXY\_HEADER - specifies the proxy header which will be prefixed to the first packet. Parameters are void * for the prefix buffer and size\_t for length of the buffer: ``` const char *hdr="PROXY TCP4 192.168.0.1 192.168.0.11 56324 443\r\n"; mysql_optionsv(mysql, MARIADB_OPT_PROXY_HEADER, hdr, strlen(hdr)); ``` ## [Connection Attributes](#Connection_Attributes) Connection attributes are stored in the session\_connect\_attrs and session\_account\_connect\_attrsPerformance Schema tables. By default, MariaDB Connector/C sends the following connection attributes to the server: * \_client\_name: always “libmariadb” * \_client\_version: version of MariaDB Connector/C * \_os: operation system * \_pid: process id * \_platform: e.g. x86 or x64 * \_server\_host: the host name (as specified in mysql\_real\_connect). This attribute was added in Connector/C 3.0.5 **Note:** If the Performance Schema is disabled, connection attributes will not be stored on server. • MYSQL\_OPT\_CONNECT\_ATTR\_DELETE Deletes a connection attribute for the given key. • MYSQL\_OPT\_CONNECT\_ATTR\_ADD Adds a key/value pair to connection attributes. The total length of the stored connection attributes is limited to a maximum of 65535 bytes. • MYSQL\_OPT\_CONNECT\_ATTR\_RESET Clears the current list of connection attributes. ## [See Also](#See_Also) *[*mysql\_init(3)*](/man/os/mariadb-12.2/mysql_init.3) [mysql\_real\_connect(3)](/man/os/mariadb-12.2/mysql_real_connect.3)* Version 3.4 --- Document: mysql_optionsv(3) from mariadb-12.2 12.2.2-r2 (Chainguard OS) Source: https://github.com/MariaDB/server.git