libu8
libu8.h File Reference

These functions provide miscellaneous functionality. More...

Data Structures

struct  U8_INT16
 
struct  U8_PILE
 
struct  U8_SOURCE_FILE_RECORD
 

Functions

U8_EXPORT void u8_mutex_lock (u8_mutex *m)
 Locks a POSIX thread mutex. More...
 
U8_EXPORT void u8_mutex_unlock (u8_mutex *m)
 Unlocks a POSIX thread mutex. More...
 
U8_EXPORT void u8_mutex_init (u8_mutex *m)
 Initialize a POSIX thread mutex. More...
 
U8_EXPORT void u8_mutex_destroy (u8_mutex *m)
 Destroys a POSIX thread mutex. More...
 
U8_EXPORT long long u8_threadid (void)
 Returns a long identifying the current thread. More...
 
U8_EXPORT char * u8_procinfo (char *buf)
 Returns a string identifying the current process and thread. More...
 
U8_EXPORT char * u8_2libc (u8_string string)
 Converts a UTF-8 string to the encoding expected by system (libc) functions. More...
 
U8_EXPORT char * u8_tolibc (u8_string string)
 Converts a UTF-8 string to the encoding expected by system (libc) functions. More...
 
U8_EXPORT u8_string u8_fromlibc (char *local_string)
 Converts a natively encoded string into a UTF-8 string. More...
 
U8_EXPORT void u8_set_libcfns (u8_string(*fromfn)(char *), char *(*tofn)(u8_string))
 This sets the functions used to map to and from libc. More...
 
U8_EXPORT u8_string u8_appid (void)
 Returns a UTF-8 string describing the current application for inclusion in messages or other output or logging. More...
 
U8_EXPORT void u8_identify_application (u8_string id)
 Sets the UTF-8 string describing the current application. More...
 
U8_EXPORT int u8_default_appid (u8_string id)
 Sets the UTF-8 string describing the current application, unless it has already been set. More...
 
U8_EXPORT int u8_config_utf8warn (int flag)
 Gets/sets whether warnings are produced for invalid UTF-8 sequences, which can be annoyingly common with some content. More...
 
U8_EXPORT int u8_config_utf8err (int flag)
 Gets/sets whether errors are produced for invalid UTF-8 sequences. More...
 
U8_EXPORT int u8_initialize (void) U8_LIBINIT_FN
 Initializes the core UTF-8 functions (from libu8.h) More...
 
U8_EXPORT int u8_initialize_io (void) U8_LIBINIT_FN
 Initializes UTF-8 io functions, including character set conversion and stream I/O. More...
 
U8_EXPORT int u8_initialize_fns (void) U8_LIBINIT_FN
 Initializes UTF-8 miscellaneous functions, including time keeping, file access, network access, and server functions. More...
 
U8_EXPORT void u8_init_chardata_c (void) U8_LIBINIT_FN
 Initializes the full character data table for the libu8 library. More...
 
U8_EXPORT void u8_initialize_u8stdio (void) U8_LIBINIT_FN
 Initializes the messaging functions which use POSIX stdio. More...
 
U8_EXPORT void u8_initialize_u8syslog (void) U8_LIBINIT_FN
 Initializes the messaging functions which use POSIX syslog. More...
 
U8_EXPORT u8_string u8_getrevision (void)
 Returns the current libu8 revision string (derived from the GIT branch) More...
 
U8_EXPORT u8_string u8_getversion (void)
 Returns the current libu8 version string (major.minor.release) More...
 
U8_EXPORT int u8_getmajorversion (void)
 Returns the current libu8 major version number. More...
 
U8_EXPORT void * u8_mallocz (size_t sz)
 Allocates and zero-clears a block of memory. More...
 
U8_EXPORT void * u8_reallocz (void *ptr, size_t sz, size_t osz)
 Reallocates a block of memory, zero clearing any new parts. More...
 
U8_EXPORT void * u8_extalloc (void *ptr, size_t sz, size_t osz)
 Copies a block of memory into a larger block, zero clearing any new parts. More...
 
U8_EXPORT void u8_raise (u8_condition ex, u8_context cxt, u8_string details)
 Signals an error with particular details. More...
 
U8_EXPORT void u8_set_error_handler (void(*h)(u8_condition, u8_context, u8_string))
 Sets the function used when an error is raised. More...
 
U8_EXPORT unsigned int u8_random (unsigned int n)
 Returns a random integer between 0 and n-1 (inclusive) More...
 
U8_EXPORT void u8_randomize (unsigned int seed)
 Sets the random seed value used for the random number generation. More...
 
U8_EXPORT void * u8_dynamic_load (u8_string filename)
 Dynamically loads a named file into the running image. More...
 
U8_EXPORT long u8_getpagesize (void)
 Returns the system page size. More...
 
U8_EXPORT u8_string u8_getenv (u8_string envvar)
 Gets a variable specified in the environment. More...
 
U8_EXPORT double u8_elapsed_time (void)
 Returns elapsed time in seconds since some moment after application startup. More...
 
