R API

The Safe Runtime (R) is a portable runtime library for embedded applications.

The R library provides management for binary searching, buffering, error handling, events, events, files, hashing, lists, logging, memory, ssl, sockets, strings, and date/time functions. It also provides a foundation of safe routines for secure programming, that help to prevent buffer overflows and other security threats. The library can be used in both C and C++ programs.

The R library uses a set extended typedefs for common types. These include: bool, cchar, cvoid, uchar, short, ushort, int, uint, long, ulong, int32, uint32, int64, uint64, float, and double. The cchar type is a const char, cvoid is const void. Several types have "u" prefixes to denote unsigned qualifiers.

The library includes a memory allocator and global memory allocation handler.

The library provides support for fiber coroutines to enable parallel programming without callbacks or complex threads. The network APIs use fibers to transparently block the fiber and resume other fibers automatically. This enables a straight-line "blocking" programming paradigm while enabling other fibers to run as required.

Function Index

PUBLIC void	assert(bool cond)
	Asser that a condition is true.
PUBLIC int	rAccessFile(cchar *path, int mode)
	Test if a file can be accessed with the given mode (F_OK, R_OK, W_OK, X_OK).
PUBLIC void	rAddDirectory(cchar *prefix, cchar *path)
	Add a directory to the directory lookup hash.
PUBLIC RName,*	rAddFmtName(RHash *hash, cchar *name, int flags, cchar *fmt, ...)
	Add a name and formatted string value into the hash table.
PUBLIC RName,*	rAddIntName(RHash *hash, cchar *name, int64 value)
	Add a name and integer value.
PUBLIC RName,*	rAddName(RHash *table, cchar *name, void *ptr, int flags)
	Add a name and value into the hash table.
PUBLIC RName,*	rAddNameSubstring(RHash *hash, cchar *name, ssize nameSize, char *value, ssize valueSize)
	Add a name and value substring into the hash table.
PUBLIC void,*	rAlloc(size_t size)
	Allocate a block of memory.
PUBLIC REvent	rAllocEvent(RFiber *fiber, REventProc proc, void *data, Ticks delay, int flags)
	Allocate and schedule a new event to be run from the event loop.
PUBLIC void	rAllocException(int cause, size_t size)
	Signal a memory allocation exception.
PUBLIC RFiber,*	rAllocFiber(cchar *name, RFiberProc fn, cvoid *data)
	Allocate a fiber coroutine object.
PUBLIC RHash,*	rAllocHash(int size, int flags)
	Create a hash table.
PUBLIC RLock,*	rAllocLock(void)
	Allocate a lock object.
PUBLIC RSocket,*	rAllocSocket(void)
	Allocate a socket object.
PUBLIC void,*	rAllocType(RType type)
	Allocate an object of a given type.
PUBLIC RWait,*	rAllocWait(int fd)
	Allocate a wait object for a file descriptor.
PUBLIC int	rBackupFile(cchar *path, int count)
	Backup the given file.
PUBLIC cchar,*	rBasename(cchar *path)
	Return the basename (filename) portion of a filename.
PUBLIC void	rBreakpoint(void)
	Trigger a breakpoint.
PUBLIC RHash,*	rCloneHash(RHash *master)
	Copy a hash table.
PUBLIC void	rCloseSocket(RSocket *sp)
	Close a socket.
PUBLIC int	rConnectSocket(RSocket *sp, cchar *host, int port, Ticks deadline)
	Connect a client socket.
PUBLIC ssize	rCopyFile(cchar *from, cchar *to, int mode)
	Copy a file.
PUBLIC int	rCreateThread(cchar *name, void *proc, void *data)
	Create an O/S thread.
PUBLIC int	rDaemonize(void)
	For the current process and run as a daemon.
PUBLIC char,*	rDirname(char *path)
	Return the directory name portion of a filename.
PUBLIC int	rEnter(bool *access, Ticks deadline)
	Enter a fiber critical section.
PUBLIC bool	rFileExists(cchar *path)
	Test if a file exists.
PUBLIC int	rFlushFile(int fd)
	Flush file buffers.
PUBLIC char,*	rFormatLocalTime(cchar *format, Time time)
	Convert a time value to local time and format as a string.
PUBLIC char,*	rFormatUniversalTime(cchar *format, Time time)
	Convert a time value to universal time and format as a string.
PUBLIC ssize	rFprintf(FILE *fp, cchar *fmt, ...)
	Formatted print to the standard error channel.
PUBLIC void	rFree(void *ptr)
	Free a block of memory allocated via rAlloc.
PUBLIC void	rFreeFiber(RFiber *fiber)
	Free a fiber coroutine.
PUBLIC void	rFreeHash(RHash *hash)
	Free a hash table.
PUBLIC void	rFreeLock(RLock *mutex)
	Free a dynamically allocated lock object.
PUBLIC void	rFreeSocket(RSocket *sp)
	Free a socket object.
PUBLIC void	rFreeWait(RWait *wp)
	Free a wait object.
PUBLIC char,*	rGetAppDir(void)
	Get the directory containing the application executable.
PUBLIC cchar,*	rGetAppName(void)
	Get the application name defined via rSetAppName.
PUBLIC RThread	rGetCurrentThread(void)
	Get the current Thread.
PUBLIC char,*	rGetCwd(void)
	Get the current application working directory.
PUBLIC char,*	rGetDate(cchar *format)
	Get a string representation of the current date/time.
PUBLIC Ticks	rGetElapsedTicks(Ticks mark)
	Get the elapsed time since a ticks mark.
PUBLIC cchar,*	rGetError(int error)
	Return a string representation of an R error code.
PUBLIC RFiber,*	rGetFiber(void)
	Get the current fiber object.
PUBLIC void,*	rGetFiberStack(void)
	Get the base address of the fiber stack.
PUBLIC char,*	rGetFilePath(cchar *path)
	Get a file path name.
PUBLIC ssize	rGetFileSize(cchar *path)
	Return the size of a file.
PUBLIC RList,*	rGetFiles(cchar *base, cchar *pattern, int flags)
	Create a list of files in a directory or subdirectories that match the given wildcard pattern.
PUBLIC RList,*	rGetFilesEx(RList *results, cchar *base, cchar *pattern, int flags)
	Get a list of files in a directory or subdirectories that match the given wildcard pattern.
PUBLIC int	rGetHashLength(RHash *hash)
	Return the count of symbols in a symbol entry.
uint64	rGetHiResTicks(void)
	Get the CPU tick count.
PUBLIC char,*	rGetIsoDate(Time time)
	Get an ISO Date string representation of the given date/time.
PUBLIC RThread	rGetMainThread(void)
	Get the main Thread.
PUBLIC RName,*	rGetNextName(RHash *hash, RName *next)
	Return the next symbol in a symbol entry.
PUBLIC int	rGetOsError(void)
	Return the native O/S error code.
PUBLIC Ticks	rGetRemainingTicks(Ticks mark, Ticks timeout)
	Return the time remaining until a timeout has elapsed.
PUBLIC cchar,*	rGetServerName(void)
	Get the application server name string.
PUBLIC int	rGetSocketAddr(RSocket *sp, char *ipbuf, int ipbufLen, int *port)
	Get the locally bound socket IP address and port for the socket.
PUBLIC RSocketCustom	rGetSocketCustom(void)
	Get the custom socket callback handler.
PUBLIC cchar,*	rGetSocketError(RSocket *sp)
	Get the socket error.
PUBLIC Socket	rGetSocketHandle(RSocket *sp)
	Get the socket file descriptor.
PUBLIC RWait,*	rGetSocketWait(RSocket *sp)
	Get the socket wait handler.
PUBLIC int	rGetState(void)
	Get the current R state.
PUBLIC char,*	rGetTempFile(cchar *dir, cchar *prefix)
	Get a temp filename.
PUBLIC Ticks	rGetTicks(void)
	Get the system time.
PUBLIC Time	rGetTime(void)
	Get the time.
PUBLIC bool	rGetTimeouts(void)
	Return true if timeouts are enabled.
PUBLIC int	rGetWaitFd(void)
	Get the global wait descriptor.
PUBLIC void	rGlobalLock(void)
	Globally lock the application.
PUBLIC void	rGlobalUnlock(void)
	Unlock the global mutex.
PUBLIC void	rGracefulStop(void)
	Gracefully stop the app.
PUBLIC RBuf,*	rHashToBuf(RHash *hash, cchar *join)
	Convert a hash of strings to a single string in a buffer.
PUBLIC char,*	rHashToJson(RHash *hash, int pretty)
	Convert a hash into JSON.
PUBLIC RBuf,*	rHashToJsonBuf(RHash *hash, RBuf *buf, int pretty)
	Convert a hash into JSON in the given buffer.
PUBLIC char,*	rHashToString(RHash *hash, cchar *join)
	Convert a hash of strings to a single string.
PUBLIC int	rInit(RFiberProc fn, cvoid *arg)
	Initialize the runtime.
PUBLIC int	rInitFibers(void)
	Initialize the fiber coroutine module.
PUBLIC int	rInitFile(void)
	Create and initialze the file subsystem.
PUBLIC RLock,*	rInitLock(RLock *mutex)
	Initialize a statically allocated lock object.
PUBLIC int	rInitOs(void)
	Create and initialze the O/S dependent subsystem.
PUBLIC int	rInitWait(void)
	Initialize the I/O wait subsystem.
PUBLIC bool	rIsFileAbs(cchar *path)
	Determine if a file path is an absolute path.
PUBLIC bool	rIsMain(void)
	Test if a fiber is the main fiber.
PUBLIC bool	rIsSocketClosed(RSocket *sp)
	Test if the socket has been closed.
PUBLIC bool	rIsSocketConnected(RSocket *sp)
	Determine if the socket has connected to a remote pper.
PUBLIC bool	rIsSocketEof(RSocket *sp)
	Test if the other end of the socket has been closed.
PUBLIC bool	rIsSocketSecure(RSocket *sp)
	Determine if the socket is secure.
PUBLIC char,*	rJoinFile(cchar *base, cchar *other)
	Join file paths.
PUBLIC char,*	rJoinFileBuf(char *buf, ssize bufsize, cchar *base, cchar *other)
	Join paths into a buffer.
PUBLIC void	rLeave(bool *access)
	Leave a fiber critical section.
PUBLIC int	rListenSocket(RSocket *sp, cchar *host, int port, RSocketProc handler, void *arg)
	Listen on a server socket for incoming connections.
PUBLIC void	rLock(RLock *lock)
	Lock access.
PUBLIC bool	rLookupEvent(REvent id)
	Lookup an event ID.
PUBLIC void,*	rLookupName(RHash *hash, cchar *name)
	Lookup a symbol in the hash table.
PUBLIC RName,*	rLookupNameEntry(RHash *hash, cchar *name)
	Lookup a symbol in the hash table and return the hash entry.
PUBLIC bool	rMatchFile(cchar *path, cchar *pattern)
	Matach a file against a glob pattern.
PUBLIC void,*	rMemdup(cvoid *ptr, size_t size)
	Duplicate a block of memory.
PUBLIC void	rMemoryBarrier(void)
	Perform a memory barrier where all queued writes are flushed to memory.
PUBLIC Time	rParseIsoDate(cchar *when)
	Parse an ISO date string.
PUBLIC ssize	rPrintf(cchar *fmt, ...)
	Formatted print.
PUBLIC char,*	rReadFile(cchar *path, ssize *lenp)
	Read data from a file.
PUBLIC ssize	rReadSocket(RSocket *sp, char *buf, ssize bufsize, Ticks deadline)
	Read from a socket.
PUBLIC ssize	rReadSocketSync(RSocket *sp, char *buf, ssize bufsize)
	Read from a socket.
PUBLIC void,*	rRealloc(void *ptr, size_t size)
	Allocate a block of memory.
PUBLIC int	rRemoveName(RHash *hash, cchar *name)
	Remove a symbol entry from the hash table.
PUBLIC void	rResetSocket(RSocket *sp)
	Reset a socket.
PUBLIC void,*	rResumeFiber(RFiber *fiber, void *result)
	Resume a fiber.
PUBLIC void	rResumeWait(RWait *wp, int mask)
	Release a waiting fiber waiting for an event.
PUBLIC char,*	rRun(cchar *command, int *status)
	Run a command using the system shell.
PUBLIC int	rRunEvent(REvent id)
	Run an event now.
PUBLIC Ticks	rRunEvents(void)
	Run due events.
PUBLIC int	rServiceEvents(void)
	Service events.
PUBLIC void	rSetFiberLimits(int maxFibers)
	Set the fiber limits.
PUBLIC void	rSetFiberStack(ssize size)
	Set the default fiber stack size.
PUBLIC void	rSetMemHandler(RMemProc handler)
	Define a global memory exhaustion handler.
