socket.h

Main socket header.

See also

The Open Group Base Specifications Issue 7, <sys/socket.h>

Omitted from original specification for now:

  • struct msghdr, struct cmesghdr, and struct linger and all related defines
  • socket.h::getsockopt()/setsockopt() and all related defines.
  • shutdown() and all related defines.
  • sockatmark()

SOCK_DGRAM

Datagram socket. 

1
(1)
SOCK_RAW

Raw socket. 

1
(2)
SOCK_SEQPACKET

Sequenced-packet socket. 

1
(3)
SOCK_STREAM

Stream socket. 

1
(4)
SO_ACCEPTCONN

Socket is accepting connections. 

1
(0)
SO_BROADCAST

Transmission of broadcast messages is supported. 

1
(1)
SO_DEBUG

Debugging information is being recorded. 

1
(2)
SO_DONTROUTE

Bypass normal routing. 

1
(3)
SO_ERROR

Socket error status. 

1
(4)
SO_KEEPALIVE

Connections are kept alive with periodic messages. 

1
(5)
SO_LINGER

Socket lingers on close. 

1
(6)
SO_OOBINLINE

Out-of-band data is transmitted in line. 

1
(7)
SO_RCVBUF

Receive buffer size. 

1
(8)
SO_RCVLOWAT

Receive “low water mark”. 

1
(9)
SO_RCVTIMEO

Receive timeout. 

1
(10)
SO_REUSEADDR

Reuse of local addresses is supported. 

1
(11)
SO_SNDBUF

Send buffer size. 

1
(12)
SO_SNDLOWAT

Send “low water mark”. 

1
(13)
SO_SNDTIMEO

Send timeout. 

1
(14)
SO_TYPE

Socket type. 

1
(15)
int getsockopt(int socket, int level, int option_name, void * option_value, bytes.h::socklen_t * option_len)

implement out these functions

int setsockopt(int socket, int level, int option_name, const void * option_value, bytes.h::socklen_t option_len)
SOCKET_POOL_SIZE

Maximum number of sockets available on for creation with socket.h::socket() 

1
(4)
SOCKET_TCP_QUEUE_SIZE

Maximum number of incoming TCP connections a listening socket can handle. 

1
(0)
SOCKADDR_MAX_DATA_LEN

Maximum data length for a socket address. 

1
(26)

It is assumed that struct sockaddr_in6 is currently the longest socket address struct. As such it’s data length is taken consisting of the IPv6 address (16 byte), the port (2 byte), the flow information (4 byte) and the scope ID (4 byte)

SOL_SOCKET

Options to be accessed at socket level, not protocol level. 

1
(-1)
unsigned short sa_family_t

address family type

int accept(int socket, struct sockaddr *__restrict address, bytes.h::socklen_t *__restrict address_len)

Accept a new connection on a socket.

The socket.h::accept() function shall extract the first connection on the queue of pending connections, create a new socket with the same socket type protocol and address family as the specified socket, and allocate a new file descriptor for that socket. If the listen queue is empty of connection requests and O_NONBLOCK is not set on the file descriptor for the socket, socket.h::accept() shall block until a connection is present. If the socket.h::listen() queue is empty of connection requests and O_NONBLOCK is set on the file descriptor for the socket, socket.h::accept() shall fail and set errno to [EAGAIN] or [EWOULDBLOCK]. The accepted socket cannot itself accept more connections. The original socket remains open and can accept more connections.

See also

The Open Group Base Specification Issue 7, accept

Parameters

socket:Specifies a socket that was created with socket.h::socket(), has been bound to an address with socket.h::bind(), and has issued a successful call to socket.h::listen().
address:Either a null pointer, or a pointer to a sockaddr structure where the address of the connecting socket shall be returned. If address is not a null pointer, the address of the peer for the accepted connection shall be stored in the sockaddr structure pointed to by address, and the length of this address shall be stored in the object pointed to by address_len. If the actual length of the address is greater than the length of the supplied sockaddr structure, the stored address shall be truncated. If the protocol permits connections by unbound clients, and the peer is not bound, then the value stored in the object pointed to by address is unspecified.
address_len:Either a null pointer, if address is a null pointer, or a pointer to a socklen_t object which on input specifies the length of the supplied sockaddr structure, and on output specifies the length of the stored address.

Return values

  • Upon successful completion, socket.h::accept() shall return the non-negative file descriptor of the accepted socket. Otherwise, -1 shall be returned and errno set to indicate the error.
int bind(int socket, const struct sockaddr * address, bytes.h::socklen_t address_len)

