Sockets

POSIX Sockets Interface for IPv4 and IPv6 Address Families More...

Topics
	Message Flags
	Socket message flags
	Options
	Socket-level options

Files
file	select.h
	Definitions for the select() function.
file	socket.h
	Main sockets header.

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.
#define	_SS_ALIGNSIZE   (sizeof(__uint64_t))
	Desired alignment of struct sockaddr_storage.
#define	_SS_PAD1SIZE   (_SS_ALIGNSIZE - sizeof(sa_family_t))
	First padding size used within struct sockaddr_storage.
#define	_SS_PAD2SIZE
	Second padding size used within struct sockaddr_storage.
#define	SOCK_DGRAM   1
	Datagram socket type.
#define	SOCK_STREAM   2
	Stream socket type.
#define	SOL_SOCKET   1
	Socket-level option setting.
#define	AF_UNSPEC   0
	Unspecified address family.
#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	PF_UNSPEC   AF_UNSPEC
	Unspecified protocol 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	SHUT_RD   0x00000001
	Disable further receive operations.
#define	SHUT_WR   0x00000002
	Disable further send operations.
#define	SHUT_RDWR   (SHUT_RD | SHUT_WR)
	Disable further send and receive operations.
#define	SOMAXCONN   32
	Maximum backlog for a listening socket.

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

Functions
int	accept (int socket, struct sockaddr *address, socklen_t *address_len)
	Accept a new connection on a socket.
int	bind (int socket, const struct sockaddr *address, socklen_t address_len)
	Bind a name to a socket.
int	connect (int socket, const struct sockaddr *address, socklen_t address_len)
	Connect a socket.
int	listen (int socket, int backlog)
	Listen for socket connections and set the queue length.
ssize_t	recv (int socket, void *buffer, size_t length, int flags)
	Receive a message on a connected socket.
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.
ssize_t	send (int socket, const void *message, size_t length, int flags)
	Send a message on a connected socket.
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.
int	shutdown (int socket, int how)
	Shutdown socket send and receive operations.
int	socket (int domain, int type, int protocol)
	Create an endpoint for communications.
int	getsockname (int socket, struct sockaddr *name, socklen_t *name_len)
	Get socket name.
int	getpeername (int socket, struct sockaddr *__RESTRICT name, socklen_t *__RESTRICT name_len)
	Get the name of the connected peer socket.
int	getsockopt (int socket, int level, int option_name, void *option_value, socklen_t *option_len)
	Get socket options.
int	setsockopt (int socket, int level, int option_name, const void *option_value, socklen_t option_len)
	Set socket options.

Detailed Description

POSIX Sockets Interface for IPv4 and IPv6 Address Families

Macro Definition Documentation

_SS_ALIGNSIZE

#define _SS_ALIGNSIZE   (sizeof(__uint64_t))

Desired alignment of struct sockaddr_storage.

_SS_MAXSIZE

#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.

_SS_PAD1SIZE

#define _SS_PAD1SIZE   (_SS_ALIGNSIZE - sizeof(sa_family_t))

First padding size used within struct sockaddr_storage.

_SS_PAD2SIZE

#define _SS_PAD2SIZE

Value:

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

Second padding size used within struct sockaddr_storage.

AF_INET

#define AF_INET   1

Internet domain sockets for use with IPv4 addresses.

AF_INET6

#define AF_INET6   2

Internet domain sockets for use with IPv6 addresses.

AF_UNSPEC

#define AF_UNSPEC   0

Unspecified address family.

PF_INET

#define PF_INET   AF_INET

Protocol family for Internet domain sockets (IPv4).

PF_INET6

#define PF_INET6   AF_INET6

Protocol family for Internet domain sockets (IPv6).

PF_UNSPEC

#define PF_UNSPEC   AF_UNSPEC

Unspecified protocol family.

SHUT_RD

#define SHUT_RD   0x00000001

Disable further receive operations.

SHUT_RDWR

#define SHUT_RDWR   (SHUT_RD | SHUT_WR)

Disable further send and receive operations.

SHUT_WR

#define SHUT_WR   0x00000002

Disable further send operations.

SOCK_DGRAM

#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.

SOCK_STREAM

#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.

SOL_SOCKET

#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.

SOMAXCONN

#define SOMAXCONN   32

Maximum backlog for a listening socket.

Typedef Documentation

sa_family_t

typedef __uint8_t sa_family_t

Socket address family type.

socklen_t

typedef __uint32_t socklen_t

Socket length type.

Function Documentation

accept()

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.

bind()

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.

connect()

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.

getpeername()

int getpeername	(	int	socket,
		struct sockaddr *__RESTRICT	name,
		socklen_t *__RESTRICT	name_len )

Get the name of the connected peer socket.

This function retrieves the address of the peer connected to the socket specified by the socket descriptor. The address is returned in the buffer pointed to by the name parameter, and the actual length of the address is returned in the name_len parameter.

Parameters

socket	A socket that is already connected to a peer.
name	A pointer to a sockaddr structure where the peer address will be stored.
name_len	A pointer to a socklen_t variable that specifies the length of the address structure. On return, it will contain the actual size of the address returned.

Return values

0

On success.

-1

On error, sets errno as appropriate, such as: EBADF: The socket argument is not a valid file descriptor. EFAULT: The addr argument points to memory not in a valid part of the process address space. ENOBUFS: Insufficient resources were available in the system to perform the operation. ENOTCONN: The socket is not connected. ENOTSOCK: The socket argument does not refer to a socket. EOPNOTSUPP: The socket does not support getpeername.

getsockname()

int getsockname	(	int	socket,
		struct sockaddr *	name,
		socklen_t *	name_len )

Get socket name.

This function returns the locally bound address information for a specified socket.

Parameters

socket	The socket to get the name of.
name	Pointer to a sockaddr structure which will hold the resulting address information.
name_len	The amount of space pointed to by name, in bytes. On return, this is set to the actual size of the returned address information.

Return values

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

getsockopt()

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

Options

Options

Options

UDP Options

listen()

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.

recv()

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.

recvfrom()

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.

send()

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.

sendto()

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.

setsockopt()

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

Options

Options

Options

UDP Options

shutdown()

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

socket()

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.