axa 3.0.2
Farsight Security Advanced Exchange Access (AXA)
|
axa_axa
contains top-level macros, datatype definitions and function declarations.
Data Structures | |
struct | axa_emsg_t |
AXA error message datatype. More... | |
Macros | |
#define | AXA_DIM(_a) ((int)((sizeof(_a) / sizeof((_a)[0])))) |
Return the number of elements in an array. | |
#define | AXA_LAST(_a) (&(_a)[AXA_DIM(_a)-1]) |
Return a pointer to the last item of an array. | |
#define | AXA_OFFSET(_p, _s, _t) |
Produce a pointer to a byte in a buffer that corresponds to a structure tag. | |
#define | AXA_IS_WHITE(c) |
Test a char to see if it's whitespace. | |
#define | AXA_IS_UPPER(c) ({char _c = (c); _c >= 'A' && _c <= 'Z';}) |
test if char is uppercase | |
#define | AXA_IS_LOWER(c) ({char _c = (c); _c >= 'a' && _c <= 'z';}) |
test if char is lowercase | |
#define | AXA_IS_DIGIT(c) ({char _c = (c); _c >= '0' && _c <= '9';}) |
test if char is base 10 digit | |
#define | AXA_TO_LOWER(c) ({char _l = (c); AXA_IS_UPPER(_l) ? (_l+'a'-'A') : _l;}) |
convert char to lowercase | |
#define | AXA_TO_UPPER(c) ({char _u = (c); AXA_IS_LOWER(_u) ? (_u-'a'-'A') : _u;}) |
convert char to uppercase | |
#define | AXA_UNUSED __attribute__((unused)) |
Tell the compiler not to complain about an unused parameter. | |
#define | AXA_PF(f, l) __attribute__((format(printf,f,l))) |
Tell the compiler to check an actual format string against the other actual parameters. | |
#define | AXA_NORETURN __attribute__((__noreturn__)) |
Tell the compiler that this function will never return. | |
#define | dcl_max(a, b) ((a) >= (b) ? (a) : (b)) |
Return the larger of two scalar values. | |
#define | AXA_CLITCMP(_b, _s) (strncasecmp((_b), (_s), sizeof(_s)-1) == 0) |
Case compare two NULL terminated strings, comparing at most sizeof(_s - 1) characters. | |
#define | AXA_SALLOC(t) ((t *)axa_zalloc(sizeof(t))) |
A calloc() wrapper that returns zero-filled memory of size sizeof (t) that is cast to (t *). | |
#define | AXA_DEBUG_WATCH 2 |
generate trace syslog messages about watches, anomalies, and channels | |
#define | AXA_DEBUG_TRACE 3 |
also generate trace syslog messages about client AXA messages and non-routine AXA messages | |
#define | AXA_DEBUG_NMSG 5 |
also generate trace syslog messages from libnmsg and client-to-server rate limiting or congestion | |
#define | AXA_DEBUG_TO_NMSG(lvl) |
convert AXA debug level to NMSG debug level | |
#define | AXA_DEBUG_MAX 10 |
maximum debugging level | |
#define | AXA_ASSERT_MSG(c, p, ...) |
Crash with a message if a condition is false. | |
#define | AXA_ASSERT(c) AXA_ASSERT_MSG((c), "\""#c"\" is false") |
Crash if a condition is false. | |
#define | AXA_FAIL(...) axa_fatal_msg(0, __VA_ARGS__) |
Crash with a message. | |
#define | AXA_DAY_SECS (24*60*60) |
one day of seconds | |
#define | AXA_DAY_MS (AXA_DAY_SECS*1000) |
one day of milliseconds | |
Enumerations | |
enum | axa_syslog_type_t |
AXA syslog types. More... | |
Functions | |
const char * | axa_domain_to_str (const uint8_t *src, size_t src_len, char *dst, size_t dst_len) |
Convert a domain name to a canonical string. | |
void * | axa_malloc (size_t s) |
A malloc() wrapper that crashes immediately (via AXA_ASSERT()) on malloc failures. | |
void * | axa_zalloc (size_t s) |
A calloc() wrapper that crashes immediately (via AXA_ASSERT()) on malloc failures. | |
char * | axa_strdup (const char *s) |
A strdup() wrapper that crashes immediately (via AXA_ASSERT()) on failure. | |
char * | axa_strndup (const char *s, size_t len) |
A strndup() wrapper that crashes immediately (via AXA_ASSERT()) on failure. | |
void | axa_vasprintf (char **bufp, const char *p, va_list args) |
A vasprintf() wrapper that crashes immediately (via AXA_ASSERT()) on vasprintf failures. | |
void | axa_asprintf (char **bufp, const char *p,...) AXA_PF(2 |
An asprintf() wrapper that crashes immediately (via AXA_ASSERT()) on asprintf failures. | |
void void | axa_set_core (void) |
Try to enable core files. | |
void | axa_set_me (const char *me) |
Set the global program name before axa_syslog_init() is called. | |
bool | axa_parse_log_opt (axa_emsg_t *emsg, const char *arg) |
Parse and set logging options before calling axa_syslog_init() | |
void | axa_syslog_init (void) |
Initialize the AXA syslog interface. | |
void | axa_buf_print (char **bufp, size_t *buf_lenp, const char *p,...) AXA_PF(3 |
Add text to an error or other message buffer. | |
void void | axa_clean_stdio (void) |
prevent surprises via use of stdio FDs by ensuring that the FDs are open to at least /dev/null | |
void | axa_vpemsg (axa_emsg_t *emsg, const char *msg, va_list args) |
Generate an error message string in a buffer, if we have a buffer. | |
void | axa_pemsg (axa_emsg_t *emsg, const char *msg,...) AXA_PF(2 |
axa_vpemsg() wrapper using the variadic stdarg macros (va_start(), va_end()). | |
void | axa_vlog_msg (axa_syslog_type_t type, bool fatal, const char *p, va_list args) |
Log an AXA message. | |
void | axa_verror_msg (const char *p, va_list args) |
Log or print an error message. | |
void | axa_error_msg (const char *p,...) AXA_PF(1 |
Log or print an error message. | |
void void | axa_io_error (const char *op, const char *src, ssize_t len) |
Log an error message for an I/O function that has returned either a negative read or write length or the wrong length. | |
void | axa_vtrace_msg (const char *p, va_list args) |
Log a trace message in the tracing syslog stream as opposed to the error syslog stream. | |
void | axa_trace_msg (const char *p,...) AXA_PF(1 |
Log a trace message in the tracing stream or AXA_SYSLOG_TRACE as opposed to the error or AXA_SYSLOG_ERROR stream. | |
void void | axa_vfatal_msg (int ex_code, const char *p, va_list args) AXA_NORETURN |
Log a serious error message and either exit with a specified exit code or crash if the exit code is EX_SOFTWARE. | |
void | axa_fatal_msg (int ex_code, const char *p,...) AXA_PF(2 |
Log a serious error message and either exit with a specified exit code or crash if the exit code is EX_SOFTWARE. | |
char * | axa_fgetln (FILE *f, const char *file_name, uint *line_num, char **bufp, size_t *buf_sizep) |
Get a logical line from a stdio stream, with leading and trailing whitespace trimmed and "\\\n" deleted as a continuation. | |
const char * | axa_strip_white (const char *str, size_t *lenp) |
Strip leading and trailing white space. | |
ssize_t | axa_get_token (char *token, size_t token_len, const char **stringp, const char *seps) |
Copy the next token from a string to a buffer and return the size of the string put into the buffer. | |
uint32_t | axa_hash_divisor (uint32_t initial, bool smaller) |
Get a modulus for a hash function that is tolerably likely to be relatively prime to most inputs. | |
bool | axa_parse_ch (axa_emsg_t *emsg, uint16_t *chp, const char *str, size_t str_len, bool all_ok, bool number_ok) |
Parse a channel string into a binary channel in host byte order. | |
time_t | axa_tv_diff2ms (const struct timeval *tv1, const struct timeval *tv2) |
Compute (tv1 - tv2) in milliseconds, but limited or clamped to 1 day. | |
time_t | axa_elapsed_ms (const struct timeval *now, struct timeval *then) |
Compute the positive elapsed time between two timevals in milliseconds, but limited or clamped to at least 0 ms and at most 1 day. | |
const char * | axa_get_version (void) |
Retrieve the semantic library version as a string. | |
uint32_t | axa_get_version_number (void) |
Retrieve the semantic library version as a packed integer. | |
Variables | |
void | AXA_NORETURN |
#define AXA_DIM | ( | _a | ) | ((int)((sizeof(_a) / sizeof((_a)[0])))) |
Return the number of elements in an array.
[in] | _a | the array to size up |
#define AXA_LAST | ( | _a | ) | (&(_a)[AXA_DIM(_a)-1]) |
Return a pointer to the last item of an array.
[in] | _a | the array containing the item |
#define AXA_OFFSET | ( | _p, | |
_s, | |||
_t | |||
) |
Produce a pointer to a byte in a buffer that corresponds to a structure tag.
This works where a cast to the structure would not work or would give the wrong answer because of word mis-alignment of the buffer or other reasons.
[in] | _p | pointer to source data |
[in] | _s | name of desired structure |
[in] | _t | desired tag in the structure |
pointer | to byte in source data corresponding to the tag. The pointer might not be properly aligned. |
#define AXA_IS_WHITE | ( | c | ) |
Test a char to see if it's whitespace.
AXA ignores locales to get consistent results on all systems, and because the AXA control files are ASCII.
[in] | c | char to test |
1 | if whitespace |
0 | if not |
#define AXA_IS_UPPER | ( | c | ) | ({char _c = (c); _c >= 'A' && _c <= 'Z';}) |
test if char is uppercase
[in] | c | char to test |
1 | if uppercase char |
0 | if not |
#define AXA_IS_LOWER | ( | c | ) | ({char _c = (c); _c >= 'a' && _c <= 'z';}) |
test if char is lowercase
[in] | c | char to test |
1 | if lowercase |
0 | if not |
#define AXA_IS_DIGIT | ( | c | ) | ({char _c = (c); _c >= '0' && _c <= '9';}) |
test if char is base 10 digit
[in] | c | char to test |
1 | if base 10 digit |
0 | if not |
#define AXA_TO_LOWER | ( | c | ) | ({char _l = (c); AXA_IS_UPPER(_l) ? (_l+'a'-'A') : _l;}) |
convert char to lowercase
[in] | c | char to convert |
#define AXA_TO_UPPER | ( | c | ) | ({char _u = (c); AXA_IS_LOWER(_u) ? (_u-'a'-'A') : _u;}) |
convert char to uppercase
[in] | c | char to convert |
#define AXA_UNUSED __attribute__((unused)) |
Tell the compiler not to complain about an unused parameter.
#define AXA_PF | ( | f, | |
l | |||
) | __attribute__((format(printf,f,l))) |
Tell the compiler to check an actual format string against the other actual parameters.
[in] | f | the number of the "format string" parameter |
[in] | l | the number of the first variadic parameter |
#define AXA_NORETURN __attribute__((__noreturn__)) |
Tell the compiler that this function will never return.
#define dcl_max | ( | a, | |
b | |||
) | ((a) >= (b) ? (a) : (b)) |
Return the larger of two scalar values.
This macro is for declarations where ({}) is not allowed and side effects can't happen.
[in] | a | first value to compare |
[in] | b | second value to compare |
#define AXA_CLITCMP | ( | _b, | |
_s | |||
) | (strncasecmp((_b), (_s), sizeof(_s)-1) == 0) |
Case compare two NULL terminated strings, comparing at most sizeof(_s - 1) characters.
[in] | _b | const char * first, not necessarily null terminated string to compare |
[in] | _s | const char * null terminated second string to compare |
#define AXA_SALLOC | ( | t | ) | ((t *)axa_zalloc(sizeof(t))) |
A calloc() wrapper that returns zero-filled memory of size sizeof (t) that is cast to (t *).
[in] | t | object to allocate memory for |
#define AXA_DEBUG_WATCH 2 |
generate trace syslog messages about watches, anomalies, and channels
#define AXA_DEBUG_TRACE 3 |
also generate trace syslog messages about client AXA messages and non-routine AXA messages
#define AXA_DEBUG_NMSG 5 |
also generate trace syslog messages from libnmsg and client-to-server rate limiting or congestion
#define AXA_DEBUG_TO_NMSG | ( | lvl | ) |
convert AXA debug level to NMSG debug level
#define AXA_DEBUG_MAX 10 |
maximum debugging level
#define AXA_ASSERT_MSG | ( | c, | |
p, | |||
... | |||
) |
Crash with a message if a condition is false.
AXA_ASSERT_MSG() can have required side effects such as stopping on a fatal condition, and so cannot be #ifdef'ed out.
[in] | c | condition to assert |
[in] | p | pattern or message |
[in] | ... | optional variadic arguments for pattern parameters) |
#define AXA_ASSERT | ( | c | ) | AXA_ASSERT_MSG((c), "\""#c"\" is false") |
Crash if a condition is false.
AXA_ASSERT() can have required side effects, usually stopping on a fatal condition.
[in] | c | condition to assert |
#define AXA_FAIL | ( | ... | ) | axa_fatal_msg(0, __VA_ARGS__) |
Crash with a message.
[in] | ... | variadic arguments |
#define AXA_DAY_SECS (24*60*60) |
one day of seconds
#define AXA_DAY_MS (AXA_DAY_SECS*1000) |
one day of milliseconds
enum axa_syslog_type_t |
const char * axa_domain_to_str | ( | const uint8_t * | src, |
size_t | src_len, | ||
char * | dst, | ||
size_t | dst_len | ||
) |
Convert a domain name to a canonical string.
Sane wrapper for wdns_domain_to_str(). dst_len must be >=NS_MAXDNAME because wdns_domain_to_str() does not check.
[in] | src | domain name in wire format |
[in] | src_len | length of domain name in bytes |
[out] | dst | caller allocated string buffer that should be of size NS_MAXDNAME |
[in] | dst_len | size of the dst buffer |
void * axa_malloc | ( | size_t | s | ) |
A malloc() wrapper that crashes immediately (via AXA_ASSERT()) on malloc failures.
[in] | s | size of memory to allocate |
void * axa_zalloc | ( | size_t | s | ) |
A calloc() wrapper that crashes immediately (via AXA_ASSERT()) on malloc failures.
The memory region will be zero-filled.
[in] | s | size of memory to allocate |
char * axa_strdup | ( | const char * | s | ) |
A strdup() wrapper that crashes immediately (via AXA_ASSERT()) on failure.
The caller must free() the result.
[in] | s | the string to duplicate |
char * axa_strndup | ( | const char * | s, |
size_t | len | ||
) |
A strndup() wrapper that crashes immediately (via AXA_ASSERT()) on failure.
The caller must free() the result.
[in] | s | the string to duplicate |
[in] | len | length of string |
void axa_vasprintf | ( | char ** | bufp, |
const char * | p, | ||
va_list | args | ||
) |
A vasprintf() wrapper that crashes immediately (via AXA_ASSERT()) on vasprintf failures.
When you're done with it, bufp should be freed.
[out] | bufp | a pointer to the newly minted and formatted string |
[in] | p | the format string |
[in] | args | a var args list |
void axa_asprintf | ( | char ** | bufp, |
const char * | p, | ||
... | |||
) |
An asprintf() wrapper that crashes immediately (via AXA_ASSERT()) on asprintf failures.
When you're done with it, bufp should be freed.
[out] | bufp | a pointer to the newly minted and formatted string |
[in] | p | the format string |
[in] | ... | a var args list |
void void axa_set_core | ( | void | ) |
Try to enable core files.
Wraps getrlimit() and setrlimit().
void axa_set_me | ( | const char * | me | ) |
Set the global program name before axa_syslog_init() is called.
[in] | me | argv[0] |
bool axa_parse_log_opt | ( | axa_emsg_t * | emsg, |
const char * | arg | ||
) |
Parse and set logging options before calling axa_syslog_init()
[out] | emsg | error message if something is wrong |
[in] | arg | comma separated string with the following options: {trace|error|acct},{off|FACILITY.LEVEL}[,{none,stderr,stdout}] {trace|error|acct} selects one of three streams of information "off" or "FACILITY.LEVEL" disable or turn on syslog for the chosen "trace", "error" and "acct" streams. {none,stderr,stdout} directs the stream independently of how it is sent to the system log. A stream can be sent to either, both, or neither the system log and stderr or stdout. |
The following settings for "trace", "error" and "acct" are assumed to send the "trace" and "error" streams to the system log and stderr and the "acct" stream to only the system log: trace,LOG_DEBUG.LOG_DAEMON error.LOG_ERR,LOG_DAEMON acct,LOG_NOTICE.LOG_AUTH,none
true | if string is valid |
false | if not |
void axa_syslog_init | ( | void | ) |
Initialize the AXA syslog interface.
Call this function after calling axa_parse_log_opt() and axa_set_me(), and before calling any AXA logging, accounting, or tracing function.
void axa_buf_print | ( | char ** | bufp, |
size_t * | buf_lenp, | ||
const char * | p, | ||
... | |||
) |
Add text to an error or other message buffer.
If we run out of room, add "...".
[in,out] | bufp | in: the original string, out: the concatenated strings |
[in,out] | buf_lenp | in: the length of bufp string, out: new length |
[in] | p | the format string to copy over |
[in] | ... | va_args business |
void void axa_clean_stdio | ( | void | ) |
prevent surprises via use of stdio FDs by ensuring that the FDs are open to at least /dev/null
void axa_vpemsg | ( | axa_emsg_t * | emsg, |
const char * | msg, | ||
va_list | args | ||
) |
Generate an error message string in a buffer, if we have a buffer.
Log or print the message with axa_vlog_msg() if there is no buffer.
[out] | emsg | if something goes wrong, this will contain the reason |
[in] | msg | message |
[in] | args | arguments to p |
void axa_pemsg | ( | axa_emsg_t * | emsg, |
const char * | msg, | ||
... | |||
) |
axa_vpemsg() wrapper using the variadic stdarg macros (va_start(), va_end()).
[out] | emsg | if something goes wrong, this will contain the reason |
[in] | msg | message |
[in] | ... | variable length argument list |
void axa_vlog_msg | ( | axa_syslog_type_t | type, |
bool | fatal, | ||
const char * | p, | ||
va_list | args | ||
) |
Log an AXA message.
Depending on type and calls to axa_parse_log_opt(), this function could write to stdout stderr, and/or syslog.
[in] | type | one of axa_syslog_type_t |
[in] | fatal | if true and fatal verbiage will be prepended to message |
[in] | p | message |
[in] | args | variadic argument list |
void axa_verror_msg | ( | const char * | p, |
va_list | args | ||
) |
Log or print an error message.
This is a wrapper for axa_vlog_msg() with type of AXA_SYSLOG_ERROR with fatal == false.
[in] | p | message |
[in] | args | variadic argument list |
void axa_error_msg | ( | const char * | p, |
... | |||
) |
Log or print an error message.
This is a variadic wrapper for axa_vlog_msg() with type of AXA_SYSLOG_ERROR with fatal == false.
[in] | p | message |
[in] | ... | variable length argument list |
void void axa_io_error | ( | const char * | op, |
const char * | src, | ||
ssize_t | len | ||
) |
Log an error message for an I/O function that has returned either a negative read or write length or the wrong length.
Complain about a non-negative length or decode errno for a negative length.
[in] | op | canonical string referring to the I/O event that caused the error |
[in] | src | error message |
[in] | len | length of src |
void axa_vtrace_msg | ( | const char * | p, |
va_list | args | ||
) |
Log a trace message in the tracing syslog stream as opposed to the error syslog stream.
[in] | p | message |
[in] | args | variadic argument list |
void axa_trace_msg | ( | const char * | p, |
... | |||
) |
Log a trace message in the tracing stream or AXA_SYSLOG_TRACE as opposed to the error or AXA_SYSLOG_ERROR stream.
[in] | p | message |
[in] | ... | variable length argument list |
void void axa_vfatal_msg | ( | int | ex_code, |
const char * | p, | ||
va_list | args | ||
) |
Log a serious error message and either exit with a specified exit code or crash if the exit code is EX_SOFTWARE.
[in] | ex_code | exit code |
[in] | p | message |
[in] | args | variadic argument list |
void axa_fatal_msg | ( | int | ex_code, |
const char * | p, | ||
... | |||
) |
Log a serious error message and either exit with a specified exit code or crash if the exit code is EX_SOFTWARE.
[in] | ex_code | exit code |
[in] | p | our last words |
[in] | ... | va_args business |
char * axa_fgetln | ( | FILE * | f, |
const char * | file_name, | ||
uint * | line_num, | ||
char ** | bufp, | ||
size_t * | buf_sizep | ||
) |
Get a logical line from a stdio stream, with leading and trailing whitespace trimmed and "\\\n" deleted as a continuation.
If the buffer is NULL or it is not big enough, it is freed and a new buffer is allocated. This must be freed by the caller after the last use of this function.
Except at error or EOF, the start of the next line is returned, which might not be at the start of the buffer.
[in] | f | the file to read from (for error reporting) |
[in] | file_name | name of the file (for error reporting) |
[in,out] | line_num | line number of file, will be progressively updated |
[in,out] | bufp | buffer to store line, can be NULL |
[in,out] | buf_sizep | size of buffer pointed to by bufp |
const char * axa_strip_white | ( | const char * | str, |
size_t * | lenp | ||
) |
Strip leading and trailing white space.
[in,out] | str | in: string to cleanse, out: cleansed string |
[in,out] | lenp | in: length of the string, out: new length |
ssize_t axa_get_token | ( | char * | token, |
size_t | token_len, | ||
const char ** | stringp, | ||
const char * | seps | ||
) |
Copy the next token from a string to a buffer and return the size of the string put into the buffer.
Honor quotes and backslash. The caller must skip leading token separators (e.g. blanks) if necessary. When the separators include whitespace and whitespace ends the token, then all trailing whitespace is skipped.
[in,out] | token | token goes here |
[in,out] | token_len | length of the token |
[in,out] | stringp | input string |
[in,out] | seps | string of token separators |
uint32_t axa_hash_divisor | ( | uint32_t | initial, |
bool | smaller | ||
) |
Get a modulus for a hash function that is tolerably likely to be relatively prime to most inputs.
We get a prime for initial values not larger than 1 million. We often get a prime after that. This works well in practice for hash tables up to at least 100 million and better than a multiplicative hash.
The algorithm starts by finding either the smallest prime number that is larger than the initial parameter value and not larger than 1009 or the largest prime smaller than the initial value and not larger than 1009. The algorithm is finished if the initial value is at most 1009. Otherwise, it finds the smallest (or largest) number that is relatively prime to all prime numbers <=1009.
[in] | initial | is the starting point for searching for number with no small divisors. That is usually the previous size of an expanding hash table or the initial guess for a new hash table. |
[in] | smaller | false if you want a value smaller than the initial value. |
bool axa_parse_ch | ( | axa_emsg_t * | emsg, |
uint16_t * | chp, | ||
const char * | str, | ||
size_t | str_len, | ||
bool | all_ok, | ||
bool | number_ok | ||
) |
Parse a channel string into a binary channel in host byte order.
[out] | emsg | if something goes wrong, this will contain the reason |
[out] | chp | pointer to a axa_p_ch_t channel in host byte order |
[in,out] | str | string containing channel number or "all" keyword |
[in,out] | str_len | length of str |
[in] | all_ok | boolean indicating "all" is allowed |
[in] | number_ok | boolean indicating "202 is the same as ch202" |
true | if no errors were encountered, chp will contain the channel |
false | error was was encountered, emsg will contain the reason |
time_t axa_tv_diff2ms | ( | const struct timeval * | tv1, |
const struct timeval * | tv2 | ||
) |
Compute (tv1 - tv2) in milliseconds, but limited or clamped to 1 day.
[in] | tv1 | const struct timeval * to first time value |
[in] | tv2 | const struct timeval * to second time value |
time_t axa_elapsed_ms | ( | const struct timeval * | now, |
struct timeval * | then | ||
) |
Compute the positive elapsed time between two timevals in milliseconds, but limited or clamped to at least 0 ms and at most 1 day.
Negative elapsed time implies that the system clock was set back. In that case, set the 'then' timestamp to 'now' and return 0.
[in] | now | const struct timeval * current time |
[in] | then | struct timeval * past value, which will be set to the current time if it in the future of the current time. |
const char * axa_get_version | ( | void | ) |
Retrieve the semantic library version as a string.
uint32_t axa_get_version_number | ( | void | ) |
Retrieve the semantic library version as a packed integer.
The number is a combination of the major, minor, and patchelevel numbers as per: MAJOR * 1000000 + MINOR * 1000 + PATCHLEVEL.