U8_EXPORT long long u8_microtime (void)
 Returns the number of microseconds since the epoch. More...
 
U8_EXPORT void u8_initialize_logging (void)
 Initializes logging. More...
 

Detailed Description

These functions provide miscellaneous functionality.

Function Documentation

U8_EXPORT char* u8_2libc ( u8_string  string)

Converts a UTF-8 string to the encoding expected by system (libc) functions.

If the system encoding is UTF-8, this returns its argument, rather than copying it, as u8_tolibc does.

Parameters
stringa utf-8 string
Returns
a character string in the local encoding

Referenced by u8_localpath().

U8_EXPORT u8_string u8_appid ( void  )

Returns a UTF-8 string describing the current application for inclusion in messages or other output or logging.

This string is not consed, so it should not be freed.

Returns
a utf-8 string

Referenced by u8_message_prefix(), and u8_sessionid().

U8_EXPORT int u8_config_utf8err ( int  flag)

Gets/sets whether errors are produced for invalid UTF-8 sequences.

Parameters
flagan int
Returns
int If the flag is negative, the current value is returned
U8_EXPORT int u8_config_utf8warn ( int  flag)

Gets/sets whether warnings are produced for invalid UTF-8 sequences, which can be annoyingly common with some content.

Parameters
flagan int
Returns
int If the flag is negative, the current value is returned
U8_EXPORT int u8_default_appid ( u8_string  id)

Sets the UTF-8 string describing the current application, unless it has already been set.

This can be used to provide default appids while allowing programs to override the default. This returns 1 if it did anything (no appid had been previously set) or zero otherwise.

Parameters
ida utf-8 string
Returns
int
U8_EXPORT void* u8_dynamic_load ( u8_string  filename)

Dynamically loads a named file into the running image.

Parameters
filenamea utf-8 pathname
Returns
void

References u8_seterr().

Referenced by u8_getenv().

U8_EXPORT double u8_elapsed_time ( void  )

Returns elapsed time in seconds since some moment after application startup.

Returns
a double indicating seconds

Referenced by u8_message_prefix().

U8_EXPORT void* u8_extalloc ( void *  ptr,
size_t  sz,
size_t  osz 
)

Copies a block of memory into a larger block, zero clearing any new parts.

Parameters
ptran existing block of memory
szthe number of bytes to allocate
oszthe number of bytes currently allocated at the location
Returns
void *

References u8_log(), and u8_seterr().

U8_EXPORT u8_string u8_fromlibc ( char *  local_string)

Converts a natively encoded string into a UTF-8 string.

If the system encoding is UTF-8, this validates and copies the argument.

Parameters
local_stringa locally encoded text string
Returns
a utf-8 encoded string

References u8_valid_copy().

Referenced by u8_do_printf(), u8_getcwd(), u8_getenv(), u8_host_primary(), u8_pathsuffix(), u8_random_vector(), u8_readlink(), u8_renew(), u8_rmdir(), u8_setcwd(), and u8_strerror().

U8_EXPORT u8_string u8_getenv ( u8_string  envvar)

Gets a variable specified in the environment.

Parameters
envvara variable name
Returns
a utf-8 string, copied

Gets a variable specified in the environment.

Parameters
envvarthe variable name, as a UTF-8 string.
Returns
a utf8 string (converted from the value) or NULL

References u8_dynamic_load(), u8_fromlibc(), u8_seterr(), and u8_tolibc().

U8_EXPORT int u8_getmajorversion ( void  )

Returns the current libu8 major version number.

Returns
an int

Returns the current libu8 major version number.

Returns
a const utf8 string (converted from the value) or NULL
U8_EXPORT long u8_getpagesize ( void  )

Returns the system page size.

Returns
long

Returns the system page size.

Returns
a const utf8 string (converted from the value) or NULL
U8_EXPORT u8_string u8_getrevision ( void  )

Returns the current libu8 revision string (derived from the GIT branch)

Returns
a utf8 string

Returns the current libu8 revision string (derived from the GIT branch)

Returns
a const utf8 string (converted from the value) or NULL
U8_EXPORT u8_string u8_getversion ( void  )

Returns the current libu8 version string (major.minor.release)

Returns
a utf8 string

Returns the current libu8 version string (major.minor.release)

Returns
a const utf8 string (converted from the value) or NULL
U8_EXPORT void u8_identify_application ( u8_string  id)

Sets the UTF-8 string describing the current application.

Parameters
ida utf-8 string
Returns
void
U8_EXPORT void u8_init_chardata_c ( void  )

Initializes the full character data table for the libu8 library.

Returns
void

References u8_set_charinfo().

U8_EXPORT int u8_initialize ( void  )

Initializes the core UTF-8 functions (from libu8.h)

Returns
void

References u8_initialize_logging().

U8_EXPORT int u8_initialize_fns ( void  )

Initializes UTF-8 miscellaneous functions, including time keeping, file access, network access, and server functions.