Bind a name to a socket.

The socket.h::bind() function shall assign a local socket address address to a socket identified by descriptor socket that has no local socket address assigned. Sockets created with the socket.h::socket() function are initially unnamed; they are identified only by their address family.

See also

The Open Group Base Specification Issue 7, bind

Parameters

socket:Specifies the file descriptor of the socket to be bound.
address:Points to a sockaddr structure containing the address to be bound to the socket. The length and format of the address depend on the address family of the socket. If the address family of the socket is AF_UNIX and the pathname in address names a symbolic link, socket.h::bind() shall fail and set errno to [EADDRINUSE].
address_len:Specifies the length of the sockaddr structure pointed to by the address argument.

Return values

  • Upon successful completion, socket.h::bind() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.
int connect(int socket, const struct sockaddr * address, bytes.h::socklen_t address_len)

Connect a socket.

The socket.h::connect() function shall attempt to make a connection on a connection-mode socket or to set or reset the peer address of a connectionless-mode socket.

See also

The Open Group Base Specification Issue 7, connect

Parameters

socket:Specifies the file descriptor associated with the socket.
address:Points to a sockaddr structure containing the peer address. The length and format of the address depend on the address family of the socket.
address_len:Specifies the length of the sockaddr structure pointed to by the address argument.

Return values

  • Upon successful completion, socket.h::connect() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.
int getpeername(int socket, struct sockaddr *__restrict address, bytes.h::socklen_t *__restrict address_len)

Get the name of the peer socket.

The socket.h::getpeername() function shall retrieve the peer address of the specified socket, store this address in the sockaddr structure pointed to by the address argument, and store the length of this address in the object pointed to by the address_len argument.

See also

The Open Group Base Specification Issue 7, getpeername

Parameters

socket:Specifies the file descriptor associated with the socket.
address:Points to a sockaddr structure containing the peer address. The length and format of the address depend on the address family of the socket.
address_len:Specifies the length of the sockaddr structure on input and the length of the stored address on output. If the address is greater than the length of the supplied sockaddr structure, the stored address shal be truncated.

Return values

  • Upon successful completion, socket.h::getpeername() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.
int getsockname(int socket, struct sockaddr *__restrict address, bytes.h::socklen_t *__restrict address_len)

Get the socket name.

The socket.h::getsockname() function shall retrieve the locally-bound name of the specified socket, store this address in the sockaddr structure pointed to by the address argument, and store the length of this address in the object pointed to by the address_len argument.

See also

The Open Group Base Specification Issue 7, getsockname

Parameters

socket:Specifies the file descriptor associated with the socket.
address:Points to a sockaddr structure containing the peer address. The length and format of the address depend on the address family of the socket.
address_len:Specifies the length of the sockaddr structure on input and the length of the stored address on output. If the address is greater than the length of the supplied sockaddr structure, the stored address shal be truncated.

Return values

  • Upon successful completion, socket.h::getsockname() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.
int listen(int socket, int backlog)

Listen for socket connections and limit the queue of incoming connections.

See also

The Open Group Base Specification Issue 7, listen

Parameters

socket:Specifies the file descriptor associated with the socket.
backlog:Provides a hint to the implementation which the implementation shall use to limit the number of outstanding connections in the socket’s listen queue. Implementations may impose a limit on backlog and silently reduce the specified value. Normally, a larger backlog argument value shall result in a larger or equal length of the listen queue. Implementations shall support values of backlog up to SOMAXCONN, defined in <sys/socket.h>.

Return values

  • Upon successful completions, socket.h::listen() shall return 0; otherwise, -1 shall be returned and errno set to indicate the error.
msp430_types.h::ssize_t recvfrom(int socket, void *__restrict buffer, msp430_types.h::size_t length, int flags, struct sockaddr *__restrict address, bytes.h::socklen_t *__restrict address_len)

Receive a message from a socket.

The socket.h::recvfrom() function shall receive a message from a connection-mode or connectionless-mode socket. It is normally used with connectionless-mode sockets because it permits the application to retrieve the source address of received data.

See also

The Open Group Base Specification Issue 7, recvfrom

Parameters

socket:Specifies the socket file descriptor.
buffer:Points to a buffer where the message should be i stored.
length:Specifies the length in bytes of the buffer pointed to by the buffer argument.
flags:Specifies the type of message reception. Support for values other than 0 is not implemented yet.
address:A null pointer, or points to a sockaddr structure in which the sending address is to be stored. The length and format of the address depend on the address family of the socket.
address_len:Either a null pointer, if address is a null pointer, or a pointer to a socklen_t object which on input specifies the length of the supplied sockaddr structure, and on output specifies the length of the stored address.

