diff options
Diffstat (limited to 'libmariadb/man/mysql_optionsv.3')
| -rw-r--r-- | libmariadb/man/mysql_optionsv.3 | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/libmariadb/man/mysql_optionsv.3 b/libmariadb/man/mysql_optionsv.3 new file mode 100644 index 00000000..b59e0ff4 --- /dev/null +++ b/libmariadb/man/mysql_optionsv.3 @@ -0,0 +1,420 @@ +.\"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] |