PUBLIC void	rSetOsError(int error)
	Set the O/S error code.
PUBLIC void	rSetSocketBlocking(RSocket *sp, bool on)
	Set a socket into blocking I/O mode.
PUBLIC void	rSetSocketCerts(RSocket *sp, cchar *ca, cchar *key, cchar *cert, cchar *revoke)
	Configure the socket TLS certificates.
PUBLIC void	rSetSocketCiphers(RSocket *sp, cchar *ciphers)
	Set the ciphers to use for communications.
PUBLIC void	rSetSocketCustom(RSocketCustom custom)
	Set the socket custom configuration callback.
PUBLIC void	rSetSocketDefaultCerts(cchar *ca, cchar *key, cchar *cert, cchar *revoke)
	Configure the default TLS certificates.
PUBLIC void	rSetSocketDefaultCiphers(cchar *ciphers)
	Set the default TLS ciphers to use for communications.
PUBLIC void	rSetSocketDefaultVerify(int verifyPeer, int verifyIssuer)
	Set the default TLS verification parameters.
PUBLIC int	rSetSocketError(RSocket *sp, cchar *fmt, ...)
	Set the socket error message.
PUBLIC void	rSetSocketVerify(RSocket *sp, int verifyPeer, int verifyIssuer)
	Set the socket TLS verification parameters.
PUBLIC void	rSetSocketWaitMask(RSocket *sp, int64 mask, Ticks deadline)
	Update the wait mask for a socket.
PUBLIC void	rSetState(int state)
	Set the R state.
PUBLIC void	rSetTimeouts(bool on)
	Control timeouts.
PUBLIC void	rSetWaitHandler(RWait *wp, RWaitProc handler, cvoid *arg, int64 mask, Ticks deadline)
	Define a wait handler function on a wait object.
PUBLIC void	rSetWaitMask(RWait *wp, int64 mask, Ticks deadline)
	Update the wait mask for a wait handler.
PUBLIC void	rSignal(cchar *name, cvoid *arg)
	Signal watches of a named event.
PUBLIC void	rSignalSync(cchar *name, cvoid *arg)
	Signal watches of a named event synchronously (blocking).
PUBLIC void	rSleep(Ticks ticks)
	Sleep a fiber for the requested number of milliseconds.
PUBLIC char,*	rSnprintf(char *buf, ssize maxsize, cchar *fmt, ...)
	Format a string into a buffer.
PUBLIC int	rSpawnFiber(cchar *name, RFiberProc fn, void *arg)
	Spawn a fiber coroutine.
PUBLIC void,*	rSpawnThread(RThreadProc fn, void *arg)
	Spawn an O/S thread and wait until it completes.
PUBLIC REvent	rStartEvent(REventProc proc, void *data, Ticks delay)
	Start a callback event.
PUBLIC void	rStartFiber(RFiber *fiber, void *data)
	Start a fiber coroutine.
PUBLIC void	rStop(void)
	Immediately stop the app.
PUBLIC int	rStopEvent(REvent id)
	Stop an event.
PUBLIC void	rTermFibers(void)
	Terminate the fiber coroutine module.
PUBLIC void	rTermFile(void)
	Stop the file subsystem.
PUBLIC void	rTermLock(RLock *mutex)
	Terminate a statically allocated lock object.
PUBLIC void	rTermOs(void)
	Stop the O/S dependent subsystem.
PUBLIC void	rTermWait(void)
	Terminate the I/O wait subsystem.
PUBLIC bool	rTryLock(RLock *lock)
	Attempt to lock access.
PUBLIC void	rUnlock(RLock *lock)
	Unlock a mutex.
PUBLIC char,*	rVsnprintf(char *buf, ssize maxsize, cchar *fmt, va_list args)
	Format a string into a buffer.
PUBLIC int	rWait(Ticks timeout)
	Wait for an I/O event.
PUBLIC int	rWaitForIO(RWait *wp, int mask, Ticks deadline)
	Wait for an IO event on a wait object.
PUBLIC void	rWakeup(void)
	Wakeup the event loop.
PUBLIC int	rWalkDir(cchar *dir, cchar *pattern, RWalkDirProc callback, void *arg, int flags)
	Walk a directory tree and invoke a callback for each path that matches a given pattern.
PUBLIC void	rWatch(cchar *name, RWatchProc proc, void *data)
	Watch for a named event to happen.
PUBLIC void	rWatchOff(cchar *name, RWatchProc proc, void *data)
	Stop watching for a named event to happen.
PUBLIC ssize	rWriteFile(cchar *path, cchar *buf, ssize len, int mode)
	Write data to a file.
PUBLIC int	rWritePid(void)
	Write the current process pid to /var/run.
PUBLIC ssize	rWriteSocket(RSocket *sp, cvoid *buf, ssize bufsize, Ticks deadline)
	Write to a socket.
PUBLIC ssize	rWriteSocketSync(RSocket *sp, cvoid *buf, ssize len)
	Write to a socket.
PUBLIC void,*	rYieldFiber(void *value)
	Yield a fiber back to the main fiber.
PUBLIC RbTree,*	rbAlloc(int flags, RbCompare compare, RbFree free, void *arg)
	Allocate a red/black tree.
PUBLIC RbNode,*	rbFirst(RbTree *rbt)
	Return the lexically first node.
PUBLIC void	rbFree(RbTree *rbt)
	Free a red/black tree.
PUBLIC RbNode,*	rbInsert(RbTree *rbt, void *data)
	Insert a new data item in the tree.
PUBLIC RbNode,*	rbLookup(RbTree *rbt, cvoid *data, void *ctx)
	Lookup a data item.
PUBLIC RbNode,*	rbLookupFirst(RbTree *rbt, cvoid *data, void *ctx)
	Return the lexically first matching node.
PUBLIC RbNode,*	rbLookupNext(RbTree *rbt, RbNode *node, cvoid *data, void *ctx)
	Return the next matching node after the given node.
PUBLIC RbNode,*	rbNext(RbTree *rbt, RbNode *node)
	Return the next node in sequence.
PUBLIC void,*	rbRemove(RbTree *rbt, RbNode *node, int keep)
	Remove a data item from the tree.
PUBLIC char,*	scamel(cchar *str)
	Create a camel case version of the string.
PUBLIC int	scaselesscmp(cchar *s1, cchar *s2)
	Compare strings ignoring case.
PUBLIC bool	scaselessmatch(cchar *s1, cchar *s2)
	Compare strings ignoring case.
PUBLIC char,*	schr(cchar *str, int c)
	Find a character in a string.
PUBLIC char,*	sclone(cchar *str)
	Clone a string.
PUBLIC char,*	scloneNull(cchar *str)
	Clone a string and preserve NULLs.
PUBLIC int	scmp(cchar *s1, cchar *s2)
	Compare strings.
PUBLIC char,*	scontains(cchar *str, cchar *pattern)
	Find a pattern in a string.
PUBLIC ssize	scopy(char *dest, ssize destMax, cchar *src)
	Copy a string.
PUBLIC cchar,*	sends(cchar *str, cchar *suffix)
	Test if the string ends with a given pattern.
PUBLIC char,*	sfmt(cchar *fmt, ...)
	Format a string.
PUBLIC char,*	sfmtbuf(char *buf, ssize maxSize, cchar *fmt, ...)
	Format a string into a static buffer.
PUBLIC char,*	sfmtbufv(char *buf, ssize maxSize, cchar *fmt, va_list args)
	Format a string into a statically allocated buffer.
PUBLIC char,*	sfmtv(cchar *fmt, va_list args)
	Format a string.
PUBLIC uint	shash(cchar *str, ssize len)
	Compute a hash code for a string.
PUBLIC uint	shashlower(cchar *str, ssize len)
	Compute a caseless hash code for a string.
PUBLIC char,*	sitos(int64 value)
	Convert an integer to a string.
PUBLIC char,*	sitosbuf(char *buf, ssize size, int64 value, int radix)
	Convert an integer to a string buffer.
PUBLIC char,*	sitosradix(int64 value, int radix)
	Convert an integer to a string.
PUBLIC char,*	sjoin(cchar *str, ...)
	Catenate strings.
PUBLIC char,*	sjoinArgs(int argc, cchar **argv, cchar *sep)
	Join an array of strings.
PUBLIC ssize	sjoinbuf(char *buf, ssize bufsize, cchar *str1, cchar *str2)
	Catenate strings into a buffer.
PUBLIC char,*	sjoinfmt(cchar *str, cchar *fmt, ...)
	Join a formatted string to an existing string.
PUBLIC char,*	sjoinv(cchar *str, va_list args)
	Catenate strings.
PUBLIC ssize	slen(cchar *str)
	Return the length of a string.
PUBLIC char,*	slower(char *str)
	Convert a string to lower case.
PUBLIC bool	smatch(cchar *s1, cchar *s2)
	Compare strings.
PUBLIC int	sncaselesscmp(cchar *s1, cchar *s2, ssize len)
	Compare strings ignoring case.
PUBLIC char,*	sncaselesscontains(cchar *str, cchar *pattern, ssize limit)
	Find a pattern in a string with a limit using a caseless comparison.
PUBLIC char,*	snclone(cchar *str, ssize len)
	Clone a substring.
PUBLIC int	sncmp(cchar *s1, cchar *s2, ssize len)
	Compare strings.
PUBLIC char,*	sncontains(cchar *str, cchar *pattern, ssize limit)
	Find a pattern in a string with a limit.
PUBLIC ssize	sncopy(char *dest, ssize destMax, cchar *src, ssize len)
	Copy characters from a string.
PUBLIC char,*	spbrk(cchar *str, cchar *set)
	Locate the a character from a set in a string.
PUBLIC char,*	sptok(char *str, cchar *pattern, char **nextp)
	Tokenize a string.
PUBLIC char,*	srchr(cchar *str, int c)
	Find a character in a string by searching backwards.
PUBLIC char,*	srejoin(char *buf, ...)
	Append strings to an existing string and reallocate as required.
PUBLIC char,*	srejoinv(char *buf, va_list args)
	Append strings to an existing string and reallocate as required.
PUBLIC char,*	ssplit(char *str, cchar *delim, char **last)
	Split a string at a delimiter.
PUBLIC ssize	sspn(cchar *str, cchar *set)
	Find the end of a spanning prefix.
PUBLIC bool	sstarts(cchar *str, cchar *prefix)
	Test if the string starts with a given pattern.
PUBLIC char,*	ssub(cchar *str, ssize offset, ssize length)
	Create a substring.
PUBLIC char,*	stemplate(cchar *str, void *tokens)
	Replace template tokens in a string with values from a lookup table.
PUBLIC char,*	stitle(cchar *str)
	Create a Title Case version of the string.
PUBLIC double	stod(cchar *str)
	Convert a string to a double floating point value.
PUBLIC double	stof(cchar *str)
	Convert a string to a double.
PUBLIC int64	stoi(cchar *str)
	Convert a string to an integer.
PUBLIC int64	stoiradix(cchar *str, int radix, int *err)
	Convert a string to an integer.
PUBLIC char,*	stok(char *str, cchar *delim, char **last)
	Tokenize a string.
PUBLIC struct,RList,*	stolist(cchar *src)
	String to list.
PUBLIC char,*	strim(char *str, cchar *set, int where)
	Trim a string.
PUBLIC char,*	supper(char *str)
	Convert a string to upper case.
PUBLIC uint64	svalue(cchar *value)
	Parse a value string.
PUBLIC void	szero(char *str)
	Erase the contents of a string.

Typedef Index

REvent	Event Subsystem.
REventProc	Callback function for events.
RFiber	Fiber state.
RFiberProc	Fiber entry point function.
RFile	R File Module.
RHash	Hash table structure.
RHashProc	Hashing function to use for the table.
RLock	Multithreading lock control structure.
RMemProc	Memory exhaustion callback procedure.
RName	Per item structure.
RString	R String Module.
RThreadProc	Thread entry point function.
RWait	Wait object.
RWaitProc	Callback function for IO wait events.
RWalkDirProc	Callback function for rWalkDir.
RWatchProc	Callback function for watched events.
RbCompare	Callback to compare a data nodes.
RbFree	Callback to free a nodes associated data.
Socket	Argument for sockets.
size_t	Unsigned integral type.
time_t	Unsigned time type.

Defines

#define	ITERATE_INDEX    node = rbLookupFirst(rbt, data, ctx); node; node = rbLookupNext(rbt, node, \ data, ctx)
	Traverse an index over matching nodes.
#define	ITERATE_TREE   node = rbFirst(rbt); node; node = rbNext(rbt, node)
#define	R_DEFAULT_DATE   "%a %b %d %T %Y %Z"
	Default date format used in rFormatLocalTime/rFormatUniversalTime when no format supplied E.g.
#define	R_DYNAMIC_NAME   0x8
	Dynamic name provided, hash will free.
#define	R_DYNAMIC_VALUE   0x1
	Dynamic (allocated) value provided, hash/list will free.
#define	R_EVENT_ASYNC   1
	Windows async select.
#define	R_EVENT_EPOLL   2
	epoll_wait.
#define	R_EVENT_FAST   0x1
	Fast event flag - must not block and runs off main fiber.
#define	R_EVENT_KQUEUE   3
	BSD kqueue.
#define	R_EVENT_SELECT   4
	traditional select().
#define	R_HASH_CASELESS   0x40
	Ignore case in comparisons.
#define	R_IO   0x6
	Wait mask for readable or writeable events.
#define	R_MEM_FAIL   0x4
	Memory allocation failed - immediate exit.
#define	R_MEM_LIMIT   0x2
	Memory use exceeds memory limit - invoking policy.
#define	R_MEM_STACK   0x10
	Too many fiber stack.
#define	R_MEM_TOO_BIG   0x8
	Memory allocation request is too big - immediate exit.
#define	R_MEM_WARNING   0x1
	Memory use exceeds warnHeap level limit.
#define	R_MODIFIED   0x200
	Wait mask for modify events.
#define	R_READABLE   0x2
	Wait mask for readable events.
#define	R_SOCKET_CLOSED   0x1
	RSocket has been closed.
#define	R_SOCKET_CONFIG_TLS   1
	Custom callback to configure TLS.
#define	R_SOCKET_EOF   0x2
	Seen end of file.
#define	R_SOCKET_LISTENER   0x4
	RSocket is server listener.
#define	R_SOCKET_SERVER   0x8
	Socket is on the server-side.
#define	R_STATIC_NAME   0x10
	Static name provided no need to clone or free.
#define	R_STATIC_VALUE   0x2
	Static value provided, no need to clone or free.
#define	R_TEMPORAL_NAME   0x20
	Temporal name provided, hash will clone and free.
#define	R_TEMPORAL_VALUE   0x4
	Temporal value provided, hash/list will clone and free.
#define	R_TIMEOUT   0x400
	Wait mask for timeout.
#define	R_TLS_HAS_AUTHORITY   0x1
	Signal to the custom callback that authority certs are available.
#define	R_TRIM_BOTH   0x3
	Flag for strim to trim from both the start and the end of the string.
#define	R_TRIM_END   0x2
	Flag for strim to trim from the end of the string.
#define	R_TRIM_START   0x1
	Flag for strim to trim from the start of the string.
#define	R_WALK_DEPTH_FIRST   0x1
	Flag for rGetFiles to do a depth-first traversal.
#define	R_WALK_DIRS   0x4
	Include hidden files starting with "." except for "." and "..".
#define	R_WALK_FILES   0x8
	Include hidden files starting with "." except for "." and "..".
#define	R_WALK_HIDDEN   0x2
	Include hidden files starting with "." except for "." and "..".
#define	R_WALK_MISSING   0x20
	Allow walking missing paths.
#define	R_WALK_RELATIVE   0x10
	Return paths relative to the original path.
#define	R_WRITABLE   0x4
	Wait mask for writable events.
#define	RB_DUP   0x1
	Flags for rbAlloc to permit duplicate keys.

Typedefs

typedef int(* RbCompare) (cvoid *n1, cvoid *n2, cvoid *ctx)

Callback to compare a data nodes.

Description:

The comparison function may perform a simple "strcmp" style comparison function or it may perform a modified comparison using the supplied context information. For example: a comparison could perform a "startsWith" style comparison. The context argument can control the type of comparison that is performed.

Parameters:

n1	Reference to first item.
n2	Reference to item to compare.
ctx	Context provided to rbLookup.

Returns:

Return -1 if n1 is lexically less than n2. Zero if equal and 1 if n1 is greater than n2.

API Stability:

Evolving.

typedef void(* RbFree) (void *arg, void *data)

Callback to free a nodes associated data.

Parameters:

data	Reference to the associated data for a node.

API Stability:

Evolving.

typedef int64 REvent

Event Subsystem.

Description:

R provides a simple based eventing mechanism. Events are described by REvent objects which are created and queued via rStartEvent. Events are scheduled once unless restarted via rRestartEvent.

API Stability:

Internal.

typedef void(* REventProc) (void *data)

Callback function for events.

Parameters:

data	Opaque data argument.

API Stability:

Evolving.

typedef void(* RFiberProc) (void *data)

Fiber entry point function.

Parameters:

data	Custom function argument.

API Stability:

Evolving.

typedef uint(* RHashProc) (cvoid *name, ssize len)

Hashing function to use for the table.

Parameters:

name	Name to hash.
len	Length of the name to hash.

Returns:

An integer hash index.

API Stability:

Internal.

typedef void(* RMemProc) (int cause, size_t size)

Memory exhaustion callback procedure.

Parameters:

cause	The cause of the memory failure.
size	The size of the failing block allocation.

typedef void *(* RThreadProc) (void *data)

Thread entry point function.

Parameters:

data	Custom function argument.

Returns:

Value to pass back from rSpawnThread.

API Stability:

Evolving.

typedef void(* RWaitProc) (cvoid *data, int mask)

Callback function for IO wait events.

Parameters:

data	Opaque data argument.
mask	IO event selection mask.

API Stability:

Evolving.

typedef int(* RWalkDirProc) (void *arg, cchar *path, int flags)

Callback function for rWalkDir.

Parameters:

arg	Argument supplied to rWalkDir.
path	Current filename path to walk.
flags	Flags supplied to rWalkDir.

API Stability:

Evolving.

typedef void(* RWatchProc) (cvoid *data, cvoid *arg)

Callback function for watched events.

Parameters:

data	Opaque data argument supplied via rWatchEvent.
arg	Watched event arg passed via rSignal.

API Stability:

Evolving.

typedef long size_t

Unsigned integral type.

Equivalent in size to void*

typedef int Socket

Argument for sockets.

typedef unsigned long time_t

Unsigned time type.

Time in seconds since Jan 1, 1970

RFiber

Fiber state.

API Stability:

Evolving.

Fields:

RFile

R File Module.

See Also:

Fields:

API Stability:

Internal.

RHash

Hash table structure.

Description:

The hash structure supports growable hash tables collision resistant hashes.

Fields:

int *	buckets	Hash collision bucket table.
uint	flags	Hash control flags.
RHashProc	fn	Hash function.
int	free	Free list of names.
uint	length	Number of names in the hash.
struct RName *	names	Hash items.
uint	numBuckets	Number of buckets in the first-level hash.
uint	size	Size of allocated names.

See Also:

RName

API Stability:

Evolving.

RLock

Multithreading lock control structure.

Description:

RLock is used for multithread locking in multithreaded applications.

Fields:

API Stability:

Evolving.

RName

Per item structure.

Fields:

uint	custom	Custom data bits.
uint	flags	Name was allocated.
char *	name	Hash name.
int	next	Next name in hash chain or next free if on free list.
void *	value	Pointer to data.

RString

R String Module.

Description:

The RT provides a suite of r ascii string manipulation routines to help prevent buffer overflows and other potential security traps.

Fields:

See Also:

API Stability:

Internal.

RWait

Wait object.

Description:

The RWait service provides a flexible IO waiting mechansim.

Fields:

cvoid *	arg	Argument to pass to the handler.
Ticks	deadline	System deadline time to wait until.
int	fd	File descriptor to wait upon.
RFiber *	fiber	Current fiber for rWaitForIO.
RWaitProc	handler	Handler function to invoke as the entrypoint in the fiber coroute.
int	mask	Current event mask.

API Stability:

Evolving.

Functions

PUBLIC void assert (bool cond)

Asser that a condition is true.

Parameters:

cond	Boolean result of a conditional test.

API Stability:

Evolving.

PUBLIC int rAccessFile (cchar *path, int mode)

Test if a file can be accessed with the given mode (F_OK, R_OK, W_OK, X_OK).

Parameters:

path	Filename to read.
mode	Set to F_OK, R_OK, W_OK, or X_OK.

Returns:

Zero if successful, otherwise a negative value.

API Stability:

Evolving.

PUBLIC void rAddDirectory (cchar *prefix, cchar *path)

Add a directory to the directory lookup hash.

Parameters:

prefix	The directory prefix name.
path	The corresponding directory.

API Stability:

Evolving.

PUBLIC RName,* rAddFmtName (RHash *hash, cchar *name, int flags, cchar *fmt, ...)

Add a name and formatted string value into the hash table.

Description:

Associate an arbitrary value with a string name and inser into the hash table.

Parameters:

hash	Hash table returned via rAllocHash.
name	String name to associate with the data.
flags	Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. If flags are zero, the flags provided to rAllocHash are used.
fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:

Added RName reference.

API Stability:

Evolving.

PUBLIC RName,* rAddIntName (RHash *hash, cchar *name, int64 value)

Add a name and integer value.

Parameters:

hash	Hash table returned via rAllocHash.
name	String name to associate with the data.
value	A 64 bit integer value.

Returns:

Added RName reference.

API Stability:

Evolving.

PUBLIC RName,* rAddName (RHash *table, cchar *name, void *ptr, int flags)

Add a name and value into the hash table.

Description:

Associate an arbitrary value with a string name and inser into the hash table.

Parameters:

table	Hash table returned via rAllocHash.
name	String name to associate with the data.
ptr	Arbitrary pointer to associate with the name in the table.
flags	Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. If flags are zero, the flags provided to rAllocHash are used.

Returns:

Added RName reference.

API Stability:

Evolving.

PUBLIC RName,* rAddNameSubstring (RHash *hash, cchar *name, ssize nameSize, char *value, ssize valueSize)

Add a name and value substring into the hash table.

Description:

Associate an arbitrary value with a string name and inser into the hash table. The flags used are: R_DYNAMIC_NAME | R_DYNAMIC_VALUE.

Parameters:

hash	Hash table returned via rAllocHash.
name	String name to associate with the data.
nameSize	Size of the name string.
value	Value string to store.
valueSize	Length of string value.

Returns:

Added RName reference.

API Stability:

Evolving.

PUBLIC void,* rAlloc (size_t size)

Allocate a block of memory.

Description:

This is the lowest level of memory allocation routine. Memory is freed via rFree.

Parameters:

size	Size of the memory block to allocate.

Returns:

Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler will be invoked.

Remarks:

Do not mix calls to rAlloc and malloc.

API Stability:

Evolving.

PUBLIC REvent rAllocEvent (RFiber *fiber, REventProc proc, void *data, Ticks delay, int flags)

Allocate and schedule a new event to be run from the event loop.

Description:

Allocate an event to run a callback via the event loop. The safe runtime (R) is not THREAD SAFE in general. A few APIs are THREAD SAFE to enable data interchange between R and foreign threads.

This API is THREAD SAFE and may be called by foreign threads provided the caller supplies a proc function and ensures the fiber is still valid. This routine is the ONLY safe way to invoke R services from a foreign-thread.

Parameters:

fiber	Fiber object.
proc	Function to invoke when the event is run.
data	Data to associate with the event and stored in event->data.
delay	Time in milliseconds used by continuous events between firing of the event.
flags	Set to R_EVENT_FAST for a "faster" event. Fast events must not block or yield as they run directly off the main service fiber.

Returns:

The event object. If called from a foreign thread, note that the event may have already run n return.

API Stability:

Internal.

PUBLIC void rAllocException (int cause, size_t size)

Signal a memory allocation exception.

Description:

R uses a global memory allocaction error handler. If doing direct malloc() allocations that fail, call this routine to signal the memory failure and run the allocation handler.

Parameters:

cause	Set to R_MEM_WARNING, R_MEM_LIMIT, R_MEM_FAIL or R_MEM_TO_BIG.
size	Size in bytes of the failing allocation.

API Stability:

Evolving.

PUBLIC RFiber,* rAllocFiber (cchar *name, RFiberProc fn, cvoid *data)

Allocate a fiber coroutine object.

Description:

This allocates a new fiber coroutine. Use rStartFiber to launch.

Parameters:

name	Fiber name.
fn	Fiber entry point.
data	Entry point argument.

Returns:

A fiber object.

API Stability:

Internal.

PUBLIC RHash,* rAllocHash (int size, int flags)

Create a hash table.

Description:

Creates a hash table that can store arbitrary objects associated with string names.

Parameters:

size

Estimated number of names in the hash table. Set to 0 or -1 to get a default (small) hash table.

flags

Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. Set to R_TEMPORAL_VALUE when providing a string value that the hash must clone and free. Set to R_HASH_CASELESS for case insensitive matching for names. The default flags is: R_STATIC_NAME | R_STATIC_VALUE.

Returns:

Returns a pointer to the allocated hash table.

API Stability:

Evolving.

PUBLIC RLock,* rAllocLock (void )

Allocate a lock object.

Description:

This call creates a lock object that can be used in rLock rTryLock and rUnlock calls. This routine is THREAD SAFE.

API Stability:

Evolving.

PUBLIC RSocket,* rAllocSocket (void )

Allocate a socket object.

Returns:

A socket object instance.

API Stability:

Evolving.

PUBLIC void,* rAllocType (RType type)

Allocate an object of a given type.

Description:

Allocates a zeroed block of memory large enough to hold an instance of the specified type.

Parameters:

type	RType of the object to allocate.

Returns:

Returns a pointer to the allocated block. If memory is not available the memory allocation handler will be invoked.

API Stability:

Evolving.

PUBLIC RWait,* rAllocWait (int fd)

Allocate a wait object for a file descriptor.

Parameters:

fd	File descriptor.

Returns:

A RWait object.

API Stability:

Evolving.

PUBLIC int rBackupFile (cchar *path, int count)

Backup the given file.

Description:

This creates backup copies of the file using the form: filename-d.ext.

Parameters:

path	Filename to backup.
count	Number of backup copies to keep.

API Stability:

Evolving.

PUBLIC RbTree,* rbAlloc (int flags, RbCompare compare, RbFree free, void *arg)

Allocate a red/black tree.

Parameters:

flags	Set to RB_DUP if you wish to store duplicate nodes.
compare	Callback to compare two nodes.
free	Callback to free a node's item data.
arg	Arg to pass to callback.

Returns:

An RbTree instance.

API Stability:

Evolving.

PUBLIC cchar,* rBasename (cchar *path)

Return the basename (filename) portion of a filename.

Parameters:

path	Filename to examine.

Returns:

A pointer to the basename portion of the supplied filename path. This call does not allocate a new string.

API Stability:

Evolving.

PUBLIC RbNode,* rbFirst (RbTree *rbt)

Return the lexically first node.

Parameters:

rbt	RbTree allocated via rbAlloc.

Returns:

The first node.

API Stability:

Evolving.

PUBLIC void rbFree (RbTree *rbt)

Free a red/black tree.

Parameters:

rbt	RbTree to free. Allocated via rbAlloc.

API Stability:

Evolving.

PUBLIC RbNode,* rbInsert (RbTree *rbt, void *data)

Insert a new data item in the tree.

Parameters:

rbt	RbTree allocated via rbAlloc.
data	User data to store in the tree. The data should contain the lookup key value for the data. The comparison callback will be passed the data and it should be able to extract the key from the data.

Returns:

The inserted node.

API Stability:

Evolving.

PUBLIC RbNode,* rbLookup (RbTree *rbt, cvoid *data, void *ctx)

Lookup a data item.

Parameters:

rbt	RbTree allocated via rbAlloc.
data	User data item to search for. This is passed to the comparison callback supplied when calling rbOpen.
ctx	Context to provide to the comparison callback.

Returns:

The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.

API Stability:

Evolving.

PUBLIC RbNode,* rbLookupFirst (RbTree *rbt, cvoid *data, void *ctx)

Return the lexically first matching node.

Parameters:

rbt	RbTree allocated via rbAlloc.
data	User data item to search for. This is passed to the comparison callback supplied when calling rbOpen.
ctx	Context to provide to the comparison callback.

Returns:

The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.

API Stability:

Evolving.

PUBLIC RbNode,* rbLookupNext (RbTree *rbt, RbNode *node, cvoid *data, void *ctx)

Return the next matching node after the given node.

Description:

This call finds the next matching node after the current node. It is assumed that the given node matches the supplied user data.

Parameters:

rbt	RbTree allocated via rbAlloc.
node	Starting node for the search.
data	User data item to search for. This is passed to the comparison callback supplied when calling rbOpen.
ctx	Context to provide to the comparison callback.

Returns:

The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.

API Stability:

Evolving.

PUBLIC RbNode,* rbNext (RbTree *rbt, RbNode *node)

Return the next node in sequence.

Parameters:

rbt	RbTree allocated via rbAlloc.
node	Starting node.

Returns:

The next node in the tree.

API Stability:

Evolving.

PUBLIC void rBreakpoint (void )

Trigger a breakpoint.

Description:

This routine is invoked for asserion errors from rAssert and errors from rError. It is useful in debuggers as breakpoint location for detecting errors.

API Stability:

Evolving.

PUBLIC void,* rbRemove (RbTree *rbt, RbNode *node, int keep)

Remove a data item from the tree.

Parameters:

rbt	RbTree allocated via rbAlloc.
node	Node to remove. The node is identified by calling rbLookup.
keep	If true, the data item will not be freed. Otherwise the free callback will be invoked on the data item.

Returns:

The node data item.

API Stability:

Evolving.

PUBLIC RHash,* rCloneHash (RHash *master)

Copy a hash table.

Parameters:

master

Original hash table.

Returns:

Returns a pointer to the new allocated hash table.

API Stability:

Evolving.

PUBLIC void rCloseSocket (RSocket *sp)

Close a socket.

Description:

Close a socket.

Parameters:

sp	Socket object returned from rAllocSocket.

API Stability:

Evolving.

PUBLIC int rConnectSocket (RSocket *sp, cchar *host, int port, Ticks deadline)

Connect a client socket.

Description:

Open a client connection. May be called from a fiber or from main.

If using TLS, this must only be called from a fiber.

Parameters:

sp	Socket object returned via rAllocSocket.
host	Host or IP address to connect to.
port	TCP/IP port number to connect to.
deadline	Maximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a deadline. Set to 0 for no deadline.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC ssize rCopyFile (cchar *from, cchar *to, int mode)

Copy a file.

Description:

Copy a file to a destination path.

Parameters:

from	Source file name.
to	Destination file name.
mode	Posix file mode on created file.

Returns:

Number of bytes copied or negative error code.

API Stability:

Evolving.

PUBLIC int rCreateThread (cchar *name, void *proc, void *data)

Create an O/S thread.

Parameters:

name	Descriptive name for the thread.
proc	Thread main function to invoke.
data	Argument to proc.

API Stability:

Evolving.

PUBLIC int rDaemonize (void )

For the current process and run as a daemon.

API Stability:

Evolving.

PUBLIC char,* rDirname (char *path)

Return the directory name portion of a filename.

Description:

This trims off the basename portion of the path by modifying the supplied path.

Parameters:

path	Filename to examine and modify.

Returns:

A pointer to the dirname portion of the supplied filename path. This call does not allocate a new string and the caller must not free.

API Stability:

Evolving.

PUBLIC int rEnter (bool *access, Ticks deadline)

Enter a fiber critical section.

Description:

This routine supports fiber critical sections where a fiber can sleep and ensure no other fiber executes the routine at the same time. The second and subsequent fibers will yield on this call until the first fiber leaves the critical section.

Parameters:

access	Pointer to a boolean initialized to false.
deadline	Time in ticks to wait for access. Set to zero for an infinite wait.

Returns:

Zero if access is granted.

API Stability:

Prototype.

PUBLIC bool rFileExists (cchar *path)

Test if a file exists.

Parameters:

path	Filename to test.

Returns:

True if the file exists.

API Stability:

Evolving.

PUBLIC int rFlushFile (int fd)

Flush file buffers.

Parameters:

fd	O/S file descriptor.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC char,* rFormatLocalTime (cchar *format, Time time)

Convert a time value to local time and format as a string.

Description:

R replacement for ctime.

Parameters:

format	Time format string. See rFormatUniversalTime for time formats.
time	Time to format. Use rGetTime to retrieve the current time.

Returns:

The formatting time string. Caller msut free.

API Stability:

Evolving.

PUBLIC char,* rFormatUniversalTime (cchar *format, Time time)

Convert a time value to universal time and format as a string.

Description:

Format a time string. This uses strftime if available and so the supported formats vary from platform to platform. Strftime should supports some of these these formats described below.

Parameters:

format

Time format string A ... full weekday name (Monday) a ... abbreviated weekday name (Mon) B ... full month name (January) b ... abbreviated month name (Jan) C ... century. Year / 100. (0-N) c ... standard date and time representation D ... date (m/d/y) d ... day-of-month (01-31) e ... day-of-month with a leading space if only one digit ( 1-31) F ... same as Y-m-d H ... hour (24 hour clock) (00-23) h ... same as b I ... hour (12 hour clock) (01-12) j ... day-of-year (001-366) k ... hour (24 hour clock) (0-23) l ... the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank. M ... minute (00-59) m ... month (01-12) n ... a newline P ... lower case am / pm p ... AM / PM R ... same as H:M r ... same as H:M:S p S ... second (00-59) s ... seconds since epoch T ... time (H:M:S) t ... a tab. U ... week-of-year, first day sunday (00-53) u ... the weekday (Monday as the first day of the week) as a decimal number (1-7). v ... is equivalent to `e-b-Y'. W ... week-of-year, first day monday (00-53) w ... weekday (0-6, sunday is 0) X ... standard time representation x ... standard date representation Y ... year with century y ... year without century (00-99) Z ... timezone name z ... offset from UTC (-hhmm or +hhmm) %+ ... national representation of the date and time (the format is similar to that produced by date(1)). %% ... percent sign Some platforms may also support the following format extensions: E* ... POSIX locale extensions. Where "*" is one of the characters: c, C, x, X, y, Y. G ... a year as a decimal number with century. This year is the one that contains the greater par of the week (Monday as the first day of the week). g ... the same year as in `G', but as a decimal number without century (00-99). O* ... POSIX locale extensions. Where "*" is one of the characters: d, e, H, I, m, M, S, u, U, V, w, W, y. Additionly OB implemented to represent alternative months names (used standalone, without day mentioned). V ... the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1. Useful formats: RFC822: "%a, %d %b %Y %H:%M:%S %Z "Fri, 07 Jan 2003 12:12:21 PDT" \n "T F "12:12:21 2007-01-03" "%v "07-Jul-2003" \n RFC3399: "FTTZ" "1985-04-12T23:20:50.52Z" which is April 12 1985, 23:20.50 and 52 msec

time

Time to format. Use rGetTime to retrieve the current time.

Returns:

The formatting time string. Caller must free.

API Stability:

Evolving.

PUBLIC ssize rFprintf (FILE *fp, cchar *fmt, ...)

Formatted print to the standard error channel.

Description:

This is a secure replacement for fprintf. It can handle null arguments without crashes.

Parameters:

fp	File handle.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:

The number of bytes written.

API Stability:

Evolving.

PUBLIC void rFree (void *ptr)

Free a block of memory allocated via rAlloc.

Description:

This releases a block of memory allocated via rAllocMem.

Parameters:

ptr	Pointer to the block. If ptr is null, the call is skipped.

Remarks:

The rFree routine is a macro over rFreeMem. Do not mix calls to rFreeMem and free.

API Stability:

Evolving.

PUBLIC void rFreeFiber (RFiber *fiber)

Free a fiber coroutine.

Description:

The fiber must have already completed before invoking this routine. This routine is typically only called internally by the fiber module.

Parameters:

fiber

Fiber to free.

API Stability:

Internal.

PUBLIC void rFreeHash (RHash *hash)

Free a hash table.

Parameters:

hash	Hash table to free.

API Stability:

Evolving.

PUBLIC void rFreeLock (RLock *mutex)

Free a dynamically allocated lock object.

Description:

This routine is THREAD SAFE.

Parameters:

mutex

Reference to an RLock structure to initialize.

API Stability:

Evolving.

PUBLIC void rFreeSocket (RSocket *sp)

Free a socket object.

API Stability:

Evolving.

PUBLIC void rFreeWait (RWait *wp)

Free a wait object.

Parameters:

wp	RWait object.

API Stability:

Evolving.

PUBLIC char,* rGetAppDir (void )

Get the directory containing the application executable.

Returns:

An allocated string containing the application directory. Caller must free.

API Stability:

Evolving.

PUBLIC cchar,* rGetAppName (void )

Get the application name defined via rSetAppName.

Returns:

The one-word lower case application name defined via rSetAppName.

API Stability:

Evolving.

PUBLIC RThread rGetCurrentThread (void )

Get the current Thread.

Description:

This routine is THREAD SAFE.

Returns:

The currently executing thread.

API Stability:

Evolving.

PUBLIC char,* rGetCwd (void )

Get the current application working directory.

Returns:

An allocated string containing the working directory. Caller must free.

API Stability:

Evolving.

PUBLIC char,* rGetDate (cchar *format)

Get a string representation of the current date/time.

Description:

Get the current date/time as a string according to the given format.

Parameters:

format

Date formatting string. See strftime for acceptable date format specifiers. If null, then this routine uses the R_DEFAULT_DATE format.

Returns:

A date string. Caller must free.

API Stability:

Evolving.

PUBLIC Ticks rGetElapsedTicks (Ticks mark)

Get the elapsed time since a ticks mark.

Create the ticks mark with rGetTicks()

Parameters:

mark	Staring time stamp.

Returns:

The time elapsed since the mark was taken.

API Stability:

Evolving.

PUBLIC cchar,* rGetError (int error)

Return a string representation of an R error code.

Parameters:

error

An R error code. These codes are always negative for errors and zero for R_OK.

Returns:

A static string error representation.

API Stability:

Evolving.

PUBLIC RFiber,* rGetFiber (void )

Get the current fiber object.

Returns:

Fiber Fiber object.

API Stability:

Evolving.

PUBLIC void,* rGetFiberStack (void )

Get the base address of the fiber stack.

Returns:

A pointer to the base of the fiber stack.

API Stability:

Evolving.

PUBLIC char,* rGetFilePath (cchar *path)

Get a file path name.

Description:

Expand any "@token" prefix in the path.

Parameters:

path	Source file path.

Returns:

The expanded path. Caller must free.

API Stability:

Evolving.

PUBLIC RList,* rGetFiles (cchar *base, cchar *pattern, int flags)

Create a list of files in a directory or subdirectories that match the given wildcard pattern.

This call returns a list of filenames

Description:

Get the list of files in a directory and return a list. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.

If the pattern is absolute.

Parameters:

base	Base directory from which to interpret the pattern. If the patternDirectory to list.
pattern	Wild card patterns to match.
flags	Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.

Returns:

A list (RList) of filenames.

API Stability:

Evolving.

PUBLIC RList,* rGetFilesEx (RList *results, cchar *base, cchar *pattern, int flags)

Get a list of files in a directory or subdirectories that match the given wildcard pattern.

This call adds the files to the supplied results list

Description:

Get the list of files in a directory and return a list. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.

Parameters:

results	Instance of RList. See rAllocList.
base	Base directory from which to interpret the pattern. If the patternDirectory to list.
pattern	Wild card patterns to match.
flags	Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.

Returns:

A list (RList) of filenames.

API Stability:

Evolving.

PUBLIC ssize rGetFileSize (cchar *path)

Return the size of a file.

Parameters:

path	Filename to test.

Returns:

The size of the file or a negative RT error code if the file does not exist.

API Stability:

Evolving.

PUBLIC int rGetHashLength (RHash *hash)

Return the count of symbols in a symbol entry.

Description:

Returns the number of symbols currently existing in a symbol table.

Parameters:

hash	Symbol table returned via rAllocHash.

Returns:

Integer count of the number of entries.

API Stability:

Evolving.

uint64 rGetHiResTicks (void )

Get the CPU tick count.

Description:

Get the current CPU tick count. This is a system dependant high resolution timer. On some systems, this returns time in nanosecond resolution.

Returns:

The CPU time in ticks. Will return the system time if CPU ticks are not available.

API Stability:

Internal.

PUBLIC char,* rGetIsoDate (Time time)

Get an ISO Date string representation of the given date/time.

Description:

Get the date/time as an ISO string.

Parameters:

time	Given time to convert.

Returns:

A date string. Caller must free.

API Stability:

Evolving.

PUBLIC RThread rGetMainThread (void )

Get the main Thread.

Description:

This routine is THREAD SAFE.

Returns:

The original main thread.

API Stability:

Evolving.

PUBLIC RName,* rGetNextName (RHash *hash, RName *next)

Return the next symbol in a symbol entry.

Description:

Continues walking the contents of a symbol table by returning the next entry in the symbol table. A previous call to rGetFirstSymbol or rGetNextSymbol is required to supply the value of the last argument.

Parameters:

hash	Hash table hash returned via rAllocHash.
next	Index of next name.

Returns:

Pointer to the first entry in the symbol table.

API Stability:

Evolving.

PUBLIC int rGetOsError (void )

Return the native O/S error code.

Description:

Returns an O/S error code from the most recent system call. This returns errno on Unix systems or GetLastError() on Windows.

Returns:

The O/S error code.

API Stability:

Evolving.

PUBLIC Ticks rGetRemainingTicks (Ticks mark, Ticks timeout)

Return the time remaining until a timeout has elapsed.

Parameters:

mark	Staring time stamp.
timeout	Time in milliseconds.

Returns:

Time in milliseconds until the timeout elapses.

API Stability:

Evolving.

PUBLIC cchar,* rGetServerName (void )

Get the application server name string.

Returns:

A string containing the application server name string.

API Stability:

Evolving.

PUBLIC int rGetSocketAddr (RSocket *sp, char *ipbuf, int ipbufLen, int *port)

Get the locally bound socket IP address and port for the socket.

Description:

Get the file descriptor associated with a socket.

Parameters:

sp	Socket object returned from rAllocSocket.
ipbuf	Buffer to receive the IP address.
ipbufLen	Size of the ipbuf.
port	Address of an integer to receive the port unumber.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC RSocketCustom rGetSocketCustom (void )

Get the custom socket callback handler.

Returns:

The custom socket callback handler.

API Stability:

Evolving.

PUBLIC cchar,* rGetSocketError (RSocket *sp)

Get the socket error.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:

The socket error message. Returns NULL if no error. Caller must NOT free.

API Stability:

Evolving.

PUBLIC Socket rGetSocketHandle (RSocket *sp)

Get the socket file descriptor.

Description:

Get the file descriptor associated with a socket.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:

The Socket file descriptor used by the O/S for the socket.

API Stability:

Evolving.

PUBLIC RWait,* rGetSocketWait (RSocket *sp)

Get the socket wait handler.

Returns:

RWait reference.

API Stability:

Evolving.

PUBLIC int rGetState (void )

Get the current R state.

Returns:

Returns R_INITIALIZED, R_READY, R_STOPPING or R_STOPPED.

API Stability:

Evolving.

PUBLIC char,* rGetTempFile (cchar *dir, cchar *prefix)

Get a temp filename.

Description:

Create a temp file name in the given directory with the specified prefix.

Parameters:

dir	Directory to contain the temporary file. If null, use system default temp directory (/tmp).
prefix	Optional filename prefix.

Returns:

An allocated string containing the file name. Caller must free.

API Stability:

Evolving.

PUBLIC Ticks rGetTicks (void )

Get the system time.

Description:

Get the system time in milliseconds. This is a monotonically increasing time counter. It does not represent wall-clock time.

Returns:

The system time in milliseconds.

API Stability:

Evolving.

PUBLIC Time rGetTime (void )

Get the time.

Description:

Get the date/time in milliseconds since Jan 1 1970.

Returns:

The time in milliseconds since Jan 1 1970.

API Stability:

Evolving.

PUBLIC bool rGetTimeouts (void )

Return true if timeouts are enabled.

Returns:

True if timeouts are enabled.

API Stability:

Evolving.

PUBLIC int rGetWaitFd (void )

Get the global wait descriptor.

Returns:

The wait file descriptor used by epoll and kqueue.

API Stability:

Evolving.

PUBLIC void rGlobalLock (void )

Globally lock the application.

Description:

This call asserts the application global lock so that other threads calling rGlobalLock will block until the current thread calls rGlobalUnlock. WARNING: Use this API very sparingly. This routine is THREAD SAFE.

API Stability:

Evolving.

PUBLIC void rGlobalUnlock (void )

Unlock the global mutex.

Description:

This call unlocks the global mutex previously locked via rGlobalLock. This routine is THREAD SAFE.

API Stability:

Evolving.

PUBLIC void rGracefulStop (void )

Gracefully stop the app.

Description:

Queued events will be serviced.

API Stability:

Evolving.

PUBLIC RBuf,* rHashToBuf (RHash *hash, cchar *join)

Convert a hash of strings to a single string in a buffer.

Parameters:

hash	Hash pointer returned from rCreateHash.
join	String to use as the element join string.

Returns:

Buffer consisting of the joined hash values. Caller must free with rFreeBuf.

API Stability:

Evolving.

PUBLIC char,* rHashToJson (RHash *hash, int pretty)

Convert a hash into JSON.

Parameters:

hash	Hash table to use for the result.
pretty	Set to true to have a prettier JSON representation.

Returns:

A JSON string. Caller must free.

API Stability:

Evolving.

PUBLIC RBuf,* rHashToJsonBuf (RHash *hash, RBuf *buf, int pretty)

Convert a hash into JSON in the given buffer.

Parameters:

hash	Hash table to use for the result.
buf	RBuf instance to store the json text.
pretty	Set to true to have a prettier JSON representation.

Returns:

The given buffer.

API Stability:

Evolving.

PUBLIC char,* rHashToString (RHash *hash, cchar *join)

Convert a hash of strings to a single string.

Parameters:

hash	Hash pointer returned from rCreateHash.
join	String to use as the element join string.

Returns:

String consisting of the joined hash values. Caller must free.

API Stability:

Evolving.

PUBLIC int rInit (RFiberProc fn, cvoid *arg)

Initialize the runtime.

Description:

This routine should be called at startup from main().

Parameters:

fn	Fiber function to start.
arg	Argument to the fiber function.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC int rInitFibers (void )

Initialize the fiber coroutine module.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC int rInitFile (void )

Create and initialze the file subsystem.

API Stability:

Internal.

PUBLIC RLock,* rInitLock (RLock *mutex)

Initialize a statically allocated lock object.

Description:

This call initialized a lock object without allocation. The object can then be used used in rLock rTryLock and rUnlock calls. This routine is THREAD SAFE.

Parameters:

mutex

Reference to an RLock structure to initialize.

Returns:

A reference to the supplied mutex. Returns null on errors.

API Stability:

Evolving.

PUBLIC int rInitOs (void )

Create and initialze the O/S dependent subsystem.

Description:

Called internally by the RT. Should not be called by users.

API Stability:

Internal.

PUBLIC int rInitWait (void )

Initialize the I/O wait subsystem.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC bool rIsFileAbs (cchar *path)

Determine if a file path is an absolute path.

Parameters:

path	Filename path to test.

Returns:

True if the path is an absolute path.

API Stability:

Evolving.

PUBLIC bool rIsMain (void )

Test if a fiber is the main fiber.

Returns:

True if the fiber is the main fiber.

API Stability:

Evolving.

PUBLIC bool rIsSocketClosed (RSocket *sp)

Test if the socket has been closed.

Description:

Determine if rCloseSocket has been called.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:

True if the socket is at end-of-file.

API Stability:

Evolving.

PUBLIC bool rIsSocketConnected (RSocket *sp)

Determine if the socket has connected to a remote pper.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:

True if the socket is connected.

API Stability:

Evolving.

PUBLIC bool rIsSocketEof (RSocket *sp)

Test if the other end of the socket has been closed.

Description:

Determine if the other end of the socket has been closed and the socket is at end-of-file.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:

True if the socket is at end-of-file.

API Stability:

Evolving.

PUBLIC bool rIsSocketSecure (RSocket *sp)

Determine if the socket is secure.

Description:

Determine if the socket is using SSL to provide enhanced security.

Parameters:

sp	Socket object returned from rAllocSocket.

Returns:

True if the socket is using SSL, otherwise zero.

API Stability:

Evolving.

PUBLIC char,* rJoinFile (cchar *base, cchar *other)

Join file paths.

Description:

Join a path to a base path. If the other path is absolute, it will be returned.

Parameters:

base	Directory filename to use as the base.
other	Other filename path to join to the base filename.

Returns:

Allocated string containing the resolved filename. Caller must free.

API Stability:

Evolving.

PUBLIC char,* rJoinFileBuf (char *buf, ssize bufsize, cchar *base, cchar *other)

Join paths into a buffer.

Description:

Join a path to a base path. If path is absolute, it will be returned.

Parameters:

buf	Destination path buffer.
bufsize	Size of buf.
base	Directory filename to use as the base.
other	Other filename path to join to the base filename.

Returns:

Allocated string containing the resolved filename.

API Stability:

Evolving.

PUBLIC void rLeave (bool *access)

Leave a fiber critical section.

Description:

This routine must be called on all exit paths from a fiber after calling rEnter.

Parameters:

access

Pointer to a boolean initialized to false.

API Stability:

Prototype.

PUBLIC int rListenSocket (RSocket *sp, cchar *host, int port, RSocketProc handler, void *arg)

Listen on a server socket for incoming connections.

Description:

Open a server socket and listen for client connections. If host is null, then this will listen on both IPv6 and IPv4.

Parameters:

sp	Socket object returned via rAllocSocket.
host	Host name or IP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
port	TCP/IP port number to connect to.
handler	Function callback to invoke for incoming connections. The function is invoked on a new fiber coroutine.
arg	Argument to handler.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC void rLock (RLock *lock)

Lock access.

Description:

This call asserts a lock on the given lock mutex so that other threads calling rLock will block until the current thread calls rUnlock. This routine is THREAD SAFE.

Parameters:

lock

object.

API Stability:

Evolving.

PUBLIC bool rLookupEvent (REvent id)

Lookup an event ID.

Parameters:

id	Event id allocated by rStartEvent.

Returns:

True if the event exists.

API Stability:

Evolving.

PUBLIC void,* rLookupName (RHash *hash, cchar *name)

Lookup a symbol in the hash table.

Description:

Lookup a name and return the value associated with that name.

Parameters:

hash	Symbol table returned via rAllocHash.
name	String name of the symbole entry to delete.

Returns:

Value associated with the name when the entry was insered via rInserSymbol.

API Stability:

Evolving.

PUBLIC RName,* rLookupNameEntry (RHash *hash, cchar *name)

Lookup a symbol in the hash table and return the hash entry.

Description:

Lookup a name and return the hash table descriptor associated with that name.

Parameters:

hash	Symbol table returned via rAllocHash.
name	String name of the symbole entry to delete.

Returns:

RName for the entry.

API Stability:

Evolving.

PUBLIC bool rMatchFile (cchar *path, cchar *pattern)

Matach a file against a glob pattern.

Description:

This tests a filename against a file pattern. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories,and a trailing "/" matches directories only.

If the pattern is absolute.

Parameters:

path	Filename to test.
pattern	Wild card patterns to match.

Returns:

True if the path matches the pattern.

API Stability:

Evolving.

PUBLIC void,* rMemdup (cvoid *ptr, size_t size)

Duplicate a block of memory.

Description:

Copy a block of memory into a newly allocated block.

Parameters:

ptr	Pointer to the block to duplicate.
size	Size of the block to copy.

Returns:

Returns an allocated block.

API Stability:

Evolving.

PUBLIC void rMemoryBarrier (void )

Perform a memory barrier where all queued writes are flushed to memory.

Description:

Use this call before accessing data that is updated and read across multiple threads.

API Stability:

Evolving.

PUBLIC Time rParseIsoDate (cchar *when)

Parse an ISO date string.

Returns:

The time in milliseconds since Jan 1, 1970.

API Stability:

Evolving.

PUBLIC ssize rPrintf (cchar *fmt, ...)

Formatted print.

This is a secure verion of printf that can handle null args

Description:

This is a secure replacement for printf. It can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
...	Variable arguments to format.

Returns:

The number of bytes written.

API Stability:

Evolving.

PUBLIC char,* rReadFile (cchar *path, ssize *lenp)

Read data from a file.

Description:

Reads data from a file.

Parameters:

path	Filename to read.
lenp	Pointer to receive the length of the file read.

Returns:

The contents of the file in an allocated string.

API Stability:

Evolving.

PUBLIC ssize rReadSocket (RSocket *sp, char *buf, ssize bufsize, Ticks deadline)

Read from a socket.

Description:

Read data from a socket. The read will return with whatever bytes are available. If none is available, this call will yield the current fiber and resume the main fiber. When data is available, the fiber will resume.

Must be called from a fiber.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Pointer to a buffer to hold the read data.
bufsize	Size of the buffer.
deadline	Maximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a deadline. Set to 0 for no deadline.

Returns:

A count of bytes actually read. Return a negative R error code on errors.

Returns:

Return -1 for EOF and errors. On success, return the number of bytes read. Use rIsSocketEof to distinguision between EOF and errors.

API Stability:

Evolving.

PUBLIC ssize rReadSocketSync (RSocket *sp, char *buf, ssize bufsize)

Read from a socket.

Description:

Read data from a socket. The read will return with whatever bytes are available. If none and the socket is in blocking mode, it will block until there is some data available or the socket is disconnected. Use rSetSocketBlocking to change the socket blocking mode. It is preferable to use rReadSocket which can wait without blocking via fiber coroutines.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Pointer to a buffer to hold the read data.
bufsize	Size of the buffer.

Returns:

A count of bytes actually read. Return a negative R error code on errors.

Returns:

Return -1 for EOF and errors. On success, return the number of bytes read. Use rIsSocketEof to distinguision between EOF and errors.

API Stability:

Evolving.

PUBLIC void,* rRealloc (void *ptr, size_t size)

Allocate a block of memory.

Description:

This is the lowest level of memory allocation routine. Memory is freed via rFree.

Parameters:

size	Size of the memory block to allocate.
ptr	Pointer to the block. If ptr is null, the call is skipped.

Returns:

Returns a pointer to the reallocated block. If memory is not available the memory exhaustion handler will be invoked.

Remarks:

Do not mix calls to rRealloc and malloc.

API Stability:

Evolving.

PUBLIC int rRemoveName (RHash *hash, cchar *name)

Remove a symbol entry from the hash table.

Description:

Removes a symbol entry from the symbol table. The entry is looked up via the supplied name.

Parameters:

hash	Symbol table returned via rAllocHash.
name	String name of the symbole entry to delete.

Returns:

Returns zero if successful, otherwise a negative RT error code is returned.

API Stability:

Evolving.

PUBLIC void rResetSocket (RSocket *sp)

Reset a socket.

Description:

Reset a socket by closing the underlying socket file descriptor. The Socket instance can be reused by rConnectSocket.

Parameters:

sp	Socket object returned from rAllocSocket.

API Stability:

Evolving.

PUBLIC void,* rResumeFiber (RFiber *fiber, void *result)

Resume a fiber.

Description:

Resume a fiber. If called from a non-main fiber or foreign-thread the target fiber is resumed via an event to the main fiber. THREAD SAFE.

Parameters:

fiber	Fiber object.
result	Result to pass to the fiber and will be the value returned from rYieldFiber.

API Stability:

Evolving.

PUBLIC void rResumeWait (RWait *wp, int mask)

Release a waiting fiber waiting for an event.

Description:

This call may be used to waken a fiber in response to external events.

Parameters:

wp	RWait object.
mask	Event mask to pass to fiber on resume.

API Stability:

Evolving.

PUBLIC char,* rRun (cchar *command, int *status)

Run a command using the system shell.

Parameters:

command	Command string to run using popen().
status	Returns the command exit status.

API Stability:

Evolving.

PUBLIC int rRunEvent (REvent id)

Run an event now.

Parameters:

id	Event id allocated by rStartEvent.

Returns:

Zero if the event is found and can be run.

API Stability:

Evolving.

PUBLIC Ticks rRunEvents (void )

Run due events.

Returns:

Time delay till the next event.

API Stability:

Evolving.

PUBLIC int rServiceEvents (void )

Service events.

Description:

This call blocks and continually services events on the event loop until the app is instructed to exit via $rStop. An app should call rServiceEvents from the main program.

Returns:

The current R state.

API Stability:

Evolving.

PUBLIC void rSetFiberLimits (int maxFibers)

Set the fiber limits.

Parameters:

maxFibers

The maximum number of fibers (stacks). Set to zero for no limit.

API Stability:

Evolving.

PUBLIC void rSetFiberStack (ssize size)

Set the default fiber stack size.

Parameters:

size	Size of fiber stack in bytes.

API Stability:

Evolving.

PUBLIC void rSetMemHandler (RMemProc handler)

Define a global memory exhaustion handler.

Description:

The memory handler will be invoked for memory allocation errors.

Parameters:

handler

Callback function invoked with the signature: void fn(int cause, size_t size).

API Stability:

Evolving.

PUBLIC void rSetOsError (int error)

Set the O/S error code.

Description:

Set errno or equivalent.

API Stability:

Evolving.

PUBLIC void rSetSocketBlocking (RSocket *sp, bool on)

Set a socket into blocking I/O mode.

from a socket

Description:

Sockets are opened in non-blocking mode by default.

Parameters:

sp	Socket object returned from rAllocSocket.
on	Set to true to enable blocking mode.

API Stability:

Evolving.

PUBLIC void rSetSocketCerts (RSocket *sp, cchar *ca, cchar *key, cchar *cert, cchar *revoke)

Configure the socket TLS certificates.

Description:

This call is a wrapper over rSetTLSCerts.

Parameters:

sp	Socket object returned from rAllocSocket.
ca	Certificate authority to use when verifying peer connections.
key	Private key for the certificate.
cert	Certificate to use for TLS.
revoke	List of revoked certificates.

API Stability:

Evolving.

PUBLIC void rSetSocketCiphers (RSocket *sp, cchar *ciphers)

Set the ciphers to use for communications.

Parameters:

sp	Socket object returned from rAllocSocket.
ciphers	String of suitable ciphers.

API Stability:

Evolving.

PUBLIC void rSetSocketCustom (RSocketCustom custom)

Set the socket custom configuration callback.

Parameters:

custom

Custom callback function.

Returns:

RWait reference.

API Stability:

Evolving.

PUBLIC void rSetSocketDefaultCerts (cchar *ca, cchar *key, cchar *cert, cchar *revoke)

Configure the default TLS certificates.

Description:

This call is a wrapper over rSetTLSCerts.

Parameters:

ca	Certificate authority to use when verifying peer connections.
key	Private key for the certificate.
cert	Certificate to use for TLS.
revoke	List of revoked certificates.

API Stability:

Evolving.

PUBLIC void rSetSocketDefaultCiphers (cchar *ciphers)

Set the default TLS ciphers to use for communications.

Parameters:

ciphers

String of suitable ciphers.

API Stability:

Evolving.

PUBLIC void rSetSocketDefaultVerify (int verifyPeer, int verifyIssuer)

Set the default TLS verification parameters.

Description:

This call is a wrapper over rSetTlsCerts.

Parameters:

verifyPeer	Set to true to verify peer certificates.
verifyIssuer	Set to true to verify the issuer of the peer certificate.

API Stability:

Evolving.

PUBLIC int rSetSocketError (RSocket *sp, cchar *fmt, ...)

Set the socket error message.

Parameters:

sp	Socket object returned from rAllocSocket.
fmt	Printf style format string.
...	Args for fmt.

API Stability:

Evolving.

PUBLIC void rSetSocketVerify (RSocket *sp, int verifyPeer, int verifyIssuer)

Set the socket TLS verification parameters.

Description:

This call is a wrapper over rSetTlsCerts.

Parameters:

sp	Socket object returned from rAllocSocket.
verifyPeer	Set to true to verify peer certificates.
verifyIssuer	Set to true to verify the issuer of the peer certificate.

API Stability:

Evolving.

PUBLIC void rSetSocketWaitMask (RSocket *sp, int64 mask, Ticks deadline)

Update the wait mask for a socket.

Parameters:

sp	Socket object returned from rAllocSocket.
mask	Set to R_READABLE or R_WRITABLE or both.
deadline	System time in ticks to wait until. Set to zero for no deadline.

API Stability:

Evolving.

PUBLIC void rSetState (int state)

Set the R state.

Description:

This API is thread safe and can be called from a foreign thread.

Parameters:

state

Set to R_INITIALIZED, R_READY, R_STOPPING or R_STOPPED.

API Stability:

Evolving.

PUBLIC void rSetTimeouts (bool on)

Control timeouts.

Parameters:

on	Set to false to disable timeouts for debugging.

API Stability:

Evolving.

PUBLIC void rSetWaitHandler (RWait *wp, RWaitProc handler, cvoid *arg, int64 mask, Ticks deadline)

Define a wait handler function on a wait object.

Description:

This will run the designated handler on a coroutine fiber in response to matching I/O events.

Parameters:

wp	RWait object.
handler	Function handler to invoke as the entrypoint in the new coroutine fiber.
arg	Parameter argument to pass to the handler.
mask	Set to R_READABLE or R_WRITABLE or both.
deadline	Optional deadline to wait system time. Set to zero for no deadline.

API Stability:

Evolving.

PUBLIC void rSetWaitMask (RWait *wp, int64 mask, Ticks deadline)

Update the wait mask for a wait handler.

Parameters:

wp	RWait object.
mask	Set to R_READABLE or R_WRITABLE or both.
deadline	System time in ticks to wait until. Set to zero for no deadline.

API Stability:

Evolving.

PUBLIC void rSignal (cchar *name, cvoid *arg)

Signal watches of a named event.

Parameters:

name	Named event.
arg	Data argument to pass to the watch function.

API Stability:

Evolving.

PUBLIC void rSignalSync (cchar *name, cvoid *arg)

Signal watches of a named event synchronously (blocking).

Parameters:

name	Named event.
arg	Data argument to pass to the watch function.

API Stability:

Evolving.

PUBLIC void rSleep (Ticks ticks)

Sleep a fiber for the requested number of milliseconds.

Must be called from a fiber.

Description:

Pause a fiber for the requested duration and then resume via the main fiber. Other fibers continue to run.

Parameters:

ticks

Time period in milliseconds to sleep.

API Stability:

Evolving.

PUBLIC char,* rSnprintf (char *buf, ssize maxsize, cchar *fmt, ...)

Format a string into a buffer.

Description:

This routine will format the arguments into a result. If a buffer is supplied, it will be used. Otherwise if the buf argument is NULL, a buffer will be allocated. The arguments will be formatted up to the maximum size supplied by the maxsize argument. A trailing NULL will always be appended.

Parameters:

buf	Optional buffer to contain the formatted result.
maxsize	Maximum size of the result.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:

The original buffer if supplied or else an allocated string.

API Stability:

Prototype.

PUBLIC int rSpawnFiber (cchar *name, RFiberProc fn, void *arg)

Spawn a fiber coroutine.

Description:

This allocates a new fiber and resumes it.

Parameters:

name	Fiber name.
fn	Fiber entry point.
arg	Entry point argument.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC void,* rSpawnThread (RThreadProc fn, void *arg)

Spawn an O/S thread and wait until it completes.

Description:

This creates a new thread and runs the given function. It then yields until the thread function returns and returns the function result.

Parameters:

fn	Thread main function entry point.
arg	Argument provided to the thread.

Returns:

Value returned from spawned thread function.

API Stability:

Evolving.

PUBLIC REvent rStartEvent (REventProc proc, void *data, Ticks delay)

Start a callback event.

Description:

This API is a wrapper for rAllocEvent with the fiber set to the current fiber. This schedules an event to run once. The event can be rescheduled in the callback by invoking rRestartEvent. This routine is THREAD SAFE.

Parameters:

proc	Callback procedure function. Signature is: void (*fn)(void *data, int id).
data	Data reference to pass to the callback.
delay	Delay in milliseconds in which to run the callback.

Returns:

A positive integer event ID.

API Stability:

Evolving.

PUBLIC void rStartFiber (RFiber *fiber, void *data)

Start a fiber coroutine.

Description:

This creates an event so that the main fiber can start the fiber. This routine is typically only called internally by the fiber module. This routine is THREAD SAFE and can be used to resume a yielded fiber.

Parameters:

fiber	The fiber object.
data	Value to pass to the fiber entry point.

API Stability:

Internal.

PUBLIC void rStop (void )

Immediately stop the app.

Description:

This API is thread safe and can be called from a foreign thread.

Description:

Queued events will not be serviced.

API Stability:

Evolving.

PUBLIC int rStopEvent (REvent id)

Stop an event.

Parameters:

id	Event id allocated by rStartEvent.

Returns:

Integer handle index. Otherwise return -1 on allocation errors.

API Stability:

Evolving.

PUBLIC void rTermFibers (void )

Terminate the fiber coroutine module.

API Stability:

Evolving.

PUBLIC void rTermFile (void )

Stop the file subsystem.

API Stability:

Internal.

PUBLIC void rTermLock (RLock *mutex)

Terminate a statically allocated lock object.

Description:

This routine is THREAD SAFE.

Parameters:

mutex

Reference to an RLock structure to initialize.

API Stability:

Evolving.

PUBLIC void rTermOs (void )

Stop the O/S dependent subsystem.

API Stability:

Internal.

PUBLIC void rTermWait (void )

Terminate the I/O wait subsystem.

API Stability:

Evolving.

PUBLIC bool rTryLock (RLock *lock)

Attempt to lock access.

Description:

This call attempts to assert a lock on the given lock mutex so that other threads calling rLock or rTryLock will block until the current thread calls rUnlock. This routine is THREAD SAFE.

Returns:

Returns zero if the successful in locking the mutex. Returns a negative error code if unsuccessful.

API Stability:

Evolving.

PUBLIC void rUnlock (RLock *lock)

Unlock a mutex.

Description:

This call unlocks a mutex previously locked via rLock or rTryLock. This routine is THREAD SAFE.

Parameters:

lock

object.

API Stability:

Evolving.

PUBLIC char,* rVsnprintf (char *buf, ssize maxsize, cchar *fmt, va_list args)

Format a string into a buffer.

Description:

This routine will format the arguments into a result. If a buffer is supplied, it will be used. Otherwise if the buf argument is NULL, a buffer will be allocated. The arguments will be formatted up to the maximum size supplied by the maxsize argument. A trailing NULL will always be appended.

Parameters:

buf	Optional buffer to contain the formatted result.
maxsize	Maximum size of the result. If set to -1, thee will be no limit.
fmt	Printf style format string.
args	Variable arguments to format.

Returns:

The original buffer if supplied or else an allocated string.

API Stability:

Prototype.

PUBLIC int rWait (Ticks timeout)

Wait for an I/O event.

Description:

This is typically called by $rServiceEvents to wait for I/O events.

Parameters:

timeout

Maximum time in milliseconds to wait for an I/O event.

Returns:

Zero if successful.

API Stability:

Evolving.

PUBLIC int rWaitForIO (RWait *wp, int mask, Ticks deadline)

Wait for an IO event on a wait object.

Description:

Wait for an IO event by yielding the current coroutine fiber until the IO event arrives. When the IO event occurs, the wait handler will be invoked on the fiber.

Parameters:

wp	RWait object.
mask	Set to R_READABLE or R_WRITABLE or both.
deadline	System time in ticks to wait until. Set to zero for no deadline.

Returns:

A mask of I/O events with R_READABLE or R_WRITABLE or R_MODIFIED or R_TIMEOUT.

API Stability:

Evolving.

PUBLIC void rWakeup (void )

Wakeup the event loop.

API Stability:

Internal.

PUBLIC int rWalkDir (cchar *dir, cchar *pattern, RWalkDirProc callback, void *arg, int flags)

Walk a directory tree and invoke a callback for each path that matches a given pattern.

Description:

The pattern may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.

Parameters:

dir	Base directory from which to interpret the pattern.
pattern	Wild card patterns to match.
callback	Callback function of the signature RWalkDirProc.
arg	Argument to callback function.
flags	Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.

API Stability:

Evolving.

PUBLIC void rWatch (cchar *name, RWatchProc proc, void *data)

Watch for a named event to happen.

Parameters:

name	Named event.
proc	Function to call.
data	Data argument to pass to the proc function as the first argument.

API Stability:

Evolving.

PUBLIC void rWatchOff (cchar *name, RWatchProc proc, void *data)

Stop watching for a named event to happen.

This will remove the watch for a previous rWatch call with exactly the same proc and data arguments

Parameters:

name	Named event.
proc	Function provided to a previous rWatch call.
data	Data argument supplied to a previous rWatch call.

API Stability:

Evolving.

PUBLIC ssize rWriteFile (cchar *path, cchar *buf, ssize len, int mode)

Write data to a file.

Description:

Write data from a file. The file will be created if required.

Parameters:

path	Filename to write.
buf	Buffer of data to write to the file.
len	Length of the buffer.
mode	Create file mode.

Returns:

The length of bytes written to the file. Should equal len.

API Stability:

Evolving.

PUBLIC int rWritePid (void )

Write the current process pid to /var/run.

Returns:

Zero on success, otherwise a negative status code.

PUBLIC ssize rWriteSocket (RSocket *sp, cvoid *buf, ssize bufsize, Ticks deadline)

Write to a socket.

Description:

Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. If no data can be written, this call will yield the current fiber and resume the main fiber. When data is available, the fiber will resume.

Must be called from a fiber.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Reference to a block to write to the socket.
bufsize	Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative error code on errors.
deadline	System time in ticks to wait until. Set to zero for no deadline.

Returns:

A count of bytes actually written. Return a negative error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and rGetError() returns EAGAIN or EWOULDBLOCK.

API Stability:

Evolving.

PUBLIC ssize rWriteSocketSync (RSocket *sp, cvoid *buf, ssize len)

Write to a socket.

Description:

Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. It is preferable to use rWriteSocket which can wait without blocking via fiber coroutines.

Parameters:

sp	Socket object returned from rAllocSocket.
buf	Reference to a block to write to the socket.
len	Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative error code on errors.

Returns:

A count of bytes actually written. Return a negative error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and rGetError() returns EAGAIN or EWOULDBLOCK.

API Stability:

Evolving.

PUBLIC void,* rYieldFiber (void *value)

Yield a fiber back to the main fiber.

Description:

Pause a fiber until resumed by the main fiber. the target fiber is resumed via an event to the main fiber.

Parameters:

value

Value to provide as a result to the main fiber that called rResumeFiber.

API Stability:

Evolving.

PUBLIC char,* scamel (cchar *str)

Create a camel case version of the string.

Description:

Copy a string into a newly allocated block and make the first character lower case.

Parameters:

str	Pointer to the block to duplicate.

Returns:

Returns a newly allocated string.

API Stability:

Evolving.

PUBLIC int scaselesscmp (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is a r replacement for strcasecmp. It can handle NULL args

Description:

Compare two strings ignoring case differences. This call operates similarly to strcmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:

Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.

API Stability:

Evolving.

PUBLIC bool scaselessmatch (cchar *s1, cchar *s2)

Compare strings ignoring case.

This is similar to scaselesscmp but it returns a boolean

Description:

Compare two strings ignoring case differences.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:

Returns true if the strings are equivalent, otherwise false.

API Stability:

Evolving.

PUBLIC char,* schr (cchar *str, int c)

Find a character in a string.

Description:

This is a r replacement for strchr. It can handle NULL args.

Parameters:

str	String to examine.
c	Character to search for.

Returns:

If the character is found, the call returns a reference to the character position in the string. Otherwise, returns NULL.

API Stability:

Evolving.

PUBLIC char,* sclone (cchar *str)

Clone a string.

Description:

Copy a string into a newly allocated block. This routine is null tolerant. It will return an allocated empty string if passed a NULL. Use scloneNull if you need to preserve NULLs.

Parameters:

str	Pointer to the block to duplicate.

Returns:

Returns a newly allocated string. Caller must free.

API Stability:

Evolving.

PUBLIC char,* scloneNull (cchar *str)

Clone a string and preserve NULLs.

Description:

Copy a string into a newly allocated block. If passed a NULL, this will return a NULL.

Parameters:

str	Pointer to the block to duplicate.

Returns:

Returns a newly allocated string or NULL. Caller must free.

API Stability:

Evolving.

PUBLIC int scmp (cchar *s1, cchar *s2)

Compare strings.

Description:

Compare two strings. This is a r replacement for strcmp. It can handle null args.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:

Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.

API Stability:

Evolving.

PUBLIC char,* scontains (cchar *str, cchar *pattern)

Find a pattern in a string.

Description:

Locate the first occurrence of pattern in a string.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.

Returns:

Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:

Evolving.

PUBLIC ssize scopy (char *dest, ssize destMax, cchar *src)

Copy a string.

Description:

R replacement for strcpy. Copy a string and ensure the destination buffer is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is always terminated with a null. It is null tolerant in that "src" may be null.

Parameters:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy. May be null.

Returns:

The number of characters in the target string.

API Stability:

Evolving.

PUBLIC cchar,* sends (cchar *str, cchar *suffix)

Test if the string ends with a given pattern.

Parameters:

str	String to examine.
suffix	Pattern to search for.

Returns:

Returns a pointer to the start of the pattern if found. Otherwise returns NULL.

API Stability:

Evolving.

PUBLIC char,* sfmt (cchar *fmt, ...)

Format a string.

This is a secure verion of printf that can handle null args

Description:

Format the given arguments according to the printf style format. See rPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
...	Variable arguments for the format string.

Returns:

Returns a newly allocated string.

API Stability:

Evolving.

PUBLIC char,* sfmtbuf (char *buf, ssize maxSize, cchar *fmt, ...)

Format a string into a static buffer.

Description:

This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.

Parameters:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
...	Variable arguments to format.

Returns:

The buffer.

API Stability:

Evolving.

PUBLIC char,* sfmtbufv (char *buf, ssize maxSize, cchar *fmt, va_list args)

Format a string into a statically allocated buffer.

Description:

This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.

Parameters:

buf	Pointer to the buffer.
maxSize	Size of the buffer.
fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:

The buffer;.

API Stability:

Evolving.

PUBLIC char,* sfmtv (cchar *fmt, va_list args)

Format a string.

This is a secure verion of printf that can handle null args

Description:

Format the given arguments according to the printf style format. See rPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.

Parameters:

fmt	Printf style format string.
args	Varargs argument obtained from va_start.

Returns:

Returns a newly allocated string.

API Stability:

Evolving.

PUBLIC uint shash (cchar *str, ssize len)

Compute a hash code for a string.

Parameters:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:

Returns an unsigned integer hash code.

API Stability:

Evolving.

PUBLIC uint shashlower (cchar *str, ssize len)

Compute a caseless hash code for a string.

Description:

This computes a hash code for the string after convering it to lower case.

Parameters:

str	String to examine.
len	Length in characters of the string to include in the hash code.

Returns:

Returns an unsigned integer hash code.

API Stability:

Evolving.

PUBLIC char,* sitos (int64 value)

Convert an integer to a string.

Description:

This call convers the supplied 64 bit integer to a string using base 10.

Parameters:

value

Integer value to conver.

Returns:

An allocated string with the converted number. Caller must free.

API Stability:

Evolving.

PUBLIC char,* sitosbuf (char *buf, ssize size, int64 value, int radix)

Convert an integer to a string buffer.

Description:

This call convers the supplied 64 bit integer into a string formatted into the supplied buffer according to the specified radix.

Parameters:

buf	Pointer to the buffer that will hold the string.
size	Size of the buffer. Must be at least 2 characters long.
value	Integer value to conver.
radix	The base radix to use when encoding the number. Supports 10 and 16.

Returns:

Returns a reference to the string.

API Stability:

Evolving.

PUBLIC char,* sitosradix (int64 value, int radix)

Convert an integer to a string.

Description:

This call convers the supplied 64 bit integer to a string according to the specified radix.

Parameters:

value	Integer value to conver.
radix	The base radix to use when encoding the number.

Returns:

An allocated string with the converted number.

API Stability:

Evolving.

PUBLIC char,* sjoin (cchar *str, ...)

Catenate strings.

Description:

This catenates strings together with an optional string separator. If the separator is NULL, not separator is used. This call accepts a variable list of strings to append, terminated by a null argument.

Parameters:

str	First string to catentate.
...	Variable number of string arguments to append. Terminate list with NULL.

Returns:

Returns an allocated string.

API Stability:

Evolving.

PUBLIC char,* sjoinArgs (int argc, cchar **argv, cchar *sep)

Join an array of strings.

Parameters:

argc	number of strings to join.
argv	Array of strings.
sep	Separator string to use. If NULL, then no separator is used.

Returns:

A single joined string. Caller must free.

API Stability:

Evolving.

PUBLIC ssize sjoinbuf (char *buf, ssize bufsize, cchar *str1, cchar *str2)

Catenate strings into a buffer.

Parameters:

buf	Destination buffer.
bufsize	Size of the buffer.
str1	First string.
str2	Second string to append.

Returns:

Number of bytes in the destination buffer.

API Stability:

Evolving.

PUBLIC char,* sjoinfmt (cchar *str, cchar *fmt, ...)

Join a formatted string to an existing string.

Description:

This uses the format and args to create a string that is joined to the first string.

Parameters:

str	First string to catentate.
fmt	First string to catentate.
...	Varargs argument obtained from va_start.

Returns:

Returns an allocated string.

API Stability:

Evolving.

PUBLIC char,* sjoinv (cchar *str, va_list args)

Catenate strings.

Description:

This catenates strings together.

Parameters:

str	First string to catentate.
args	Varargs argument obtained from va_start.

Returns:

Returns an allocated string.

API Stability:

Evolving.

PUBLIC ssize slen (cchar *str)

Return the length of a string.

Description:

R replacement for strlen. This call returns the length of a string and tests if the length is less than a given maximum. It will return zero for NULL args.

Parameters:

str	String to measure.

Returns:

The length of the string.

API Stability:

Evolving.

PUBLIC char,* slower (char *str)

Convert a string to lower case.

Description:

Convert a string to its lower case equivalent.

Parameters:

str	String to conver.

API Stability:

Evolving.

PUBLIC bool smatch (cchar *s1, cchar *s2)

Compare strings.

Description:

Compare two strings. This is similar to scmp but it returns a boolean.

Parameters:

s1	First string to compare.
s2	Second string to compare.

Returns:

Returns true if the strings are equivalent, otherwise false.

API Stability:

Evolving.

PUBLIC int sncaselesscmp (cchar *s1, cchar *s2, ssize len)

Compare strings ignoring case.

Description:

Compare two strings ignoring case differences for a given string length. This call operates similarly to strncasecmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:

Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.

API Stability:

Evolving.

PUBLIC char,* sncaselesscontains (cchar *str, cchar *pattern, ssize limit)

Find a pattern in a string with a limit using a caseless comparison.

Description:

Locate the first occurrence of pattern in a string, but do not search more than the given character limit. Use a caseless comparison.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.
limit	Count of characters in the string to search.

Returns:

Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:

Evolving.

PUBLIC char,* snclone (cchar *str, ssize len)

Clone a substring.

Description:

Copy a substring into a newly allocated block.

Parameters:

str	Pointer to the block to duplicate.
len	Number of bytes to copy. The actual length copied is the minimum of the given length and the length of the supplied string. The result is null terminated.

Returns:

Returns a newly allocated string.

API Stability:

Evolving.

PUBLIC int sncmp (cchar *s1, cchar *s2, ssize len)

Compare strings.

Description:

Compare two strings for a given string length. This call operates similarly to strncmp.

Parameters:

s1	First string to compare.
s2	Second string to compare.
len	Length of characters to compare.

Returns:

Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.

API Stability:

Evolving.

PUBLIC char,* sncontains (cchar *str, cchar *pattern, ssize limit)

Find a pattern in a string with a limit.

Description:

Locate the first occurrence of pattern in a string, but do not search more than the given character limit.

Parameters:

str	Pointer to the string to search.
pattern	String pattern to search for.
limit	Count of characters in the string to search.

Returns:

Returns a reference to the start of the pattern in the string. If not found, returns NULL.

API Stability:

Evolving.

PUBLIC ssize sncopy (char *dest, ssize destMax, cchar *src, ssize len)

Copy characters from a string.

Description:

R replacement for strncpy. Copy bytes from a string and ensure the target string is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is terminated with a null.

Parameters:

dest	Pointer to a pointer that will hold the address of the allocated block.
destMax	Maximum size of the target string in characters.
src	String to copy.
len	Maximum count of characters to copy.

Returns:

Returns a reference to the destination if successful or NULL if the string won't fit.

API Stability:

Evolving.

PUBLIC char,* spbrk (cchar *str, cchar *set)

Locate the a character from a set in a string.

Description:

This locates in the string the first occurence of any character from a given set of characters.

Parameters:

str	String to examine.
set	Set of characters to scan for.

Returns:

Returns a reference to the first character from the given set. Returns NULL if none found.

API Stability:

Evolving.

PUBLIC char,* sptok (char *str, cchar *pattern, char **nextp)

Tokenize a string.

Description:

Split a string into tokens using a string pattern as delimiters.

Parameters:

str	String to tokenize.
pattern	String pattern to use for token delimiters.
nextp	Next token pointer.

Returns:

Returns a pointer to the string.

API Stability:

Evolving.

PUBLIC char,* srchr (cchar *str, int c)

Find a character in a string by searching backwards.

Description:

This locates in the string the last occurence of a character.

Parameters:

str	String to examine.
c	Character to scan for.

Returns:

Returns a reference in the string to the requested character. Returns NULL if none found.

API Stability:

Evolving.

PUBLIC char,* srejoin (char *buf, ...)

Append strings to an existing string and reallocate as required.

Description:

Append a list of strings to an existing string. The list of strings is terminated by a null argument. The call returns the size of the allocated block.

Parameters:

buf	Existing (allocated) string to reallocate. May be null. May not be a string literal.
...	Variable number of string arguments to append. Terminate list with NULL.

Returns:

Returns an allocated string.

API Stability:

Evolving.

PUBLIC char,* srejoinv (char *buf, va_list args)

Append strings to an existing string and reallocate as required.

Description:

Append a list of strings to an existing string. The list of strings is terminated by a null argument. The call returns the size of the allocated block.

Parameters:

buf	Existing (allocated) string to reallocate. May be null. May not be a string literal.
args	Varargs argument obtained from va_start.

Returns:

Returns an allocated string.

API Stability:

Evolving.

PUBLIC char,* ssplit (char *str, cchar *delim, char **last)

Split a string at a delimiter.

Description:

Split a string and return pars. The string is modified. This routiner never returns null. If there are leading delimiters, the empty string will be returned and *last will be set to the portion after the delimiters. If str is null, a managed reference to the empty string will be returned. If there are no characters after the delimiter, then *last will be set to the empty string.

Parameters:

str	String to tokenize.
delim	Set of characters that are used as token separators.
last	Reference to the portion after the delimiters. Will return an empty string if is not trailing portion.

Returns:

Returns a pointer to the first par before the delimiters. If the string begins with delimiters, the empty string will be returned.

API Stability:

Evolving.

PUBLIC ssize sspn (cchar *str, cchar *set)

Find the end of a spanning prefix.

Description:

This scans the given string for characters from the set and returns an index to the first character not in the set.

Parameters:

str	String to examine.
set	Set of characters to span.

Returns:

Returns an index to the first character after the spanning set. If not found, returns the index of the first null.

API Stability:

Evolving.

PUBLIC bool sstarts (cchar *str, cchar *prefix)

Test if the string starts with a given pattern.

Parameters:

str	String to examine.
prefix	Pattern to search for.

Returns:

Returns true if the pattern was found. Otherwise returns zero.

API Stability:

Evolving.

PUBLIC char,* ssub (cchar *str, ssize offset, ssize length)

Create a substring.

Parameters:

str	String to examine.
offset	Staring offset within str for the beginning of the substring.
length	Length of the substring in characters.

Returns:

Returns a newly allocated substring.

API Stability:

Evolving.

PUBLIC char,* stemplate (cchar *str, void *tokens)

Replace template tokens in a string with values from a lookup table.

Tokens are ${variable} references

Parameters:

str	String to expand.
tokens	Hash table of token values to use.

Returns:

An expanded string. May return the original string if no "$" references are present.

API Stability:

Evolving.

PUBLIC char,* stitle (cchar *str)

Create a Title Case version of the string.

Description:

Copy a string into a newly allocated block and make the first character upper case.

Parameters:

str	Pointer to the block to duplicate.

Returns:

Returns a newly allocated string.

API Stability:

Evolving.

PUBLIC double stod (cchar *str)

Convert a string to a double floating point value.

Description:

This call convers the supplied string to a double.

Parameters:

str	Pointer to the string to parse. If passed null, returns NAN.

Returns:

The double equivalent value of the string.

API Stability:

Evolving.

PUBLIC double stof (cchar *str)

Convert a string to a double.

Description:

This call convers the supplied string to a double.

Parameters:

str	Pointer to the string to parse.

Returns:

The double equivalent value of the string.

API Stability:

Evolving.

PUBLIC int64 stoi (cchar *str)

Convert a string to an integer.

Description:

This call convers the supplied string to an integer using base 10.

Parameters:

str	Pointer to the string to parse.

Returns:

The integer equivalent value of the string.

API Stability:

Evolving.

PUBLIC int64 stoiradix (cchar *str, int radix, int *err)

Convert a string to an integer.

Description:

This call convers the supplied string to an integer using the specified radix (base).

Parameters:

str	Pointer to the string to parse.
radix	Base to use when parsing the string.
err	Return error code. Set to 0 if successful.

Returns:

The integer equivalent value of the string.

PUBLIC char,* stok (char *str, cchar *delim, char **last)

Tokenize a string.

Description:

Split a string into tokens using a character set as delimiters.

Parameters:

str	String to tokenize.
delim	Set of characters that are used as token separators.
last	Last token pointer.

Returns:

Returns a pointer to the next token inside the original string. Caller must not free the result.

API Stability:

Evolving.

PUBLIC struct,RList,* stolist (cchar *src)

String to list.

This parses the string of space separated arguments. Single and double quotes are supported

Parameters:

src	Source string to parse.

Returns:

List of arguments.

API Stability:

Evolving.

PUBLIC char,* strim (char *str, cchar *set, int where)

Trim a string.

Description:

Trim leading and trailing characters off a string. The original string is modified and the return value point into the original string.

Parameters:

str	String to trim.
set	String of characters to remove.
where	Flags to indicate trim from the start, end or both. Use R_TRIM_START, R_TRIM_END, R_TRIM_BOTH.

Returns:

Returns a reference into the original string. Caller must not free.

API Stability:

Evolving.

PUBLIC char,* supper (char *str)

Convert a string to upper case.

Description:

Convert a string to its upper case equivalent.

Parameters:

str	String to conver.

Returns:

Returns a pointer to the converted string. Will always equal str.

API Stability:

Evolving.

PUBLIC uint64 svalue (cchar *value)

Parse a value string.

Description:

Parse a textual number with unit suffixes. The following suffixes are supported: sec, secs, second, seconds, min, mins, minute, minutes, hr, hrs, hour, hours, day, days, week, weeks, month, months, year, years, byte, bytes, k, kb, m, mb, g, gb. Also supports the strings: unlimited, infinite, never, forever.

Returns:

A 64 bit unsigned number.

API Stability:

Evolving.

PUBLIC void szero (char *str)

Erase the contents of a string.

Parameters:

str	String to erase.

API Stability:

Evolving.