Return values

  • Upon successful completion, socket.h::recvfrom() shall return the length of the message in bytes. If no messages are available to be received and the peer has performed an orderly shutdown, socket.h::recvfrom() shall return 0. Otherwise, the function shall return -1 and set errno to indicate the error.
msp430_types.h::ssize_t recv(int socket, void * buffer, msp430_types.h::size_t length, int flags)

Receive a message from a connected socket.

Shall receive a message from a connection-mode or connectionless-mode socket. It is normally used with connected sockets because it does not permit the application to retrieve the source address of received data.

See also

The Open Group Base Specification Issue 7, recv

Parameters

socket:Specifies the socket file descriptor.
buffer:Points to a buffer where the message should be stored.
length:Specifies the length in bytes of the buffer pointed to by the buffer argument.
flags:Specifies the type of message reception. Support for values other than 0 is not implemented yet.

Return values

  • Upon successful completion, socket.h::recv() shall return the length of the message in bytes. If no messages are available to be received and the peer has performed an orderly shutdown, socket.h::recv() shall return 0. Otherwise, -1 shall be returned and errno set to indicate the error.
msp430_types.h::ssize_t sendto(int socket, const void * buffer, msp430_types.h::size_t length, int flags, const struct sockaddr * address, bytes.h::socklen_t address_len)

Send a message on a socket.

Shall send a message through a connection-mode or connectionless-mode socket. If the socket is a connectionless-mode socket, the message shall be sent to the address specified by address if no pre-specified peer address has been set. If a peer address has been pre-specified, either the message shall be sent to the address specified by address (overriding the pre-specified peer address), or the function shall return -1 and set errno to EISCONN.

See also

The Open Group Base Specification Issue 7, sendto

Parameters

socket:Specifies the socket file descriptor.
buffer:Points to the buffer containing the message to send.
length:Specifies the length of the message in bytes.
flags:Specifies the type of message reception. Support for values other than 0 is not implemented yet.
address:Points to a sockaddr structure containing the destination address. The length and format of the address depend on the address family of the socket.
address_len:Specifies the length of the sockaddr structure pointed to by the address argument.

For Generic (GNRC) network stack any socket.h::recvfrom() call that is called to receive an expected response to this send command, must be called from the same thread. This is undesired behavior and will be fixed in upcoming versions of RIOT.

Return values

  • Upon successful completion, socket.h::send() shall return the number of bytes sent. Otherwise, -1 shall be returned and errno set to indicate the error.
msp430_types.h::ssize_t send(int socket, const void * buffer, msp430_types.h::size_t length, int flags)

Send a message on a socket.

Shall initiate transmission of a message from the specified socket to its peer. The socket.h::send() function shall send a message only when the socket is connected. If the socket is a connectionless-mode socket, the message shall be sent to the pre-specified peer address.

See also

The Open Group Base Specification Issue 7, send

Parameters

socket:Specifies the socket file descriptor.
buffer:Points to the buffer containing the message to send.
length:Specifies the length of the message in bytes.
flags:Specifies the type of message reception. Support for values other than 0 is not implemented yet.

Return values

  • Upon successful completion, socket.h::send() shall return the number of bytes sent. Otherwise, -1 shall be returned and errno set to indicate the error.
int socket(int domain, int type, int protocol)

Create an endpoint for communication.

Shall create an unbound socket in a communications domain, and return a file descriptor that can be used in later function calls that operate on sockets.

Parameters

domain:Specifies the communications domain in which a socket is to be created. Valid values are prefixed with `AF_ and defined in socket.h.
type:Specifies the type of socket to be created. Valued values are prefixed with SOCK_ and defined in socket.h.
protocol:Specifies a particular protocol to be used with the socket. Specifying a protocol of 0 causes socket.h::socket() to use an unspecified default protocol appropriate for the requested socket type.

Return values

  • Upon successful completion, socket.h::socket() shall return a non-negative integer, the socket file descriptor. Otherwise, a value of -1 shall be returned and errno set to indicate the error.
struct sockaddr

Used to define the socket address.

socket.h::sa_family_t sa_family

Address family.

char sa_data()

Socket address (variable length data)

struct sockaddr_storage

Implementation based socket address table.

sockaddr

socket.h::sa_family_t ss_family

Address family.

uint8_t ss_data()

Socket address.