libinetsocket

C functions for work with BSD sockets (INET domain) More...

Functions
static signed int	check_error (int return_value)
	Checks return value for error. More...
int	create_inet_stream_socket (const char *host, const char *service, char proto_osi3, int flags)
	Create and connect a new TCP/IP socket. More...
int	create_inet_dgram_socket (char proto_osi3, int flags)
	Creates a new UDP/IP socket. More...
ssize_t	sendto_inet_dgram_socket (int sfd, const void *buf, size_t size, const char *host, const char *service, int sendto_flags)
	This function is the equivalent to sendto(2) More...
ssize_t	recvfrom_inet_dgram_socket (int sfd, void *buffer, size_t size, char *src_host, size_t src_host_len, char *src_service, size_t src_service_len, int recvfrom_flags, int numeric)
	Receive data from a UDP/IP socket. More...
int	connect_inet_dgram_socket (int sfd, const char *host, const char *service)
	Connect a UDP socket. More...
int	destroy_inet_socket (int sfd)
	Close a socket. More...
int	shutdown_inet_stream_socket (int sfd, int method)
	Perform a shutdown(2) call on a socket. More...
int	create_inet_server_socket (const char *bind_addr, const char *bind_port, char proto_osi4, char proto_osi3, int flags)
	Create a TCP or UDP server socket. More...
int	accept_inet_stream_socket (int sfd, char *src_host, size_t src_host_len, char *src_service, size_t src_service_len, int flags, int accept_flags)
	Accept a connection attempt on a server socket. More...
int	get_address_family (const char *hostname)
	Look up which address families a host supports. More...
int	create_multicast_socket (const char *group, const char *port, const char *if_name)
	Create a datagram socket and join to the multicast group address. More...

Detailed Description

C functions for work with BSD sockets (INET domain)

This module contains all functions which are part of the C internet socket library. Note: To obtain informations about errors, use errno. You may find possible values in the syscall's man pages.

Function Documentation

check_error()

static signed int check_error ( int  return_value )

inlinestatic

Checks return value for error.

Every value returned by a syscall is passed to this function. It returns 0 if the return value is ok or -1 if there was an error. If the macro VERBOSE is defined, an appropriate message is printed to STDERR.

Parameters

return_value

A return value from a syscall.

Return values

0	The syscall was successful.
-1	There was an error.

Definition at line 127 of file libinetsocket.c.

Here is the caller graph for this function:

create_inet_stream_socket()

int create_inet_stream_socket	(	const char *	host,
		const char *	service,
		char	proto_osi3,
		int	flags
	)

Create and connect a new TCP/IP socket.

This function returns a working client TCP/IP socket.

Parameters

host	The host the socket will be connected to (everything resolvable, e.g. "::1", "8.8.8.8", "example.com")
service	The host's port, either numeric or as service name ("http").
proto_osi3	LIBSOCKET_IPv4 or LIBSOCKET_IPv6.
flags	Flags to be passed to socket(2). Most flags are Linux-only!

Returns

A valid socket file descriptor.

Definition at line 155 of file libinetsocket.c.

create_inet_dgram_socket()

int create_inet_dgram_socket	(	char	proto_osi3,
		int	flags
	)

Creates a new UDP/IP socket.

Returns an integer describing a DGRAM (UDP) socket. The socket is automatically bound to some port.

Parameters

proto_osi3	is LIBSOCKET_IPv4 (AF_INET) or LIBSOCKET_IPv6 (AF_INET6).
flags	may be the flags specified in socket(2), i.e. SOCK_NONBLOCK and/or SOCK_CLOEXEC. More than one flags may be ORed. This argument is only sensible on Linux >= 2.6.27!

Returns

The socket file descriptor number, on error -1.

To send and receive data with this socket use the functions explained below, sendto_inet_dgram_socket() and recvfrom_inet_dgram_socket().

Definition at line 250 of file libinetsocket.c.

Here is the call graph for this function:

sendto_inet_dgram_socket()

