|
C API Function Descriptions
In the descriptions below, a parameter or return value of
NULL means
NULL in the sense of the
C programming language, not a MySQL
NULL value.
Functions that return a value generally return a pointer or an integer.
Unless specified otherwise, functions returning a pointer return a
non-NULL value to
indicate success or a
NULL value to indicate
an error, and functions returning an integer return zero to indicate success or
non-zero to indicate an error. Note that ´´non-zero'' means just that.
Unless the function description says otherwise, do not test against a value
other than zero:
if (result)
/* correct */
... error
...
if (result < 0)
/* incorrect */
... error
...
if (result == -1)
/* incorrect */
... error
...
When a function returns an error, the Errors subsection of the
function description lists the possible types of errors. You can find out which
of these occurred by calling
mysql_errno(). A string
representation of the error may be obtained by calling
mysql_error().
my_ulonglong
mysql_affected_rows(MYSQL *mysql)
Description
Returns the number of rows changed by the last
UPDATE, deleted by the
last DELETE or inserted
by the last INSERT
statement. May be called immediately after
mysql_query() for
UPDATE,
DELETE, or
INSERT statements. For
SELECT statements,
mysql_affected_rows()
works like
mysql_num_rows().
Return Values
An integer greater than zero indicates the number of rows affected or
retrieved. Zero indicates that no records where updated for an
UPDATE statement, no
rows matched the WHERE
clause in the query or that no query has yet been executed. -1 indicates that
the query returned an error or that, for a
SELECT query,
mysql_affected_rows()
was called prior to calling
mysql_store_result()
Errors
None.
void mysql_close(MYSQL
*mysql)
Description
Closes a previously opened connection.
mysql_close() also
deallocates the connection handle pointed to by
mysql if the handle was
allocated automatically by
mysql_init() or
mysql_connect().
Return Values
None.
Errors
None
mysql_connect()
MYSQL *mysql_connect(MYSQL
*mysql, const char *host, const char *user, const char *passwd)
Description
This function is deprecated. It is preferable to use
mysql_real_connect()
instead.
mysql_connect()
attempts to establish a connection to a MySQL database engine running on
host.
mysql_connect() must
complete successfully before you can execute any of the other API functions,
with the exception of
mysql_get_client_info().
The meanings of the parameters are the same as for the corresponding
parameters for
mysql_real_connect()
with the difference that the connection parameter may be
NULL. In this case the C
API allocates memory for the connection structure automatically and frees it
when you call
mysql_close(). The
disadvantage of this approach is that you can't retrieve an error message if the
connection fails. (To get error information from
mysql_errno() or
mysql_error(), you must
provide a valid MYSQL
pointer.)
Return Values
Same as for
mysql_real_connect().
Errors
Same as for
mysql_real_connect().
my_bool mysql_change_user(MYSQL
*mysql, const char *user, const char *password, const char *db)
Description
Changes the user and causes the database specified by
db to become the default
(current) database on the connection specified by
mysql. In subsequent
queries, this database is the default for table references that do not include
an explicit database specifier.
This function was introduced in MySQL Version 3.23.3.
mysql_change_user()
fails unless the connected user can be authenticated or if he doesn't have
permission to use the database. In this case the user and database are not
changed
The db parameter
may be set to NULL if
you don't want to have a default database.
Return values
Zero for success. Non-zero if an error occurred.
Errors
The same that you can get from
mysql_real_connect().
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
ER_UNKNOWN_COM_ERROR
The MySQL server
doesn't implement this command (probably an old server)
ER_ACCESS_DENIED_ERROR
The user or
password was wrong.
ER_BAD_DB_ERROR
The database
didn't exist.
ER_DBACCESS_DENIED_ERROR
The user did not
have access rights to the database.
ER_WRONG_DB_NAME
The database name
was too long.
const char
*mysql_character_set_name(MYSQL *mysql
Description
Returns the default character set for the current connection.
Return Values
The default character set
Errors
None.
int mysql_create_db(MYSQL
*mysql, const char *db)
Description
Creates the database named by the
db parameter.
This function is deprecated. It is preferable to use
mysql_query() to issue a
SQL CREATE DATABASE
statement instead.
Return Values
Zero if the database was created successfully. Non-zero if an error
occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
void mysql_data_seek(MYSQL_RES
*result, unsigned long long offset)
Description
Seeks to an arbitrary row in a query result set. This requires that the
result set structure contains the entire result of the query, so
mysql_data_seek() may be
used in conjunction only with
mysql_store_result(),
not with
mysql_use_result().
The offset should be a value in the range from 0 to
mysql_num_rows(result)-1.
Return Values
None.
Errors
None.
void mysql_debug(char
*debug)
Description
Does a DBUG_PUSH
with the given string.
mysql_debug() uses the
Fred Fish debug library. To use this function, you must compile the client
library to support debugging.
Return Values
None.
Errors
None.
int mysql_drop_db(MYSQL *mysql,
const char *db)
Description
Drops the database named by the
db parameter.
This function is deprecated. It is preferable to use
mysql_query() to issue a
SQL DROP DATABASE
statement instead.
Return Values
Zero if the database was dropped successfully. Non-zero if an error
occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
int mysql_dump_debug_info(MYSQL
*mysql)
Description
Instructs the server to write some debug information to the log. The
connected user must have the process privilege for this to work.
Return values
Zero if the command was successful. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
my_bool mysql_eof(MYSQL_RES
*result)
Description
This function is deprecated.
mysql_errno() or
mysql_error() may be
used instead.
mysql_eof()
determines whether or not the last row of a result set has been read.
If you acquire a result set from a successful call to
mysql_store_result(),
the client receives the entire set in one operation. In this case, a
NULL return from
mysql_fetch_row() always
means the end of the result set has been reached and it is unnecessary to call
mysql_eof().
On the other hand, if you use
mysql_use_result() to
initiate a result set retrieval, the rows of the set are obtained from the
server one by one as you call
mysql_fetch_row()
repeatedly. Because an error may occur on the connection during this process, a
NULL return value from
mysql_fetch_row() does
not necessarily mean the end of the result set was reached normally. In this
case, you can use
mysql_eof() to determine
what happened.
mysql_eof() returns a
non-zero value if the end of the result set was reached and zero if an error
occurred.
Historically,
mysql_eof() predates the
standard MySQL error functions
mysql_errno() and
mysql_error(). Because
those error functions provide the same information, their use is preferred over
mysql_eof(), which is
now deprecated. (In fact, they provide more information, because
mysql_eof() returns only
a boolean value whereas the error functions indicate a reason for the error when
one occurs.)
Return Values
Zero if no error occurred. Non-zero if the end of the result set has been
reached.
Errors
None.
)
Description
For the connection specified by
mysql,
mysql_errno() returns
the error code for the most recently invoked API function that can succeed or
fail. A return value of zero means that no error occurred. Client error message
numbers are listed in the MySQL
´errmsg.h' header
file. Server error message numbers are listed in
´mysqld_error.h'. In
the MySQL source distribution you can find a complete list of error messages and
error numbers in the file
´Docs/mysqld_error.txt'.
Return Values
An error code value. Zero if no error occurred.
Errors
None.
char *mysql_error(MYSQL
*mysql)
Description
For the connection specified by
mysql,
mysql_error() returns
the error message for the most recently invoked API function that can succeed or
fail. An empty string
("") is returned if no
error occurred. This means the following two tests are equivalent:
if(mysql_errno(&mysql))
{
// an error
occurred
}
if(mysql_error(&mysql)[0]
!= '\0')
{
// an error
occurred
}
The language of the client error messages may be changed by recompiling the
MySQL client library. Currently you can choose error messages in several
different languages..
Return Values
A character string that describes the error. An empty string if no error
occurred.
Errors
None.
You should use
mysql_real_escape_string()
instead!
This is identical to
mysql_real_escape_string()
except that it takes the connection as the first argument.
mysql_real_escape_string()
will escape the string according to the current character set while
mysql_escape_string()
does not respect the current charset setting.
MYSQL_FIELD
*mysql_fetch_field(MYSQL_RES *result)
Description
Returns the definition of one column of a result set as a
MYSQL_FIELD structure.
Call this function repeatedly to retrieve information about all columns in the
result set.
mysql_fetch_field()
returns NULL when no
more fields are left.
mysql_fetch_field()
is reset to return information about the first field each time you execute a new
SELECT query. The field
returned by
mysql_fetch_field() is
also affected by calls to
mysql_field_seek().
If you've called
mysql_query() to perform
a SELECT on a table but
have not called
mysql_store_result(),
MySQL returns the default blob length (8K bytes) if you call
mysql_fetch_field() to
ask for the length of a
BLOB field. (The 8K size
is chosen because MySQL doesn't know the maximum length for the
BLOB. This should be
made configurable sometime.) Once you've retrieved the result set,
field->max_length
contains the length of the largest value for this column in the specific query.
Return Values
The MYSQL_FIELD
structure for the current column.
NULL if no columns are
left.
Errors
None.
8.4. Example
MYSQL_FIELD
*field;
while((field =
mysql_fetch_field(result)))
{
printf("field name %s\n",
field->name);
}
MYSQL_FIELD
*mysql_fetch_fields(MYSQL_RES *result)
Description
Returns an array of all
MYSQL_FIELD structures
for a result set. Each structure provides the field definition for one column of
the result set.
Return Values
An array of
MYSQL_FIELD structures
for all columns of a result set.
Errors
None.
MYSQL_FIELD
*mysql_fetch_field_direct(MYSQL_RES *result, unsigned int fieldnr)
Description
Given a field number
fieldnr for a column
within a result set, returns that column's field definition as a
MYSQL_FIELD structure.
You may use this function to retrieve the definition for an arbitrary column.
The value of fieldnr
should be in the range from 0 to
mysql_num_fields(result)-1.
Return Values
The MYSQL_FIELD
structure for the specified column
Errors
None.
unsigned long
*mysql_fetch_lengths(MYSQL_RES *result)
Description
Returns the lengths of the columns of the current row within a result set.
If you plan to copy field values, this length information is also useful for
optimization, because you can avoid calling
strlen(). In addition,
if the result set contains binary data, you must use this function to
determine the size of the data, because
strlen() returns
incorrect results for any field containing null characters.
The length for empty columns and for columns containing
NULL values is zero. To
see how to distinguish these two cases, see the description for
mysql_fetch_row().
Return Values
An array of unsigned long integers representing the size of each column
(not including any terminating null characters).
NULL if an error
occurred.
Errors
mysql_fetch_lengths()
is valid only for the current row of the result set. It returns
NULL if you call it
before calling
mysql_fetch_row() or
after retrieving all rows in the result.
MYSQL_ROW
mysql_fetch_row(MYSQL_RES *result)
Description
Retrieves the next row of a result set. When used after
mysql_store_result(),
mysql_fetch_row()
returns NULL when there
are no more rows to retrieve. When used after
mysql_use_result(),
mysql_fetch_row()
returns NULL when there
are no more rows to retrieve or if an error occurred.
The number of values in the row is given by
mysql_num_fields(result).
If row holds the return
value from a call to
mysql_fetch_row(),
pointers to the values are accessed as
row[0] to
row[mysql_num_fields(result)-1].
NULL values in the row
are indicated by NULL
pointers.
The lengths of the field values in the row may be obtained by calling
mysql_fetch_lengths().
Empty fields and fields containing
NULL both have length 0;
you can distinguish these by checking the pointer for the field value. If the
pointer is NULL, the
field is NULL; otherwise
the field is empty.
Return Values
A MYSQL_ROW
structure for the next row.
NULL if there are no
more rows to retrieve or if an error occurred.
Errors
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
unsigned int
mysql_field_count(MYSQL *mysql)
If you are using a version of MySQL earlier than Version 3.22.24, you
should use unsigned int
mysql_num_fields(MYSQL *mysql) instead.
Description
Returns the number of columns for the most recent query on the connection.
The normal use of this function is when
mysql_store_result()
returned NULL (and thus
you have no result set pointer). In this case, you can call
mysql_field_count() to
determine whether or not
mysql_store_result()
should have produced a non-empty result. This allows the client program to take
proper action without knowing whether or not the query was a
SELECT (or
SELECT-like) statement.
The example shown below illustrates how this may be done.
Return Values
An unsigned integer representing the number of fields in a result set.
Errors
None.
MYSQL_FIELD_OFFSET
mysql_field_seek(MYSQL_RES *result, MYSQL_FIELD_OFFSET offset)
* Threaded clients:: How to Make a Threaded Client
Description
Sets the field cursor to the given offset. The next call to
mysql_fetch_field() will
retrieve the field definition of the column associated with that offset.
To seek to the beginning of a row, pass an
offset value of zero.
Return Values
The previous value of the field cursor.
Errors
None.
MYSQL_FIELD_OFFSET
mysql_field_tell(MYSQL_RES *result)
Description
Returns the position of the field cursor used for the last
mysql_fetch_field().
This value can be used as an argument to
mysql_field_seek().
Return Values
The current offset of the field cursor.
Errors
None.
void
mysql_free_result(MYSQL_RES *result)
Description
Frees the memory allocated for a result set by
mysql_store_result(),
mysql_use_result(),
mysql_list_dbs(), etc.
When you are done with a result set, you must free the memory it uses by calling
mysql_free_result().
Return Values
None.
Errors
None.
char
*mysql_get_client_info(void)
Description
Returns a string that represents the client library version.
Return Values
A character string that represents the MySQL client library version.
Errors
None.
char *mysql_get_host_info(MYSQL
*mysql)
Description
Returns a string describing the type of connection in use, including the
server host name.
Return Values
A character string representing the server host name and the connection
type.
Errors
None.
unsigned int
mysql_get_proto_info(MYSQL *mysql)
Description
Returns the protocol version used by current connection.
Return Values
An unsigned integer representing the protocol version used by the current
connection.
Errors
None.
char
*mysql_get_server_info(MYSQL *mysql)
Description
Returns a string that represents the server version number.
Return Values
A character string that represents the server version number.
Errors
None.
char *mysql_info(MYSQL
*mysql)
Description
Retrieves a string providing information about the most recently executed
query, but only for the statements listed below. For other statements,
mysql_info() returns
NULL. The format of the
string varies depending on the type of query, as described below. The numbers
are illustrative only; the string will contain values appropriate for the query.
INSERT INTO ... SELECT
...
String format:
Records: 100 Duplicates: 0 Warnings:
0
INSERT INTO ... VALUES
(...),(...),(...)...
String format:
Records: 3 Duplicates: 0 Warnings:
0
LOAD DATA INFILE
...
String format:
Records: 1 Deleted: 0 Skipped: 0
Warnings: 0
ALTER TABLE
String format:
Records: 3 Duplicates: 0 Warnings:
0
UPDATE
String format:
Rows matched: 40 Changed: 40
Warnings: 0
Note that
mysql_info() returns a
non-NULL value for the
INSERT ... VALUES
statement only if multiple value lists are specified in the statement.
Return Values
A character string representing additional information about the most
recently executed query.
NULL if no information
is available for the query.
Errors
None.
MYSQL *mysql_init(MYSQL
*mysql)
Description
Allocates or initializes a
MYSQL object suitable
for
mysql_real_connect(). If
mysql is a
NULL pointer, the
function allocates, initializes, and returns a new object. Otherwise the object
is initialized and the address of the object is returned. If
mysql_init() allocates a
new object, it will be freed when
mysql_close() is called
to close the connection.
Return Values
An initialized
MYSQL* handle.
NULL if there was
insufficient memory to allocate a new object.
Errors
In case of insufficient memory,
NULL is returned.
my_ulonglong
mysql_insert_id(MYSQL *mysql)
Description
Returns the ID generated for an
AUTO_INCREMENT column by
the previous query. Use this function after you have performed an
INSERT query into a
table that contains an
AUTO_INCREMENT field.
Note that
mysql_insert_id()
returns 0 if the
previous query does not generate an
AUTO_INCREMENT value. If
you need to save the value for later, be sure to call
mysql_insert_id()
immediately after the query that generates the value.
mysql_insert_id()
is updated after INSERT
and UPDATE statements
that generate an
AUTO_INCREMENT value or
that set a column value to
LAST_INSERT_ID(expr).
Also note that the value of the SQL
LAST_INSERT_ID()
function always contains the most recently generated
AUTO_INCREMENT value,
and is not reset between queries because the value of that function is
maintained in the server.
Return Values
The value of the
AUTO_INCREMENT field
that was updated by the previous query. Returns zero if there was no previous
query on the connection or if the query did not update an
AUTO_INCREMENT value.
Errors
None.
int mysql_kill(MYSQL *mysql,
unsigned long pid)
Description
Asks the server to kill the thread specified by
pid.
Return Values
Zero for success. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
MYSQL_RES *mysql_list_dbs(MYSQL
*mysql, const char *wild)
Description
Returns a result set consisting of database names on the server that match
the simple regular expression specified by the
wild parameter.
wild may contain the
wild-card characters
´%' or
´_', or may be a
NULL pointer to match
all databases. Calling
mysql_list_dbs() is
similar to executing the query SHOW
databases [LIKE wild].
You must free the result set with
mysql_free_result().
Return Values
A MYSQL_RES result
set for success. NULL if
an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
MYSQL_RES
*mysql_list_fields(MYSQL *mysql, const char *table, const char
*wild)
Description
Returns a result set consisting of field names in the given table that
match the simple regular expression specified by the
wild parameter.
wild may contain the
wild-card characters
´%' or
´_', or may be a
NULL pointer to match
all fields. Calling
mysql_list_fields() is
similar to executing the query SHOW
COLUMNS FROM tbl_name [LIKE wild].
Note that it's recommended that you use
SHOW COLUMNS FROM
tbl_name instead of
mysql_list_fields().
You must free the result set with
mysql_free_result().
Return Values
A MYSQL_RES result
set for success. NULL if
an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
MYSQL_RES
*mysql_list_processes(MYSQL *mysql)
Description
Returns a result set describing the current server threads. This is the
same kind of information as that reported by
mysqladmin processlist
or a SHOW PROCESSLIST
query.
You must free the result set with
mysql_free_result().
Return Values
A MYSQL_RES result
set for success. NULL if
an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
MYSQL_RES
*mysql_list_tables(MYSQL *mysql, const char *wild)
Description
Returns a result set consisting of table names in the current database that
match the simple regular expression specified by the
wild parameter.
wild may contain the
wild-card characters
´%' or
´_', or may be a
NULL pointer to match
all tables. Calling
mysql_list_tables() is
similar to executing the query SHOW
tables [LIKE wild].
You must free the result set with
mysql_free_result().
Return Values
A MYSQL_RES result
set for success. NULL if
an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
unsigned int
mysql_num_fields(MYSQL_RES *result)
or
unsigned int
mysql_num_fields(MYSQL *mysql)
The second form doesn't work on MySQL Version 3.22.24 or newer. To pass a
MYSQL* argument, you
must use unsigned int
mysql_field_count(MYSQL *mysql) instead.
Description
Returns the number of columns in a result set.
Note that you can get the number of columns either from a pointer to a
result set or to a connection handle. You would use the connection handle if
mysql_store_result() or
mysql_use_result()
returned NULL (and thus
you have no result set pointer). In this case, you can call
mysql_field_count() to
determine whether or not
mysql_store_result()
should have produced a non-empty result. This allows the client program to take
proper action without knowing whether or not the query was a
SELECT (or
SELECT-like) statement.
The example shown below illustrates how this may be done.
. Return Values
An unsigned integer representing the number of fields in a result set.
Errors
None.
my_ulonglong
mysql_num_rows(MYSQL_RES *result)
Description
Returns the number of rows in the result set.
The use of
mysql_num_rows() depends
on whether you use
mysql_store_result() or
mysql_use_result() to
return the result set. If you use
mysql_store_result(),
mysql_num_rows() may be
called immediately. If you use
mysql_use_result(),
mysql_num_rows() will
not return the correct value until all the rows in the result set have been
retrieved.
Return Values
The number of rows in the result set.
Errors
None.
int mysql_options(MYSQL *mysql,
enum mysql_option option, const char *arg)
Description
Can be used to set extra connect options and affect behavior for a
connection. This function may be called multiple times to set several options.
mysql_options()
should be called after
mysql_init() and before
mysql_connect() or
mysql_real_connect().
The option argument
is the option that you want to set; the
arg argument is the
value for the option. If the option is an integer, then
arg should point to the
value of the integer.
Possible options values:
|
Option
|
Argument type
|
Function
|
|
MYSQL_OPT_CONNECT_TIMEOUT
|
unsigned int *
|
Connect timeout in seconds.
|
|
MYSQL_OPT_COMPRESS
|
Not used
|
Use the compressed client/server protocol.
|
|
MYSQL_OPT_NAMED_PIPE
|
Not used
|
Use named pipes to connect to a MySQL server on NT.
|
|
MYSQL_INIT_COMMAND
|
char *
|
Command to execute when connecting to the MySQL server. Will automatically
be re-executed when reconnecting.
|
|
MYSQL_READ_DEFAULT_FILE
|
char *
|
Read options from the named option file instead of from
´my.cnf'.
|
|
MYSQL_READ_DEFAULT_GROUP
|
char *
|
Read options from the named group from
´my.cnf' or the file
specified with
MYSQL_READ_DEFAULT_FILE.
|
Note that the group
client is always read if
you use
MYSQL_READ_DEFAULT_FILE
or
MYSQL_READ_DEFAULT_GROUP.
The specified group in the option file may contain the following options:
|
connect_timeout
|
Connect timeout in seconds. On Linux this timeout is also used for waiting
for the first answer from the server.
|
|
compress
|
Use the compressed client/server protocol.
|
|
database
|
Connect to this database if no database was specified in the connect
command.
|
|
debug
|
Debug options.
|
|
host
|
Default host name.
|
|
init-command
|
Command to execute when connecting to MySQL server. Will automatically be
re-executed when reconnecting.
|
|
interactive-timeout
|
|
|
password
|
Default password.
|
|
pipe
|
Use named pipes to connect to a MySQL server on NT.
|
|
port
|
Default port number.
|
|
return-found-rows
|
Tell mysql_info()
to return found rows instead of updated rows when using
UPDATE.
|
|
socket
|
Default socket number.
|
|
|
|
user
|
Default user.
|
Note that timeout
has been replaced by
connect_timeout, but
timeout will still work
for a while.
Return Values
Zero for success. Non-zero if you used an unknown option.
int mysql_ping(MYSQL
*mysql)
Description
Checks whether or not the connection to the server is working. If it has
gone down, an automatic reconnection is attempted.
This function can be used by clients that remain idle for a long while, to
check whether or not the server has closed the connection and reconnect if
necessary.
Return Values
Zero if the server is alive. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_UNKNOWN_ERROR
An unknown error
occurred.
int mysql_query(MYSQL *mysql,
const char *query)
Description
Executes the SQL query pointed to by the null-terminated string
query. The query must
consist of a single SQL statement. You should not add a terminating semicolon
(´;') or
\g
to the statement.
mysql_query()
cannot be used for queries that contain binary data; you should use
mysql_real_query()
instead. (Binary data may contain the
´\0' character, which
mysql_query() interprets
as the end of the query string.)
If you want to know if the query should return a result set or not, you can
use mysql_field_count()
to check for this. See section
8.4.3.85 mysql_field_count().
Return Values
Zero if the query was successful. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
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 int
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 of the other API
functions, with the exception of
mysql_get_client_info().
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 section
8.4.3.159 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, the current user
is assumed. Under Unix, this is the current login name. Under Windows ODBC, the
current user name must be specified explicitly.
- 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 will be 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
will set the default database to this value.
- If port is not 0,
the value will be 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 meaning
mysqld to be more
ODBC-friendly.
|
|
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.
|
|
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
|
|
CLIENT_SSL
|
Use SSL (encrypted protocol).
|
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, unless you pass
NULL for that 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 then
connect_timeout seconds
to connect to the server or if the server died while executing the
init-command.
unsigned int
mysql_real_escape_string(MYSQL *mysql, char *to, const char *from, unsigned int
length)
Description
This function is used to create a legal SQL string that you can use in a
SQL statement..
The string in from
is encoded to an escaped SQL string, taking into account the current character
set of the connection. The result is placed in
to and a terminating
null byte is appended. Characters encoded are
NUL (ASCII 0),
´\n',
´\r',
´\',
´'',
´"', and Control-Z
.
The string pointed to by
from must be
length bytes long. You
must allocate the to
buffer to be at least
length*2+1 bytes long.
(In the worse case, each character may need to be encoded as using two bytes,
and you need room for the terminating null byte.) When
mysql_escape_string()
returns, the contents of
to will be a
null-terminated string. The return value is the length of the encoded string,
not including the terminating null character.
.
Return Values
The length of the value placed into
to, not including the
terminating null character.
Errors
None.
int mysql_real_query(MYSQL
*mysql, const char *query, unsigned int length)
Description
Executes the SQL query pointed to by
query, which should be a
string length bytes
long. The query must consist of a single SQL statement. You should not add a
terminating semicolon
(´;') or
\g
to the statement.
You must use
mysql_real_query()
rather than
mysql_query() for
queries that contain binary data, because binary data may contain the
´\0' character. In
addition,
mysql_real_query() is
faster than
mysql_query() because it
does not call strlen()
on the query string.
If you want to know if the query should return a result set or not, you can
use mysql_field_count()
to check for this.
Return Values
Zero if the query was successful. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
int mysql_reload(MYSQL
*mysql)
Description
Asks the MySQL server to reload the grant tables. The connected user must
have the reload privilege.
This function is deprecated. It is preferable to use
mysql_query() to issue a
SQL FLUSH PRIVILEGES
statement instead.
Return Values
Zero for success. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
MYSQL_ROW_OFFSET
mysql_row_seek(MYSQL_RES *result, MYSQL_ROW_OFFSET offset)
Description
Sets the row cursor to an arbitrary row in a query result set. This
requires that the result set structure contains the entire result of the query,
so mysql_row_seek() may
be used in conjunction only with
mysql_store_result(),
not with
mysql_use_result().
The offset should be a value returned from a call to
mysql_row_tell() or to
mysql_row_seek(). This
value is not simply a row number; if you want to seek to a row within a result
set using a row number, use
mysql_data_seek()
instead.
Return Values
The previous value of the row cursor. This value may be passed to a
subsequent call to
mysql_row_seek().
Errors
None.
MYSQL_ROW_OFFSET
mysql_row_tell(MYSQL_RES *result)
Description
Returns the current position of the row cursor for the last
mysql_fetch_row(). This
value can be used as an argument to
mysql_row_seek().
You should use
mysql_row_tell() only
after
mysql_store_result(),
not after
mysql_use_result().
Return Values
The current offset of the row cursor.
Errors
None.
int mysql_select_db(MYSQL
*mysql, const char *db)
Description
Causes the database specified by
db to become the default
(current) database on the connection specified by
mysql. In subsequent
queries, this database is the default for table references that do not include
an explicit database specifier.
mysql_select_db()
fails unless the connected user can be authenticated as having permission to use
the database.
Return Values
Zero for success. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
int mysql_shutdown(MYSQL
*mysql)
Description
Asks the database server to shut down. The connected user must have
shutdown privileges.
Return Values
Zero for success. Non-zero if an error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
char *mysql_stat(MYSQL
*mysql)
Description
Returns a character string containing information similar to that provided
by the mysqladmin status
command. This includes uptime in seconds and the number of running threads,
questions, reloads, and open tables.
Return Values
A character string describing the server status.
NULL if an error
occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
MYSQL_RES
*mysql_store_result(MYSQL *mysql)
Description
You must call
mysql_store_result() or
mysql_use_result() for
every query that successfully retrieves data
(SELECT,
SHOW,
DESCRIBE,
EXPLAIN).
You don't have to call
mysql_store_result() or
mysql_use_result() for
other queries, but it will not do any harm or cause any notable performance if
you call
mysql_store_result() in
all cases. You can detect if the query didn't have a result set by checking if
mysql_store_result()
returns 0 (more about this later one).
If you want to know if the query should return a result set or not, you can
use mysql_field_count()
to check for this. See section
8.4.3.85 mysql_field_count().
mysql_store_result()
reads the entire result of a query to the client, allocates a
MYSQL_RES structure, and
places the result into this structure.
mysql_store_results()
returns a null pointer if the query didn't return a result set (if the query
was, for example, an
INSERT statement).
mysql_store_results()
also returns a null pointer if reading of the result set failed. You can check
if you got an error by checking if
mysql_error() doesn't
return a null pointer, if
mysql_errno() returns
<> 0, or if
mysql_field_count()
returns <> 0.
An empty result set is returned if there are no rows returned. (An empty
result set differs from a null pointer as a return value.)
Once you have called
mysql_store_result() and
got a result back that isn't a null pointer, you may call
mysql_num_rows() to find
out how many rows are in the result set.
You can call
mysql_fetch_row() to
fetch rows from the result set, or
mysql_row_seek() and
mysql_row_tell() to
obtain or set the current row position within the result set.
You must call
mysql_free_result() once
you are done with the result set.
.
Return Values
A MYSQL_RES result
structure with the results.
NULL if an error
occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
unsigned long
mysql_thread_id(MYSQL *mysql)
Description
Returns the thread ID of the current connection. This value can be used as
an argument to
mysql_kill() to kill the
thread.
If the connection is lost and you reconnect with
mysql_ping(), the thread
ID will change. This means you should not get the thread ID and store it for
later. You should get it when you need it.
Return Values
The thread ID of the current connection.
Errors
None.
MYSQL_RES
*mysql_use_result(MYSQL *mysql)
Description
You must call
mysql_store_result() or
mysql_use_result() for
every query that successfully retrieves data
(SELECT,
SHOW,
DESCRIBE,
EXPLAIN).
mysql_use_result()
initiates a result set retrieval but does not actually read the result set into
the client like
mysql_store_result()
does. Instead, each row must be retrieved individually by making calls to
mysql_fetch_row(). This
reads the result of a query directly from the server without storing it in a
temporary table or local buffer, which is somewhat faster and uses much less
memory than
mysql_store_result().
The client will only allocate memory for the current row and a communication
buffer that may grow up to
max_allowed_packet
bytes.
On the other hand, you shouldn't use
mysql_use_result() if
you are doing a lot of processing for each row on the client side, or if the
output is sent to a screen on which the user may type a
^S (stop scroll). This
will tie up the server and prevent other threads from updating any tables from
which the data is being fetched.
When using
mysql_use_result(), you
must execute
mysql_fetch_row() until
a NULL value is
returned, otherwise the unfetched rows will be returned as part of the result
set for your next query. The C API will give the error
Commands out of sync; You can't run
this command now if you forget to do this!
You may not use
mysql_data_seek(),
mysql_row_seek(),
mysql_row_tell(),
mysql_num_rows(), or
mysql_affected_rows()
with a result returned from
mysql_use_result(), nor
may you issue other queries until the
mysql_use_result() has
finished. (However, after you have fetched all the rows,
mysql_num_rows() will
accurately return the number of rows fetched.)
You must call
mysql_free_result() once
you are done with the result set.
Return Values
A MYSQL_RES result
structure. NULL if an
error occurred.
Errors
CR_COMMANDS_OUT_OF_SYNC
Commands were
executed in an improper order.
CR_OUT_OF_MEMORY
Out of memory.
CR_SERVER_GONE_ERROR
The MySQL server
has gone away.
CR_SERVER_LOST
The connection to
the server was lost during the query.
CR_UNKNOWN_ERROR
An unknown error
occurred.
|
