axa  2.2.0
Farsight Security Advanced Exchange Access (AXA)
axa_socket

Detailed Description

axa_socket contains socket and IP address macros and function declarations.

Data Structures

union  axa_socku_t
 AXA socket union. More...
 

Macros

#define AXA_SU_LEN(s)
 Return the length of an axa_socku_t union. More...
 
#define AXA_SU_PORT(su)
 Return the port number of a axa_socku_t union L-value use IPv4 port number if sa_family is AF_UNSPEC. More...
 
#define AXA_POLL_IN   (POLLIN | POLLRDNORM | POLLRDBAND | POLLPRI)
 interesting poll(2) flags for an input socket More...
 
#define AXA_POLL_OUT   (POLLOUT | POLLWRNORM | POLLWRBAND)
 interesting poll(2) flags for an output socket More...
 
#define AXA_POLL_OFF   (POLLERR | POLLHUP | POLLNVAL)
 poll(2) flags for noticing disconnect More...
 
#define AXA_IGNORED_UDP_ERRNO(e)
 Tests for errors on UDP output that are not necessarily fatal. More...
 
#define AXA_CONN_WAIT_ERRORS()
 Tests for non-errors during non-blocking connect(). More...
 
#define AXA_BIND_WAIT_SECS   5
 wait this long for a busy port or UNIX domain socket More...
 
#define AXA_SU_TO_STR_LEN
 maximum string buffer needed the contents of an axa_socku_t INET6_ADDRSTRLEN+1+5+1 comes from "xxxx:...:xxx/65535" More...
 

Functions

char * axa_su_to_str (char *str, size_t str_len, char portc, const axa_socku_t *su)
 Extract IP address and port information from AXA socket union into a string. More...
 
bool axa_data_to_su (axa_socku_t *su, const void *data, size_t data_len)
 Populate an axa_socku_t union with a supplied IPv4 or IPv6 address. More...
 
bool axa_ip_to_su (axa_socku_t *su, const void *ip, uint family)
 Populate an axa_socku_t union with the supplied IPv4 or IPv6 address. More...
 
bool axa_str_to_su (axa_socku_t *su, const char *str)
 Get a socket address from a dotted quad or IPv6 string. More...
 
void axa_bits_to_mask (struct in6_addr *mask, int bits)
 Get an IP prefix mask. More...
 
int axa_str_to_cidr (axa_emsg_t *emsg, axa_socku_t *su, const char *str)
 Get an IP address and netmask. More...
 
bool axa_get_srvr (axa_emsg_t *emsg, const char *addr_port, bool passive, struct addrinfo **resp)
 Parse a "hostname,port" string. More...
 
bool axa_set_sock (axa_emsg_t *emsg, int s, const char *label, int bufsize, bool nonblock)
 Set socket (or other communications file descriptor) options. More...
 

Macro Definition Documentation

◆ AXA_SU_LEN

#define AXA_SU_LEN (   s)
Value:
({sa_family_t _family = (s)->sa.sa_family; \
(_family == AF_INET) ? (int)sizeof((s)->ipv4) \
: (_family == AF_INET6) ? (int)sizeof((s)->ipv6) \
: (_family == AF_UNIX) ? (int)(sizeof((s)->sun) \
-sizeof((s)->sun.sun_path) \
+strlen((s)->sun.sun_path)) \
: -1;})

Return the length of an axa_socku_t union.

Parameters
[in]sa pointer to a populated axa_socku_t structure
Returns
the size of socket union structure as determined by family, or -1 if family is unrecognized

◆ AXA_SU_PORT

#define AXA_SU_PORT (   su)
Value:
(*((su)->sa.sa_family == AF_INET6 \
? &(su)->ipv6.sin6_port \
: &(su)->ipv4.sin_port))

Return the port number of a axa_socku_t union L-value use IPv4 port number if sa_family is AF_UNSPEC.

Parameters
[in]sua pointer to a populated axa_socku_t structure
Returns
a pointer to the 16-bit port number

◆ AXA_POLL_IN

#define AXA_POLL_IN   (POLLIN | POLLRDNORM | POLLRDBAND | POLLPRI)

interesting poll(2) flags for an input socket

◆ AXA_POLL_OUT

#define AXA_POLL_OUT   (POLLOUT | POLLWRNORM | POLLWRBAND)

interesting poll(2) flags for an output socket

◆ AXA_POLL_OFF

#define AXA_POLL_OFF   (POLLERR | POLLHUP | POLLNVAL)

poll(2) flags for noticing disconnect

◆ AXA_IGNORED_UDP_ERRNO

#define AXA_IGNORED_UDP_ERRNO (   e)
Value:
(e == ECONNREFUSED \
|| e == EHOSTUNREACH \
|| e == ENETUNREACH \
|| e == EHOSTDOWN \
|| e == ENETDOWN \
|| e == EACCES \
|| e == ENOBUFS)

Tests for errors on UDP output that are not necessarily fatal.

Some firewall filters or access control lists including IPFW say EACCES on hits, and so treat EACCES like unreachables.

Parameters
[in]eerrno
Return values
trueon an errno that corresponds to an error that should not be fatal
falseon errno that should be fatal

◆ AXA_CONN_WAIT_ERRORS

#define AXA_CONN_WAIT_ERRORS ( )
Value:
(errno == EAGAIN || errno == EINPROGRESS \
|| errno == EALREADY)

Tests for non-errors during non-blocking connect().

