diff options
Diffstat (limited to 'static/openbsd/man2/socket.2')
| -rw-r--r-- | static/openbsd/man2/socket.2 | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/static/openbsd/man2/socket.2 b/static/openbsd/man2/socket.2 new file mode 100644 index 00000000..ac17d321 --- /dev/null +++ b/static/openbsd/man2/socket.2 @@ -0,0 +1,308 @@ +.\" $OpenBSD: socket.2,v 1.46 2025/08/04 04:59:31 guenther Exp $ +.\" $NetBSD: socket.2,v 1.5 1995/02/27 12:37:53 cgd 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 $Mdocdate: August 4 2025 $ +.Dt SOCKET 2 +.Os +.Sh NAME +.Nm socket +.Nd create an endpoint for communication +.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 +.In sys/socket.h . +The currently understood formats are: +.Pp +.Bl -tag -width "AF_INET6XXX" -offset indent -compact +.It Dv AF_UNIX +UNIX internal protocols +.It Dv AF_INET +Internet Protocol version 4 (IPv4) protocol family +.It Dv AF_INET6 +Internet Protocol version 6 (IPv6) protocol family +.El +.Pp +The socket has the indicated +.Fa type , +which specifies the semantics of communication. +Currently defined types are: +.Pp +.Bl -tag -width "SOCK_SEQPACKETXXX" -offset indent -compact +.It Dv SOCK_STREAM +.It Dv SOCK_DGRAM +.It Dv SOCK_RAW +.It Dv SOCK_SEQPACKET +.El +.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 implemented only for +.Dv AF_UNIX . +.Dv SOCK_RAW +sockets provide access to internal network protocols and interfaces, +and are available only to the superuser. +.Pp +Any combination of the following flags may additionally be used in the +.Fa type +argument: +.Pp +.Bl -tag -width "SOCK_NONBLOCKX" -offset indent -compact +.It Dv SOCK_CLOEXEC +Set close-on-exec flag on the new descriptor. +.It Dv SOCK_CLOFORK +Set close-on-fork flag on the new descriptor. +.It Dv SOCK_NONBLOCK +Set non-blocking I/O mode on the new socket. +.It Dv SOCK_DNS +For domains +.Dv AF_INET +or +.Dv AF_INET6 , +only allow +.Xr connect 2 , +.Xr sendto 2 , +or +.Xr sendmsg 2 +to the DNS port (typically 53). +.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 +.Dq communication domain +in which communication is to take place; see +.Xr protocols 5 . +A value of 0 for +.Fa protocol +will let the system select an appropriate protocol for the requested +socket type. +.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 +.In sys/socket.h . +.Xr setsockopt 2 +and +.Xr getsockopt 2 +are used to set and get options, respectively. +.Sh RETURN VALUES +If successful, +.Fn socket +returns a non-negative integer, the socket file descriptor. +Otherwise, a value of \-1 is returned and +.Va errno +is set to indicate the error. +.Sh ERRORS +The +.Fn socket +call fails if: +.Bl -tag -width Er +.It Bq Er EAFNOSUPPORT +The specified address family is not supported on this machine. +.It Bq Er EPROTONOSUPPORT +The protocol type or the specified protocol is not supported +within this domain. +.It Bq Er EPROTOTYPE +The combination of the specified protocol and type is not supported. +.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 resources were available in the system +to perform the operation. +.It Bq Er EACCES +Permission to create a socket of the specified type and/or protocol +is denied. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr bind 2 , +.Xr connect 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 , +.Xr inet 4 , +.Xr inet6 4 , +.Xr netintro 4 , +.Xr unix 4 +.Rs +.%T "An Introductory 4.3 BSD Interprocess Communication Tutorial" +.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" +.Re +.Rs +.%T "BSD Interprocess Communication Tutorial" +.%O "reprinted in UNIX Programmer's Supplementary Documents Volume 1" +.Re +.Sh STANDARDS +The +.Fn socket +function conforms to +.St -p1003.1-2024 . +.Pp +The +.Dv SOCK_DNS +flag is an +.Ox +extension. +.Sh HISTORY +The +.Fn socket +system call first appeared in +.Bx 4.1c . +Support for the +.Dv SOCK_CLOEXEC +and +.Dv SOCK_NONBLOCK +flags appeared in +.Ox 5.7 . +Support for the +.Dv SOCK_DNS +flag appeared in +.Ox 5.9 . |