mirror of
https://github.com/VCMP-SqMod/SqMod.git
synced 2024-11-08 08:47:17 +01:00
391 lines
9.9 KiB
Groff
391 lines
9.9 KiB
Groff
.\"t
|
|
.\" Automatically generated by Pandoc 2.5
|
|
.\"
|
|
.TH "mysql_optionsv" "3" "" "Version 3.2.2" "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_OPT_LOCAL_INFILE\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_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]
|
|
T}
|
|
T{
|
|
\-
|
|
T}@T{
|
|
\f[C]MYSQL_OPT_CONNECT_ATTR_RESET\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
|
|
[[configuring\-mariadb\-with\-mycnf|my.cnf]] 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.
|
|
.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]
|