socket.h File Reference

Main sockets header. More...

#include <sys/cdefs.h>
#include <sys/types.h>

Go to the source code of this file.

Data Structures
struct	sockaddr
	Socket address structure. More...
struct	sockaddr_storage
	Socket address structure of appropriate size to hold any supported socket type's addresses. More...

Macros
#define	_SS_MAXSIZE   128
	Size of the struct sockaddr_storage. The size here is chosen for compatibility with anything that may expect the struct sockaddr_storage to be of size 128. Technically, since there are no current plans to support AF_UNIX sockets, this could be smaller, but most implementations make it 128 bytes. More...
#define	_SS_ALIGNSIZE   (sizeof(__uint64_t))
	Desired alignment of struct sockaddr_storage. More...
#define	_SS_PAD1SIZE   (_SS_ALIGNSIZE - sizeof(sa_family_t))
	First padding size used within struct sockaddr_storage. More...
#define	_SS_PAD2SIZE
	Second padding size used within struct sockaddr_storage. More...
#define	SOCK_DGRAM   1
	Datagram socket type. More...
#define	SOCK_STREAM   2
	Stream socket type. More...
#define	SOL_SOCKET   1
	Socket-level option setting. More...
#define	SO_ACCEPTCONN   1
	Socket is accepting connections (get) More...
#define	SO_BROADCAST   2
	Support broadcasting (get/set) More...
#define	SO_DEBUG   3
	Record debugging info (get/set) More...
#define	SO_DONTROUTE   4
	Do not route packets (get/set) More...
#define	SO_ERROR   5
	Retrieve error status (get) More...
#define	SO_KEEPALIVE   6
	Send keepalive messages (get/set) More...
#define	SO_LINGER   7
	Socket lingers on close (get/set) More...
#define	SO_OOBINLINE   8
	OOB data is inline (get/set) More...
#define	SO_RCVBUF   9
	Receive buffer size (get/set) More...
#define	SO_RCVLOWAT   10
	Receive low-water mark (get/set) More...
#define	SO_RCVTIMEO   11
	Receive timeout value (get/set) More...
#define	SO_REUSEADDR   12
	Reuse local addresses (get/set) More...
#define	SO_SNDBUF   13
	Send buffer size (get/set) More...
#define	SO_SNDLOWAT   14
	Send low-water mark (get/set) More...
#define	SO_SNDTIMEO   15
	Send timeout value (get/set) More...
#define	SO_TYPE   16
	Socket type (get) More...
#define	MSG_CTRUNC   0x01
	Control data truncated (U) More...
#define	MSG_DONTROUTE   0x02
	Send without routing (U) More...
#define	MSG_EOR   0x04
	Terminate a record (U) More...
#define	MSG_OOB   0x08
	Out-of-band data (U) More...
#define	MSG_PEEK   0x10
	Leave received data in queue. More...
#define	MSG_TRUNC   0x20
	Normal data truncated (U) More...
#define	MSG_WAITALL   0x40
	Attempt to fill read buffer. More...
#define	MSG_DONTWAIT   0x80
	Make this call non-blocking (non-standard) More...
#define	AF_UNSPEC   0
	Unspecified address family. More...
#define	AF_INET   1
	Internet domain sockets for use with IPv4 addresses. More...
#define	AF_INET6   2
	Internet domain sockets for use with IPv6 addresses. More...
#define	PF_UNSPEC   AF_UNSPEC
	Unspecified protocol family. More...
#define	PF_INET   AF_INET
	Protocol family for Internet domain sockets (IPv4). More...
#define	PF_INET6   AF_INET6
	Protocol family for Internet domain sockets (IPv6). More...
#define	SHUT_RD   0x00000001
	Disable furhter receive operations. More...
#define	SHUT_WR   0x00000002
	Disable further send operations. More...
#define	SHUT_RDWR   (SHUT_RD | SHUT_WR)
	Disable further send and receive operations. More...
#define	SOMAXCONN   32
	Maximum backlog for a listening socket. More...

Typedefs
typedef __uint32_t	socklen_t
	Socket length type. More...
typedef __uint8_t	sa_family_t
	Socket address family type. More...

Functions
int	accept (int socket, struct sockaddr *address, socklen_t *address_len)
	Accept a new connection on a socket. More...
int	bind (int socket, const struct sockaddr *address, socklen_t address_len)
	Bind a name to a socket. More...
int	connect (int socket, const struct sockaddr *address, socklen_t address_len)
	Connect a socket. More...
int	listen (int socket, int backlog)
	Listen for socket connections and set the queue length. More...
ssize_t	recv (int socket, void *buffer, size_t length, int flags)
	Receive a message on a connected socket. More...
ssize_t	recvfrom (int socket, void *buffer, size_t length, int flags, struct sockaddr *address, socklen_t *address_len)
	Receive a message on a socket. More...
