.\"t
.\" Automatically generated by Pandoc 2.5
.\"
.TH "mysql_real_connect" "3" "" "Version 3.3.1" "MariaDB Connector/C"
.hy
.SS Name
.PP
mysql_real_connect \- establishes a connection to a MariaDB database
server
.SS Synopsis
.IP
.nf
\f[C]
MYSQL * mysql_real_connect(MYSQL *mysql,
                           const char *host,
                           const char *user,
                           const char *passwd,
                           const char *db,
                           unsigned int port,
                           const char *unix_socket,
                           unsigned long flags);
\f[R]
.fi
.SS Description
.PP
Establishes a connection to a database server.
.SS Parameter
.IP \[bu] 2
\f[C]mysql\f[R] \- a mysql handle, which was previously allocated by
\f[B]mysql_init(3)\f[R]
.IP \[bu] 2
\f[C]host\f[R] \- can be either a host name or an IP address.
Passing the NULL value or the string \[lq]localhost\[rq] to this
parameter, the local host is assumed.
When possible, pipes will be used instead of the TCP/IP protocol.
Since version 3.3.0 it is also possible to provide a comma separated
list of hosts for simple fail over in case of one or more hosts are not
available.
.IP \[bu] 2
\f[C]user\f[R] \- the user name.
.IP \[bu] 2
\f[C]passwd\f[R] \- If provided or NULL, the server will attempt to
authenticate the user against those user records which have no password
only.
This allows one username to be used with different permissions
(depending on if a password as provided or not).
.IP \[bu] 2
\f[C]db\f[R] \- if provided will specify the default database to be used
when performing queries.
.IP \[bu] 2
\f[C]port\f[R] \- specifies the port number to attempt to connect to the
server.
.IP \[bu] 2
\f[C]unix_socket\f[R] \- specifies the socket or named pipe that should
be used.
.IP \[bu] 2
\f[C]flags\f[R] \- the flags allows various connection options to be set
.PD 0
.P
.PD
.PP
.TS
tab(@);
lw(35.0n) lw(35.0n).
T{
Flag
T}@T{
Description
T}
_
T{
\f[C]CLIENT_FOUND_ROWS\f[R]
T}@T{
Return the number of matched rows instead of number of changed rows.
T}
T{
\f[C]CLIENT_NO_SCHEMA\f[R]
T}@T{
Forbids the use of database.tablename.column syntax and forces the SQL
parser to generate an error.
T}
T{
\f[C]CLIENT_COMPRESS\f[R]
T}@T{
Use compression protocol
T}
T{
\f[C]CLIENT_IGNORE_SPACE\f[R]
T}@T{
Allows spaces after function names.
All function names will become reserved words.
T}
T{
\f[C]CLIENT_LOCAL_FILES\f[R]
T}@T{
Allows LOAD DATA LOCAL statements
T}
T{
\f[C]CLIENT_MULTI_STATEMENTS\f[R]
T}@T{
Allows the client to send multiple statements in one command.
Statements will be divided by a semicolon.
T}
T{
\f[C]CLIENT_MULTI_RESULTS\f[R]
T}@T{
Indicates that the client is able to handle multiple result sets from
stored procedures or multi statements.
This option will be automatically set if CLIENT_MULTI_STATEMENTS is set.
T}
T{
\f[C]CLIENT_REMEMBER_OPTIONS\f[R]
T}@T{
Rembers options passed to \f[B]mysql_optionsv(3)\f[R] if a connect
attempt failed.
If MYSQL_OPTIONS_RECONNECT option was set to true, options will be saved
and used for reconnection.
T}
.TE
.SS Return value
.PP
returns a connection handle (same as passed for 1st parameter) or NULL
on error.
On error, please check \f[B]mysql_errno(3)\f[R] and
\f[B]mysql_error(3)\f[R] functions for more information.
.SS Notes
.IP \[bu] 2
The password doesn\[cq]t need to be encrypted before executing
mysql_real_connect().
This will be handled in the client server protocol.
.IP \[bu] 2
The connection handle can\[cq]t be reused for establishing a new
connection.
It must be closed and reinitialized before.
.IP \[bu] 2
mysql_real_connect() must complete successfully before you can execute
any other API functions beside \f[B]mysql_optionsv(3)\f[R].
.IP \[bu] 2
host parameter may contain multiple host/port combinations (supported
since version 3.3.0).
The following syntax is required:
.RS 2
.IP \[bu] 2
hostname and port must be seperated by a colon (:)
.IP \[bu] 2
IPv6 addresses must be enclosed within square brackets
.IP \[bu] 2
hostname:port pairs must be be seperated by a comma (,)
.IP \[bu] 2
if only one host:port was specified, the host string needs to end with a
comma.
.IP \[bu] 2
if no port was specified, the default port will be used.
.PP
\f[B]Examples for failover host string:\f[R]
.PP
\f[C]host=[::1]:3306,192.168.0.1:3306,test.example.com\f[R]
.PP
\f[C]host=127.0.0.1:3306,\f[R]
.RE
.SS See also
.IP \[bu] 2
\f[B]mysql_init(3)\f[R]
.IP \[bu] 2
\f[B]mysql_close(3)\f[R]
.IP \[bu] 2
\f[B]mariadb_reconnect(3)\f[R]
.IP \[bu] 2
\f[B]mysql_error(3)\f[R]
.IP \[bu] 2
\f[B]mysql_errno(3)\f[R]