C Standard Library Extensions  1.1.2
Functions
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

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

Write formatted output to a newly allocated string.

Parameters
stringAddress where the allocated string is stored.
formatThe 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().

cxint cx_bits_find ( cxuint32  mask,
cxint  start 
)

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

Parameters
maskA 32 bit integer containing bit flags.
startBit 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().

cxint cx_bits_rfind ( cxuint32  mask,
cxint  start 
)

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

Parameters
maskA 32 bit integer containing bit flags.
startBit 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()
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().

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().

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().

void cx_program_set_name ( const cxchar *  name)

Set the name of the application.

Parameters
nameThe 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().

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

Safe version of sprintf().

Parameters
stringDestination string.
nMaximum number of characters to be written.
formatThe 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().

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
stringAddress where the allocated string is stored.
formatThe format string.
argsList 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().

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

Safe version of vsprintf().

Parameters
stringDestination string.
nMaximum number of characters to be written.
formatThe format string.
argsList 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().