Editing Berkeley sockets (section)

==Socket API functions==
[[File:InternetSocketBasicDiagram zhtw.png|thumb|right|Flow diagram of client-server transaction using sockets with the Transmission Control Protocol (TCP).]]

The Berkeley socket API typically provides the following functions:
* ''socket()'' creates a new socket of a certain type, identified by an integer number, and allocates system resources to it.
* ''bind()'' is typically used on the server side, and associates a socket with a socket address structure, i.e. a specified local IP address and a port number.
* ''listen()'' is used on the server side, and causes a bound TCP socket to enter listening state.
* ''connect()'' is used on the client side, and assigns a free local port number to a socket. In case of a TCP socket, it causes an attempt to establish a new TCP connection.
* ''accept()'' is used on the server side. It accepts a received incoming attempt to create a new TCP connection from the remote client, and creates a new socket associated with the socket address pair of this connection.
* ''send()'', ''recv()'', ''sendto()'', and ''recvfrom()'' are used for sending and receiving data. The standard functions ''write()'' and ''read()'' may also be used.
* ''close()'' causes the system to release resources allocated to a socket. In case of TCP, the connection is terminated.
* ''gethostbyname()'' and ''gethostbyaddr()'' are used to resolve host names and addresses. IPv4 only.
* ''getaddrinfo()'' and ''freeaddrinfo()'' are used to resolve host names and addresses. IPv4, IPv6.
* ''select()'' is used to suspend, waiting for one or more of a provided list of sockets to be ready to read, ready to write, or that have errors.
* ''poll()'' is used to check on the state of a socket in a set of sockets. The set can be tested to see if any socket can be written to, read from or if an error occurred.
* ''getsockopt()'' is used to retrieve the current value of a particular socket option for the specified socket.
* ''setsockopt()'' is used to set a particular socket option for the specified socket.

===socket===
The function ''socket()'' creates an endpoint for communication and returns a [[file descriptor]] for the socket. It uses three arguments:
* {{mono|<var>domain</var>}}, which specifies the protocol family of the created socket. For example:
**{{mono|PF_INET}} for network protocol [[IPv4]] (IPv4-only)
** {{mono|PF_INET6}} for [[IPv6]] (and in some cases, [[backward compatible]] with IPv4)
** {{mono|PF_UNIX}} for local socket (using a special filesystem node)
* {{mono|<var>type</var>}}, one of:
** {{mono|SOCK_STREAM}} (reliable stream-oriented service or [[stream socket]]s)
** {{mono|SOCK_DGRAM}} (datagram service or [[datagram socket]]s)
** {{mono|SOCK_SEQPACKET}} (reliable sequenced packet service)
** {{mono|SOCK_RAW}} (raw protocols atop the network layer)
* {{mono|<var>protocol</var>}} specifying the actual transport protocol to use. The most common are [[Transmission Control Protocol|{{mono|IPPROTO_TCP}}]], [[SCTP|{{mono|IPPROTO_SCTP}}]], [[User Datagram Protocol|{{mono|IPPROTO_UDP}}]], [[DCCP|{{mono|IPPROTO_DCCP}}]]. These protocols are specified in file ''netinet/in.h''. The value {{mono|0}} may be used to select a default protocol from the selected domain and type.

The function returns {{mono|-1}} if an error occurred. Otherwise, it returns an integer representing the newly assigned descriptor.

===bind===
''bind()'' associates a socket with an address. When a socket is created with ''socket()'', it is only given a protocol family, but not assigned an address. This association must be performed before the socket can accept connections from other hosts. The function has three arguments:
*<var>sockfd</var>, a descriptor representing the socket
*<var>my_addr</var>, a pointer to a ''sockaddr'' structure representing the address to bind to.
*<var>addrlen</var>, a field of type ''socklen_t'' specifying the size of the ''sockaddr'' structure.
''bind()'' returns 0 on success and -1 if an error occurs.

===listen===
After a socket has been associated with an address, <var>listen()</var> prepares it for incoming connections. However, this is only necessary for the stream-oriented (connection-oriented) data modes, i.e., for socket types (<var>SOCK_STREAM</var>, <var>SOCK_SEQPACKET</var>). <var>listen()</var> requires two arguments:
* <var>sockfd</var>, a valid socket descriptor.
* <var>backlog</var>, an integer representing the number of pending connections that can be queued up at any one time. The operating system usually places a cap on this value.
Once a connection is accepted, it is dequeued. On success, 0 is returned. If an error occurs, -1 is returned.

