Miscellaneous Utilities

## Functions

const cxchar * | cx_program_get_name (void)
| Get the name of the application.
void | cx_program_set_name (const cxchar *name)
| Set the name of the application.
cxint | cx_bits_find (cxuint32 mask, cxint start)
| Get the position of the first bit set, searching from left to right.
cxint | cx_bits_rfind (cxuint32 mask, cxint start)
| Get the position of the first bit set, searching from right to left.
cxint | cx_snprintf (cxchar *string, cxsize n, const cxchar *format,...)
| Safe version of sprintf().
cxint | cx_vsnprintf (cxchar *string, cxsize n, const cxchar *format, va_list args)
| Safe version of vsprintf().
cxint | cx_asprintf (cxchar **string, const cxchar *format,...)
| Write formatted output to a newly allocated string.
cxint | cx_vasprintf (cxchar **string, const cxchar *format, va_list args)
| Write formatted output to a newly allocated string with a variable-length argument list.
cxlong | cx_line_max (void)
| Get the maximum length of a line supported by the system.
cxchar * | cx_line_alloc (void)
| Allocate a line buffer with the maximum size supported by the system.

## Detailed Description

The module provides a portable implementation of a selection of miscellaneous utility functions.

Synopsis:
  #include "cxutils.h"

## Function Documentation

## cx_asprintf()

cxint cx_asprintf | ( | cxchar ** | string,
|  | const cxchar * | format,
|  |  | ... )

Write formatted output to a newly allocated string.

Parameters

  string | Address where the allocated string is stored.
  format | The format string.
  ... | Arguments to be inserted into the format string.

Returns
  The number of characters (excluding the trailing null) written to allocated string, i.e. its length. If sufficient space cannot be allocated, -1 is returned.

The function is similar to cx_snprintf() or sprintf(). The difference to cx_snprintf() is that the output created from the format string format and the formatted arguments is placed into a string which is allocated using cx_malloc(). All standard C conversion directives are supported. The allocated string is always null terminated.

The pointer to the allocated string buffer sufficiently large to hold the string is returned to the caller in the string argument. This pointer should be passed to cx_free to release the allocated storage when it is no longer needed. If sufficient memory cannot be allocated is set to `NULL`.

See also
  cx_snprintf(), cx_strdupf(), cx_malloc(), cx_free()

References cx_vasprintf().

## cx_bits_find()

cxint cx_bits_find | ( | cxuint32 | mask,
|  | cxint | start )

Get the position of the first bit set, searching from left to right.

Parameters

  mask | A 32 bit integer containing bit flags.
  start | Bit position where the search starts.

Returns
  The bit position of the first bit set which is lower than start. If no bit is set -1 is returned.

The function searches for the first bit set in mask, starting at the bit position start - 1. The bit mask mask is searched from left to right. If start is less than 0 or bigger than 32 the search starts at the 31st bit.

See also
  cx_bits_rfind()

Referenced by cx_logv().

## cx_bits_rfind()

cxint cx_bits_rfind | ( | cxuint32 | mask,
|  | cxint | start )

Get the position of the first bit set, searching from right to left.

Parameters

  mask | A 32 bit integer containing bit flags.
  start | Bit position where the search starts.

Returns
  The bit position of the first bit set which is higher than start. If no bit is set -1 is returned.

The function searches for the first bit set in mask, starting at the bit position start + 1. The bit mask mask is searched from right to left. If start is less than 0 the search starts at the 1st bit.

See also
  cx_bits_find()

## cx_line_alloc()

cxchar * cx_line_alloc | ( | void |  | ) |

Allocate a line buffer with the maximum size supported by the system.

Returns
  A pointer allocated memory.

The function creates a line buffer with the maximum length supported by the system. The size of the buffer is determined calling cx_line_max() which gives the maximum size including the trailing zero.

References cx_calloc(), and cx_line_max().

## cx_line_max()

cxlong cx_line_max | ( | void |  | ) |

Get the maximum length of a line supported by the system.

Returns
  The length of a line including the trailing zero.