ssize_t	send (int socket, const void *message, size_t length, int flags)
	Send a message on a connected socket. More...
ssize_t	sendto (int socket, const void *message, size_t length, int flags, const struct sockaddr *dest_addr, socklen_t dest_len)
	Send a message on a socket. More...
int	shutdown (int socket, int how)
	Shutdown socket send and receive operations. More...
int	socket (int domain, int type, int protocol)
	Create an endpoint for communications. More...
int	getsockopt (int socket, int level, int option_name, void *option_value, socklen_t *option_len)
	Get socket options. More...
int	setsockopt (int socket, int level, int option_name, const void *option_value, socklen_t option_len)
	Set socket options. More...

Detailed Description

Main sockets header.

This file contains the standard definitions (as directed by the POSIX 2008 standard) for socket-related functionality in the AF_INET address family. This does not include anything related to AF_INET6 (as IPv6 is not currently implemented in KOS) nor UNIX domain sockets, and is not guaranteed to have everything that one might have in a fully-standard compliant implementation of the POSIX standard.

Author

Lawrence Sebald

Macro Definition Documentation

#define _SS_ALIGNSIZE   (sizeof(__uint64_t))

Desired alignment of struct sockaddr_storage.

#define _SS_MAXSIZE   128

Size of the struct sockaddr_storage. The size here is chosen for compatibility with anything that may expect the struct sockaddr_storage to be of size 128. Technically, since there are no current plans to support AF_UNIX sockets, this could be smaller, but most implementations make it 128 bytes.

#define _SS_PAD1SIZE   (_SS_ALIGNSIZE - sizeof(sa_family_t))

First padding size used within struct sockaddr_storage.

#define _SS_PAD2SIZE

Value:

(_SS_MAXSIZE - (sizeof(sa_family_t) + \
                                     _SS_PAD1SIZE + _SS_ALIGNSIZE))

Second padding size used within struct sockaddr_storage.

#define AF_INET   1

Internet domain sockets for use with IPv4 addresses.

#define AF_INET6   2

Internet domain sockets for use with IPv6 addresses.

#define AF_UNSPEC   0

Unspecified address family.

#define PF_INET   AF_INET

Protocol family for Internet domain sockets (IPv4).

#define PF_INET6   AF_INET6

Protocol family for Internet domain sockets (IPv6).

#define PF_UNSPEC   AF_UNSPEC

Unspecified protocol family.

#define SHUT_RD   0x00000001

Disable furhter receive operations.

#define SHUT_RDWR   (SHUT_RD | SHUT_WR)

Disable further send and receive operations.

#define SHUT_WR   0x00000002

Disable further send operations.

#define SOCK_DGRAM   1

Datagram socket type.

This socket type specifies that the socket in question transmits datagrams that may or may not be reliably transmitted. With IP, this implies using UDP as the underlying protocol.

#define SOCK_STREAM   2

Stream socket type.

This socket type specifies that the socket in question acts like a stream or pipe between the two endpoints. Sockets of this type can be assumed to be reliable – unless an error is returned, all packets will be received at the other end in the order they are sent. With IP, this implies using TCP as the underlying protocol.

#define SOL_SOCKET   1

Socket-level option setting.

This constant should be used with the setsockopt() or getsockopt() function to represent that options should be accessed at the socket level, not the protocol level.

#define SOMAXCONN   32

Maximum backlog for a listening socket.

Typedef Documentation

typedef __uint8_t sa_family_t

Socket address family type.

typedef __uint32_t socklen_t

Socket length type.

Function Documentation

int accept	(	int	socket,
		struct sockaddr *	address,
		socklen_t *	address_len
	)

Accept a new connection on a socket.

This function extracts the first connection on the queue of connections of the specified socket, creating a new socket with the same protocol and address family as that socket for communication with the extracted connection.

Parameters

socket	A socket created with socket() that has been bound to an address with bind() and is listening for connections after a call to listen().
address	A pointer to a sockaddr structure where the address of the connecting socket will be returned (can be NULL).
address_len	A pointer to a socklen_t which specifies the amount of space in address on input, and the amount used of the space on output.

Returns

On success, the non-negative file descriptor of the new connection, otherwise -1 and errno will be set to the appropriate error value.

int bind	(	int	socket,
		const struct sockaddr *	address,
		socklen_t	address_len
	)

Bind a name to a socket.

This function assigns the socket to a unique name (address).

Parameters

socket	A socket that is to be bound.
address	A pointer to a sockaddr structure where the name to be assigned to the socket resides.
address_len	The length of the address structure.

Return values

0	On success.
-1	On error, sets errno as appropriate.

int connect	(	int	socket,
		const struct sockaddr *	address,
		socklen_t	address_len
	)

Connect a socket.

This function attempts to make a connection to a resource on a connection- mode socket, or sets/resets the peer address on a connectionless one.

Parameters

