libu8
Data Structures | Functions
include/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_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:
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.
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)
addrpa 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:
cba pointer to a connection block structure
ca 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:
cba 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:
newida 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:
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
inithow 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:
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.
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:
cba pointer to a connection block structure
ca 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:
cba pointer to a connection block structure
ca 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:
sockaddra pointer to a sockaddr struct.
Returns:
a mallocd UTF-8 string