Return values
trueon an errno that corresponds to a non-fatal error
falseon errno that should be fatal

◆ AXA_BIND_WAIT_SECS

#define AXA_BIND_WAIT_SECS   5

wait this long for a busy port or UNIX domain socket

◆ AXA_SU_TO_STR_LEN

#define AXA_SU_TO_STR_LEN
Value:
dcl_max(INET6_ADDRSTRLEN+1+5+1, \
sizeof(((axa_socku_t*)0)->sun.sun_path)+1)

maximum string buffer needed the contents of an axa_socku_t INET6_ADDRSTRLEN+1+5+1 comes from "xxxx:...:xxx/65535"

Function Documentation

◆ axa_su_to_str()

char* axa_su_to_str ( char *  str,
size_t  str_len,
char  portc,
const axa_socku_t su 
)

Extract IP address and port information from AXA socket union into a string.

The finished string will be of the format "[IP][separator char][PORT]". If the address family of su is unrecognized, the function will crash with AXA_FAIL().

Parameters
[out]stra char buffer of size str_len that will contain the finished string
[in]str_lenlength of str; AXA_SU_TO_STR_LEN is sufficient
[in]portcchar to separate the IP address and port such as '.' or '/'
[in]supointer to source axa_socku_t
Returns
the value of str

◆ axa_data_to_su()

bool axa_data_to_su ( axa_socku_t su,
const void *  data,
size_t  data_len 
)

Populate an axa_socku_t union with a supplied IPv4 or IPv6 address.

Parameters
[out]supointer to a axa_socku_t union
[in]datapointer to wire-format IPv4 or IPv6 address
[in]data_lensize of data and so 4 for IPv4 or 16 for IPv6
Return values
truesuccess, su contains the IP address
falsefailure, data_len was unrecognized and su is filled with 0s

◆ axa_ip_to_su()

bool axa_ip_to_su ( axa_socku_t su,
const void *  ip,
uint  family 
)

Populate an axa_socku_t union with the supplied IPv4 or IPv6 address.

Parameters
[out]supointer to a axa_socku_t union
[in]ippointer to wire-format IPv4 or IPv6 address
[in]familyaddress family, should be AF_INET or AF_INET6
Return values
truesuccess, su contains the IP address
falsefailure, family was unrecognized and su is filled with 0s

◆ axa_str_to_su()

bool axa_str_to_su ( axa_socku_t su,
const char *  str 
)

Get a socket address from a dotted quad or IPv6 string.

The function will fail if the IPv4 or IPv6 strings are invalid.

Parameters
[out]supointer to a axa_socku_t union
[in]strdotted quad or IPv6 string
Return values
truesuccess, su contains the IP address
falsefailure, the address string was invalid and su filled with 0s

◆ axa_bits_to_mask()

void axa_bits_to_mask ( struct in6_addr *  mask,
int  bits 
)

Get an IP prefix mask.

Parameters
[out]maskIPv6 address
[in]bitsnumber of bits

◆ axa_str_to_cidr()

int axa_str_to_cidr ( axa_emsg_t emsg,
axa_socku_t su,
const char *  str 
)

Get an IP address and netmask.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]supointer to a populated axa_socku_t union
[in]strstring containing IP address with CIDR mask
Returns
the number of bits in the CIDR mask or -1 on error

◆ axa_get_srvr()

bool axa_get_srvr ( axa_emsg_t emsg,
const char *  addr_port,
bool  passive,
struct addrinfo **  resp 
)

Parse a "hostname,port" string.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]addr_portstring of the format "hostname,port"
[in]passiveif true, an empty ("") or asterisk (*) hostname results in IP addresses of INADDR_ANY and IN6ADDR_ANY
[out]resppointer to address of struct addrinfo, results appear here
Return values
truesuccess, *resp will have the results
falseparsing error, check emsg

◆ axa_set_sock()

bool axa_set_sock ( axa_emsg_t emsg,
int  s,
const char *  label,
int  bufsize,
bool  nonblock 
)

Set socket (or other communications file descriptor) options.

AXA has the option of using several communications primitives. Depending on network details and the user's whim, AXA may use:

  • Unix domain (unix:/foo/bar)
  • TCP (tcp:10.0.0.1,123)
  • SSH (ssh:10.0.0.1,123)
  • UDP (udp:10.0.0.1,123)
  • NMSG over TCP (nmsg:tcp:10.0.0.1,123)
  • NMSG over UDP (nmsg:udp:10.0.0.1,123)

There are several uses of this function. They won't know which of the above connection primitives was specified. Thos primitives need some or all of the following:

  • close-on-exec (FD_CLOEXEC)
  • non-blocking (O_NONBLOCK, set if nonblock is true)
  • Nagle Algorithm disabled (TCP only)
  • TCP keepalives enabled (TCP only)
  • UDP and TCP socket buffer sizes
  • Broadcasting enabled (UDP to broadcast IP address only)

axa_set_sock() tries to do the right thing. However, some facilities are not available on some systems (e.g. OS X does not support SO_PROTOCOL) and so there may be spurious warnings when AXA about unsupported socket options.

Parameters
[out]emsgif something goes wrong, this will contain the reason
[in]ssocket or fd
[in]labeldescriptive label for s such as an address
[in]bufsizenon-zero to set the SO_RCVBUF and SO_SNDBUF sizes
[in]nonblockboolean, if true, set O_NONBLOCK
Return values
truesuccess
falsesomething went wrong, check emsg