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>

usr/src/man/man2/read.2

@@ -43,9 +43,9 @@
 .\" Copyright 1989 AT&T
 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
-.\" Copyright (c) 2015, Joyent, Inc.  All rights reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH READ 2 "Jan 15, 2015"
+.TH READ 2 "September 10, 2018"
 .SH NAME
 read, readv, pread, preadv \- read from file
 .SH SYNOPSIS
@@ -284,6 +284,12 @@ processed an asynchronous error before the call.  In this case, the value of
 reflects the prior error. If a hangup occurs on the stream being read,
 \fBread()\fR continues to operate normally until the stream head read queue is
 empty. Thereafter, it returns \fB0\fR.
+.sp
+.LP
+If an asynchronous error occurs on a socket, it is possible for the \fBread()\fR
+and \fBreadv()\fR functions to return an asynchronous error, just as in the
+STREAMS case described above. This might occur, for example, if a TCP socket
+that is using TCP keep-alive is closed due to failing the keep-alive check.
 .SS "\fBreadv()\fR"
 .LP
 The \fBreadv()\fR function is equivalent to \fBread()\fR, but places the input
@@ -338,6 +344,13 @@ non-negative integer indicating the number of bytes actually read. Otherwise,
 the functions return \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, if the \fIfiledes\fR argument refers
+to a socket, then an asynchronous error generated by the underlying socket
+protocol may be returned. For the full list of errors, please see the
+corresponding socket protocol manual page. For example, for a list of TCP
+errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBread()\fR, \fBreadv()\fR, \fBpread()\fR, and \fBpreadv()\fR functions will fail if:
 .sp
 .ne 2
@@ -563,4 +576,4 @@ Standard	See \fBstandards\fR(5).
 \fBIntro\fR(2), \fBchmod\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2),
 \fBgetmsg\fR(2), \fBioctl\fR(2), \fBlseek\fR(2), \fBopen\fR(2), \fBpipe\fR(2),
 \fBrecv\fR(3SOCKET), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5),
-\fBstreamio\fR(7I), \fBtermio\fR(7I)
+\fBstreamio\fR(7I), \fBtermio\fR(7I), \fBtcp\fR(7P)

usr/src/man/man2/write.2

@@ -43,9 +43,9 @@
 .\" Copyright 1989 AT&T
 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
-.\" Copyright (c) 2015, Joyent, Inc.  All rights reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH WRITE 2 "Jan 15, 2015"
+.TH WRITE 2 "September 10, 2018"
 .SH NAME
 write, pwrite, writev, pwritev\- write on a file
 .SH SYNOPSIS
@@ -296,6 +296,12 @@ The \fBwrite()\fR and \fBwritev()\fR functions will fail if the stream head had
 processed an asynchronous error before the call.  In this case, the value of
 \fBerrno\fR does not reflect the result of \fBwrite()\fR or \fBwritev()\fR but
 reflects the prior error.
+.sp
+.LP
+If an asynchronous error occurs on a socket, it is possible for the
+\fBwrite()\fR and \fBwritev()\fR to return an asynchronous error, just as in the
+STREAMS case described above. This might occur, for example, if a TCP socket
+that is using TCP keep-alive is closed due to failing the keep-alive check.
 .SS "\fBpwrite()\fR"
 .LP
 The \fBpwrite()\fR function is equivalent to \fBwrite()\fR, except that it
@@ -355,6 +361,11 @@ Upon successful completion, \fBwritev()\fR returns the number of bytes actually
 written.  Otherwise, it returns  \fB\(mi1\fR, the file-pointer remains
 unchanged, and \fBerrno\fR is set to indicate an error.
 .SH ERRORS
+In addition to the errors documented below, if the \fIfiledes\fR argument refers
+to a socket, then an asynchronous error generated by the underlying socket
+protocol may be returned. For the full list of errors, please see the
+corresponding socket protocol manual page. For example, for a list of TCP
+errors, please see \fBtcp\fR(7P).
 .LP
 The \fBwrite()\fR, \fBpwrite()\fR, \fBwritev()\fR, and \fBpwritev()\fR
 functions will fail if:
@@ -639,4 +650,5 @@ Standard	See \fBstandards\fR(5).
 \fBIntro\fR(2), \fBchmod\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2),
 \fBgetrlimit\fR(2), \fBioctl\fR(2), \fBlseek\fR(2), \fBopen\fR(2),
 \fBpipe\fR(2), \fBulimit\fR(2), \fBsend\fR(3SOCKET), \fBsocket\fR(3SOCKET),
