libu8
u8netfns.h File Reference

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_byte * u8_parse_addr (u8_string spec, int *portp, u8_byte *result, ssize_t buflen)
 Parses a variety of host/port syntaxes. More...
 
U8_EXPORT u8_string u8_gethostname (void)
 Returns the configured name of the current host. More...
 
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. More...
 
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. More...
 
U8_EXPORT u8_string u8_host_primary (u8_string hostname)
 Returns the primary hostname for a particular hostname. More...
 
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. More...
 
U8_EXPORT u8_string u8_canonical_addr (u8_string spec)
 Converts a connection spec (e.g. More...
 
U8_EXPORT u8_socket 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. More...
 
U8_EXPORT u8_socket u8_connect (u8_string spec)
 Opens a socket to a specified port and host. More...
 
U8_EXPORT u8_string u8_sessionid (void)
 Returns a unique identifer for the current session. More...
 
U8_EXPORT int u8_get_portno (u8_string portspec)
 Returns an integer port id from a port string. More...
 
U8_EXPORT int u8_set_nodelay (u8_socket conn, int flag)
 Sets whether a connection delays output to fill packets (the Nagle algorithm) More...
 
U8_EXPORT int u8_set_blocking (u8_socket conn, int flag)
 Sets whether I/O on the connection blocks. More...
 
U8_EXPORT u8_string u8_sockaddr_string (struct sockaddr *sockaddr)
 Returns a human readable string representation of a sockaddr structure. More...
 
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. More...
 
U8_EXPORT u8_socket u8_get_connection (u8_connpool cb)
 Returns a connection (an int socket id) from a given connection block. More...
 
U8_EXPORT u8_socket u8_return_connection (u8_connpool cb, u8_socket c)
 Returns a connection to a connection block. More...
 
U8_EXPORT u8_socket u8_discard_connection (u8_connpool cb, u8_socket c)
 Discards a connection received from a connection block. More...
 
U8_EXPORT u8_socket u8_reconnect (u8_connpool cb, u8_socket c)
 Reopens a connection from a connection block, replacing it in the block. More...
 
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. More...
 
U8_EXPORT u8_connpool u8_close_connpool (u8_connpool cb, int dowarn)
 Closes a connection block. More...
 
U8_EXPORT u8_string u8_identify_session (u8_string newid)
 Sets the session identifier This sets the global process session identifier. More...
 

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

References u8_mkstring(), and u8_parse_addr().

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
cba pointer to a connection block structure
dowarnan int controlling the output of warning messages on closing live sockets
Returns
a pointer to a connection block structure.

References u8_log().

U8_EXPORT u8_socket 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_socket (int) which is a socket_id

References u8_connect_x().

Referenced by u8_get_connection(), u8_init_connpool(), and u8_sessionid().

U8_EXPORT u8_socket 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)
addrpa pointer to a pointer to a utf-8 string, in which is deposited identifying information for the host contacted
Returns
a u8_socket (int) which is a socket_id

References u8_graberr(), u8_lookup_host(), u8_parse_addr(), u8_seterr(), and u8_sockaddr_string().

Referenced by u8_connect().

U8_EXPORT u8_socket u8_discard_connection ( u8_connpool  cb,
u8_socket  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
cba pointer to a connection block structure
ca u8_socket (integer socket id)
Returns
a u8_socket (integer socket id)

References u8_open_connpool().

U8_EXPORT u8_socket 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
cba pointer to a connection block structure
Returns
a u8_socket (integer socket id)

References u8_connect(), u8_log(), u8_mkstring(), and u8_seterr().

Referenced by u8_reconnect().

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

References u8_raise().

Referenced by u8_parse_addr(), and u8_shutdown_server().

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.

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 
)

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

References u8_graberr(), u8_seterr(), and u8_tolibc().

Referenced by u8_add_server(), and u8_host_primary().

U8_EXPORT u8_string u8_gethostname ( void  )

Returns the configured name of the current host.

Returns
a utf-8 string describing the current host

References u8_graberr().

Referenced by u8_add_server(), and u8_sessionid().

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

References u8_fromlibc(), u8_gethostbyname(), and u8_lookup_host().

U8_EXPORT u8_string u8_identify_session ( u8_string  newid)

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

Parameters
newida utf-8 string
Returns
its argument, which should not be freed

References u8_log().

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
cba pointer to a connection block structure or NULL
ida utf-8 string identifying the connection, passed to u8_connect
reservean int indicating the maximum number of open connections to keep in reserve
caphow many connections to keep alive at any time
inithow many initial connections to create
Returns
a pointer to a connpool, either as passed in or mallocd.

References u8_connect(), and u8_graberr().

Referenced by u8_open_connpool().

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

References u8_graberr(), u8_parse_addr(), u8_seterr(), and u8_tolibc().

Referenced by u8_connect_x(), and u8_host_primary().

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
ida utf-8 string identifying the connection, passed to u8_connect
reservean int indicating the maximum number of open connections to keep in reserve
capan int indicating the maximum number of open connections for this pool
initan 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.

References u8_init_connpool().

Referenced by u8_discard_connection().

U8_EXPORT u8_byte* u8_parse_addr ( u8_string  spec,
int *  portp,
u8_byte *  result,
ssize_t  buflen 
)

Parses a variety of host/port syntaxes.

Parameters
specthe address specification (a utf-8 string)
portpa pointer to the port number (an int for the family, e.g. )
resulta buffer to hold the host address
buflenthe length of the buffer
Returns
the hostname for TCP/IP addresses or the filename for filesystem domain addresses; puts a port number in portp, storing zero for filesystem domain addresses and -1 for an error (also returns NULL)

References u8_get_portno().

Referenced by u8_canonical_addr(), u8_connect_x(), u8_lookup_host(), and u8_shutdown_server().

U8_EXPORT u8_socket u8_reconnect ( u8_connpool  cb,
u8_socket  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
cba pointer to a connection block structure
ca u8_socket (integer socket id)

References u8_get_connection(), u8_log(), and u8_seterr().

U8_EXPORT u8_socket u8_return_connection ( u8_connpool  cb,
u8_socket  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
cba pointer to a connection block structure
ca u8_socket (integer socket id)
Returns
a u8_socket (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

References u8_appid(), u8_connect(), u8_gethostname(), u8_graberr(), U8_INIT_FIXED_OUTPUT, U8_INIT_STATIC_OUTPUT, u8_local_xtime(), u8_log(), u8_printf(), u8_set_nodelay(), and u8_seterr().

U8_EXPORT int u8_set_blocking ( u8_socket  conn,
int  flag 
)

Sets whether I/O on the connection blocks.

Parameters
conn(a u8_socket, an int socket id)
flag(whether the connection should block on I/O)
Returns
1 if successful
U8_EXPORT int u8_set_nodelay ( u8_socket  conn,
int  flag 
)

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

Parameters
conn(a u8_socket, an int socket id)
flag(whether the connection should delay output)
Returns
1 if successful

References u8_graberr().

Referenced by u8_sessionid().

U8_EXPORT u8_string u8_sockaddr_string ( struct sockaddr *  sockaddr)

Returns a human readable string representation of a sockaddr structure.

Parameters
sockaddra pointer to a sockaddr struct.
Returns
a mallocd UTF-8 string

References u8_mkstring().

Referenced by u8_add_server(), u8_connect_x(), and u8_shutdown_server().