diff options
Diffstat (limited to 'static/netbsd/man2/socket.2')
| -rw-r--r-- | static/netbsd/man2/socket.2 | 307 |
1 files changed, 307 insertions, 0 deletions
diff --git a/static/netbsd/man2/socket.2 b/static/netbsd/man2/socket.2 new file mode 100644 index 00000000..d6391dd8 --- /dev/null +++ b/static/netbsd/man2/socket.2 @@ -0,0 +1,307 @@ +.\" $NetBSD: socket.2,v 1.52 2025/07/17 17:16:07 kre Exp $ +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)socket.2 8.1 (Berkeley) 6/4/93 +.\" +.Dd July 17, 2025 +.Dt SOCKET 2 +.Os +.Sh NAME +.Nm socket +.Nd create an endpoint for communication +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In sys/socket.h +.Ft int +.Fn socket "int domain" "int type" "int protocol" +.Sh DESCRIPTION +.Fn socket +creates an endpoint for communication and returns a descriptor. +.Pp +The +.Fa domain +parameter specifies a communications domain within which +communication will take place; this selects the protocol family +which should be used. +These families are defined in the include file +.Ao Pa sys/socket.h Ac . +The currently understood formats are: +.Bl -column -offset indent ".Dv PF_APPLETALK" +.It Dv PF_LOCAL Ta local domain Po previously Tn UNIX domain Pc protocols +.It Dv PF_INET Ta Tn ARPA Internet protocols +.It Dv PF_INET6 Ta Tn IPv6 (Internet Protocol version 6) protocols +.It Dv PF_NS Ta Xerox Network Systems protocols +.It Dv PF_APPLETALK Ta AppleTalk protocols +.It Dv PF_BLUETOOTH Ta Bluetooth protocols +.It Dv PF_CAN Ta Tn CAN bus protocols +.El +.Pp +The socket has the indicated +.Fa type , +which specifies the semantics of communication. +Currently defined types are: +.Bl -tag -offset indent -width SOCK_NOSIGPIPE +.It Dv SOCK_STREAM +Provides sequenced, reliable, two-way connection based byte streams. +An out-of-band data transmission mechanism may be supported. +.It Dv SOCK_DGRAM +Supports datagrams: connectionless, unreliable messages of a +fixed\(emtypically small\(emmaximum length. +.It Dv SOCK_RAW +Provides access to internal network protocols and interfaces. +Available only to the super-user. +Not described here. +.It Dv SOCK_SEQPACKET +Provides 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. +.It Dv SOCK_RDM +Not implemented. +.El +.Pp +The following flags can be or'ed to the socket type to add conditions to +the returned file descriptor: +.Bl -tag -offset indent -width SOCK_NOSIGPIPE +.It Dv SOCK_CLOEXEC +Set the +.Dq close on exec +property. +.It Dv SOCK_CLOFORK +Set the +.Dq close on fork +property. +.It Dv SOCK_NONBLOCK +Set non-blocking I/O. +.It Dv SOCK_NOSIGPIPE +Return +.Er EPIPE +instead of raising +.Dv SIGPIPE . +.El +.Pp +The +.Fa protocol +specifies a particular protocol to be used with the socket. +Normally only a single protocol exists to support a particular +socket type within a given protocol family. +However, it is possible that many protocols may exist, in which case +a particular protocol must be specified in this manner. +The protocol number to use is +particular to the \*(lqcommunication domain\*(rq in which communication +is to take place; see +.Xr protocols 5 . +.Pp +Sockets of type +.Dv SOCK_STREAM +are full-duplex byte streams. +A stream socket must be in a +.Em connected +state before any data may be sent or received +on it. +A connection to another socket is created with a +.Xr connect 2 +call. +Once connected, data may be transferred using +.Xr read 2 +and +.Xr write 2 +calls or some variant of the +.Xr send 2 +and +.Xr recv 2 +calls. +When a session has been completed a +.Xr close 2 +may be performed. +Out-of-band data may also be transmitted as described in +.Xr send 2 +and received as described in +.Xr recv 2 . +.Pp +The communications protocols used to implement a +.Dv SOCK_STREAM +ensure 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 +.Dq 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 an extended period (e.g., 5 minutes). +A +.Dv SIGPIPE +signal is raised if a process 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 sending of datagrams to correspondents +named in +.Xr send 2 +calls. +Datagrams are generally received with +.Xr recvfrom 2 , +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 may also enable non-blocking I/O +and asynchronous notification of I/O events +via +.Dv SIGIO . +.Pp +The operation of sockets is controlled by socket level +.Em options . +These options are defined in the file +.Ao Pa sys/socket.h Ac . +The +.Xr setsockopt 2 +and +.Xr getsockopt 2 +system calls are used to set and get options, respectively. +.Sh RETURN VALUES +A \-1 is returned if an error occurs, otherwise the return +value is a descriptor referencing the socket. +.Sh ERRORS +The +.Fn socket +call fails if: +.Bl -tag -width Er +.It Bq Er EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.It Bq Er EAFNOSUPPORT +The address family (domain) is not supported or +the specified domain is not supported by this protocol family. +.It Bq Er EMFILE +The per-process descriptor table is full. +.It Bq Er ENFILE +The system file table is full. +.It Bq Er ENOBUFS +Insufficient buffer space is available. +The socket cannot be created until sufficient resources are freed. +.It Bq Er EPROTONOSUPPORT +The protocol family is not supported or +the specified protocol is not supported within this domain. +.It Bq Er EPROTOTYPE +The socket type is not supported by the protocol. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr connect 2 , +.Xr fcntl 2 , +.Xr getsockname 2 , +.Xr getsockopt 2 , +.Xr ioctl 2 , +.Xr listen 2 , +.Xr poll 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr shutdown 2 , +.Xr socketpair 2 , +.Xr write 2 , +.Xr getprotoent 3 +.Rs +.%T "An Introductory 4.4BSD Interprocess Communication Tutorial" +.%A Stuart Sechrest +.Re +.Pq see Pa /usr/share/doc/reference/ref3/sockets +.Rs +.%T "Advanced 4.4BSD IPC Tutorial" +.%A Samuel J. Leffler +.%A Robert S. Fabry +.%A William N. Joy +.%A Phil Lapsley +.%A Steve Miller +.%A Chris Torek +.Re +.Pq see Pa /usr/share/doc/reference/ref3/sockets-advanced +.Sh STANDARDS +The +.Fn socket +call conforms to +.St -p1003.1-2001 . +Including the +.Dv SOCK_CLOEXEC , +.Dv SOCK_CLOFORK , +and +.Dv SOCK_NONBLOCK +flags in the +.Fa type +conforms to +.St -p1003.1-2024 . +Using +.Dv SOCK_NOSIGPIPE +is an extension to the standard. +.Sh HISTORY +The +.Fn socket +function call appeared in +.Bx 4.2 . +.Pp +The +.Dv SOCK_CLOFORK +flag appeared in +.Fx 15.0 , +.Dx 6.5 , +and +.Nx 11.0 . |