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
client_flag)
Description
mysql_real_connect()
attempts to establish
a connection to a MySQL database engine running on
host
.
mysql_real_connect()
must complete
successfully before you can execute any other API functions
that require a valid MYSQL
connection
handle structure.
The parameters are specified as follows:
The first parameter should be the address of an existing
MYSQL
structure. Before calling
mysql_real_connect()
you must call
mysql_init()
to initialize the
MYSQL
structure. You can change a lot
of connect options with the
mysql_options()
call. See
Sección 24.2.3.44, “mysql_options()
”.
The value of host
may be either a
hostname or an IP address. If host
is
NULL
or the string
"localhost"
, a connection to the local
host is assumed. If the OS supports sockets (Unix) or
named pipes (Windows), they are used instead of TCP/IP to
connect to the server.
The user
parameter contains the user's
MySQL login ID. If user
is
NULL
or the empty string
""
, the current user is assumed. Under
Unix, this is the current login name. Under Windows ODBC,
the current username must be specified explicitly. See
Sección 25.1.3.2, “Configuring a Connector/ODBC DSN on Windows”.
The passwd
parameter contains the
password for user
. If
passwd
is NULL
, only
entries in the user
table for the user
that have a blank (empty) password field are checked for a
match. This allows the database administrator to set up
the MySQL privilege system in such a way that users get
different privileges depending on whether or not they have
specified a password.
Note: Do not attempt to encrypt the password before
calling mysql_real_connect()
; password
encryption is handled automatically by the client API.
db
is the database name. If
db
is not NULL
, the
connection sets the default database to this value.
If port
is not 0, the value is used as
the port number for the TCP/IP connection. Note that the
host
parameter determines the type of
the connection.
If unix_socket
is not
NULL
, the string specifies the socket
or named pipe that should be used. Note that the
host
parameter determines the type of
the connection.
The value of client_flag
is usually 0,
but can be set to a combination of the following flags in
very special circumstances:
Flag Name | Flag Description |
CLIENT_COMPRESS |
Use compression protocol. |
CLIENT_FOUND_ROWS |
Return the number of found (matched) rows, not the number of affected rows. |
CLIENT_IGNORE_SPACE |
Allow spaces after function names. Makes all functions names reserved words. |
CLIENT_INTERACTIVE |
Allow interactive_timeout seconds (instead of
wait_timeout seconds) of
inactivity before closing the connection. The
client's session wait_timeout
variable is set to the value of the session
interactive_timeout variable. |
CLIENT_LOCAL_FILES |
Enable LOAD DATA LOCAL handling. |
CLIENT_MULTI_STATEMENTS |
Tell the server that the client may send multiple statements in a single
string (separated by '; '). If
this flag is not set, multiple-statement execution
is disabled. New in 4.1. |
CLIENT_MULTI_RESULTS |
Tell the server that the client can handle multiple result sets from
multiple-statement executions or stored
procedures. This is automatically set if
CLIENT_MULTI_STATEMENTS is set.
New in 4.1. |
CLIENT_NO_SCHEMA |
Don't allow the db_name.tbl_name.col_name
syntax. This is for ODBC. It causes the parser to
generate an error if you use that syntax, which is
useful for trapping bugs in some ODBC programs. |
CLIENT_ODBC |
The client is an ODBC client. This changes mysqld to be more ODBC-friendly. |
CLIENT_SSL |
Use SSL (encrypted protocol). This option should not be set by application programs; it is set internally in the client library. |
Return Values
A MYSQL*
connection handle if the
connection was successful, NULL
if the
connection was unsuccessful. For a successful connection, the
return value is the same as the value of the first parameter.
Errors
CR_CONN_HOST_ERROR
Failed to connect to the MySQL server.
CR_CONNECTION_ERROR
Failed to connect to the local MySQL server.
CR_IPSOCK_ERROR
Failed to create an IP socket.
CR_OUT_OF_MEMORY
Out of memory.
CR_SOCKET_CREATE_ERROR
Failed to create a Unix socket.
CR_UNKNOWN_HOST
Failed to find the IP address for the hostname.
CR_VERSION_ERROR
A protocol mismatch resulted from attempting to connect to
a server with a client library that uses a different
protocol version. This can happen if you use a very old
client library to connect to a new server that wasn't
started with the --old-protocol
option.
CR_NAMEDPIPEOPEN_ERROR
Failed to create a named pipe on Windows.
CR_NAMEDPIPEWAIT_ERROR
Failed to wait for a named pipe on Windows.
CR_NAMEDPIPESETSTATE_ERROR
Failed to get a pipe handler on Windows.
CR_SERVER_LOST
If connect_timeout
> 0 and it took
longer than connect_timeout
seconds to
connect to the server or if the server died while
executing the init-command
.
Example
MYSQL mysql; mysql_init(&mysql); mysql_options(&mysql,MYSQL_READ_DEFAULT_GROUP,"your_prog_name"); if (!mysql_real_connect(&mysql,"host","user","passwd","database",0,NULL,0)) { fprintf(stderr, "Failed to connect to database: Error: %s\n", mysql_error(&mysql)); }
By using mysql_options()
the MySQL library
reads the [client]
and
[your_prog_name]
sections in the
my.cnf
file which ensures that your
program works, even if someone has set up MySQL in some
non-standard way.
Note that upon connection,
mysql_real_connect()
sets the
reconnect
flag (part of the
MYSQL
structure) to a value of
1
in versions of the API strictly older
than 5.0.3, of 0
in newer versions. A value
of 1
for this flag indicates, in the event
that a query cannot be performed because of a lost connection,
to try reconnecting to the server before giving up.
Ésta es una traducción del manual de referencia de MySQL, que puede encontrarse en dev.mysql.com. El manual de referencia original de MySQL está escrito en inglés, y esta traducción no necesariamente está tan actualizada como la versión original. Para cualquier sugerencia sobre la traducción y para señalar errores de cualquier tipo, no dude en dirigirse a mysql-es@vespito.com.