ssize_t sendto_inet_dgram_socket	(	int	sfd,
		const void *	buf,
		size_t	size,
		const char *	host,
		const char *	service,
		int	sendto_flags
	)

This function is the equivalent to sendto(2)

Parameters

sfd	is the Socket File Descriptor (every socket file descriptor argument in libsocket is called sfd) which you got from create_inet_dgram_socket(). The usage with STREAM sockets is not recommended and the result is undefined!
buf	is a pointer to some data.
size	is the length of the buffer to which buf points.
host	is the host to which we want to send the data. It's a string so you may specify everything what's resolved by getaddrinfo(), i.e. an IP ("193.21.34.21") or a hostname ("example.net").
service	is the port on the remote host. Like in host, you may specify the port either as number ("123") or as service string ("ntp", "http", "gopher").
sendto_flags	is available on all platforms. The value given here goes directly to the internal sendto() call. The flags which may be specified differ between the platforms.

If it is not possible to send data at the moment, this call blocks excepted you specified SOCK_NONBLOCK when creating the socket.

Return values

n	n bytes of data could be sent.
-1	Error.

Definition at line 303 of file libinetsocket.c.

Here is the call graph for this function:

recvfrom_inet_dgram_socket()

ssize_t recvfrom_inet_dgram_socket	(	int	sfd,
		void *	buffer,
		size_t	size,
		char *	src_host,
		size_t	src_host_len,
		char *	src_service,
		size_t	src_service_len,
		int	recvfrom_flags,
		int	numeric
	)

Receive data from a UDP/IP socket.

