[lwip-devel] [bug #60757] tcp_close can never fail, but its signature and documentation suggest it can

[Christopher Head]

URL:
  <https://savannah.nongnu.org/bugs/?60757>

                 Summary: tcp_close can never fail, but its signature and
documentation suggest it can
                 Project: lwIP - A Lightweight TCP/IP stack
            Submitted by: hawk777
            Submitted on: Wed 09 Jun 2021 05:48:33 PM UTC
                Category: TCP
                Severity: 3 - Normal
              Item Group: Change Request
                  Status: None
                 Privacy: Public
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
         Planned Release: None
            lwIP version: Other

    _______________________________________________________

Details:

Version is 2.1.2; this is not available in the drop-down list.

The tcp_close() function returns an err_t, and the documentation says:
> ERR_OK if connection has been closed another err_t if closing failed and pcb
is not freed

However:
* tcp_close always returns tcp_close_shutdown(pcb, 1)
* tcp_close_shutdown always returns either ERR_OK or
tcp_close_shutdown_fin(pcb)
* tcp_close_shutdown_fin returns either ERR_OK or tcp_send_fin(pcb), except in
the latter case, ERR_MEM is converted to ERR_OK
* tcp_send_fin returns either ERR_OK or tcp_enqueue_flags(pcb, TCP_FIN)
* tcp_enqueue_flags returns either ERR_OK or ERR_MEM

Therefore tcp_close can only ever return ERR_OK. Normally this wouldn’t
matter much, and I would say it’s reasonable to check for errors in case
future versions of lwIP need to add error returns, but tcp_close is special:
closing and disposing of resources is something that’s often done in
situations where recovering from an error is difficult (for example when
already handling another error). It would make using lwIP more ergonomic if
tcp_close were documented as never failing, which ideally would be accompanied
by a change of signature to return void instead of err_t.




    _______________________________________________________

Reply to this item at:

  <https://savannah.nongnu.org/bugs/?60757>

_______________________________________________
  Message sent via Savannah
  https://savannah.nongnu.org/