Returns
void
U8_EXPORT int u8_initialize_io ( void  )

Initializes UTF-8 io functions, including character set conversion and stream I/O.

Returns
void
U8_EXPORT void u8_initialize_logging ( void  )

Initializes logging.

Returns
void

Referenced by u8_initialize(), u8_message_prefix(), and u8_threadid().

U8_EXPORT void u8_initialize_u8stdio ( void  )

Initializes the messaging functions which use POSIX stdio.

References u8_set_error_handler(), and u8_set_logfn().

U8_EXPORT void u8_initialize_u8syslog ( void  )

Initializes the messaging functions which use POSIX syslog.

U8_EXPORT void* u8_mallocz ( size_t  sz)

Allocates and zero-clears a block of memory.

Parameters
szthe number of bytes to allocate
Returns
void *

References u8_seterr().

Referenced by u8_mutex_destroy().

U8_EXPORT long long u8_microtime ( void  )

Returns the number of microseconds since the epoch.

This returns a value with whatever accuracy it can get.

Returns
a long long counting microseconds

Referenced by u8_list_clients(), u8_server_curstats(), and u8_server_init().

U8_EXPORT void u8_mutex_destroy ( u8_mutex *  m)

Destroys a POSIX thread mutex.

Parameters
ma pointer to a mutex
Returns
void

References u8_mallocz(), and u8_procinfo().

U8_EXPORT void u8_mutex_init ( u8_mutex *  m)

Initialize a POSIX thread mutex.

Parameters
ma pointer to a mutex
Returns
void
U8_EXPORT void u8_mutex_lock ( u8_mutex *  m)

Locks a POSIX thread mutex.

Parameters
ma pointer to a mutex
Returns
void
U8_EXPORT void u8_mutex_unlock ( u8_mutex *  m)

Unlocks a POSIX thread mutex.

Parameters
ma pointer to a mutex
Returns
void
U8_EXPORT char* u8_procinfo ( char *  buf)

Returns a string identifying the current process and thread.

Parameters
bufa buffer to use (mallocd otherwise)
Returns
a character string

References u8_threadid().

Referenced by u8_message_prefix(), and u8_mutex_destroy().

U8_EXPORT void u8_raise ( u8_condition  ex,
u8_context  cxt,
u8_string  details 
)

Signals an error with particular details.

This currently exits, though it may be expanded to an exception throwing architecture in the near future.

Parameters
exa utf-8 condition string (u8_condition)
cxta utf-8 context string (a const string)
detailsa utf-8 string detailing the error, or NULL
Returns
void (shouldn't)

References u8_log(), and u8_set_error_handler().

Referenced by u8_get_portno(), u8_hmac_sha1(), u8_hmac_sha256(), u8_hmac_sha384(), u8_hmac_sha512(), and u8_signal_raise().

U8_EXPORT unsigned int u8_random ( unsigned int  n)

Returns a random integer between 0 and n-1 (inclusive)

Parameters
nthe upper limit for the random number
Returns
an int between 0 and n-1

Referenced by u8_consuuid(), u8_random_vector(), u8_rfc822_to_xtime(), and u8_uuid_xtime().

U8_EXPORT void u8_randomize ( unsigned int  seed)

Sets the random seed value used for the random number generation.

Setting the random seed value to the same value will cause the sequence of numbers generated by u8_random to be the same.

Parameters
seedthe seed value
Returns
void

References u8_log().

U8_EXPORT void* u8_reallocz ( void *  ptr,
size_t  sz,
size_t  osz 
)

Reallocates a block of memory, zero clearing any new parts.

Parameters
ptra previously allocated (with malloc) block of memory
szthe number of bytes to allocate
oszthe previous number of bytes, needed to know how much to zero out
Returns
void *

References u8_seterr().

U8_EXPORT void u8_set_error_handler ( void(*)(u8_condition, u8_context, u8_string)  h)

Sets the function used when an error is raised.

Parameters
his a function on a condition, a context, and a utf-8 string
Returns
void (shouldn't)

Referenced by u8_initialize_u8stdio(), and u8_raise().

U8_EXPORT void u8_set_libcfns ( u8_string(*)(char *)  fromfn,
char *(*)(u8_string)  tofn 
)

This sets the functions used to map to and from libc.

Parameters
fromfna function from character strings to utf-8 strings
tofna function from utf-8 strings to character strings.
Returns
void
U8_EXPORT long long u8_threadid ( void  )

Returns a long identifying the current thread.

Returns
long a numeric thread identifier (OS dependent)

References u8_initialize_logging(), and u8_log().

Referenced by u8_procinfo().

U8_EXPORT char* u8_tolibc ( u8_string  string)

Converts a UTF-8 string to the encoding expected by system (libc) functions.

If the system encoding is UTF-8, this validates and copies the argument.

Parameters
stringa utf-8 string
Returns
a character string in the local encoding

References u8_valid_copy().

Referenced by u8_getenv(), u8_gethostbyname(), and u8_lookup_host().