-\fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5), \fBstreamio\fR(7I)
+\fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5), \fBstreamio\fR(7I),
+\fBtcp\fR(7P)

usr/src/man/man3socket/recv.3socket

@@ -1,10 +1,11 @@
 '\" te
 .\"  Copyright 1989 AT&T
 .\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
+.\" Copyright (c) 2018, Joyent, Inc.
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH RECV 3SOCKET "Dec 03, 2014"
+.TH RECV 3SOCKET "September 10, 2018"
 .SH NAME
 recv, recvfrom, recvmsg \- receive a message from a socket
 .SH SYNOPSIS
@@ -61,7 +62,8 @@ For that reason, one or more bytes of data should be provided when
 \fBrecvmsg()\fR passes a file descriptor.
 .sp
 .LP
-The \fBselect\fR(3C) call can be used to determine when more data arrives.
+The \fBpoll\fR(2), \fBselect\fR(3C), and \fBport_get\fR(3C) functions can be
+used to determine when more data arrives.
 .sp
 .LP
 The \fIflags\fR parameter is formed by an \fBOR\fR operation on one or more of
@@ -121,6 +123,12 @@ received. Otherwise, they return \fB-1\fR and set \fBerrno\fR to indicate the
 error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBrecv()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR functions return errors
 under the following conditions:
 .sp
@@ -285,7 +293,8 @@ MT-Level	Safe
 
 .SH SEE ALSO
 .LP
-\fBfcntl\fR(2), \fBioctl\fR(2), \fBread\fR(2), \fBconnect\fR(3SOCKET),
-\fBgetsockopt\fR(3SOCKET), \fBlibxnet\fR(3LIB), \fBselect\fR(3C),
-\fBsend\fR(3SOCKET), \fBsockaddr\fR(3SOCKET), \fBsocket\fR(3SOCKET),
-\fBsocket.h\fR(3HEAD), \fBattributes\fR(5)
+\fBfcntl\fR(2), \fBioctl\fR(2), \fBpoll\fR(2), \fBread\fR(2),
+\fBconnect\fR(3SOCKET), \fBgetsockopt\fR(3SOCKET), \fBlibxnet\fR(3LIB),
+\fBport_get(3C)\fR, \fBselect\fR(3C), \fBsend\fR(3SOCKET),
+\fBsockaddr\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD),
+\fBattributes\fR(5), \fBtcp\fR(7P)

usr/src/man/man3socket/send.3socket

@@ -1,10 +1,11 @@
 '\" te
 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
+.\" Copyright (c) 2018, Joyent, Inc.
 .\" Copyright 1989 AT&T
 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
-.TH SEND 3SOCKET "Jun 18, 2017"
+.TH SEND 3SOCKET "September 10, 2018"
 .SH NAME
 send, sendto, sendmsg \- send a message from a socket
 .SH SYNOPSIS
@@ -93,13 +94,20 @@ longer connected.
 
 .sp
 .LP
-See \fBrecv\fR(3SOCKET) for a description of the \fBmsghdr\fR structure.
+The \fBsendmsg()\fR function call uses a \fBmsghdr\fR structure defined in
+<\fBsys/socket.h\fR> to minimize the number of directly supplied parameters.
 .SH RETURN VALUES
 .LP
 Upon successful completion, these functions return the number of bytes sent.
 Otherwise, they return \fB-1\fR and set \fBerrno\fR to indicate the error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBsend()\fR, \fBsendto()\fR, and \fBsendmsg()\fR functions return errors
 under the following conditions:
 .sp