The function uses the sysconf() function to determine the maximum length of a line buffer that is supported by the system and available for utility programs. If the sysconf() facility is not available the function returns a guessed value of 4096 characters as the maximum length of a line taking into account the trailing zero.

Referenced by cx_line_alloc().

## cx_program_get_name()

const cxchar * cx_program_get_name | ( | void |  | ) |

Get the name of the application.

Returns
  The program's name string.

The program's name is retrieved and returned to the caller. The returned pointer is a library resource and must not be freed or modified.

Referenced by cx_log_default_handler().

## cx_program_set_name()

void cx_program_set_name | ( | const cxchar * | name | ) |

Set the name of the application.

Parameters

  name | The program name.

Returns
  Nothing.

The program's name is set to the string name.

Attention
  For thread-safety reasons this function may be called only once!

References cx_free(), and cx_strdup().

## cx_snprintf()

cxint cx_snprintf | ( | cxchar * | string,
|  | cxsize | n,
|  | const cxchar * | format,
|  |  | ... )

Safe version of sprintf().

Parameters

  string | Destination string.
  n | Maximum number of characters to be written.
  format | The format string.
  ... | Arguments to be inserted into the format string.

Returns
  The number of characters (excluding the trailing null) which would have been written to the destination string if enough space had been available, i.e. if the destination string is large enough the function returns the number of characters written to the string.

The function is a safe form of sprintf(). It writes output to the string string, under the control of the format string format. The format string specifies how the arguments are formatted for output. All standard C conversion directives are supported.

The difference compared to sprintf() is that the produced number of characters does not exceed n (including the trailing null).

Note
  The return value of cx_snprintf() conforms to the snprintf() function as standardized in ISO C99. This might be different from traditional implementations.

See also
  cx_asprintf(), cx_strdupf()

References cx_vsnprintf().

## cx_vasprintf()

cxint cx_vasprintf | ( | cxchar ** | string,
|  | const cxchar * | format,
|  | va_list | args )

Write formatted output to a newly allocated string with a variable-length argument list.

Parameters

  string | Address where the allocated string is stored.
  format | The format string.
  args | List of arguments to be inserted into the format string.

Returns
  The number of characters (excluding the trailing null) written to allocated string, i.e. its length. If sufficient space cannot be allocated, -1 is returned.

The function is similar to cx_vsnprintf() or vsprintf(). The difference to cx_vsnprintf() is that the output, created from the format string format and the arguments given by the variable-length argument list args, is placed into a string which is allocated using cx_malloc(). All standard C conversion directives are supported. The allocated string is always null terminated.

The pointer to the allocated string buffer sufficiently large to hold the string is returned to the caller in the string argument. This pointer should be passed to cx_free to release the allocated storage when it is no longer needed. If sufficient memory cannot be allocated is set to `NULL`.

See also
  cx_vsnprintf(), cx_strvdupf(), cx_malloc(), cx_free()

References cx_malloc(), cx_memory_is_system_malloc(), cx_strdup(), and cx_vsnprintf().

Referenced by cx_asprintf(), and cx_strvdupf().

## cx_vsnprintf()

cxint cx_vsnprintf | ( | cxchar * | string,
|  | cxsize | n,
|  | const cxchar * | format,
|  | va_list | args )

Safe version of vsprintf().

Parameters

  string | Destination string.
  n | Maximum number of characters to be written.
  format | The format string.
  args | List of arguments to be inserted into the format string.

Returns
  The number of characters (excluding the trailing null) which would have been written to the destination string if enough space had been available, i.e. if the destination string is large enough the function returns the number of characters written to the string.

The function is a safe form of vsprintf(). It writes output to the string string, under the control of the format string format. The format string specifies how the arguments, provided through the variable-length argument list args, are formatted for output. All standard C conversion directives are supported.

The difference compared to vsprintf() is that the produced number of characters does not exceed n (including the trailing null).

Note
  The return value of cx_vsnprintf() conforms to the vsnprintf() function as standardized in ISO C99. This might be different from traditional implementations.

See also
  cx_vasprintf(), cx_strvdupf()

Referenced by cx_logv(), cx_snprintf(), and cx_vasprintf().