LibGGZ: Easysock IO

#define GGZ_SOCKET_DEBUG "socket"

ggz_debug debugging type for Easysock debugging.

To enable socket debugging, add this to the list of debugging types.

See also:: ggz_debug_enable

typedef void(*) ggzIOError(const char *msg, const GGZIOType type, const int fd, const GGZDataType data)

An error function type.

This function type will be called when there is an error in a GGZ socket function.

Parameters:

	msg	The strerror message associated with the error
	type	The type of error that occurred
	fd	The socket on which the error occurred, or -1 if not applicable
	data	Extra data associated with the error

typedef void(*) ggzIOExit(int status)

An exit function type.

This function type will be called to exit the program.

Parameters:

status

The exit value

typedef void(*) ggzNetworkNotify(const char *address, int socket)

A network resolver function type.

This function type will be called whenever a hostname has been resolved or a socket has been created asynchronously.

Parameters:

	status	The IP address of the host name
	socket	File descriptor or error code like in ggz_make_socket

enum GGZIOType

An error type for the GGZ socket functions.

If there is a GGZ socket error, the registered error handler will be called and will be given one of these error types.

Enumerator:

GGZ_IO_CREATE	Error creating a socket.
GGZ_IO_READ	Error reading from a socket.
GGZ_IO_WRITE	Error writing to a socket.
GGZ_IO_ALLOCATE	Error when the allocation limit is exceeded.

enum GGZDataType

A data type for the GGZ socket function error handler.

If there is a GGZ socket error, the registered error handler will be called and will be given one of these error data types.

Enumerator:

GGZ_DATA_NONE	No data is associated with the error.
GGZ_DATA_CHAR	The error occurred while dealing with a char.
GGZ_DATA_INT	The error occurred in dealing with an integer.
GGZ_DATA_STRING	The error occurred in dealing with a string.
GGZ_DATA_FD	Error while dealing with a file descriptor.

enum GGZSockType

A socket type.

These socket types are used by ggz_make_socket() and friends to decide what actions are necessary in making a connection.

Enumerator:

GGZ_SOCK_SERVER	Just listen on a particular port.
GGZ_SOCK_CLIENT	Connect to a particular port of a server.

int ggz_set_io_error_func ( ggzIOError func )

Set the ggz/easysock error handling function.

Any time an error occurs in a GGZ socket function, the registered error handling function will be called. Use this function to register a new error function. Any previous error function will be discarded.

Parameters:

func

The new error-handling function

Returns:: 0

Todo:: Shouldn't this function return a void or ggzIOError?

ggzIOError ggz_remove_io_error_func ( void )

Remove the ggz/easysock error handling function.

