path: root/libmariadb/man/mysql_optionsv.3

.\"t
.\" Automatically generated by Pandoc 2.5
.\"
.TH "mysql_optionsv" "3" "" "Version 3.3.1" "MariaDB Connector/C"
.hy
.SS Name
.PP
mysql_optionsv \- Used to set extra connect options and affect behavior
of a connection
.SS Synopsis
.IP
.nf
\f[C]
#include <mysql.h>

int mysql_optionsv(MYSQL * mysql,
                   enum mysql_option,
                   const void * arg,
                   ...);
\f[R]
.fi
.SS Description
.PP
Used to set extra connect options and affect behavior for a connection.
This function may be called multiple times to set several options.
\f[C]mysql_optionsv()\f[R] should be called after
\f[B]mysql_init(3)\f[R].
.SS Options
.PP
The following table shows which variable type to use for each option.
.PP
.TS
tab(@);
lw(35.0n) lw(35.0n).
T{
Variable Type
T}@T{
Values
T}
_
T{
\f[C]my_bool\f[R]
T}@T{
\f[C]MYSQL_OPT_RECONNECT\f[R], \f[C]MYSQL_SECURE_AUTH\f[R],
\f[C]MYSQL_REPORT_DATA_TRUNCATION\f[R], \f[C]MYSQL_OPT_SSL_ENFORCE\f[R],
\f[C]MYSQL_OPT_SSL_VERIFY_SERVER_CERT\f[R]
T}
T{
\f[C]unsigned int\f[R]
T}@T{
\f[C]MYSQL_OPT_PORT\f[R], \f[C]MYSQL_OPT_LOCAL_INFILE\f[R],
\f[C]MYSQL_OPT_CONNECT_TIMEOUT\f[R], \f[C]MYSQL_OPT_PROTOCOL\f[R],
\f[C]MYSQL_OPT_READ_TIMEOUT\f[R], \f[C]MYSQL_OPT_WRITE_TIMEOUT\f[R]
T}
T{
\f[C]unsigned long\f[R]
T}@T{
\f[C]MYSQL_OPT_NET_BUFFER_LENGTH\f[R],
\f[C]MYSQL_OPT_MAX_ALLOWED_PACKET\f[R]
T}
T{
\f[C]const char *\f[R]
T}@T{
\f[C]MYSQL_INIT_COMMAND\f[R], \f[C]MARIADB_OPT_UNIXSOCKET\f[R],
\f[C]MARIADB_OPT_PASSWORD\f[R] , \f[C]MARIADB_OPT_USER\f[R],
\f[C]MARIADB_OPT_HOST\f[R], \f[C]MARIADB_OPT_SCHEMA\f[R],
\f[C]MYSQL_OPT_SSL_KEY\f[R], \f[C]MYSQL_OPT_SSL_CERT\f[R],
\f[C]MYSQL_OPT_SSL_CA\f[R], \f[C]MYSQL_OPT_SSL_CAPATH\f[R],
\f[C]MYSQL_SET_CHARSET_NAME\f[R], \f[C]MYSQL_SET_CHARSET_DIR\f[R],
\f[C]MYSQL_OPT_SSL_CIPHER\f[R], \f[C]MYSQL_SHARED_MEMORY_BASE_NAME\f[R],
\f[C]MYSQL_PLUGIN_DIR\f[R], \f[C]MYSQL_DEFAULT_AUTH\f[R],
\f[C]MARIADB_OPT_SSL_FP\f[R], \f[C]MARIADB_OPT_SSL_FP_LIST\f[R],
\f[C]MARIADB_OPT_TLS_PASSPHRASE\f[R], \f[C]MARIADB_OPT_TLS_VERSION\f[R],
\f[C]MYSQL_OPT_BIND\f[R], \f[C]MYSQL_OPT_CONNECT_ATTR_DELETE\f[R],
\f[C]MYSQL_OPT_CONNECT_ATTR_ADD\f[R],
\f[C]MARIADB_OPT_CONNECTION_HANDLER\f[R],
\f[C]MYSQL_SERVER_PUBLIC_KEY\f[R], \f[C]MARIADB_OPT_RESTRICTED_AUTH\f[R]
T}
T{
\-
T}@T{
\f[C]MYSQL_OPT_CONNECT_ATTR_RESET\f[R]
T}
T{
void *
T}@T{
\f[C]MARIADB_OPT_PROXY_HEADER\f[R]
T}
.TE
.IP \[bu] 2
\f[C]MYSQL_INIT_COMMAND\f[R]
.PD 0
.P
.PD
Command(s) which will be executed when connecting and reconnecting to
the server.
.IP \[bu] 2
\f[C]MYSQL_OPT_COMPRESS\f[R]
.PD 0
.P
.PD
Use the compressed protocol for client server communication.
If the server doesn\[cq]t support compressed protocol, the default
protocol will be used.
.IP \[bu] 2
\f[C]MYSQL_OPT_CONNECT_TIMEOUT\f[R]
.PD 0
.P
.PD
Connect timeout in seconds.
This value will be passed as an unsigned ##int## parameter.
.IP \[bu] 2
\f[C]MYSQL_OPT_LOCAL_INFILE\f[R]
.PD 0
.P
.PD
Enable or disable the use of \f[C]LOAD DATA LOCAL INFILE\f[R]
.IP \[bu] 2
\f[C]MYSQL_OPT_NAMED_PIPE\f[R]
.PD 0
.P
.PD
For Windows operating systems only: Use named pipes for client/server
communication.
.IP \[bu] 2
\f[C]MYSQL_PROGRESS_CALLBACK\f[R]
.PD 0
.P
.PD
Specifies a callback function which will be able to visualize the
progress of certain long running statements
(i.e.\ \f[C]LOAD DATA LOCAL INFILE\f[R] or \f[C]ALTER TABLE\f[R]).
The callback function must be defined as followed:
.IP
.nf
\f[C]
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)))
\f[R]
.fi
.IP \[bu] 2
\f[C]MYSQL_OPT_PROTOCOL\f[R]
.PD 0
.P
.PD
Specify the type of client/server protocol.
Possible values are: \f[C]MYSQL_PROTOCOL_TCP\f[R],
\f[C]MYSQL_PROTOCOL_SOCKET\f[R], \f[C]MYSQL_PROTOCOL_PIPE\f[R] and
\f[C]MYSQL_PROTOCOL_MEMORY\f[R].
.IP \[bu] 2
\f[C]MYSQL_OPT_RECONNECT\f[R]
.PD 0
.P
.PD
Enable or disable automatic reconnect.
.IP \[bu] 2
\f[C]MYSQL_OPT_READ_TIMEOUT\f[R]
.PD 0
.P
.PD
Specifies the timeout in seconds for reading packets from the server.
.IP \[bu] 2
\f[C]MYSQL_OPT_WRITE_TIMEOUT\f[R]
.PD 0
.P
.PD
Specifies the timeout in seconds for sending packets to the server.
.IP \[bu] 2
\f[C]MYSQL_READ_DEFAULT_FILE\f[R]
.PD 0
.P
.PD
Read options from named configuration file.
To read from default \f[C]my.cnf\f[R] configuration file, a NULL pointer
has to be passed with option MYSQL_READ_DEFAULT_GROUP.
\f[B]Note:\f[R] MariaDB Connector/C will not read the configuration by
default.
If \f[C]MYSQL_READ_DEFAULT_FILE\f[R] is specified the following sections
will be always processed:
.IP \[bu] 2
[client]
.IP \[bu] 2
[client\-server]
.IP \[bu] 2
[client\-mariadb]
.IP \[bu] 2
\f[C]MYSQL_READ_DEFAULT_GROUP\f[R]
.PD 0
.P
.PD
Read options from the named group from default configuration
file (config_files) or the file specified with MYSQL_READ_DEFAULT_FILE.
.IP \[bu] 2
\f[C]MYSQL_REPORT_DATA_TRUNCATION\f[R]
.PD 0
.P
.PD
Enable or disable reporting data truncation errors for prepared
statements.
.IP \[bu] 2
\f[C]MYSQL_OPT_BIND\f[R]
.PD 0
.P
.PD
Specify the network interface from which to connect to MariaDB Server.
.IP \[bu] 2
\f[C]MYSQL_PLUGIN_DIR\f[R]
.PD 0
.P
.PD
Specify the location of client plugins.
.IP \[bu] 2
\f[C]MYSQL_OPT_NONBLOCK\f[R]
.PD 0
.P
.PD
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.
.IP \[bu] 2
\f[C]MARIADB_OPT_CONNECTION_HANDLER\f[R]
.PD 0
.P
.PD
Specify the name of a connection handler plugin.
.IP \[bu] 2
\f[C]MARIADB_OPT_USERDATA\f[R]
.PD 0
.P
.PD
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:
.IP
.nf
\f[C]
mysql_optionsv(mysql, MARIADB_OPT_USERDATA, (void *)\[dq]ssh_user\[dq], (void *)ssh_user);
\f[R]
.fi
.IP \[bu] 2
\f[C]MARIADB_OPT_CONNECTION_READ_ONLY\f[R]
.PD 0
.P
.PD
This option is used by connection handler plugins and indicates that the
current connection will be used for read operations only.
.IP \[bu] 2
\f[C]MYSQL_OPT_CAN_HANDLE_EXPIRED_PASSWORDS\f[R]
.PD 0
.P
.PD
If this option is set, the client indicates that it will be able to
handle expired passwords by setting the
\f[C]CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS\f[R] capability flag.
If the password has expired and
\f[C]CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS\f[R] 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
(\f[C]ER_MUST_CHANGE_PASSWORD\f[R]) unless a new password was set.
This option was added in MariaDB Connector/C 3.0.4
.SS TLS/SSL and Security options
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_KEY\f[R]
.PD 0
.P
.PD
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 \f[C]MARIADB_OPT_PASSPHRASE\f[R] option.
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_CERT\f[R]
.PD 0
.P
.PD
Specify the name of a certificate for a secure connection.
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_CA\f[R]
.PD 0
.P
.PD
Specify the name of a file which contains one or more trusted CAs.
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_CAPATH\f[R]
.PD 0
.P
.PD
Specify the path which contains trusted CAs.
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_CIPHER\f[R]
.PD 0
.P
.PD
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.
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_CRL\f[R]
.PD 0
.P
.PD
Specify a file with a certificate revocation list.
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_CRLPATH\f[R]
.PD 0
.P
.PD
Specify a directory with contains files with certificate revocation
lists.
.IP \[bu] 2
\f[C]MARIADB_OPT_SSL_FP\f[R]
.PD 0
.P
.PD
Specify the SHA1 fingerprint of a server certificate for validation
during the TLS handshake.
.IP \[bu] 2
\f[C]MARIADB_OPT_SSL_FP\f[R]
.PD 0
.P
.PD
Specify a file which contains one or more SHA1 fingerprints of server
certificates for validation during the TLS handshake.
.IP \[bu] 2
\f[C]MARIADB_OPT_SSL_PASPHRASE\f[R]
.PD 0
.P
.PD
Specify a passphrase for a passphrase protected client key.
.IP \[bu] 2
\f[C]MYSQL_OPT_SSL_VERIFY_SERVER_CERT\f[R]
.PD 0
.P
.PD
Enable (or disable) the verification of the hostname against common name
(CN) of the server\[cq]s host certificate.
.IP \[bu] 2
\f[C]MYSQL_SERVER_PUBLIC_KEY\f[R]
.PD 0
.P
.PD
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
.IP \[bu] 2
\f[C]MARIADB_OPT_TLS_CIPHER_STRENGTH\f[R]
.PD 0
.P
.PD
This option is not in use anymore.
.IP \[bu] 2
\f[C]MARIADB_OPT_RESTRICTED_AUTH\f[R]
.PD 0
.P
.PD
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
.SS Proxy settings
.PP
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\[cq]s IP address
is the one set in the proxy header.
* \f[C]MARIADB_OPT_PROXY_HEADER\f[R] \- 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:
.IP
.nf
\f[C]
const char *hdr=\[dq]PROXY TCP4 192.168.0.1 192.168.0.11 56324 443\[rs]r\[rs]n\[dq];
mysql_optionsv(mysql, MARIADB_OPT_PROXY_HEADER, hdr,  strlen(hdr));
\f[R]
.fi
.SS Connection Attributes
.PP
Connection attributes are stored in the \f[C]session_connect_attrs\f[R]
and \f[C]session_account_connect_attrs\f[R]Performance Schema tables.
By default, MariaDB Connector/C sends the following connection
attributes to the server: * \f[C]_client_name\f[R]: always
\[lq]libmariadb\[rq] * \f[C]_client_version\f[R]: version of MariaDB
Connector/C * \f[C]_os\f[R]: operation system * _pid: process id *
\f[C]_platform\f[R]: e.g.\ x86 or x64 * \f[C]_server_host\f[R]: the
hostname (as specified in mysql_real_connect).
This attribute was added in Connector/C 3.0.5
.PP
\f[B]Note:\f[R] If the Performance Schema is disabled, connection
attributes will not be stored on server.
.IP \[bu] 2
\f[C]MYSQL_OPT_CONNECT_ATTR_DELETE\f[R]
.PD 0
.P
.PD
Deletes a connection attribute for the given key.
.IP \[bu] 2
\f[C]MYSQL_OPT_CONNECT_ATTR_ADD\f[R]
.PD 0
.P
.PD
Adds a key/value pair to connection attributes.
.IP \[bu] 2
\f[C]MYSQL_OPT_CONNECT_ATTR_RESET\f[R]
.PD 0
.P
.PD
Clears the current list of connection attributes.
.SS See Also
.PP
\f[I]\f[BI]mysql_init(3)\f[I] \f[R]\f[B]mysql_real_connect(3)\f[R]