- 20.8.3 C API Function Descriptions
- 20.8.3.1 mysql_affected_rows()
- 20.8.3.2 mysql_autocommit()
- 20.8.3.3 mysql_change_user()
- 20.8.3.4 mysql_character_set_name()
- 20.8.3.5 mysql_close()
- 20.8.3.6 mysql_commit()
- 20.8.3.7 mysql_connect()
- 20.8.3.8 mysql_create_db()
- 20.8.3.9 mysql_data_seek()
- 20.8.3.10 mysql_debug()
- 20.8.3.11 mysql_drop_db()
- 20.8.3.12 mysql_dump_debug_info()
- 20.8.3.13 mysql_eof()
- 20.8.3.14 mysql_errno()
- 20.8.3.15 mysql_error()
- 20.8.3.16 mysql_escape_string()
- 20.8.3.17 mysql_fetch_field()
- 20.8.3.18 mysql_fetch_field_direct()
- 20.8.3.19 mysql_fetch_fields()
- 20.8.3.20 mysql_fetch_lengths()
- 20.8.3.21 mysql_fetch_row()
- 20.8.3.22 mysql_field_count()
- 20.8.3.23 mysql_field_seek()
- 20.8.3.24 mysql_field_tell()
- 20.8.3.25 mysql_free_result()
- 20.8.3.26 mysql_get_character_set_info()
- 20.8.3.27 mysql_get_client_info()
- 20.8.3.28 mysql_get_client_version()
- 20.8.3.29 mysql_get_host_info()
- 20.8.3.30 mysql_get_proto_info()
- 20.8.3.31 mysql_get_server_info()
- 20.8.3.32 mysql_get_server_version()
- 20.8.3.33 mysql_get_ssl_cipher()
- 20.8.3.34 mysql_hex_string()
- 20.8.3.35 mysql_info()
- 20.8.3.36 mysql_init()
- 20.8.3.37 mysql_insert_id()
- 20.8.3.38 mysql_kill()
- 20.8.3.39 mysql_library_end()
- 20.8.3.40 mysql_library_init()
- 20.8.3.41 mysql_list_dbs()
- 20.8.3.42 mysql_list_fields()
- 20.8.3.43 mysql_list_processes()
- 20.8.3.44 mysql_list_tables()
- 20.8.3.45 mysql_more_results()
- 20.8.3.46 mysql_next_result()
- 20.8.3.47 mysql_num_fields()
- 20.8.3.48 mysql_num_rows()
- 20.8.3.49 mysql_options()
- 20.8.3.50 mysql_ping()
- 20.8.3.51 mysql_query()
- 20.8.3.52 mysql_real_connect()
- 20.8.3.53 mysql_real_escape_string()
- 20.8.3.54 mysql_real_query()
- 20.8.3.55 mysql_refresh()
- 20.8.3.56 mysql_reload()
- 20.8.3.57 mysql_rollback()
- 20.8.3.58 mysql_row_seek()
- 20.8.3.59 mysql_row_tell()
- 20.8.3.60 mysql_select_db()
- 20.8.3.61 mysql_set_character_set()
- 20.8.3.62 mysql_set_local_infile_default()
- 20.8.3.63 mysql_set_local_infile_handler()
- 20.8.3.64 mysql_set_server_option()
- 20.8.3.65 mysql_shutdown()
- 20.8.3.66 mysql_sqlstate()
- 20.8.3.67 mysql_ssl_set()
- 20.8.3.68 mysql_stat()
- 20.8.3.69 mysql_store_result()
- 20.8.3.70 mysql_thread_id()
- 20.8.3.71 mysql_use_result()
- 20.8.3.72 mysql_warning_count()
int mysql_ping(MYSQL *mysql)
Description
Checks whether the connection to the server is working. If the
connection has gone down and auto-reconnect is enabled an
attempt to reconnect is made. If the connection is down and
auto-reconnect is disabled,
mysql_ping() returns an error.
Auto-reconnect is enabled by default before MySQL 5.0.3 and
enabled from 5.0.3 on. To enable auto-connect, call
mysql_options() with the
MYSQL_OPT_RECONNECT option. For details, see
Section 20.8.3.49, “mysql_options()”.
mysql_ping() can be used by
clients that remain idle for a long while, to check whether the
server has closed the connection and reconnect if necessary.
If mysql_ping()) does cause a
reconnect, there is no explicit indication of it. To determine
whether a reconnect occurs, call
mysql_thread_id() to get the
original connection identifier before calling
mysql_ping(), and then call
mysql_thread_id() again to see
whether the identifier has changed.
If reconnect occurs, some characteristics of the connection will have been reset. For details about these characteristics, see Section 20.8.11, “Controlling Automatic Reconnection Behavior”.
Return Values
Zero if the connection to the server is alive. Nonzero if an error occurred. A nonzero return does not indicate whether the MySQL server itself is down; the connection might be broken for other reasons such as network problems.
Errors
-
Commands were executed in an improper order.
-
The MySQL server has gone away.
-
An unknown error occurred.
User Comments
An important thing to keep in mind, especially if you're using threads to keep a database connection open/persistant:
A call to mysql_ping, even if the connection never went down, will wipe the results of a mysql_affected_rows, if it somehow occurs between a command execution, and the call.
Symptom: mysql_affected_rows returns -1, when you expect a different number.
(Note - there could be other reasons, this is just one way to guarantee this behavior.)
Add your own comment.