These functions provide for network access, especially network database functions and connection creation. More...

Data Structures
struct	U8_CONNPOOL
struct	U8_MAILHEADER
Functions
U8_EXPORT u8_string	u8_gethostname (void)
	Returns the configured name of the current host.
U8_EXPORT struct hostent *	u8_gethostbyname (u8_string hostname, int family)
	Returns a mallocd pointer to a host entry for a named host for a particular address family.
U8_EXPORT struct hostent *	u8_gethostbyaddr (char *addr, int len, int family)
	Returns a mallocd pointer to a host entry for the host with a particular address.
U8_EXPORT u8_string	u8_host_primary (u8_string hostname)
	Returns the primary hostname for a particular hostname.
U8_EXPORT char **	u8_lookup_host (u8_string hostname, int n_addrsp, unsigned int addr_familyp)
	Returns a vector of addresses assigned to a particular hostname The number of address is deposited in n_addrsp and the address family of the returned addresses is deposited in addr_familyp.
U8_EXPORT u8_string	u8_canonical_addr (u8_string spec)
	Converts a connection spec (e.g.
U8_EXPORT u8_connection	u8_connect_x (u8_string spec, u8_string *addrp)
	Opens a socket to a specified port and host, storing the host's address in addrp.
U8_EXPORT u8_connection	u8_connect (u8_string spec)
	Opens a socket to a specified port and host.
U8_EXPORT u8_string	u8_sessionid (void)
	Returns a unique identifer for the current session.
U8_EXPORT int	u8_get_portno (u8_string portspec)
	Returns an integer port id from a port string.
U8_EXPORT int	u8_set_nodelay (u8_connection conn, int flag)
	Sets whether a connection delays output to fill packets (the Nagle algorithm)
U8_EXPORT int	u8_set_blocking (u8_connection conn, int flag)
	Sets whether I/O on the connection blocks.
U8_EXPORT u8_string	u8_sockaddr_string (struct sockaddr *sockaddr)
	Returns a human readable string representation of a sockaddr structure.
U8_EXPORT u8_connpool	u8_init_connpool (u8_connpool cb, u8_string id, int reserve, int cap, int init)
	Returns a connection block structure initialized with a particular connection id and a reserve count.
U8_EXPORT u8_connection	u8_get_connection (u8_connpool cb)
	Returns a connection (an int socket id) from a given connection block.
U8_EXPORT u8_connection	u8_return_connection (u8_connpool cb, u8_connection c)
	Returns a connection to a connection block.
U8_EXPORT u8_connection	u8_discard_connection (u8_connpool cb, u8_connection c)
	Discards a connection received from a connection block.
U8_EXPORT u8_connection	u8_reconnect (u8_connpool cb, u8_connection c)
	Reopens a connection from a connection block, replacing it in the block.
U8_EXPORT u8_connpool	u8_open_connpool (u8_string id, int reserve, int cap, int init)
	Returns a connection block structure initialized with a particular connection id and a reserve count.
U8_EXPORT u8_connpool	u8_close_connpool (u8_connpool cb, int dowarn)
	Closes a connection block.
U8_EXPORT u8_string	u8_identify_session (u8_string newid)
	Sets the session identifier This sets the global process session identifier.

Detailed Description

These functions provide for network access, especially network database functions and connection creation.

Function Documentation

U8_EXPORT u8_string u8_canonical_addr ( u8_string spec )

Converts a connection spec (e.g.

port@host) into canonical form, converting the port into a number and the host into a primary hostname.

Parameters:

spec	(a utf-8 string of the form port@host

Returns:: a utf-8 canonical string

U8_EXPORT u8_connpool u8_close_connpool	(	u8_connpool	cb,
		int	dowarn
	)

Closes a connection block.

This closes the open sockets and frees the associated memory for a connection block.

Parameters:

cb	a pointer to a connection block structure
dowarn	an int controlling the output of warning messages on closing live sockets

Returns:: a pointer to a connection block structure.

U8_EXPORT u8_connection u8_connect ( u8_string spec )

Opens a socket to a specified port and host.

Parameters:

spec	(a utf-8 string of the form port@host)

Returns:: a u8_connection (int) which is a socket_id

U8_EXPORT u8_connection u8_connect_x	(	u8_string	spec,
		u8_string *	addrp
	)

Opens a socket to a specified port and host, storing the host's address in addrp.

Parameters:

spec	(a utf-8 string of the form port@host)
addrp	a pointer to a pointer to a utf-8 string, in which is deposited identifying information for the host contacted

Returns:: a u8_connection (int) which is a socket_id

U8_EXPORT u8_connection u8_discard_connection	(	u8_connpool	cb,
		u8_connection	c
	)

Discards a connection received from a connection block.

This removes the connection argument from the queue of connections for a connection block. This removes it from inuse queue but does not add it back to the free queue. It is intended to be used for connections which have been closed or are in error states. If there are requests pending on the connection block, this will attempt to open a new connection and add it to the block. Zero is returned if the connection was closed and no new connection made, -1 is returned on error, and otherwise the new connection is returned.

Parameters:

cb	a pointer to a connection block structure
c	a u8_connection (integer socket id)

Returns:: a u8_connection (integer socket id)

U8_EXPORT u8_connection u8_get_connection ( u8_connpool cb )

Returns a connection (an int socket id) from a given connection block.

This opens a new connection if needed but will use existing connections which have been passed in with u8_return_connection.

Parameters:

cb	a pointer to a connection block structure

Returns:: a u8_connection (integer socket id)

U8_EXPORT int u8_get_portno ( u8_string portspec )

Returns an integer port id from a port string.

This looks port ids up and (if that fails) converts the string into an integer based on "touch-tone" encoding

Parameters:

portspec (a utf-8 string)

Returns:: an integer port number

U8_EXPORT struct hostent* u8_gethostbyaddr	(	char *	addr,
		int	len,
		int	family
	)		`[read]`

Returns a mallocd pointer to a host entry for the host with a particular address.

Parameters:

addr	(a pointer to a byte array describing an address)
len	(the number of bytes in the address)
family	(an int for the address family, e.g. AF_INET, AF_INET6)

Returns:: a pointer to a hostent structure

U8_EXPORT struct hostent* u8_gethostbyname	(	u8_string	hostname,
		int	family
	)		`[read]`

Returns a mallocd pointer to a host entry for a named host for a particular address family.

Parameters:

hostname	(a utf-8 string)
family	(an int for the family, e.g. )

Returns:: a pointer to a hostent structure

U8_EXPORT u8_string u8_gethostname ( void )

Returns the configured name of the current host.

Returns:: a utf-8 string describing the current host

U8_EXPORT u8_string u8_host_primary ( u8_string hostname )

Returns the primary hostname for a particular hostname.

This looks up the hostname and then returns the first name in the entry.

Parameters:

hostname (a network hostname)

Returns:: a mallocd UTF-8 string describing the primary host name

U8_EXPORT u8_string u8_identify_session ( u8_string newid )

Sets the session identifier This sets the global process session identifier.

Parameters:

newid a utf-8 string

Returns:: its argument, which should not be freed

U8_EXPORT u8_connpool u8_init_connpool	(	u8_connpool	cb,
		u8_string	id,
		int	reserve,
		int	cap,
		int	init
	)

Returns a connection block structure initialized with a particular connection id and a reserve count.

This mallocs the connection block structure if neccessary.

Parameters:

cb	a pointer to a connection block structure or NULL
id	a utf-8 string identifying the connection, passed to u8_connect
reserve	an int indicating the maximum number of open connections to keep in reserve
init	how many initial connections to create

Returns:: a pointer to a connpool, either as passed in or mallocd.

U8_EXPORT char** u8_lookup_host	(	u8_string	hostname,
		int *	n_addrsp,
		unsigned int *	addr_familyp
	)

Returns a vector of addresses assigned to a particular hostname The number of address is deposited in n_addrsp and the address family of the returned addresses is deposited in addr_familyp.

Parameters:

hostname	(a network hostname)
n_addrsp	(a pointer to an int)
addr_familyp	(a pointer to an int (address family))

Returns:: a vector of pointers to byte arrays describing addresses

U8_EXPORT u8_connpool u8_open_connpool	(	u8_string	id,
		int	reserve,
		int	cap,
		int	init
	)

Returns a connection block structure initialized with a particular connection id and a reserve count.

This registers the resulting structure so that subsequent calls with identical ids yield the same structure, which is created if neccessary.

Parameters:

id	a utf-8 string identifying the connection, passed to u8_connect
reserve	an int indicating the maximum number of open connections to keep in reserve
cap	an int indicating the maximum number of open connections for this pool
init	an int indicating the number of initial connections to open

Returns:: a pointer to a connpool If the cap and reserve values are negative, the current or default values are used; otherwise, the cap and reserve for the pool may be increased but will not be decreased (so the actual cap and reserve is the max of the values specified in different calls to u8_open_connpool.

U8_EXPORT u8_connection u8_reconnect	(	u8_connpool	cb,
		u8_connection	c
	)

Reopens a connection from a connection block, replacing it in the block.

The new connection (socket) is returned or -1 if there is an error.

Parameters:

cb	a pointer to a connection block structure
c	a u8_connection (integer socket id)

U8_EXPORT u8_connection u8_return_connection	(	u8_connpool	cb,
		u8_connection	c
	)

Returns a connection to a connection block.

This adds the connection argument back to the queue of connections so it can be reused by u8_get_connection. If the number of unused connections is over the connection block's reserve, the connection is just close()d. Consequently, if the reserve is zero, this always closes the connection. Zero is returned if the connection was closed (and discarded), -1 on an error, and otherwise the connection itself is returned.

Parameters:

cb	a pointer to a connection block structure
c	a u8_connection (integer socket id)

Returns:: a u8_connection (integer socket id)

U8_EXPORT u8_string u8_sessionid ( void )

Returns a unique identifer for the current session.

This is based on a pid, a hostname, and the time at which the id was generated.

Returns:: a string

U8_EXPORT int u8_set_blocking	(	u8_connection	conn,
		int	flag
	)

Sets whether I/O on the connection blocks.

Parameters:

conn	(a u8_connection, an int socket id)
flag	(whether the connection should block on I/O)

Returns:: 1 if successful

U8_EXPORT int u8_set_nodelay	(	u8_connection	conn,
		int	flag
	)

Sets whether a connection delays output to fill packets (the Nagle algorithm)

Parameters:

conn	(a u8_connection, an int socket id)
flag	(whether the connection should delay output)

Returns:: 1 if successful

U8_EXPORT u8_string u8_sockaddr_string ( struct sockaddr * sockaddr )

Returns a human readable string representation of a sockaddr structure.

Parameters:

sockaddr a pointer to a sockaddr struct.

Returns:: a mallocd UTF-8 string

Data Structures

Functions

Detailed Description

Function Documentation