socket	A socket that is to be connected.
address	A pointer to a sockaddr structure where the name of the peer resides.
address_len	The length of the address structure.

Return values

0	On success.
-1	On error, sets errno as appropriate.

int getsockopt	(	int	socket,
		int	level,
		int	option_name,
		void *	option_value,
		socklen_t *	option_len
	)

Get socket options.

This function retrieves options associated with a socket. This function shall attempt to retrieve the specified option (at the specified level) from the given socket.

Parameters

socket	The socket to get options for.
level	The protocol level to get options at.
option_name	The option to look up.
option_value	Storage for the value of the option.
option_len	The length of option_value on call, and the real option length (if less than the original value) on return.

Returns

Zero on success. -1 on error, and sets errno as appropriate.

See also

Socket-level options

IPv4 protocol level options

IPv6 protocol level options

UDP protocol level options

int listen	(	int	socket,
		int	backlog
	)

Listen for socket connections and set the queue length.

This function marks a connection-mode socket for incoming connections.

Parameters

socket	A connection-mode socket to listen on.
backlog	The number of queue entries.

Return values

0	On success.
-1	On error, sets errno as appropriate.

ssize_t recv	(	int	socket,
		void *	buffer,
		size_t	length,
		int	flags
	)

Receive a message on a connected socket.

This function receives messages from the peer on a connected socket.

Parameters

socket	The socket to receive on.
buffer	A pointer to a buffer to store the message in.
length	The length of the buffer.
flags	The type of message reception. Set to 0 for now.

Returns

On success, the length of the message in bytes. If no messages are available, and the socket has been shut down, 0. On error, -1, and sets errno as appropriate.

ssize_t recvfrom	(	int	socket,
		void *	buffer,
		size_t	length,
		int	flags,
		struct sockaddr *	address,
		socklen_t *	address_len
	)

Receive a message on a socket.

This function receives messages from a peer on a (usually connectionless) socket.

Parameters

socket	The socket to receive on.
buffer	A pointer to a buffer to store the message in.
length	The length of the buffer.
flags	The type of message reception. Set to 0 for now.
address	A pointer to a sockaddr structure to store the peer's name in.
address_len	A pointer to the length of the address structure on input, the number of bytes used on output.

Returns

On success, the length of the message in bytes. If no messages are available, and the socket has been shut down, 0. On error, -1, and sets errno as appropriate.

ssize_t send	(	int	socket,
		const void *	message,
		size_t	length,
		int	flags
	)

Send a message on a connected socket.

This function sends messages to the peer on a connected socket.

Parameters

socket	The socket to send on.
message	A pointer to a buffer with the message to send.
length	The length of the message.
flags	The type of message transmission. Set to 0 for now.

Returns

On success, the number of bytes sent. On error, -1, and sets errno as appropriate.

ssize_t sendto	(	int	socket,
		const void *	message,
		size_t	length,
		int	flags,
		const struct sockaddr *	dest_addr,
		socklen_t	dest_len
	)

Send a message on a socket.

This function sends messages to the peer on a (usually connectionless) socket. If used on a connection-mode socket, this function may change the peer that the socket is connected to, or it may simply return error.

Parameters

socket	The socket to send on.
message	A pointer to a buffer with the message to send.
length	The length of the message.
flags	The type of message transmission. Set to 0 for now.
dest_addr	A pointer to a sockaddr structure with the peer's name.
dest_len	The length of dest_addr, in bytes.

Returns

On success, the number of bytes sent. On error, -1, and sets errno as appropriate.

int setsockopt	(	int	socket,
		int	level,
		int	option_name,
		const void *	option_value,
		socklen_t	option_len
	)

Set socket options.

This function sets options associated with a socket. This function shall attempt to set the specified option (at the specified level) from the given socket.

Parameters

socket	The socket to set options for.
level	The protocol level to set options at.
option_name	The option to set.
option_value	The value to set for the option.
option_len	The length of option_value in bytes.

Returns

Zero on success. -1 on error, and sets errno as appropriate.

See also

Socket-level options

IPv4 protocol level options

IPv6 protocol level options

UDP protocol level options

int shutdown	(	int	socket,
		int	how
	)

Shutdown socket send and receive operations.

This function closes a specific socket for the set of specified operations.

Parameters

socket	The socket to shutdown.
how	The type of shutdown.

Return values

0	On success.
-1	On error, sets errno as appropriate.

See also

SHUT_RD

SHUT_WR

SHUT_RDWR

int socket	(	int	domain,
		int	type,
		int	protocol
	)

Create an endpoint for communications.

This function creates an unbound socket for communications with the specified parameters.

Parameters

domain	The domain to create the socket in (i.e, AF_INET).
type	The type of socket to be created (i.e, SOCK_DGRAM).
protocol	The protocol to use with the socket. May be 0 to allow a default to be used.

Returns

A non-negative file descriptor on success. -1 on error, and sets errno as appropriate.