--- /dev/null	Sun Aug  5 23:41:10 2018
+++ new/usr/src/man/man3c/socket.3c	Sun Aug  5 23:41:10 2018
@@ -0,0 +1,301 @@
+.\"
+.\" 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]
+.\"
+.\"
+.\" Copyright 1989 AT&T
+.\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All Rights Reserved.
+.\" Copyright 2018 Nexenta Systems, Inc.
+.\"
+.Dd August 2, 2018
+.Dt SOCKET 3C
+.Os
+.Sh NAME
+.Nm socket
+.Nd create an endpoint for communication
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In sys/types.h
+.In sys/socket.h
+.Ft int
+.Fo socket
+.Fa "int domain"
+.Fa "int type"
+.Fa "int protocol"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn socket
+function creates an endpoint for communication and returns a
+descriptor.
+.Pp
+The
+.Fa domain
+argument specifies the protocol family within which communication takes place.
+The protocol family is generally the same as the address family for the
+addresses supplied in later operations on the socket.
+These families are defined in
+.In sys/socket.h .
+.Pp
+The currently supported protocol families are:
+.Bl -tag -width "PF_INET6"
+.It Dv PF_UNIX
+UNIX system internal protocols
+.It Dv PF_INET
+Internet Protocol Version 4 (IPv4)
+.It Dv PF_INET6
+Internet Protocol Version 6 (IPv6)
+.It Dv PF_NCA
+Network Cache and Accelerator (NCA) protocols
+.El
+.Pp
+The socket has the indicated
+.Fa type ,
+which specifies the communication semantics.
+Currently defined types are:
+.Bl -tag -width Ds
+.It Dv SOCK_STREAM
+.It Dv SOCK_DGRAM
+.It Dv SOCK_RAW
+.It Dv SOCK_SEQPACKET
+.It Dv SOCK_RDM
+.El
+.Pp
+The
+.Fa type
+may be augmented by a bitwise-inclusive-OR of flags from the following list,
+defined in
+.In sys/socket.h :
+.Bl -tag -width Ds
+.It Dv SOCK_CLOEXEC
+Creates the socket with the
+.Dv FD_CLOEXEC
+flag set, causing the underlying file descriptor to be closed prior to any
+future calls to
+.Xr exec 2 .
+This is similar in purpose to the
+.Dv O_CLOEXEC
+flag to
+.Xr open 2 .
+.It Dv SOCK_NDELAY
+Creates the socket with the
+.Dv O_NDELAY
+flag set, causing the socket to provide nonblocking semantics as described for
+.Dv O_NDELAY
+in
+.Xr open 2 .
+.Dv SOCK_NONBLOCK
+should normally be used in preference to
+.Dv SOCK_NDELAY ,
+and takes precedence if both are set.
+See
+.Xr open 2
+for further details.
+.It Dv SOCK_NONBLOCK
+Creates the socket with the
+.Dv O_NONBLOCK
+flag set, causing the socket to provide nonblocking semantics as described for
+.Dv O_NONBLOCK
+in
+.Xr open 2 .
+.El
+.Pp
+There must be an entry in the
+.Xr netconfig 4
+file for at least each protocol family and type required.
+If a non-zero protocol has been specified but no exact match for the protocol
+family, type, and protocol is found, then the first entry containing the
+specified family and type with a
+.Fa protocol
+value of zero will be used.
+.Pp
+A
+.Dv SOCK_STREAM
+type provides sequenced, reliable, two-way connection-based byte streams.
+An out-of-band data transmission mechanism may be supported.
+A
+.Dv SOCK_DGRAM
+socket supports datagrams (connectionless, unreliable messages of a fixed
+(typically small) maximum length).
+A
+.Dv SOCK_SEQPACKET
+socket may provide a sequenced, reliable, two-way connection-based data
+transmission path for datagrams of fixed maximum length; a consumer may be
+required to read an entire packet with each read system call.
+This facility is protocol specific, and presently not implemented for any
+protocol family.
+.Dv SOCK_RAW
+sockets provide access to internal network interfaces.
+The types
+.Dv SOCK_RAW ,
+which is available only to a user with the
+.Em net_rawaccess
+privilege, and
+.Dv SOCK_RDM ,
+for which no implementation currently exists, are not described here.
+.Pp
+The
+.Fa protocol
+parameter is a protocol-family-specific value which specifies a particular
+protocol to be used with the socket.
+Normally this value is zero, as commonly only a single protocol exists to
+support a particular socket type within a given protocol family.
+However, multiple protocols may exist, in which case a particular protocol may
+be specified in this manner.
+.Pp
+Sockets of type
+.Dv SOCK_STREAM
+are full-duplex byte streams, similar to pipes.
+A stream socket must be in a "connected" state before any data may be sent or
+received on it.
+A connection to another socket is created with a
+.Xr connect 3C
+call.
+Once connected, data may be transferred using
+.Xr read 2
+and
+.Xr write 2
+calls or some variant of the
+.Xr send 3C
+and
+.Xr recv 3C
+calls.
+When a session has been completed, a
+.Xr close 2
+may be performed.
+Out-of-band data may also be transmitted as described on the
+.Xr send 3C
+manual page and received as described on the
+.Xr recv 3C
+manual page.
+.Pp
+The communications protocols used to implement a
+.Dv SOCK_STREAM
+insure that data is not lost or duplicated.
+If a piece of data for which the peer protocol has buffer space cannot be
+successfully transmitted within a reasonable length of time, then the connection
+is considered broken and calls will indicate an error with -1 returns and with
+.Er ETIMEDOUT
+as the specific code in the global variable
+.Va errno .
+The protocols optionally keep sockets "warm" by forcing transmissions roughly
+every minute in the absence of other activity.
+An error is then indicated if no response can be elicited on an otherwise idle
+connection for a extended period (for instance 5 minutes).
+A
+.Dv SIGPIPE
+signal is raised if a thread sends on a broken stream; this causes naive
+processes, which do not handle the signal, to exit.
+.Pp
+.Dv SOCK_SEQPACKET
+sockets employ the same system calls as
+.Dv SOCK_STREAM
+sockets.
+The only difference is that
+.Xr read 2
+calls will return only the amount of data requested, and any remaining in the
+arriving packet will be discarded.
+.Pp
+.Dv SOCK_DGRAM
+and
+.Dv SOCK_RAW
+sockets allow datagrams to be sent to correspondents named in
+.Xr sendto 3C
+calls.
+Datagrams are generally received with
+.Xr recvfrom 3C ,
+which returns the next datagram with its return address.
+.Pp
+An
+.Xr fcntl 2
+call can be used to specify a process group to receive a
+.Dv SIGURG
+signal when the out-of-band data arrives.
+It can also enable non-blocking I/O.
+.Pp
+The operation of sockets is controlled by socket level options.
+These options are defined in the file
+.In sys/socket.h .
+.Xr setsockopt 3C
+and
+.Xr getsockopt 3C
+are used to set and get options, respectively.
+.Sh RETURN VALUES
+Upon successful completion, a descriptor referencing the socket is returned.
+Otherwise, -1 is returned and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+The
+.Fn socket
+function will fail if:
+.Bl -tag -width Er
+.It Bq Er EACCES
+Permission to create a socket of the specified type or protocol is denied.
+.It Bq Er EAGAIN
+There were insufficient resources available to complete the operation.
+.It Bq Er EAFNOSUPPORT
+The specified address family is not supported by the protocol family.
+.It Bq Er EMFILE
+The per-process descriptor table is full.
+.It Bq Er ENOMEM
+Insufficient user memory is available.
+.It Bq Er ENOSR
+There were insufficient STREAMS resources available to complete the operation.
+.It Bq Er EPFNOSUPPORT
+The specified protocol family is not supported.
+.It Bq Er EPROTONOSUPPORT
+The protocol type is not supported by the address family.
+.It Bq Er EPROTOTYPE
+The socket type is not supported by the protocol.
+.It Bq Er EINVAL
+One or more of the specified flags is not supported.
+.El
+.Sh MT-LEVEL
+.Sy Safe
+.Sh SEE ALSO
+.Xr nca 1 ,
+.Xr close 2 ,
+.Xr exec 2 ,
+.Xr fcntl 2 ,
+.Xr ioctl 2 ,
+.Xr open 2 ,
+.Xr read 2 ,
+.Xr write 2 ,
+.Xr accept 3C ,
+.Xr bind 3C ,
+.Xr connect 3C ,
+.Xr getsockname 3C ,
+.Xr getsockopt 3C ,
+.Xr listen 3C ,
+.Xr recv 3C ,
+.Xr send 3C ,
+.Xr setsockopt 3C ,
+.Xr shutdown 3C ,
+.Xr socketpair 3C ,
+.Xr in.h 3HEAD ,
+.Xr socket.h 3HEAD ,
+.Xr attributes 5
+.Sh NOTES
+Historically,
+.Dv AF_ Ns *
+was commonly used in places where
+.Dv PF_ Ns *
+was meant.
+New code should be careful to use
+.Dv PF_ Ns *
+as necessary.