===accept===
When an application is listening for stream-oriented connections from other hosts, it is notified of such events (cf. [[Select (Unix)|select()]] function) and must initialize the connection using function ''accept()''. It creates a new socket for each connection and removes the connection from the listening queue. The function has the following arguments:
* <var>sockfd</var>, the descriptor of the listening socket that has the connection queued.
* <var>cliaddr</var>, a pointer to a sockaddr structure to receive  the client's address information.
* <var>addrlen</var>, a pointer to a ''socklen_t'' location that specifies the size of the client address structure passed to accept(). When ''accept()'' returns, this location contains the size (in bytes) of the  structure.

''accept()'' returns the new socket descriptor for the accepted connection, or the value ''-1'' if an error occurs. All further communication with the remote host now occurs via this new socket.

Datagram sockets do not require processing by accept() since the receiver may immediately respond to the request using the listening socket.

===connect===
''connect()'' establishes a direct communication link to a specific remote host identified by its address via a socket, identified by its file descriptor.

When using a [[Connection-oriented communication|connection-oriented]] protocol, this establishes a connection. Certain types of protocols are connectionless, most notably the [[User Datagram Protocol]]. When used with connectionless protocols, ''connect'' defines the remote address for sending and receiving data, allowing the use of functions such as ''send'' and ''recv''. In these cases, the connect function prevents reception of datagrams from other sources.

''connect()'' returns an integer representing the error code: ''0'' represents success, while ''–1'' represents an error. Historically, in BSD-derived systems, the state of a socket descriptor is undefined if the call to ''connect'' fails (as it is specified in the Single Unix Specification), thus, portable applications should close the socket descriptor immediately and obtain a new descriptor with socket(), in the case the call to connect() fails.{{sfn|Stevens|Rago|2013|p=607}}

===gethostbyname and gethostbyaddr===
The functions ''gethostbyname()'' and ''gethostbyaddr()'' are used to resolve host names and addresses in the [[domain name system]] or the local host's other resolver mechanisms (e.g., /etc/hosts lookup). They return a pointer to an object of type <var>struct hostent</var>, which describes an [[Internet Protocol]] host.  The functions use the following arguments:
* <var>name</var> specifies the name of the host.
* <var>addr</var> specifies a pointer to a <var>struct in_addr</var> containing the address of the host.
* <var>len</var> specifies the length, in bytes, of <var>addr</var>.
* <var>type</var> specifies the address family type (e.g., AF_INET) of the host address.

The functions return a NULL pointer in case of error, in which case the external integer {{mono|<var>h_errno</var>}} may be checked to see whether this is a temporary failure or an invalid or unknown host. Otherwise a valid <var>struct hostent *</var> is returned.

These functions are not strictly a component of the BSD socket API, but are often used in conjunction with the API functions for looking up a host. These functions are now considered legacy interfaces for querying the domain name system. New functions that are completely protocol-agnostic (supporting IPv6) have been defined. These new functions are [[getaddrinfo|getaddrinfo() and getnameinfo()]], and are based on a new ''[[addrinfo]]'' data structure.<ref>POSIX.1-2004</ref>

This pair of functions appeared at the same time as the BSD socket API proper in 4.2BSD (1983),<ref>{{man|3|gethostbyname|FreeBSD}}</ref> the same year DNS was first created. Early versions did not query DNS and only performed /etc/hosts lookup. The 4.3BSD (1984) version added DNS in a crude way. The current implementation using [[Name Service Switch]] derives Solaris and later NetBSD 1.4 (1999).<ref name="Conill">{{cite web |last1=Conill |first1=Ariadne |title=the tragedy of gethostbyname |url=https://ariadne.space/2022/03/27/the-tragedy-of-gethostbyname/ |website=ariadne.space |date=March 27, 2022}}</ref> Initially defined for [[NIS+]], NSS makes DNS only one of the many options for lookup by these functions and its use can be disabled even today.<ref>{{man|5|nsswitch.conf|FreeBSD}}</ref>