Analysis of MYSQL_OPT_READ_TIMEOUT Behavior in the MySQL C API

MYSQL_OPT_READ_TIMEOUT is a parameter in the MySQL C API client used to set the read timeout. The official MySQL documentation describes it as the timeout in seconds for each read attempt, with the effective timeout being three times the option value.

In practice, testing showed that the actual timeout matched the configured value, not three times it, and the documentation did not specify when the triple timeout would occur.

Analyzing the source code of MySQL 5.7.20 with GDB revealed that the vio_read() function uses recv and poll for reading and timeout handling, and net_should_retry() only retries on EINTR , without a fixed three‑retry limit.

A search uncovered Bug #31163, which reported that in MySQL 5.0 the actual read timeout was three times the configured value, matching the documentation at that time.

Further GDB analysis of MySQL 5.0.96 showed code that performs three read attempts: the first timeout occurs at point A, the socket is set to blocking mode at point B, the retry count is reset at point C, and subsequent loops trigger point D, resulting in two retries (three total reads) before exiting at point E.

These findings indicate that the current MySQL documentation for MYSQL_OPT_READ_TIMEOUT is outdated; the option no longer exhibits the three‑times timeout behavior, and the bug fix that updated the documentation was not propagated to later versions.

Community announcements follow: a free Mycat diagnostic service (including source analysis and performance tuning) is offered via QQ group 669663113 and email [email protected], and a call for original technical articles on MySQL, DBLE, and DTLE with a reward of a JD e‑card and community merchandise.