@@ -288,4 +296,4 @@ MT-Level	Safe
 \fBfcntl\fR(2), \fBpoll\fR(2), \fBwrite\fR(2), \fBconnect\fR(3SOCKET),
 \fBgetsockopt\fR(3SOCKET), \fBrecv\fR(3SOCKET), \fBselect\fR(3C),
 \fBsockaddr\fR(3SOCKET), \fBsocket\fR(3SOCKET), \fBsocket.h\fR(3HEAD),
-\fBattributes\fR(5)
+\fBattributes\fR(5), \fBtcp\fR(7P)

usr/src/man/man3xnet/recv.3xnet

@@ -42,8 +42,9 @@
 .\"
 .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Portions Copyright (c) 1998, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH RECV 3XNET "Dec 03, 2014"
+.TH RECV 3XNET "September 10, 2018"
 .SH NAME
 recv \- receive a message from a connected socket
 .SH SYNOPSIS
@@ -168,6 +169,12 @@ an orderly shutdown, \fBrecv()\fR returns 0.  Otherwise, -1 is returned and
 \fBerrno\fR is set to indicate the error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBrecv()\fR function will fail if:
 .sp
 .ne 2
@@ -332,4 +339,4 @@ MT-Level	MT-Safe
 \fBpoll\fR(2), \fBrecvmsg\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBselect\fR(3C),
 \fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET),
 \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5),
-\fBstandards\fR(5)
+\fBstandards\fR(5), \fBtcp\fR(7P)

usr/src/man/man3xnet/recvfrom.3xnet

@@ -42,8 +42,9 @@
 .\"
 .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Portions Copyright (c) 1998, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH RECVFROM 3XNET "April 9, 2016"
+.TH RECVFROM 3XNET "September 10, 2018"
 .SH NAME
 recvfrom \- receive a message from a socket
 .SH SYNOPSIS
@@ -207,6 +208,12 @@ performed an orderly shutdown, \fBrecvfrom()\fR returns 0.  Otherwise the
 function returns \(mi1 and sets \fBerrno\fR to indicate the error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBrecvfrom()\fR function will fail if:
 .sp
 .ne 2
@@ -370,4 +377,4 @@ MT-Level	MT-Safe
 \fBrecv\fR(3XNET), \fBrecvmsg\fR(3XNET), \fBselect\fR(3C)
 \fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET),
 \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5),
-\fBstandards\fR(5)
+\fBstandards\fR(5), \fBtcp\fR(7P)

usr/src/man/man3xnet/recvmsg.3xnet

@@ -42,8 +42,9 @@
 .\"
 .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Portions Copyright (c) 2006, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH RECVMSG 3XNET "Feb 27, 2006"
+.TH RECVMSG 3XNET "September 10, 2018"
 .SH NAME
 recvmsg \- receive a message from a socket
 .SH SYNOPSIS
@@ -56,7 +57,6 @@ recvmsg \- receive a message from a socket
 .fi
 
 .SH DESCRIPTION
-.sp
 .LP
 The \fBrecvmsg()\fR function receives a message from a connection-mode or
 connectionless-mode socket. It is normally used with connectionless-mode
@@ -165,7 +165,6 @@ Control data was truncated.
 .RE
 
 .SH PARAMETERS
-.sp
 .LP
 The function takes the following arguments:
 .sp
@@ -231,18 +230,21 @@ an error is pending for the socket.
 .RE
 
 .SH USAGE
-.sp
 .LP
 The \fBselect\fR(3C) and \fBpoll\fR(2) functions can be used to determine when
 data is available to be received.
 .SH RETURN VALUES
-.sp
 .LP
 Upon successful completion, \fBrecvmsg()\fR returns the length of the message
 in bytes. If no messages are available to be received and the peer has
 performed an orderly shutdown, \fBrecvmsg()\fR returns \fB0\fR. Otherwise,
 \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
 .SH ERRORS
+.LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
 .sp
 .LP
 The \fBrecvmsg()\fR function will fail if:
@@ -399,7 +401,6 @@ complete.
 .RE
 
 .SH ATTRIBUTES
-.sp
 .LP
 See \fBattributes\fR(5) for descriptions of the following attributes:
 .sp
@@ -417,9 +418,8 @@ MT-Level	MT-Safe
 .TE
 
 .SH SEE ALSO
-.sp
 .LP
 \fBpoll\fR(2), \fBrecv\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBselect\fR(3C),
 \fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET),
 \fBsetsockopt\fR(3XNET), \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET),
-\fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5)
+\fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5), \fBtcp\fR(7P)

usr/src/man/man3xnet/send.3xnet

@@ -42,8 +42,9 @@
 .\"
 .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH SEND 3XNET "Aug 16, 2018"
+.TH SEND 3XNET "September 10, 2018"
 .SH NAME
 send \- send a message on a socket
 .SH SYNOPSIS
@@ -159,6 +160,12 @@ Upon successful completion, \fBsend()\fR returns the number of bytes sent.
 Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate the error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBsend()\fR function will fail if:
 .sp
 .ne 2
@@ -351,4 +358,4 @@ MT-Level	MT-Safe
 \fBrecv\fR(3XNET), \fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET),
 \fBselect\fR(3C), \fBsendmsg\fR(3XNET), \fBsendto\fR(3XNET),
 \fBsetsockopt\fR(3XNET), \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET),
-\fBattributes\fR(5), \fBstandards\fR(5)
+\fBattributes\fR(5), \fBstandards\fR(5), \fBtcp\fR(7P)

usr/src/man/man3xnet/sendmsg.3xnet

@@ -42,8 +42,9 @@
 .\"
 .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH SENDMSG 3XNET "Aug 16, 2018"
+.TH SENDMSG 3XNET "September 10, 2018"
 .SH NAME
 sendmsg \- send a message on a socket using a message structure
 .SH SYNOPSIS
@@ -165,6 +166,12 @@ bytes sent.  Otherwise, \(mi1 is returned and \fBerrno\fR is set to indicate
 the error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBsendmsg()\fR function will fail if:
 .sp
 .ne 2
@@ -475,4 +482,4 @@ MT-Level	MT-Safe
 \fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET), \fBselect\fR(3C),
 \fBsend\fR(3XNET), \fBsendto\fR(3XNET), \fBsetsockopt\fR(3XNET),
 \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5),
-\fBstandards\fR(5)
+\fBstandards\fR(5), \fBtcp\fR(7P)

usr/src/man/man3xnet/sendto.3xnet

@@ -42,8 +42,9 @@
 .\"
 .\" Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved.
+.\" Copyright (c) 2018, Joyent, Inc.
 .\"
-.TH SENDTO 3XNET "Aug 16, 2018"
+.TH SENDTO 3XNET "September 10, 2018"
 .SH NAME
 sendto \- send a message on a socket
 .SH SYNOPSIS
@@ -186,6 +187,12 @@ Upon successful completion, \fBsendto()\fR returns the number of bytes sent.
 Otherwise, \fB-1\fR is returned and \fBerrno\fR is set to indicate the error.
 .SH ERRORS
 .LP
+In addition to the errors documented below, an asynchronous error generated by
+the underlying socket protocol may be returned. For the full list of errors,
+please see the corresponding socket protocol manual page. For example, for a
+list of TCP errors, please see \fBtcp\fR(7P).
+.sp
+.LP
 The \fBsendto()\fR function will fail if:
 .sp
 .ne 2
@@ -492,4 +499,4 @@ MT-Level	MT-Safe
 \fBrecvfrom\fR(3XNET), \fBrecvmsg\fR(3XNET), \fBselect\fR(3C),
 \fBsend\fR(3XNET), \fBsendmsg\fR(3XNET), \fBsetsockopt\fR(3XNET),
 \fBshutdown\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR(5),
-\fBstandards\fR(5)
+\fBstandards\fR(5), \fBtcp\fR(7P)