Receives data like recvfrom(2). Pointers may be NULL, then the information (e.g. the source port) is lost (you may use NULL pointers if you're not interested in some information)

Parameters

sfd	The socket file descriptor.
buffer	Where the data will be written
size	The size of buffer
src_host	Where the sending host's name/IP will be stored
src_host_len	src_host's length
src_service	Where the port on remote side will be written to
src_service_len	src_service's length
recvfrom_flags	Flags for recvfrom(2)
numeric	LIBSOCKET_NUMERIC if you want the names to remain unresolved.

Return values

n	n bytes of data were received.
0	Peer sent EOF.
<0	An error occurred.

Definition at line 385 of file libinetsocket.c.

Here is the call graph for this function:

connect_inet_dgram_socket()

int connect_inet_dgram_socket	(	int	sfd,
		const char *	host,
		const char *	service
	)

Connect a UDP socket.

If a datagram socket is connected, all data written to it (using write(2)) is sent to the peer connected to and all data read(2) from it is data sent by the peer. Usually used by clients only.

Parameters

sfd	The socket file descriptor
host	The host to connect to
service	The port/service specifier

Return values

0	Success
-1	Error.

Definition at line 500 of file libinetsocket.c.

Here is the call graph for this function:

destroy_inet_socket()

int destroy_inet_socket

(

int

sfd

)

Close a socket.

This function closes a socket. You may also use close(2).

Parameters

sfd	The file descriptor

Return values

0	Closed socket successfully
-1	Socket was already closed (other errors are very unlikely to occur)

Definition at line 595 of file libinetsocket.c.

Here is the call graph for this function:

shutdown_inet_stream_socket()

int shutdown_inet_stream_socket	(	int	sfd,
		int	method
	)

Perform a shutdown(2) call on a socket.

If you're done with writing or reading from a socket you may signalize this to the OS and/or the peer. For example, shutting down a socket for writing sends the peer an EOF signal.

Parameters

sfd	The socket
method	LIBSOCKET_READ or LIBSOCKET_WRITE or the combination via |

Return values

0	Everything's fine.
-1	Something went wrong, e.g. the socket was closed, the file descriptor is invalid etc.

Definition at line 619 of file libinetsocket.c.

Here is the call graph for this function:

create_inet_server_socket()

int create_inet_server_socket	(	const char *	bind_addr,
		const char *	bind_port,
		char	proto_osi4,
		char	proto_osi3,
		int	flags
	)

Create a TCP or UDP server socket.

To accept connections from clients via TCP or receive datagrams via UDP, you need to create a server socket. This function creates such a socket and bind(2)s it to the specified address. If proto_osi4 is LIBSOCKET_TCP, listen(2) is called, too.

Parameters

bind_addr	Address to bind to. If you want to bind to every address use "0.0.0.0" or "::" (IPv6 wildcard)
bind_port	The port to bind to. If you write a webserver, this will be "http" or "80" or "https" or "443".
proto_osi4	Either LIBSOCKET_TCP or LIBSOCKET_UDP. Server sockets in TCP and UDP differ only in that TCP sockets need a call to listen(2)
proto_osi3	Either LIBSOCKET_IPv4, LIBSOCKET_IPv6 or LIBSOCKET_BOTH; latter means that the DNS resolver should decide.
flags	The flags argument is passed ORed to the type argument of socket(2); everything other than 0 does not make sense on other OSes than Linux.

Return values

>0	A working passive socket. Call accept_inet_stream_socket() next.
<0	Something went wrong; for example, the addresses where garbage or the port was not free.

Definition at line 670 of file libinetsocket.c.

accept_inet_stream_socket()

int accept_inet_stream_socket	(	int	sfd,
		char *	src_host,
		size_t	src_host_len,
		char *	src_service,
		size_t	src_service_len,
		int	flags,
		int	accept_flags
	)

Accept a connection attempt on a server socket.

This function accepts an incoming connection on a server socket.

(the src_* arguments may be NULL, in which case the address is not stored)

Parameters

sfd	The server socket
src_host	Buffer where the client's address is copied to
src_host_len	src_host's length. If the hostname is longer than this, it is truncated.
src_service	Buffer in which the client's port is stored
src_service_len	Its size. If shorter than the hostname it gets truncated.
flags	May be LIBSOCKET_NUMERIC; then there is no rDNS lookup and the IP and port number are stored as-is.
accept_flags	Flags for accept4(2) (which is only used on Linux)

Return values

>0	A socket file descriptor which can be used to talk to the client
<0	Error.

Definition at line 791 of file libinetsocket.c.

Here is the call graph for this function:

get_address_family()

int get_address_family

(

const char *

hostname

)

Look up which address families a host supports.

If you want to send a datagram to a host but you don't know if it supports IPv4 or IPv6, use this function. It returns the address family returned by a DNS lookup. On most systems IPv6 is the preferred address family.

Parameters

hostname

The hostname of the host you want to look up.

Return values

LIBSOCKET_IPv4	Host supports only IPv4
LIBSOCKET_IPv6	Host supports IPv6 (usually it supports IPv4 then, too)
<0	Error.

Definition at line 902 of file libinetsocket.c.

create_multicast_socket()

int create_multicast_socket	(	const char *	group,
		const char *	port,
		const char *	if_name
	)

Create a datagram socket and join to the multicast group address.

This function creates a multicast socket bound to address. The only option set is the IP_MULTICAST_IF (IPV6_MULTICAST_IF) option to avoid an explicit routing entry for the multicast address.

An option you want to set very likely is IP_MULTICAST_LOOP. Refer to ip(7) respectively ipv6(7) for setsockopt() options; for example:

int c = 0;
setsockopt(sfd,IPPROTO_IP,IP_MULTICAST_LOOP,&c,4);

The group address and port is also used as arguments to bind(2). After creating this socket, you may use the usual I/O functions on it, i.e. sendto_inet_dgram_socket and recvfrom_inet_dgram_socket.

Parameters

group	Group address. This address is also used to bind the socket
port	Multicast port.
local	For IPv4 multicast groups: The address of the interface to be used. Ignored for IPv6, NULL for kernel's choice

Return values

<0	Error (Check errno or use `LIBSOCKET_VERBOSE`)
>=0	A valid file descriptor.

Definition at line 964 of file libinetsocket.c.

Here is the call graph for this function: