Abstracted functions pertaining to other areas. More...

Data Structures
struct	ruTimeVal
	Abstracted version of the Posix struct timeval. More...

struct	ruTryLoop

Macros
#define	RU_SIZE_AUTO (~0LU)
	Says to determine the size parameter using strlen or an equivalent. More...

#define	RU_NON_BLOCK (-1)
	Indicates that an operation is non blocking. Used by ruRunProg. More...

#define	RU_NO_TIMEOUT 0
	Indicates that an operation that has no timeout. Used by ruRunProg. More...

#define	ruSleep(secs) ruSleepMs(((msec_t)(secs))*1000)
	Sleeps for the given number of seconds. More...

#define	ruRetWithCode(ptr, code, res)
	Convenience macro for setting a potentially passed in result pointer and returning a result. More...

#define	RU_IP4 0x1
	Used by ruIpAddrs to specify filtering for IPv4 numbers. More...

#define	RU_IP6 0x2
	Used by ruIpAddrs to specify filtering for IPv6 numbers. More...

#define	RU_IP (RU_IP4 \| RU_IP6)
	Used by ruIpAddrs to specify filtering for IP numbers. More...

Typedefs
typedef signed long	rusize_s
	Abstracted version of size_t but signed. More...

typedef pid_t	ru_pid
	Abstracted process id type. More...

typedef const char *	perm_chars
	A permanent NULL terminated string pointer. More...

typedef const char *	trans_chars
	A transient NULL terminated string pointer. More...

typedef char *	alloc_chars
	An allocated NULL terminated string pointer. More...

typedef const uint16_t *	perm_uni
	A permanent UTF16 wchar_t character type. More...

typedef const uint16_t *	trans_uni
	A transient UTF16 wchar_t character type. More...

typedef uint16_t *	alloc_uni
	An allocated UTF16 wchar_t character type. More...

typedef const unsigned char *	perm_bytes
	A permanent data bytes pointer. More...

typedef const unsigned char *	trans_bytes
	A transient data bytes pointer. More...

typedef unsigned char *	alloc_bytes
	An allocated data bytes pointer. More...

typedef const void *	perm_ptr
	A permanent pointer. More...

typedef const void *	trans_ptr
	A transient pointer. More...

typedef void *	alloc_ptr
	An allocated pointer. More...

typedef void *	ptr
	A generic pointer. More...

typedef long	sec_t
	A signed type for expressing seconds. More...

typedef int64_t	msec_t
	A signed type for expressing milli seconds. More...

typedef int64_t	usec_t
	A signed type for expressing micro seconds. More...

typedef intptr_t	ru_int
	A pointer sized integer type for collections like ruMap or ruList. More...

typedef uintptr_t	ru_uint
	A pointer sized unsigned integer type for collections like ruMap or ruList. More...

typedef size_t	rusize
	Abstracted version of size_t. More...

Functions
RUAPI const char *	ruVersion (void)
	Returns the build version of this package. More...

RUAPI const char *	ruLastError (void)
	Returns an English textual representation of the last error this thread generated. More...

RUAPI perm_chars	ruGetOs (void)
	Returns a lowercase string representation of the current OS. More...

RUAPI alloc_chars	ruGetHostname (void)
	Returns the name of this host. More...

RUAPI trans_chars	ruGetenv (const char *variable)
	Returns the value of the requested environment vartiable or NULL if it is not set. More...

RUAPI bool	ruIsInt64 (const char *numstr)
	Returns true if given string contains a valid 64 bit integer. More...

RUAPI ru_pid	ruProcessId (void)
	Return the current process id. More...

RUAPI int32_t	ruRunProg (const char **argv, sec_t timeout)
	Runs given program. More...

RUAPI alloc_chars	ruGetLanguage (void)
	Returns the ISO-639-1 2 letter country code pertaining to the running system,. More...

RUAPI unsigned long	ruSemiRandomNumber (unsigned long max, long offset)
	Returns a quasi ramdom number between 0 and max + offset. More...

RUAPI int	ruVersionComp (trans_chars ver1, trans_chars ver2)
	Compares 2 version strings This function compares version number strings that are made up of real numbers. The advantage is that the delimiter does not matter. It will work with, for example, 141.01.03, 141:1:3, or even 141A1P3. It also handles mismatched tails so that 141.1.3 will come before 141.1.3.1. Finally NULLs are also properly compared. More...

RUAPI int32_t	ruGetTimeVal (ruTimeVal *result)
	Returns a ruTimeVal representing the current time. More...

RUAPI usec_t	ruTimeUs (void)
	Return the current local time in microseconds since Jan. 1 1970. More...

RUAPI msec_t	ruTimeMs (void)
	Return the current local time in milliseconds since Jan. 1 1970. More...

RUAPI sec_t	ruTimeSec (void)
	Return the current local time in seconds since Jan. 1 1970. More...

RUAPI bool	ruTimeUsEllapsed (usec_t stamp)
	Checks if given stamp has elapsed. More...

RUAPI bool	ruTimeMsEllapsed (msec_t stamp)
	Checks if given stamp has elapsed. More...

RUAPI bool	ruTimeEllapsed (sec_t stamp)
	Checks if given stamp has elapsed. More...

RUAPI void	ruSleepUs (usec_t microseconds)
	Sleeps for the given number of micro seconds. More...

RUAPI void	ruSleepMs (msec_t milliseconds)
	Sleeps for the given number of milli seconds. More...

RUAPI void	ruTryLoopInit (ruTryLoop *cycle, msec_t retryMs, msec_t timeoutMs)

RUAPI bool	ruTryLoopDone (ruTryLoop *cycle)

RUAPI sec_t	ruTimeParse (trans_chars dateformat, trans_chars datestr)
	Convert a string representation of time to a time stamp. More...

RUAPI sec_t	ruUtcParse (trans_chars dateformat, trans_chars datestr)
	UTC version of ruTimeParse. More...

RUAPI int	ruTimeFormat (trans_chars format, rusize len, alloc_chars timeStr, sec_t timesecs)
	Return the current local time formatted in given buffer. More...

RUAPI int	ruUtcFormat (trans_chars format, rusize len, alloc_chars timeStr, sec_t timesecs)
	UTC version of ruTimeFormat. More...

RUAPI sec_t	ruTimeLocalToUtc (sec_t stamp)
	Converts given local time stamp to UTC. More...

RUAPI sec_t	ruTimeUtcToLocal (sec_t stamp)
	Converts given UTC time stamp to local time. More...

RUAPI ptr	ruCharPtrDup (char *in)
	Copies the given string and returns the pointer. More...

RUAPI ruList	ruIpAddrs (int32_t ipfilter)
	Returns the IP numbers bound to the host. More...

RUAPI int32_t	ruGetOptMap (ruMap parms, trans_chars opts, int argc, char *argv)
	Runs getopt short with given parameters. More...

Detailed Description

Abstracted functions pertaining to other areas.

Macro Definition Documentation

◆ RU_IP

#define RU_IP (RU_IP4 | RU_IP6)

Used by ruIpAddrs to specify filtering for IP numbers.

◆ RU_IP4

#define RU_IP4 0x1

Used by ruIpAddrs to specify filtering for IPv4 numbers.

◆ RU_IP6

#define RU_IP6 0x2

Used by ruIpAddrs to specify filtering for IPv6 numbers.

◆ RU_NO_TIMEOUT

#define RU_NO_TIMEOUT 0

Indicates that an operation that has no timeout. Used by ruRunProg.

◆ RU_NON_BLOCK

#define RU_NON_BLOCK (-1)

Indicates that an operation is non blocking. Used by ruRunProg.

◆ RU_SIZE_AUTO

#define RU_SIZE_AUTO (~0LU)

Says to determine the size parameter using strlen or an equivalent.

◆ ruRetWithCode

#define ruRetWithCode	(	ptr,
		code,
		res
	)

Value:

    ruMacStart { \
    if (ptr) { *ptr = code; } return res; \
    } ruMacEnd

Convenience macro for setting a potentially passed in result pointer and returning a result.

◆ ruSleep

#define ruSleep ( secs ) ruSleepMs(((msec_t)(secs))*1000)

Sleeps for the given number of seconds.

Parameters

secs	time to sleep

Typedef Documentation

◆ alloc_bytes

typedef unsigned char* alloc_bytes

An allocated data bytes pointer.

On input this can represent a place on the stack or heap that will be written to by the called function. Usually accompanied by a length parameter. It can also represent a parameter that will be freed in conjunction with an enclosing object after use. On output this data belongs to the caller and must be freed after use. Within functions this can also be used for data pointers that must be freed.

◆ alloc_chars

typedef char* alloc_chars

An allocated NULL terminated string pointer.

On input this can represent a place on the stack or heap that will be written to by the called function. Usually accompanied by a length parameter. It can also represent a parameter that will be freed in conjunction with an enclosing object after use. On output this string belongs to the caller and must be freed after use. Within functions this can also be used for string pointers that must be freed.

◆ alloc_ptr

typedef void* alloc_ptr

An allocated pointer.

On input this can represent a place on the stack or heap that will be written to by the called function. Usually accompanied by a length parameter. It can also represent a parameter that will be freed in conjunction with an enclosing object after use. On output this object belongs to the caller and must be freed after use.

◆ alloc_uni

typedef uint16_t* alloc_uni

An allocated UTF16 wchar_t character type.

On input this can represent a place on the stack or heap that will be written to by the called function. Usually accompanied by a length parameter. It can also represent a parameter that will be freed in conjunction with an enclosing object after use. On output this data belongs to the caller and must be freed after use. Within functions this can also be used for data pointers that must be freed.

◆ msec_t

typedef int64_t msec_t

A signed type for expressing milli seconds.

◆ perm_bytes

typedef const unsigned char* perm_bytes

A permanent data bytes pointer.

On input it needs to persist through the life of a given context. On output it is guaranteed to live as long as it's context or until it has been explicitly finalized. It must not be freed. Within functions this can also be used for string pointers that must not be freed.

◆ perm_chars

typedef const char* perm_chars

A permanent NULL terminated string pointer.

On input it needs to persist through the life of a given context. On output it is guaranteed to live as long as it's context or until it has been explicitly finalized. It must not be freed. Within functions this can also be used for string pointers that must not be freed.

◆ perm_ptr

typedef const void* perm_ptr

A permanent pointer.

On input it needs to persist through the life of a given context. On output it is guaranteed to live as long as it's context or until it has been explicitly finalized. It must not be freed.

◆ perm_uni

typedef const uint16_t* perm_uni

A permanent UTF16 wchar_t character type.

On input it needs to persist through the life of a given context. On output it is guaranteed to live as long as it's context or until it has been explicitly finalized. It must not be freed. Within functions this can also be used for string pointers that must not be freed.

◆ ptr

typedef void* ptr

A generic pointer.

◆ ru_int

typedef intptr_t ru_int

A pointer sized integer type for collections like ruMap or ruList.

◆ ru_pid

typedef pid_t ru_pid

Abstracted process id type.

◆ ru_uint

typedef uintptr_t ru_uint

A pointer sized unsigned integer type for collections like ruMap or ruList.

◆ rusize

typedef size_t rusize

Abstracted version of size_t.

◆ rusize_s

typedef signed long rusize_s

Abstracted version of size_t but signed.

◆ sec_t

typedef long sec_t

A signed type for expressing seconds.

◆ trans_bytes

typedef const unsigned char* trans_bytes

A transient data bytes pointer.

On input this string must only persist for the duration of the function call. On output this string is valid until another call with the given context is performed and must not be freed.

◆ trans_chars

typedef const char* trans_chars

A transient NULL terminated string pointer.

On input this string must only persist for the duration of the function call. On output this string is valid until another call with the given context is performed and must not be freed.

◆ trans_ptr

typedef const void* trans_ptr

A transient pointer.

On input this string must only persist for the duration of the function call. On output this string is valid until another call with the given context is performed and must not be freed.

◆ trans_uni

typedef const uint16_t* trans_uni

A transient UTF16 wchar_t character type.

On input this string must only persist for the duration of the function call. On output this string is valid until another call with the given context is performed and must not be freed.

◆ usec_t

typedef int64_t usec_t

A signed type for expressing micro seconds.

Function Documentation

◆ ruCharPtrDup()

RUAPI ptr ruCharPtrDup ( char * in )

Copies the given string and returns the pointer.

Parameters

in	String to duplicate

Returns: Pointer to copied string. Caller must free.

◆ ruGetenv()

RUAPI trans_chars ruGetenv ( const char * variable )

Returns the value of the requested environment vartiable or NULL if it is not set.

Parameters

variable Variable name to retrieve

Returns: A copy of the value. May not be freed by the caller.

◆ ruGetHostname()

RUAPI alloc_chars ruGetHostname ( void )

Returns the name of this host.

Returns: hostname. Caller should free this with ruFree.

◆ ruGetLanguage()

RUAPI alloc_chars ruGetLanguage ( void )

Returns the ISO-639-1 2 letter country code pertaining to the running system,.

Returns: The country code. Caller must free with ruFree.

◆ ruGetOptMap()

RUAPI int32_t ruGetOptMap	(	ruMap *	parms,
		trans_chars	opts,
		int	argc,
		char **	argv
	)

Runs getopt short with given parameters.

It does not process non option arguments or permute argv to place these at the end.

Parameters

parms	Where the string/string map with the parameters will be placed. Caller must free with ruMapFree
opts	getopt short definition string
argc	length of argv, as given in main
argv	array of string parameters with the first being the comman itself as given in main

Returns: RUE_OK on success map will be set RUE_PARAMETER_NOT_SET when called wrong, no map RUE_FILE_NOT_FOUND if there were no options, no map RUE_INVALID_PARAMETER if there were invalid parameters, no map

◆ ruGetOs()

RUAPI perm_chars ruGetOs ( void )

Returns a lowercase string representation of the current OS.

Currently knows about windows, android, linux, osx, ios and unix.

Returns: os string. Caller should copy this for persistence.

◆ ruGetTimeVal()

RUAPI int32_t ruGetTimeVal ( ruTimeVal * result )

Returns a ruTimeVal representing the current time.

Parameters

result Pointer to the ruTimeVal structure to populate.

Returns: Return code of the operation or RUE_OK on success.

◆ ruIpAddrs()

RUAPI ruList ruIpAddrs ( int32_t ipfilter )

Returns the IP numbers bound to the host.

Parameters

ipfilter Whether to filter for IPv4(RU_IP4), IPv6(RU_IP6) or both (RU_IP).

Returns: ruList of IP strings. Caller to free with ruListFree

◆ ruIsInt64()

RUAPI bool ruIsInt64 ( const char * numstr )

Returns true if given string contains a valid 64 bit integer.

Parameters

numstr String to parse

Returns: parse result overflow returns as false

◆ ruLastError()

RUAPI const char* ruLastError ( void )

Returns an English textual representation of the last error this thread generated.

Note, not all functions use this, so this function should only be called after a function that does use it is called, else misleading information will appear.

Returns: Ephemeral error message. Must be copied if it is to persist.

◆ ruProcessId()

RUAPI ru_pid ruProcessId ( void )

Return the current process id.

Returns: the current process id

◆ ruRunProg()

RUAPI int32_t ruRunProg	(	const char **	argv,
		sec_t	timeout
	)

Runs given program.

Example:

const char* command[] = {"/bin/sleep", "3", NULL};

int ret = ruRunProg(command, RU_NO_TIMEOUT);

RU_NO_TIMEOUT

#define RU_NO_TIMEOUT

Indicates that an operation that has no timeout. Used by ruRunProg.

Definition: regify-util.h:442

ruRunProg

RUAPI int32_t ruRunProg(const char **argv, sec_t timeout)

Runs given program.

Parameters

argv	program with params to run
timeout	Use RU_NON_BLOCK for non blocking, RU_NO_TIMEOUT for blocking and > 0 to a timeout in seconds.

Returns: RUE_FORK_FAILED for a fork failure, RUE_RUN_FAILED for a launch failure, RUE_TIMEOUT for a timeout, else the return code of the process or 0 if it was launched non blocking.

◆ ruSemiRandomNumber()

RUAPI unsigned long ruSemiRandomNumber	(	unsigned long	max,
		long	offset
	)

Returns a quasi ramdom number between 0 and max + offset.

This function ORs timevals usec with sec, so it is not designed for cryptographic use.

Parameters

max	The maximum random value.
offset	An off set to add to the result to move the range.

Returns: A number between offset and offset + max.

◆ ruSleepMs()

RUAPI void ruSleepMs ( msec_t milliseconds )

Sleeps for the given number of milli seconds.

Parameters

milliseconds

◆ ruSleepUs()

RUAPI void ruSleepUs ( usec_t microseconds )

Sleeps for the given number of micro seconds.

Parameters

microseconds

◆ ruTimeEllapsed()

RUAPI bool ruTimeEllapsed ( sec_t stamp )

Checks if given stamp has elapsed.

Parameters

stamp second stamp to compare to.

Returns: Return true if now is >= stamp

◆ ruTimeFormat()

RUAPI int ruTimeFormat	(	trans_chars	format,
		rusize	len,
		alloc_chars	timeStr,
		sec_t	timesecs
	)

Return the current local time formatted in given buffer.

Parameters

format	format string for strftime
len	length of the given buffer must include room for the null terminator
timeStr	buffer where formatted null terminated string will be placed
timesecs	datestamp in seconds since epoch or 0 to use current time

Returns: microsecond part of the current time or -1 on error;

◆ ruTimeLocalToUtc()

RUAPI sec_t ruTimeLocalToUtc ( sec_t stamp )

Converts given local time stamp to UTC.

Parameters

stamp seconds since epoch in local time

Returns: UTC seconds since epoch

◆ ruTimeMs()

RUAPI msec_t ruTimeMs ( void )

Return the current local time in milliseconds since Jan. 1 1970.

Returns: Milli seconds since epoch

◆ ruTimeMsEllapsed()

RUAPI bool ruTimeMsEllapsed ( msec_t stamp )

Checks if given stamp has elapsed.

Parameters

stamp millisecond stamp to compare to.

Returns: Return true if now is >= stamp

◆ ruTimeParse()

RUAPI sec_t ruTimeParse	(	trans_chars	dateformat,
		trans_chars	datestr
	)

Convert a string representation of time to a time stamp.

Parameters

dateformat	a strptime type format string
datestr	the string representation of the given date time

Returns: given date time in seconds since epoch

◆ ruTimeSec()

RUAPI sec_t ruTimeSec ( void )

Return the current local time in seconds since Jan. 1 1970.

Returns: Seconds since epoch

◆ ruTimeUs()

RUAPI usec_t ruTimeUs ( void )

Return the current local time in microseconds since Jan. 1 1970.

Returns: Micro seconds since epoch

◆ ruTimeUsEllapsed()

RUAPI bool ruTimeUsEllapsed ( usec_t stamp )

Checks if given stamp has elapsed.

Parameters

stamp microsecond stamp to compare to.

Returns: Return true if now is >= stamp

◆ ruTimeUtcToLocal()

RUAPI sec_t ruTimeUtcToLocal ( sec_t stamp )

Converts given UTC time stamp to local time.

Parameters

stamp UTC seconds since epoch

Returns: seconds since epoch in local time

◆ ruTryLoopDone()

RUAPI bool ruTryLoopDone ( ruTryLoop * cycle )

Blocks and returns whether loop is done or not.

See also: ruTryLoopInit

Parameters

