Project

General

Profile

Bug #10289

asynchronous socket errors should be better documented

Added by Robert Mustacchi 11 months ago. Updated 10 months ago.

Status:
Closed
Priority:
Normal
Category:
manpage - manual pages
Start date:
2019-01-24
Due date:
% Done:

100%

Estimated time:
Difficulty:
Medium
Tags:

Description

Although read(2) isn't explicitly documented on illumos to return -1 with ETIMEDOUT, the man page has this bit:

        In addition, read() and readv() will fail if the stream head
        had  processed  an  asynchronous  error before the call.  In
        this case, the value of errno does not reflect the result of
        read()  or readv() but reflects the prior error. If a hangup
        occurs on the stream being read, read() continues to operate
        normally   until  the  stream  head  read  queue  is  empty.
        Thereafter, it returns 0.

It's not that clear if that part applies out of context, or only in the context of specific kinds of streams in specific modes. Also, the tcp(7p) man page says:

   DIAGNOSTICS
        A socket operation may fail if:
...
        ETIMEDOUT
                         A connection was dropped due  to  excessive
                         retransmissions.

Anyway, I've confirmed that read(2) does do this when TCP keep-alive drops the connection.


As a result of this, we should improve the documentation here to point users to the fact that they can see errors from the underlying network protocols when using sockets.

History

#1

Updated by Electric Monk 10 months ago

  • Status changed from New to Closed

git commit 8549f3a1b574354ace01065ded5d1da81c2b91aa

commit  8549f3a1b574354ace01065ded5d1da81c2b91aa
Author: Robert Mustacchi <rm@joyent.com>
Date:   2019-01-29T00:03:33.000Z

    10289 asynchronous socket errors should be better documented
    Reviewed by: David Pacheco <dap@joyent.com>
    Reviewed by: Jason King <jason.king@joyent.com>
    Reviewed by: Andy Fiddaman <af@citrus-it.net>
    Approved by: Joshua M. Clulow <jmc@joyent.com>

Also available in: Atom PDF