The default behavior when a socket failure occurs in one of the GGZ socket functions is to do nothing (outside of the function's return value). This may be overridden by registering an error handler with ggz_set_io_error_func(), but the behavior may be returned by calling this function to remove the error handler.

Returns:: The previous error-handling function, or NULL if none.

int ggz_set_io_exit_func ( ggzIOExit func )

Set the ggz/easysock exit function.

Any of the *_or_die() functions will call the set exit function if there is an error. If there is no set function, exit() will be called.

Parameters:

func

The newly set exit function

Returns:: 0

Todo:: Shouldn't this return a void?

ggzIOExit ggz_remove_io_exit_func ( void )

Remove the ggz/easysock exit function.

This removes the existing exit function, if one is set. exit() will then be called to exit the program.

Returns:: The old exit function (or NULL if none)

unsigned int ggz_get_io_alloc_limit ( void )

Get libggz's limit on memory allocation.

Returns:: The limit to allow on ggz_read_*_alloc() calls, in bytes

See also:: ggz_set_io_alloc_limit

unsigned int ggz_set_io_alloc_limit ( const unsigned int limit )

Set libggz's limit on memory allocation.

In functions of the form ggz_read_*_alloc(), libggz will itself allocate memory for the * object that is being read in. This presents an obvious security concern, so we limit the amount of memory that can be allocated. The default value is 32,767 bytes, but it can be changed by calling this function.

Parameters:

limit

The new limit to allow on alloc-style calls, in bytes

Returns:: The previous limit

See also:: ggz_get_io_alloc_limit
ggz_read_string_alloc

int ggz_init_network ( void )

Initialize the network.

This function will do anything necessary to initialize the network to use sockets (this is needed on some platforms). It should be called at least once before any sockets are put to use. Calling it more than once is harmless. It will be called automatically at the start of all GGZ socket creation functions.

Returns:: 0 on success, negative on failure

int ggz_set_network_notify_func ( ggzNetworkNotify func )

Set the ggz/easysock resolver notification function.

This function will be called whenever a resolving task submitted to ggz_resolvename() or ggz_make_socket() has finished.

Parameters:

func

The newly set resolver notification function

Returns:: 0

Todo:: Shouldn't this return a void? (from ggz_set_io_exit_func)

const char* ggz_resolvename ( const char * name )

Resolve a host name.

In order to prevent blocking GUIs, this function can handle resolving a hostname into a numerical address asynchronously. The notification function will be called whenever it finishes. It receives as its argument the address, which might still be the same hostname in the case of errors. The result should be passed to gethostbyname() to receive the network data structures. If no notification function is set, this function returns the hostname as it is, without any lookup. If no GAI support is available, but a notification function is set, it is called with the unresolved hostname, too.

Parameters:

name

Hostname to resolve

Returns:: The hostname in case no notification function is set, or NULL

Todo:: Should this resolve synchronously in the special cases above?

const char* ggz_getpeername	(	int	fd,
		int	resolve
	)

Get the IP address or host name of a connected peer.

This function tells about the IP address of the peer which is connected to the specified socket. If resolving is enabled, then the hostname is returned instead. In this case, resolving will be a blocking operation.

Parameters:

	fd	Local end file descriptor of the connection
	resolve	Whether or not to resolve the host name

Returns:: IP address or host name of peer, or NULL on error

Note:: The string must be ggz_free()d afterwards

int ggz_make_socket	(	const GGZSockType	type,
		const unsigned short	port,
		const char *	server
	)

Make a socket connection.

This function makes a TCP socket connection.

For a server socket, we'll just listen on the given port and accept the first connection that is made there.
For a client socket, we'll connect to a server that is (hopefully) listening at the given port and hostname.

Note that when a ggzNetworkNotify callback has been set up, this function returns immediately and creates the socket later on.

Parameters:

	type	The type of socket (server or client)
	port	The port to listen/connect to
	server	The server hostname for clients, the interface address else

Returns:: File descriptor on success, -1 on creation error, -2 on lookup error, -3 when using asynchronous creation

int ggz_make_socket_or_die	(	const GGZSockType	type,
		const unsigned short	port,
		const char *	server
	)

Make a socket connection, exiting on error.

Aside from the error condition, this is identical to ggz_make_socket().

int ggz_make_unix_socket	(	const GGZSockType	type,
		const char *	name
	)

Connect to a unix domain socket.

This function connects to a unix domain socket, a socket associated with a file on the VFS.

For a server socket, we unlink the socket file first and then create it.
For a client socket, we connect to a pre-existing socket file.

Parameters:

	type	The type of socket (server or client)
	name	The name of the socket file

Returns:: The socket FD on success, -1 on error

Note:: When possible, this should not be used. Use socketpair() instead.

int ggz_make_unix_socket_or_die	(	const GGZSockType	type,
		const char *	name
	)

Connect to a unix domain socket, exiting on error.

Aside from the error condition, this is identical to ggz_make_unix_socket().

int ggz_write_char	(	const int	sock,
		const char	data
	)

Write a character value to the given socket.

This function will write a single character to the socket. The character will be readable at the other end with ggz_read_char.

Parameters:

	sock	The socket file descriptor to write to
	data	A single character to write

Returns:: 0 on success, -1 on error

void ggz_write_char_or_die	(	const int	sock,
		const char	data
	)

Write a character value to the given socket, exiting on error.

Parameters:

	sock	The socket file descriptor to write to
	data	A single character to write

Note:: Aside from error handling, this is identical to ggz_write_char().

int ggz_read_char	(	const int	sock,
		char *	data
	)

Read a character value from the given socket.

This function will read a single character (as written by ggz_write_char()) from a socket. It places the value into the character pointed to.

Parameters:

	sock	The socket file descriptor to read from
	data	A pointer to a single character

Returns:: 0 on success, -1 on error

void ggz_read_char_or_die	(	const int	sock,
		char *	data
	)

Read a character value from the given socket, exiting on error.

Parameters:

	sock	The socket file descriptor to read from
	data	A pointer to a single character

Note:: Aside from error handling, this is identical to ggz_read_char().

int ggz_write_int	(	const int	sock,
		const int	data
	)

Write an integer to the socket in network byte order.

ggz_write_int() and ggz_read_int() can be used to send an integer across a socket. The integer will be sent in network byte order, so the functions may safely be used across a network. Note, though, that it is probably not safe to use this function to send structs or other data that may use a different representation than a simple integer.

Parameters:

	sock	The socket to write to
	data	The integer to write

Returns:: 0 on success, -1 on error

void ggz_write_int_or_die	(	const int	sock,
		const int	data
	)

Write an integer to the socket, exiting on error.

Aside from the error condition, this function is identical to ggz_write_int().

int ggz_read_int	(	const int	sock,
		int *	data
	)

Read an integer from the socket in network byte order.

See also:: ggz_write_int

Parameters:

	sock	The socket to read from
	data	A pointer to an integer in which to place the data

Returns:: 0 on success, -1 on error

void ggz_read_int_or_die	(	const int	sock,
		int *	data
	)

Read an integer from the socket, exiting on error.

Aside from the error condition, this function is identical to ggz_read_int.

int ggz_write_string	(	const int	sock,
		const char *	data
	)

Write a string to the given socket.

This function will write a full string to the given socket. The string may be read at the other end by ggz_read_string() and friends.

Parameters:

	sock	The socket file descriptor to write to
	data	A pointer to the string to write

Returns:: 0 on success, -1 on error

void ggz_write_string_or_die	(	const int	sock,
		const char *	data
	)

Write a string to the given socket, exiting on error.

Aside from the error condition, this function is identical to ggz_write_string().

int ggz_va_write_string	(	const int	sock,
		const char *	fmt,
			...
	)

Write a printf-style formatted string to the given socket.

This function allows a format string and a list of arguments to be passed in. The function will assemble the string (printf-style) and write it to the socket.

Parameters:

	sock	The socket file descriptor to write to
	fmt	A printf-style formatting string
	...	A printf-style list of arguments

Note:: This function will write identically to ggz_write_string().

int void ggz_va_write_string_or_die	(	const int	sock,
		const char *	fmt,
			...
	)

Write a formatted string to the socket, exiting on error.

Aside from the error condition, this function is identical to ggz_va_write_string.

int void int ggz_read_string	(	const int	sock,
		char *	data,
		const unsigned int	len
	)

Read a string from the given socket.

This function will read a full string from the given socket. The string may be written at the other end by ggz_write_string() and friends. The length of the string is given as well to avoid buffer overruns; any characters beyond this will be lost.

Parameters:

	sock	The socket file descriptor to read from
	data	A pointer to the string to read; it will be changed
	len	The length of the string pointed to by data

Returns:: 0 on success, -1 on error

void ggz_read_string_or_die	(	const int	sock,
		char *	data,
		const unsigned int	len
	)

Read a string from the given socket, exiting on error.

Aside from the error condition, this function is identical to ggz_read_string().

int ggz_read_string_alloc	(	const int	sock,
		char **	data
	)

Read and allocate a string from the given socket.

This function reads a string from the socket, just like ggz_read_string(). But instead of passing in a pre-allocated buffer to write in, here we pass a pointer to a string pointer:

    char* str;
    if (ggz_read_string_alloc(fd, &str) >= 0) {
        // ... handle the string ...
        ggz_free(str);
    }

Parameters:

	sock	The socket file descriptor to read from
	data	A pointer to an empty string pointer

Returns:: 0 on success, -1 on error

Note:: The use of this function is a security risk.

See also:: ggz_set_io_alloc_limit

void ggz_read_string_alloc_or_die	(	const int	sock,
		char **	data
	)

Read and allocate string from the given socket, exiting on error.

Aside from the error condition, this function is identical to ggz_read_string_alloc().

int ggz_write_fd	(	const int	sock,
		int	sendfd
	)

Write a file descriptor to the given (local) socket.

ggz_write_fd() and ggz_read_fd() handle the rather tricky task of sending a file descriptor across a socket. The FD is written with ggz_write_fd() and can be read at the other end by ggz_read_fd(). Note that this will only work for local sockets (i.e. not over the network). Many thanks to Richard Stevens and his wonderful books, from which these functions come.

Parameters:

	sock	The socket to write to
	sendfd	The FD to send across the socket

Returns:: 0 on success, -1 on error

int ggz_read_fd	(	const int	sock,
		int *	recvfd
	)

Read a file descriptor from the given (local) socket.

See also:: ggz_write_fd

Parameters:

	sock	The socket to read from
	recvfd	The FD that is read

Returns:: 0 on success, -1 on error

int ggz_writen	(	const int	sock,
		const void *	vdata,
		size_t	n
	)

Write a sequence of bytes to the socket.

ggz_writen() and ggz_readn() are used to send an arbitrary quantity of raw data across the a socket. The data is written with ggz_writen() and can be read at the other end with ggz_readn(). Many thanks to Richard Stevens and his wonderful books, from which these functions come.

Parameters:

	sock	The socket to write to
	vdata	A pointer to the data to write
	n	The number of bytes of data to write from vdata

Returns:: 0 on success, -1 on error

int ggz_readn	(	const int	sock,
		void *	data,
		size_t	n
	)

Read a sequence of bytes from the socket.

See also:: ggz_writen

Parameters:

	sock	The socket to read from
	data	A pointer a buffer of size >= n in which to place the data
	n	The number of bytes to read

Returns:: 0 on success, -1 on error

Note:: You must know how much data you want BEFORE calling this function.

Easysock IO

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation


Defines
#define	GGZ_SOCKET_DEBUG "socket"
	ggz_debug debugging type for Easysock debugging.
Typedefs
typedef void(*)	ggzIOError (const char *msg, const GGZIOType type, const int fd, const GGZDataType data)
	An error function type.
typedef void(*)	ggzIOExit (int status)
	An exit function type.
typedef void(*)	ggzNetworkNotify (const char *address, int socket)
	A network resolver function type.
Enumerations
enum	GGZIOType { GGZ_IO_CREATE, GGZ_IO_READ, GGZ_IO_WRITE, GGZ_IO_ALLOCATE }
	An error type for the GGZ socket functions. More...
enum	GGZDataType { GGZ_DATA_NONE, GGZ_DATA_CHAR, GGZ_DATA_INT, GGZ_DATA_STRING, GGZ_DATA_FD }
	A data type for the GGZ socket function error handler. More...
enum	GGZSockType { GGZ_SOCK_SERVER, GGZ_SOCK_CLIENT }
	A socket type. More...
Functions
int	ggz_set_io_error_func (ggzIOError func)
	Set the ggz/easysock error handling function.
ggzIOError	ggz_remove_io_error_func (void)
	Remove the ggz/easysock error handling function.
int	ggz_set_io_exit_func (ggzIOExit func)
	Set the ggz/easysock exit function.
ggzIOExit	ggz_remove_io_exit_func (void)
	Remove the ggz/easysock exit function.
unsigned int	ggz_get_io_alloc_limit (void)
	Get libggz's limit on memory allocation.
unsigned int	ggz_set_io_alloc_limit (const unsigned int limit)
	Set libggz's limit on memory allocation.
int	ggz_init_network (void)
	Initialize the network.
int	ggz_set_network_notify_func (ggzNetworkNotify func)
	Set the ggz/easysock resolver notification function.
const char *	ggz_resolvename (const char *name)
	Resolve a host name.
const char *	ggz_getpeername (int fd, int resolve)
	Get the IP address or host name of a connected peer.
int	ggz_make_socket (const GGZSockType type, const unsigned short port, const char *server)
	Make a socket connection.
int	ggz_make_socket_or_die (const GGZSockType type, const unsigned short port, const char *server)
	Make a socket connection, exiting on error.
int	ggz_make_unix_socket (const GGZSockType type, const char *name)
	Connect to a unix domain socket.
int	ggz_make_unix_socket_or_die (const GGZSockType type, const char *name)
	Connect to a unix domain socket, exiting on error.
int	ggz_write_char (const int sock, const char data)
	Write a character value to the given socket.
void	ggz_write_char_or_die (const int sock, const char data)
	Write a character value to the given socket, exiting on error.
int	ggz_read_char (const int sock, char *data)
	Read a character value from the given socket.
void	ggz_read_char_or_die (const int sock, char *data)
	Read a character value from the given socket, exiting on error.
int	ggz_write_int (const int sock, const int data)
	Write an integer to the socket in network byte order.
void	ggz_write_int_or_die (const int sock, const int data)
	Write an integer to the socket, exiting on error.
int	ggz_read_int (const int sock, int *data)
	Read an integer from the socket in network byte order.
void	ggz_read_int_or_die (const int sock, int *data)
	Read an integer from the socket, exiting on error.
int	ggz_write_string (const int sock, const char *data)
	Write a string to the given socket.
void	ggz_write_string_or_die (const int sock, const char *data)
	Write a string to the given socket, exiting on error.
int	ggz_va_write_string (const int sock, const char *fmt,...) ggz__attribute((format(printf
	Write a printf-style formatted string to the given socket.
int void	ggz_va_write_string_or_die (const int sock, const char *fmt,...) ggz__attribute((format(printf
	Write a formatted string to the socket, exiting on error.
int void int	ggz_read_string (const int sock, char *data, const unsigned int len)
	Read a string from the given socket.
void	ggz_read_string_or_die (const int sock, char *data, const unsigned int len)
	Read a string from the given socket, exiting on error.
int	ggz_read_string_alloc (const int sock, char **data)
	Read and allocate a string from the given socket.
void	ggz_read_string_alloc_or_die (const int sock, char **data)
	Read and allocate string from the given socket, exiting on error.
int	ggz_write_fd (const int sock, int sendfd)
	Write a file descriptor to the given (local) socket.
int	ggz_read_fd (const int sock, int *recvfd)
	Read a file descriptor from the given (local) socket.
int	ggz_writen (const int sock, const void *vdata, size_t n)
	Write a sequence of bytes to the socket.
int	ggz_readn (const int sock, void *data, size_t n)
	Read a sequence of bytes from the socket.