cycle pointer to a ruTryLoop structure

Returns: true if cycle is done or false after blocking for retryMs milliseconds

◆ ruTryLoopInit()

RUAPI void ruTryLoopInit	(	ruTryLoop *	cycle,
		msec_t	retryMs,
		msec_t	timeoutMs
	)

Handles the details of looping delayed until a timeout is reached. Example:

ruTryLoop tl;
ruTryLoopInit(&tl, 10, 8000);
 
do {
  // do something
  // break out if done early
while(!ruTryLoopDone(&tl));

Parameters

cycle	pointer to a ruTryLoop structure
retryMs	how long ruTryLoopDone should block when not done
timeoutMs	how long ruTryLoopDone should return false after blocking

◆ ruUtcFormat()

RUAPI int ruUtcFormat	(	trans_chars	format,
		rusize	len,
		alloc_chars	timeStr,
		sec_t	timesecs
	)

UTC version of ruTimeFormat.

Parameters

format	format string for strftime
len	length of the given buffer must include room for the null terminator
timeStr	buffer where formatted null terminated string will be placed
timesecs	datestamp in seconds since epoch or 0 to use current time

Returns: microsecond part of the current time or -1 on error;

◆ ruUtcParse()

RUAPI sec_t ruUtcParse	(	trans_chars	dateformat,
		trans_chars	datestr
	)

UTC version of ruTimeParse.

Parameters

dateformat	a strptime type format string
datestr	the string representation of the given date time

Returns: given date time in seconds since epoch

◆ ruVersion()

RUAPI const char* ruVersion ( void )

Returns the build version of this package.

Returns: Version of this package. This string is static and must not be freed.

◆ ruVersionComp()

RUAPI int ruVersionComp	(	trans_chars	ver1,
		trans_chars	ver2
	)

Compares 2 version strings This function compares version number strings that are made up of real numbers. The advantage is that the delimiter does not matter. It will work with, for example, 141.01.03, 141:1:3, or even 141A1P3. It also handles mismatched tails so that 141.1.3 will come before 141.1.3.1. Finally NULLs are also properly compared.

Parameters

ver1	First version to check
ver2	Second version to check

Returns: -1, 0 or 1 depending on whether ver1 is less equal or greater ver2

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ RU_IP

◆ RU_IP4

◆ RU_IP6

◆ RU_NO_TIMEOUT

◆ RU_NON_BLOCK

◆ RU_SIZE_AUTO

◆ ruRetWithCode

◆ ruSleep

Typedef Documentation

◆ alloc_bytes

◆ alloc_chars

◆ alloc_ptr

◆ alloc_uni

◆ msec_t

◆ perm_bytes

◆ perm_chars

◆ perm_ptr

◆ perm_uni

◆ ptr

◆ ru_int

◆ ru_pid

◆ ru_uint

◆ rusize

◆ rusize_s

◆ sec_t

◆ trans_bytes

◆ trans_chars

◆ trans_ptr

◆ trans_uni

◆ usec_t

Function Documentation

◆ ruCharPtrDup()

◆ ruGetenv()

◆ ruGetHostname()

◆ ruGetLanguage()

◆ ruGetOptMap()

◆ ruGetOs()

◆ ruGetTimeVal()

◆ ruIpAddrs()

◆ ruIsInt64()

◆ ruLastError()

◆ ruProcessId()

◆ ruRunProg()

◆ ruSemiRandomNumber()

◆ ruSleepMs()

◆ ruSleepUs()

◆ ruTimeEllapsed()

◆ ruTimeFormat()

◆ ruTimeLocalToUtc()

◆ ruTimeMs()

◆ ruTimeMsEllapsed()

◆ ruTimeParse()

◆ ruTimeSec()

◆ ruTimeUs()

◆ ruTimeUsEllapsed()

◆ ruTimeUtcToLocal()

◆ ruTryLoopDone()

◆ ruTryLoopInit()

◆ ruUtcFormat()

◆ ruUtcParse()

◆ ruVersion()

◆ ruVersionComp()