Adding upstream version 1:10.11.6.upstream/1%10.11.6upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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]