R Native API

Extensions

RBuf Dynamic Buffer Module.
REvent Event Subsystem.
RFile R File Module.
RHash Has table structure.
RList List data structure.
RLog Log Services.
RString R String Module.
RWait Wait object.

Functions

PUBLIC voidassert(bool cond)
 Asser that a condition is true.
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 intrAddItem(RList *list, cvoid *item)
 Add an item to a list.
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 intrAddNullItem(RList *list)
 Add a null item to the list.
PUBLIC voidrAddNullToBuf(RBuf *buf)
 Add a null character to the buffer contents.
PUBLIC voidrAdjustBufEnd(RBuf *buf, ssize count)
 Adjust the buffer end position.
PUBLIC voidrAdjustBufStart(RBuf *buf, ssize count)
 Adjust the buffer start position.
PUBLIC RBuf*rAllocBuf(ssize initialSize)
 Create a new buffer.
PUBLIC voidrAllocException(int cause, size_t size)
 Signal a memory allocation exception.
PUBLIC RFiber*rAllocFiber(RFiberProc fn, cvoid *data)
 Allocate a fiber coroutine object.
PUBLIC RHash*rAllocHash(int size, int flags)
 Create a hash table.
PUBLIC RList*rAllocList(int size, int flags)
 Allocate a list.
PUBLIC RSocket*rAllocSocket(void)
 Allocate a socket object.
PUBLIC RWait*rAllocWait(int fd)
 Allocate a wait object for a file descriptor.
PUBLIC intrBackupFile(cchar *path, int count)
 Backup the given file.
PUBLIC voidrBackupLog(void)
 Backup a log.
PUBLIC cchar*rBasename(cchar *path)
 Return the basename (filename) portion of a filename.
PUBLIC voidrBreakpoint(void)
 Trigger a breakpoint.
PUBLIC char*rBufToString(RBuf *buf)
 Return a reference to the buffer contents.
PUBLIC char*rBufToStringAndFree(RBuf *buf)
 Conver the buffer contents to a string.
PUBLIC voidrClearList(RList *list)
 Clears the list of all items.
PUBLIC RHash*rCloneHash(RHash *master)
 Copy a hash table.
PUBLIC voidrCloseSocket(RSocket *sp)
 Close a socket.
PUBLIC voidrCompactBuf(RBuf *buf)
 Compact the buffer contents.
PUBLIC intrConnectSocket(RSocket *sp, cchar *host, int port, Ticks deadline)
 Connect a client socket.
PUBLIC voidrDefaultLogHandler(cchar *type, cchar *source, cchar *msg)
 The default RT log handler.
PUBLIC boolrEmitLog(cchar *type, cchar *source)
 Test if a log message should be emitted.
PUBLIC voidrFlushBuf(RBuf *buf)
 Flush the buffer contents.
PUBLIC char*rFormatLocalTime(cchar *format, Time time)
 Conver a time value to local time and format as a string.
PUBLIC RBuf*rFormatLogMsg(RBuf *buf, cchar *type, cchar *source, cchar *msg)
 Format a log message into a buffer.
PUBLIC char*rFormatUniversalTime(cchar *format, Time time)
 Conver a time value to universal time and format as a string.
PUBLIC voidrFreeBuf(RBuf *buf)
 Free a buffer.
PUBLIC voidrFreeFiber(RFiber *fiber)
 Free a fiber coroutine.
PUBLIC voidrFreeHash(RHash *hash)
 Free a hash table.
PUBLIC voidrFreeList(RList *list)
 Free a list.
PUBLIC voidrFreeSocket(RSocket *sp)
 Free a socket object.
PUBLIC voidrFreeWait(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 ssizerGetBlockFromBuf(RBuf *buf, char *blk, ssize count)
 Get a block of data from the buffer.
PUBLIC cchar*rGetBuf(RBuf *buf)
 Get the origin of the buffer content storage.
PUBLIC cchar*rGetBufEnd(RBuf *buf)
 Get a reference to the end of the buffer contents.
PUBLIC ssizerGetBufLength(RBuf *buf)
 Get the buffer content length.
PUBLIC ssizerGetBufSize(RBuf *buf)
 Get the current size of the buffer content storage.
PUBLIC ssizerGetBufSpace(RBuf *buf)
 Get the space available to store content.
PUBLIC cchar*rGetBufStart(RBuf *buf)
 Get the start of the buffer contents.
PUBLIC intrGetCharFromBuf(RBuf *buf)
 Get a character from the buffer.
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 TicksrGetElapsedTicks(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 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 intrGetHashLength(RHash *hash)
 Return the count of symbols in a symbol entry.
uint64rGetHiResTicks(void)
 Get the CPU tick count.
PUBLIC void*rGetItem(RList *list, int index)
 Get an list item.
PUBLIC intrGetListLength(RList *list)
 Get the number of items in the list.
PUBLIC intrGetLogFile(void)
 Get the log file file handle.
PUBLIC RLogHandlerrGetLogHandler(void)
 Return the currently configured log handler defined via rSetLogHandler
PUBLIC void*rGetNextItem(RList *list, int *lastIndex)
 Get the next item in the list.
PUBLIC RName*rGetNextName(RHash *hash, RName *next)
 Return the next symbol in a symbol entry.
PUBLIC intrGetOsError(void)
 Return the native O/S error code.
PUBLIC TicksrGetRemainingTicks(Ticks mark, Ticks timeout)
 Return the time remaining until a timeout has elapsed.
PUBLIC cchar*rGetServerName(void)
 Get the application server name string.
PUBLIC SocketrGetSocketHandle(RSocket *sp)
 Get the socket file descriptor.
PUBLIC intrGetState(void)
 Get the current R state.
PUBLIC char*rGetTempFile(cchar *dir, cchar *prefix)
 Get a temp filename.
PUBLIC TicksrGetTicks(void)
 Get the system time.
PUBLIC TimerGetTime(void)
 Get the time.
PUBLIC boolrGetTimeouts(void)
 Return true if timeouts are enabled.
PUBLIC intrGetWaitFd(void)
 Get the global wait descriptor.
PUBLIC voidrGracefulStop(void)
 Gracefully stop the app.
PUBLIC intrGrowBuf(RBuf *buf, ssize count)
 Grow the buffer.
PUBLIC intrGrowList(RList *list, int size)
 Grow the list to be at least the requested size in elements.
PUBLIC char*rHashToString(RHash *hash, cchar *join)
 Conver a hash of strings to a single string.
PUBLIC intrInit(RFiberProc fn, cvoid *arg, ssize stackSize)
 Initialize the runtime.
PUBLIC intrInitBuf(RBuf *buf, ssize size)
 Initialize the buffer and set the initial buffer size.
PUBLIC intrInitFibers(ssize stackSize)
 Initialize the fiber coroutine module.
PUBLIC intrInitLog()
 Initialize the tracing subsystem.
PUBLIC intrInitOs(void)
 Create and initialze the O/S dependent subsystem.
PUBLIC intrInitWait(void)
 Initialize the I/O wait subsystem.
PUBLIC intrInserCharToBuf(RBuf *buf, int c)
 Inser a character into the buffer.
PUBLIC intrInserItemAt(RList *list, int index, cvoid *item)
 Inser an item into a list at a specific position.
PUBLIC boolrIsFileAbs(cchar *path)
 Determine if a file path is an absolute path.
PUBLIC boolrIsLogSet(void)
 Test if the log has been configured.
PUBLIC boolrIsMain(void)
 Test if a fiber is the main fiber.
PUBLIC boolrIsSocketClosed(RSocket *sp)
 Test if the socket has been closed.
PUBLIC boolrIsSocketConnected(RSocket *sp)
 Determine if the socket has connected to a remote pper.
PUBLIC boolrIsSocketEof(RSocket *sp)
 Test if the other end of the socket has been closed.
PUBLIC boolrIsSocketHandshaking(RSocket *sp)
 Determine if the socket is partway through a TLS handshake.
PUBLIC boolrIsSocketSecure(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 char*rListToString(RList *list, cchar *join)
 Conver a list of strings to a single string.
PUBLIC intrListenSocket(RSocket *sp, cchar *host, int port, RSocketProc handler, void *arg)
 Listen on a server socket for incoming connections.
PUBLIC voidrLogConfig(void)
 Print the product configuration at the start of the log file.
PUBLIC intrLookAtLastCharInBuf(RBuf *buf)
 Peek at the last character in the buffer.
PUBLIC intrLookAtNextCharInBuf(RBuf *buf)
 Peek at the next character in the buffer.
PUBLIC boolrLookupEvent(REvent id)
 Lookup an event ID.
PUBLIC intrLookupItem(RList *list, cvoid *item)
 Find an item and return its index.
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 intrLookupStringItem(RList *list, cchar *str)
 Find a string item and return its index.
PUBLIC boolrMatchFile(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*rPopItem(RList *list)
 Pop an item.
PUBLIC voidrPushItem(RList *list, void *item)
 Push an item onto the list.
PUBLIC ssizerPutBlockToBuf(RBuf *buf, cchar *ptr, ssize size)
 Put a block to the buffer.
PUBLIC intrPutCharToBuf(RBuf *buf, int c)
 Put a character to the buffer.
PUBLIC ssizerPutIntToBuf(RBuf *buf, int64 i)
 Put an integer to the buffer.
PUBLIC ssizerPutStringToBuf(RBuf *buf, cchar *str)
 Put a string to the buffer.
PUBLIC ssizerPutSubToBuf(RBuf *buf, cchar *str, ssize count)
 Put a substring to the buffer.
PUBLIC ssizerPutToBuf(RBuf *buf, cchar *fmt, ...)
 Put a formatted string to the buffer.
PUBLIC char*rReadFile(cchar *path, ssize *lenp)
 Read data from a file.
PUBLIC ssizerReadSocket(RSocket *sp, char *buf, ssize bufsize, Ticks deadline)
 Read from a socket.
PUBLIC ssizerReadSocketSync(RSocket *sp, char *buf, ssize bufsize)
 Read from a socket.
PUBLIC intrRemoveItem(RList *list, cvoid *item)
 Remove an item from the list.
PUBLIC intrRemoveItemAt(RList *list, int index)
 Remove an item from the list.
PUBLIC intrRemoveName(RHash *hash, cchar *name)
 Remove a symbol entry from the hash table.
PUBLIC intrRemoveStringItem(RList *list, cchar *str)
 Remove a string item from the list.
PUBLIC intrReserveBufSpace(RBuf *buf, ssize need)
 Grow the buffer so that there is at least the needed minimum space available.
PUBLIC voidrResetBufIfEmpty(RBuf *buf)
 Reset the buffer.
PUBLIC voidrResetSocket(RSocket *sp)
 Reset a socket.
PUBLIC void*rResumeFiber(RFiber *fiber, void *result)
 Resume a fiber.
PUBLIC TicksrRunEvents(void)
 Run due events.
PUBLIC voidrServiceEvents(void)
 Service events.
PUBLIC intrSetAppName(cchar *name, cchar *title, cchar *version)
 Set the application name, title and version.
PUBLIC voidrSetDefaultSocketCa(cchar *ca)
 Set the default CA root certificate bundle.
PUBLIC voidrSetError(int error)
 Set the error code.
PUBLIC voidrSetFiberStack(ssize size)
 Set the default fiber stack size.
PUBLIC void*rSetItem(RList *list, int index, cvoid *item)
 Set a list item.
PUBLIC intrSetLog(cchar *logSpec, cchar *format, bool force)
 Initialize tracing.
PUBLIC voidrSetLogFilter(cchar *types, cchar *sources, bool force)
 Define a filter for log messages.
PUBLIC RLogHandlerrSetLogHandler(RLogHandler handler)
 Define a log handler routine that will be invoked to process log messages.
PUBLIC voidrSetMemHandler(RMemProc handler)
 Define a global memory exhaustion handler.
PUBLIC voidrSetOsError(int error)
 Set the O/S error code.
PUBLIC voidrSetSocketBlocking(RSocket *sp, bool on)
 Set a socket into blocking I/O mode.
PUBLIC voidrSetSocketCerts(RSocket *sp, cchar *key, cchar *cert, cchar *ca, cchar *revoke)
 Configure the socket TLS certificates.
PUBLIC voidrSetSocketCiphers(RSocket *sp, cchar *ciphers)
 Set the ciphers to use for communications.
PUBLIC voidrSetSocketVerify(RSocket *sp, int verifyPeer, int verifyIssuer)
 Set the socket TLS verification parameters.
PUBLIC voidrSetSocketWaitMask(RSocket *sp, int64 mask, Ticks deadline)
 Update the wait mask for a socket.
PUBLIC voidrSetState(int state)
 Set the R state.
PUBLIC voidrSetTimeouts(bool on)
 Control timeouts.
PUBLIC voidrSetWaitHandler(RWait *wp, RWaitProc handler, cvoid *arg, int64 mask)
 Define a wait handler function on a wait object.
PUBLIC voidrSetWaitMask(RWait *wp, int64 mask, Ticks deadline)
 Update the wait mask for a wait handler.
PUBLIC voidrSleep(Ticks ticks)
 Sleep a fiber for the requested number of milliseconds.
PUBLIC RList*rSorList(RList *list, RSortProc compare, void *ctx)
 Sor a list.
PUBLIC void*rSort(void *base, ssize num, ssize width, RSortProc compare, void *ctx)
 Quicksor.
PUBLIC intrSpawnFiber(RFiberProc fn, void *arg)
 Spawn a fiber coroutine.
PUBLIC REventrCreateEvent(REventProc proc, void *data, Ticks delay)
 Start a callback event.
PUBLIC voidrStartFiber(RFiber *fiber, void *data)
 Start a fiber coroutine.
PUBLIC voidrStop(void)
 Immediately stop the app.
PUBLIC intrStopEvent(REvent id)
 Stop an event.
PUBLIC voidrTermBuf(RBuf *buf)
 Terminate a buffer.
PUBLIC voidrTermFibers(void)
 Terminate the fiber coroutine module.
PUBLIC voidrTermLog(void)
 Terminate tracing.
PUBLIC voidrTermOs(void)
 Stop the O/S dependent subsystem.
PUBLIC voidrTermWait(void)
 Terminate the I/O wait subsystem.
PUBLIC intrWait(Ticks timeout)
 Wait for an I/O event.
PUBLIC void*rWaitForEvent(RWait *wp, int mask, Ticks deadline)
 Wait for an IO event on a wait object.
PUBLIC intrWalkDir(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 ssizerWriteFile(cchar *path, cchar *buf, ssize len, int mode)
 Write data to a file.
PUBLIC ssizerWriteSocket(RSocket *sp, cvoid *buf, ssize bufsize, Ticks deadline)
 Write to a socket.
PUBLIC ssizerWriteSocketSync(RSocket *sp, cvoid *buf, ssize len)
 Write to a socket.
PUBLIC void*rYieldFiber(void *value)
 Yield a fiber back to the main fiber.
PUBLIC void*ralloc(size_t size)
 Allocate a block of memory.
PUBLIC void*ralloct(RType type)
 Allocate an object of a given type.
PUBLIC voidrassert(cchar *loc, cchar *msg)
 Output an assert failed message.
PUBLIC voidrdebug(cchar *source, cchar *fmt, ...)
 Emit a debug message to the log.
PUBLIC voidrerror(cchar *source, cchar *fmt, ...)
 Emit an error message to the log.
PUBLIC voidrfree(void *ptr)
 Free a block of memory allocated via ralloc.
PUBLIC voidrinfo(cchar *source, cchar *fmt, ...)
 Emit an informational message to the log.
PUBLIC voidrlog(char *type, cchar *source, cchar *fmt, ...)
 Write a message to the error log file.
PUBLIC voidrlogv(cchar *type, cchar *source, cchar *fmt, va_list args)
 Write a message to the error log file.
PUBLIC voidrlog(cchar *source, cchar *fmt, ...)
 Emit a log message to the log.
PUBLIC char*scamel(cchar *str)
 Create a camel case version of the string.
PUBLIC intscaselesscmp(cchar *s1, cchar *s2)
 Compare strings ignoring case.
PUBLIC boolscaselessmatch(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 intscmp(cchar *s1, cchar *s2)
 Compare strings.
PUBLIC char*scontains(cchar *str, cchar *pattern)
 Find a pattern in a string.
PUBLIC ssizescopy(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 uintshash(cchar *str, ssize len)
 Compute a hash code for a string.
PUBLIC uintshashlower(cchar *str, ssize len)
 Compute a caseless hash code for a string.
PUBLIC char*sitos(int64 value)
 Conver an integer to a string.
PUBLIC char*sitosbuf(char *buf, ssize size, int64 value, int radix)
 Conver an integer to a string buffer.
PUBLIC char*sitosradix(int64 value, int radix)
 Conver an integer to a string.
PUBLIC char*sjoin(cchar *str, ...)
 Catenate strings.
PUBLIC cchar*sjoinArgs(int argc, cchar **argv, cchar *sep)
 Join an array of strings.
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 ssizeslen(cchar *str)
 Return the length of a string.
PUBLIC char*slower(char *str)
 Conver a string to lower case.
PUBLIC boolsmatch(cchar *s1, cchar *s2)
 Compare strings.
PUBLIC intsncaselesscmp(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 comparision.
PUBLIC char*snclone(cchar *str, ssize len)
 Clone a substring.
PUBLIC intsncmp(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 ssizesncopy(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 **last)
 Tokenize a string.
PUBLIC char*srchr(cchar *str, int c)
 Find a character in a string by searching backwards.
PUBLIC char*ssplit(char *str, cchar *delim, char **last)
 Split a string at a delimiter.
PUBLIC ssizesspn(cchar *str, cchar *set)
 Find the end of a spanning prefix.
PUBLIC boolsstarts(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, bool json)
 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 doublestof(cchar *str)
 Conver a string to a double.
PUBLIC int64stoi(cchar *str)
 Conver a string to an integer.
PUBLIC int64stoiradix(cchar *str, int radix, int *err)
 Conver 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)
 Conver a string to upper case.
PUBLIC voidszero(char *str)
 Erase the contents of a string.

Typedefs

REventProcCallback function for events.
RFiberFiber state.
RFiberContextFiber coroutine stack context.
RFiberProcFiber entry point function.
RHashProcHashing function to use for the table.
RListCompareProcList comparison procedure for soring.
RLogHandlerLog handler callback type.
RMemProcMemory exhaustion callback procedure.
RNamePer item structure.
RSortProcQuicksor callback function.
RWaitProcCallback function for IO wait events.
RWalkDirProcCallback function for rWalkDir
SocketArgument for sockets.
size_tUnsigned integral type.

Defines

#defineME_R_LOGGING   1
 Default for tracing is "on".
#defineR_DEFAULT_DATE   "%a %b %d %T %Y %Z"
 Default date format used in rFormatLocalTime/rFormatUniversalTime when no format supplied E.g.
#defineR_DYNAMIC_NAME   0x8
 Dynamic name provided, hash will free.
#defineR_DYNAMIC_VALUE   0x1
 Dynamic (allocated) value provided, hash will free.
#defineR_EVENT_ASYNC   1
 Windows async select.
#defineR_EVENT_EPOLL   2
 epoll_wait.
#defineR_EVENT_KQUEUE   3
 BSD kqueue.
#defineR_EVENT_SELECT   4
 traditional select().
#defineR_HASH_CASELESS   0x40
 Ignore case in comparisons.
#defineR_IO   0x6
 Wait mask for readable or writeable events.
#defineR_MEM_FAIL   0x4
 Memory allocation failed - immediate exit.
#defineR_MEM_LIMIT   0x2
 Memory use exceeds memory limit - invoking policy.
#defineR_MEM_TOO_BIG   0x8
 Memory allocation request is too big - immediate exit.
#defineR_MEM_WARNING   0x1
 Memory use exceeds warnHeap level limit.
#defineR_MODIFIED   0x200
 Wait mask for modify events.
#defineR_READABLE   0x2
 Wait mask for readable events.
#defineR_SOCKET_CLOSED   0x1
 RSocket has been closed.
#defineR_SOCKET_EOF   0x2
 Seen end of file.
#defineR_SOCKET_LISTENER   0x4
 RSocket is server listener.
#defineR_SOCKET_SERVER   0x8
 Socket is on the server-side.
#defineR_STATIC_NAME   0x10
 Static name provided no need to clone or free.
#defineR_STATIC_VALUE   0x2
 Static value provided, no need to clone or free.
#defineR_TEMPORAL_NAME   0x20
 Temporal name provided, hash will clone and free.
#defineR_TEMPORAL_VALUE   0x4
 Temporal value provided, hash will clone and free.
#defineR_TRIM_BOTH   0x3
 Flag for strim to trim from both the start and the end of the string.
#defineR_TRIM_END   0x2
 Flag for strim to trim from the end of the string.
#defineR_TRIM_START   0x1
 Flag for strim to trim from the start of the string.
#defineR_WALK_DEPTH_FIRST   0x1
 Flag for rGetFiles to do a depth-first traversal.
#defineR_WALK_DIRS   0x4
 Include hidden files starting with "." except for "." and "..".
#defineR_WALK_FILES   0x8
 Include hidden files starting with "." except for "." and "..".
#defineR_WALK_HIDDEN   0x2
 Include hidden files starting with "." except for "." and "..".
#defineR_WALK_MISSING   0x20
 Allow walking missing paths.
#defineR_WALK_RELATIVE   0x10
 Return paths relative to the original path.
#defineR_WRITABLE   0x4
 Wait mask for writable events.

RBuf

RBuf

Dynamic Buffer Module.

Description:
RBuf is a flexible, dynamic growable buffer structure. It has start and end pointers to the data buffer which act as read/write pointers. Routines are provided to get and put data into and out of the buffer and automatically advance the appropriate start/end pointer. By definition, the buffer is empty when the start pointer == the end pointer. Buffers can be created with a fixed size or can grow dynamically as more data is added to the buffer.

For performance, the specification of RBuf is deliberately exposed. All members of RBuf are implicitly public. However, it is still recommended that wherever possible, you use the accessor routines provided.
See Also:
rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
API Stability:
Internal.
Fields:
char *buf Actual buffer for data.
ssizebuflen Current size of buffer.
char *end Pointer one past the last data chr.
char *endbuf Pointer one past the end of buffer.
char *start Pointer to next data char.
PUBLIC void void rAddNullToBuf (RBuf *buf)

Add a null character to the buffer contents.

Description:
Add a null byte but do not change the buffer content lengths. The null is added outside the "official" content length. This is useful when calling rGetBufStart and using the returned pointer as a "C" string pointer.
Parameters:
bufBuffer created via rAllocBuf.
API Stability:
Evolving.
See Also:
RBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC void void rAdjustBufEnd (RBuf *buf, ssize count)

Adjust the buffer end position.

Description:
Adjust the buffer end position by the specified amount. This is typically used to advance the end position as content is appended to the buffer. Adjusting the start or end position will change the value returned by rGetBufLength. If using the rPutBlock or rPutChar routines, adjusting the end position is done automatically.
Parameters:
bufBuffer created via rAllocBuf.
countPositive or negative count of bytes to adjust the end position.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC void void rAdjustBufStart (RBuf *buf, ssize count)

Adjust the buffer start position.

Description:
Adjust the buffer start position by the specified amount. This is typically used to advance the start position as content is consumed. Adjusting the start or end position will change the value returned by rGetBufLength. If using the rGetBlock or rGetChar routines, adjusting the start position is done automatically.
Parameters:
bufBuffer created via rAllocBuf.
countPositive or negative count of bytes to adjust the start position.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC RBuf,* RBuf* rAllocBuf (ssize initialSize)
PUBLIC char,* char* rBufToString (RBuf *buf)

Return a reference to the buffer contents.

Parameters:
bufBuffer created via rAllocBuf.
Returns:
A pointer into the buffer data. Caller must not free.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC char,* char* rBufToStringAndFree (RBuf *buf)

Conver the buffer contents to a string.

The string is allocated and the buffer is freed
Parameters:
bufBuffer created via rAllocBuf.
Returns:
Allocated string.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC void void rCompactBuf (RBuf *buf)

Compact the buffer contents.

Description:
Compact the buffer contents by copying the contents down to start the the buffer origin.
Parameters:
bufBuffer created via rAllocBuf.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC void void rFlushBuf (RBuf *buf)

Flush the buffer contents.

Description:
Discard the buffer contents and reset the start end content pointers.
Parameters:
bufBuffer created via rAllocBuf.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC void void rFreeBuf (RBuf *buf)
PUBLIC ssize ssize rGetBlockFromBuf (RBuf *buf, char *blk, ssize count)

Get a block of data from the buffer.

Description:
Get a block of data from the buffer start and advance the start position. If the requested length is greater than the available buffer content, then return whatever data is available.
Parameters:
bufBuffer created via rAllocBuf.
blkDestination block for the read data.
countCount of bytes to read from the buffer.
Returns:
The count of bytes read into the block or -1 if the buffer is empty.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC cchar,* cchar* rGetBuf (RBuf *buf)

Get the origin of the buffer content storage.

Description:
Get a pointer to the start of the buffer content storage. This is always and allocated block.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
A pointer to the buffer content storage.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC cchar,* cchar* rGetBufEnd (RBuf *buf)

Get a reference to the end of the buffer contents.

Description:
Get a pointer to the location immediately after the end of the buffer contents.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
Pointer to the end of the buffer data contents. Points to the location one after the last data byte.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rGetBufLength (RBuf *buf)

Get the buffer content length.

Description:
Get the length of the buffer contents. This is not the same as the buffer size which may be larger.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
The length of the content stored in the buffer in bytes.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rGetBufSize (RBuf *buf)

Get the current size of the buffer content storage.

Description:
This returns the size of the memory block allocated for storing the buffer contents.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
The size of the buffer content storage.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rGetBufSpace (RBuf *buf)

Get the space available to store content.

Description:
Get the number of bytes available to store content in the buffer.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
The number of bytes available.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC cchar,* cchar* rGetBufStart (RBuf *buf)

Get the start of the buffer contents.

Description:
Get a pointer to the start of the buffer contents. Use rGetBufLength to determine the length of the content. Use rGetBufEnd to get a pointer to the location after the end of the content.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
Pointer to the start of the buffer data contents.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rGetCharFromBuf (RBuf *buf)

Get a character from the buffer.

Description:
Get the next byte from the buffer start and advance the start position.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
The character or -1 if the buffer is empty.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rGrowBuf (RBuf *buf, ssize count)

Grow the buffer.

Description:
Grow the storage allocated for content for the buffer. The new size must be less than the maximum limit specified via rAllocBuf or rInitBuf
Parameters:
bufBuffer created via rAllocBuf.
countCount of bytes by which to grow the buffer content size.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rInitBuf (RBuf *buf, ssize size)

Initialize the buffer and set the initial buffer size.

Description:
This initializes a buffer that is already allocated and is useful for static buffer declarations. This call sets the initial buffer content size. Setting a non-zero size will immediately grow the buffer to be this size.
Parameters:
bufBuffer created via rAllocBuf.
sizeSize to make the buffer.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rInserCharToBuf (RBuf *buf, int c)

Inser a character into the buffer.

Description:
Inser a character into to the buffer prior to the current buffer start point.
Parameters:
bufBuffer created via rAllocBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rLookAtLastCharInBuf (RBuf *buf)

Peek at the last character in the buffer.

Description:
Non-destructively return the last character from just prior to the end position in the buffer. The character is returned and the end position is not altered.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rLookAtNextCharInBuf (RBuf *buf)

Peek at the next character in the buffer.

Description:
Non-destructively return the next character from the start position in the buffer. The character is returned and the start position is not altered.
Parameters:
bufBuffer created via rAllocBuf.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rPutBlockToBuf (RBuf *buf, cchar *ptr, ssize size)

Put a block to the buffer.

Description:
Append a block of data to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via rAllocBuf.
ptrBlock to append.
sizeSize of block to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rPutCharToBuf (RBuf *buf, int c)

Put a character to the buffer.

Description:
Append a character to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via rAllocBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rPutIntToBuf (RBuf *buf, int64 i)

Put an integer to the buffer.

Description:
Append a integer to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via rAllocBuf.
iInteger to append to the buffer.
Returns:
Number of characters added to the buffer, otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rPutStringToBuf (RBuf *buf, cchar *str)

Put a string to the buffer.

Description:
Append a null terminated string to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via rAllocBuf.
strString to append.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rPutSubToBuf (RBuf *buf, cchar *str, ssize count)

Put a substring to the buffer.

Description:
Append a null terminated substring to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via rAllocBuf.
strString to append.
countPut at most count characters to the buffer.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rResetBufIfEmpty
PUBLIC ssize ssize rPutToBuf (RBuf *buf, cchar *fmt, ...)

Put a formatted string to the buffer.

Description:
Format a string and append to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via rAllocBuf.
fmtPrintf style format string.
...Variable arguments for the format string.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC int int rReserveBufSpace (RBuf *buf, ssize need)

Grow the buffer so that there is at least the needed minimum space available.

Description:
Grow the storage allocated for content for the buffer if required to ensure the minimum specified by "need" is available.
Parameters:
bufBuffer created via rAllocBuf.
needRequired free space in bytes.
Returns:
Zero if successful and otherwise a negative error code.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
PUBLIC void void rResetBufIfEmpty (RBuf *buf)

Reset the buffer.

Description:
If the buffer is empty, reset the buffer start and end pointers to the beginning of the buffer.
Parameters:
bufBuffer created via rAllocBuf.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf
PUBLIC void void rTermBuf (RBuf *buf)

Terminate a buffer.

Description:
This frees memory allocated by the buffer. This call should be used for buffers initialized via rInitBuf
Parameters:
bufBuffer created via rAllocBuf.
API Stability:
Evolving.
See Also:
RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetBufEnd, rGetBufLength, rGetBufSize, rGetBufSpace, rGetBufStart, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty

REvent

REvent

Event Subsystem.

Description:
R provides a simple based eventing mechanism. Events are described by REvent objects which are created and queued via rCreateEvent. Events are scheduled once unless restarted via rRestartEvent.
API Stability:
Internal.
Fields:
PUBLIC bool bool rLookupEvent (REvent id)

Lookup an event ID.

Parameters:
idEvent id allocated by rCreateEvent.
Returns:
True if the event exists.
API Stability:
Evolving.
See Also:
PUBLIC Ticks Ticks rRunEvents (void )

Run due events.

Returns:
Time delay till the next event.
API Stability:
Evolving.
See Also:
PUBLIC void void 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 thread.
API Stability:
Evolving.
See Also:
PUBLIC void void rSetWaitMask (RWait *wp, int64 mask, Ticks deadline)

Update the wait mask for a wait handler.

Parameters:
wpRWait object.
maskSet to R_READABLE or R_WRITABLE or both.
deadlineSystem time in ticks to wait until.
API Stability:
Evolving.
Returns:
Zero if successful.
See Also:
PUBLIC REvent REvent rCreateEvent (REventProc proc, void *data, Ticks delay)

Start a callback event.

Description:
This schedules an event to run once. The event can be rescheduled in the callback by invoking rRestartEvent.
Parameters:
procCallback procedure function. Signature is: void (*fn)(void *data, int id).
dataData reference to pass to the callback.
delayDelay in milliseconds in which to run the callback.
Returns:
A positive integer event ID.
API Stability:
Evolving.
See Also:
PUBLIC int int rStopEvent (REvent id)

Stop an event.

Parameters:
idEvent id allocated by rCreateEvent.
Returns:
Integer handle index. Otherwise return -1 on allocation errors.
API Stability:
Evolving.
See Also:
PUBLIC int int rWait (Ticks timeout)

Wait for an I/O event.

Description:
This is typically called by $rServiceEvents to wait for I/O events.
Parameters:
timeoutMaximum time in milliseconds to wait for an I/O event.
Returns:
Zero if successful.
API Stability:
Evolving.
See Also:
PUBLIC void,* void* rWaitForEvent (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:
wpRWait object.
maskSet to R_READABLE or R_WRITABLE or both.
deadlineSystem time in ticks to wait until.
API Stability:
Evolving.
See Also:

RFile

RFile

R File Module.

See Also:
API Stability:
Internal.
Fields:
PUBLIC int 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:
pathFilename to backup.
countNumber of backup copies to keep.
API Stability:
Evolving.
See Also:
RFile
PUBLIC cchar,* cchar* rBasename (cchar *path)

Return the basename (filename) portion of a filename.

Parameters:
pathFilename 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.
See Also:
RFile
PUBLIC char,* char* rGetAppDir (void )

Get the directory containing the application executable.

Returns:
An allocated string containing the application directory. Caller must free.
API Stability:
Evolving.
See Also:
RFile
PUBLIC char,* char* rGetCwd (void )

Get the current application working directory.

Returns:
An allocated string containing the working directory. Caller must free.
API Stability:
Evolving.
See Also:
RFile
PUBLIC RList,* 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:
baseBase directory from which to interpret the pattern. If the patternDirectory to list.
patternWild card patterns to match.
flagsSet 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. Use R_FILES_EXCLUDE with rGetFilesEx to remove matching files from the result set.
Returns:
A list (RList) of filenames.
API Stability:
Evolving.
See Also:
RFile
PUBLIC RList,* 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:
resultsInstance of RList. See rAllocList
baseBase directory from which to interpret the pattern. If the patternDirectory to list.
patternWild card patterns to match.
flagsSet 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. Use R_FILES_EXCLUDE with rGetFilesEx to remove matching files from the result set.
Returns:
A list (RList) of filenames.
API Stability:
Evolving.
See Also:
RFile
PUBLIC char,* 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:
dirDirectory to contain the temporary file. If null, use system default temp directory (/tmp).
prefixOptional filename prefix.
Returns:
An allocated string containing the file name. Caller must free.
API Stability:
Evolving.
See Also:
RFile
PUBLIC bool bool rIsFileAbs (cchar *path)

Determine if a file path is an absolute path.

Parameters:
pathFilename path to test.
Returns:
True if the path is an absolute path.
API Stability:
Evolving.
See Also:
RFile
PUBLIC char,* 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:
baseDirectory filename to use as the base.
otherOther filename path to join to the base filename.
Returns:
Allocated string containing the resolved filename.
API Stability:
Evolving.
See Also:
RFile
PUBLIC char,* 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:
bufDestination path buffer.
bufsizeSize of buf.
baseDirectory filename to use as the base.
otherOther filename path to join to the base filename.
Returns:
Allocated string containing the resolved filename.
API Stability:
Evolving.
See Also:
RFile
PUBLIC bool 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:
pathFilename to test.
patternWild card patterns to match.
Returns:
True if the path matches the pattern.
API Stability:
Evolving.
See Also:
RFile
PUBLIC char,* char* rReadFile (cchar *path, ssize *lenp)

Read data from a file.

Description:
Reads data from a file.
Parameters:
pathFilename to read.
lenpPointer to receive the length of the file read.
Returns:
The contents of the file in an allocated string.
API Stability:
Evolving.
See Also:
RFile
PUBLIC int 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:
dirBase directory from which to interpret the pattern.
patternWild card patterns to match.
callbackCallback function of the signature RWalkDirProc
argArgument to callback function.
flagsSet 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. Use R_FILES_EXCLUDE with rGetFilesEx to remove matching files from the result set.
API Stability:
Evolving.
See Also:
RFile
PUBLIC ssize 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:
pathFilename to write.
bufBuffer of data to write to the file.
lenLength of the buffer.
modeCreate file mode.
Returns:
The length of bytes written to the file. Should equal len.
API Stability:
Evolving.
See Also:
RFile

RHash

RHash

Has table structure.

Description:
The hash structure supports growable hash tables collision resistant hashes.
See Also:
RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
API Stability:
Evolving.
Fields:
int *buckets Hash collision bucket table.
uintflags Hash control flags.
RHashProcfn Hash function.
intfree Free list of names.
uintlength Number of names in the hash.
struct RName *names Hash items.
uintnumBuckets Number of buckets in the first-level hash.
uintsize Size of allocated names.
PUBLIC RName,* 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:
hashHash table returned via rAllocHash.
nameString name to associate with the data.
flagsSet 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.
fmtPrintf style format string.
...Variable arguments for the format string.
Returns:
Added RName reference.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC RName,* RName* rAddIntName (RHash *hash, cchar *name, int64 value)

Add a name and integer value.

Parameters:
hashHash table returned via rAllocHash.
nameString name to associate with the data.
valueA 64 bit integer value.
Returns:
Added RName reference.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC RName,* 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:
tableHash table returned via rAllocHash.
nameString name to associate with the data.
ptrArbitrary pointer to associate with the name in the table.
flagsSet 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.
See Also:
RHash, RName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC RName,* 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:
hashHash table returned via rAllocHash.
nameString name to associate with the data.
nameSizeSize of the name string.
valueValue string to store.
valueSizeLength of string value.
Returns:
Added RName reference.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC RHash,* 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:
sizeEstimated number of names in the hash table. Set to 0 or -1 to get a default (small) hash table.
flagsSet 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_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.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC RHash,* RHash* rCloneHash (RHash *master)

Copy a hash table.

Parameters:
masterOriginal hash table.
Returns:
Returns a pointer to the new allocated hash table.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC void void rFreeHash (RHash *hash)

Free a hash table.

Parameters:
hashHash table to free.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC int 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:
hashSymbol table returned via rAllocHash.
Returns:
Integer count of the number of entries.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC RName,* 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:
hashHash table hash returned via rAllocHash.
nextIndex of next name.
Returns:
Pointer to the first entry in the symbol table.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC char,* char* rHashToString (RHash *hash, cchar *join)

Conver a hash of strings to a single string.

Parameters:
hashHash pointer returned from rCreateHash.
joinString to use as the element join string.
Returns:
String consisting of the joined hash values.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
PUBLIC void,* 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:
hashSymbol table returned via rAllocHash.
nameString name of the symbole entry to delete.
Returns:
Value associated with the name when the entry was insered via rInserSymbol.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupNameEntry, rRemoveName
PUBLIC RName,* 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:
hashSymbol table returned via rAllocHash.
nameString name of the symbole entry to delete.
Returns:
RName for the entry.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rRemoveName
PUBLIC int 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:
hashSymbol table returned via rAllocHash.
nameString name of the symbole entry to delete.
Returns:
Returns zero if successful, otherwise a negative RT error code is returned.
API Stability:
Evolving.
See Also:
RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry

RList

RList

List data structure.

Description:
The RList is a dynamic, growable list suitable for storing pointers to arbitrary objects.
See Also:
RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
API Stability:
Internal.
Fields:
uintcapacity Current list capacity.
uintflags Items should be freed when list is freed.
void **items List item data.
uintlength Current length of the list contents.
PUBLIC int int rAddItem (RList *list, cvoid *item)

Add an item to a list.

Description:
Add the specified item to the list. The list must have been previously created via rAllocList. The list will grow as required to store the item.
Parameters:
listList pointer returned from rAllocList
itemPointer to item to store.
Returns:
Returns a positive list index for the insered item. If the item cannot be insered due to a memory allocation failure, -1 is returned.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rAddNullItem (RList *list)

Add a null item to the list.

Description:
Add a null item to the list. This item does not count in the length returned by rGetListLength and will not be visible when iterating using rGetNextItem
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC RList,* RList* rAllocList (int size, int flags)

Allocate a list.

Description:
Creates an empty list. RList's can store generic pointers. They automatically grow as required when items are added to the list.
Parameters:
sizeInitial capacity of the list. Set to < 0 to get a growable list with a default initial size. Set to 0 to to create the list but without any initial list storage. Then call rSetListLimits to define the initial list size.
flagsSet to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. Default is R_STATIC_VALUE.
Returns:
Returns a pointer to the list.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC void void rClearList (RList *list)

Clears the list of all items.

Description:
Resets the list length to zero and clears all items.
Parameters:
listList pointer returned from rAllocList.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC void void rFreeList (RList *list)
PUBLIC void,* void* rGetItem (RList *list, int index)

Get an list item.

Description:
Get an list item specified by its index.
Parameters:
listList pointer returned from rAllocList.
indexItem index into the list. Indexes have a range from zero to the lenghth of the list - 1.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rGetListLength (RList *list)

Get the number of items in the list.

Description:
Returns the number of items in the list. This will always be less than or equal to the list capacity.
Parameters:
listList pointer returned from rAllocList.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC void,* void* rGetNextItem (RList *list, int *lastIndex)

Get the next item in the list.

Description:
Returns the value of the next item in the list.
Parameters:
listList pointer returned from rAllocList.
lastIndexPointer to an integer that will hold the last index retrieved.
Returns:
Next item in list or null for an empty list or after the last item.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rInserItemAt (RList *list, int index, cvoid *item)

Inser an item into a list at a specific position.

Description:
Inser the item into the list before the specified position. The list will grow as required to store the item.
Parameters:
listList pointer returned from rAllocList
indexLocation at which to store the item. The previous item at this index is moved up to make room.
itemPointer to item to store.
Returns:
The position index (positive integer) if successful. If the item cannot be insered due to a memory allocation failure, -1 is returned.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC char,* char* rListToString (RList *list, cchar *join)

Conver a list of strings to a single string.

This uses the specified join string between the elements
Parameters:
listList pointer returned from rAllocList.
joinString to use as the element join string. May be null.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rLookupItem (RList *list, cvoid *item)

Find an item and return its index.

Description:
Search for an item in the list and return its index.
Parameters:
listList pointer returned from rAllocList.
itemPointer to value stored in the list.
Returns:
Positive list index if found, otherwise a negative RT error code.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rLookupStringItem (RList *list, cchar *str)

Find a string item and return its index.

Description:
Search for the first matching string in the list and return its index.
Parameters:
listList pointer returned from rAllocList.
strPointer to string to look for.
Returns:
Positive list index if found, otherwise a negative RT error code.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC void,* void* rPopItem (RList *list)

Pop an item.

Description:
Treat the list as a stack and pop the last pushed item.
Parameters:
listList pointer returned from rAllocList.
Returns:
The last pushed item. If the list is empty, returns NULL.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC void void rPushItem (RList *list, void *item)

Push an item onto the list.

Description:
Treat the list as a stack and push the last pushed item.
Parameters:
listList pointer returned from rAllocList.
itemItem to push onto the list.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rRemoveItem (RList *list, cvoid *item)

Remove an item from the list.

Description:
Search for a specified item and then remove it from the list.
Parameters:
listList pointer returned from rAllocList.
itemItem pointer to remove.
Returns:
The positive index of the removed item, otherwise a negative RT error code.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rRemoveItemAt (RList *list, int index)

Remove an item from the list.

Description:
Removes the element specified by index, from the list. The list index is provided by rInserItem.
Returns:
The positive index of the removed item, otherwise a negative RT error code.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveStringItem, rSetItem, rSorList
PUBLIC int int rRemoveStringItem (RList *list, cchar *str)

Remove a string item from the list.

Description:
Search for the first matching string and then remove it from the list.
Parameters:
listList pointer returned from rAllocList.
strString value to remove.
Returns:
The positive index of the removed item, otherwise a negative RT error code.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rSetItem, rSorList
PUBLIC void,* void* rSetItem (RList *list, int index, cvoid *item)

Set a list item.

Description:
Update the list item stored at the specified index.
Parameters:
listList pointer returned from rAllocList.
indexLocation to update.
itemPointer to item to store.
Returns:
The old item previously at that location index.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSorList
PUBLIC RList,* RList* rSorList (RList *list, RSortProc compare, void *ctx)

Sor a list.

Description:
Sor a list using the sor ordering dictated by the supplied compare function.
Parameters:
listList pointer returned from rAllocList.
compareComparison function. If null, then a default string comparison is used.
ctxContext to provide to comparison function.
Returns:
The sorted list.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem
PUBLIC void,* void* rSort (void *base, ssize num, ssize width, RSortProc compare, void *ctx)

Quicksor.

Description:
This is a quicksor with a context argument.
Parameters:
baseBase of array to sor.
numNumber of array elements.
widthWidth of array elements.
compareComparison function.
ctxContext argument to provide to comparison function.
Returns:
The base array for chaining.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList

RLog

RLog

Log Services.

See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
API Stability:
Internal.
Fields:
PUBLIC void void assert (bool cond)

Asser that a condition is true.

Parameters:
condBoolean result of a conditional test.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rassert (cchar *loc, cchar *msg)

Output an assert failed message.

Description:
This will emit an assert failed message to the standard error output. It may bypass the tracing system.
Parameters:
locSource code location string. Use R_LOC to define a file name and line number string suitable for this parameter.
msgSimple string message to output.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rBackupLog (void )

Backup a log.

API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rdebug (cchar *source, cchar *fmt, ...)

Emit a debug message to the log.

Parameters:
sourceModule emitting the log message.
fmtPrintf style format string. Variable number of arguments to.
...Variable arg list from va_list.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rDefaultLogHandler (cchar *type, cchar *source, cchar *msg)

The default RT log handler.

Parameters:
typeLog message type.
sourceSource of the message.
msgLog message.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC bool bool rEmitLog (cchar *type, cchar *source)

Test if a log message should be emitted.

Description:
This call enables routines to test if messages should be logged for a given type/source pair.
Parameters:
typeLog message type string.
sourceLog message source.
Returns:
True if the message should be logged.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rerror (cchar *source, cchar *fmt, ...)

Emit an error message to the log.

Parameters:
sourceModule emitting the log message.
fmtPrintf style format string. Variable number of arguments to.
...Variable arg list from va_list.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog
PUBLIC RBuf,* RBuf* rFormatLogMsg (RBuf *buf, cchar *type, cchar *source, cchar *msg)

Format a log message into a buffer.

Description:
This formats the log message according to the current log format string.
Parameters:
bufRBuf instance.
typeLog message type string.
sourceLog message source.
msgMessage to log.
Returns:
The buffer suitable for chaining calls.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC int int rGetLogFile (void )

Get the log file file handle.

Description:
Returns the file handle used for tracing.
Returns:
An file handle.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogHandler, rSetLog, rerror
PUBLIC RLogHandler RLogHandler rGetLogHandler (void )

Return the currently configured log handler defined via rSetLogHandler

API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rSetLog, rerror
PUBLIC void void rinfo (cchar *source, cchar *fmt, ...)

Emit an informational message to the log.

Parameters:
sourceModule emitting the log message.
fmtPrintf style format string. Variable number of arguments to.
...Variable arg list from va_list.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC int int rInitLog ()

Initialize the tracing subsystem.

API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC bool bool rIsLogSet (void )

Test if the log has been configured.

Returns:
True if the log has been defined.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rlog (char *type, cchar *source, cchar *fmt, ...)

Write a message to the error log file.

Description:
Send a message to the RT error tracing subsystem. The purpose of the error log is to record essential configuration and error conditions. Per-request log typically is sent to a separate log log.

By default, error log messages are sent to the standard output. Applications may redirect output by installing a log handler using rSetLogHandler.

Log messages should be a single text line to facilitate machine processing of log files.

Log typically is enabled in both debug and release builds and may be controlled via the build define ME_R_LOGGING which is typically set via the MakeMe setting "tracing: true".

Parameters:
typeMessage type.
sourceModule emitting the log message.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
Remarks:
Rlog is highly useful as a debugging aid.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rLogConfig (void )

Print the product configuration at the start of the log file.

API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rlogv (cchar *type, cchar *source, cchar *fmt, va_list args)

Write a message to the error log file.

Description:
Send a message to the RT error tracing subsystem. The purpose of the error log is to record essential configuration and error conditions. Per-request log typically is sent to a separate log log.

By default, error log messages are sent to the standard output. Applications may redirect output by installing a log handler using rSetLogHandler.

Log messages should be a single text line to facilitate machine processing of log files.

Log typically is enabled in both debug and release builds and may be controlled via the build define ME_R_LOGGING which is typically set via the MakeMe setting "tracing: true".

Parameters:
typeMessage type.
sourceModule emitting the log message.
fmtPrintf style format string. Variable number of arguments to.
argsVariable arg list from va_list.
Remarks:
Rlog is highly useful as a debugging aid.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rSetError (int error)

Set the error code.

Description:
Set errno or equivalent.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC int int rSetLog (cchar *logSpec, cchar *format, bool force)

Initialize tracing.

Parameters:
logSpecThe log spec is of the form: "destination:filter". The destination may be a filename, "stdout", "stderr" or "none". The log filter portion is of the form: "types:sources" and is passed to rSetLogFilter.
formatThe log pattern to use to format the message. The format can use Letter tokens that are expanded at runtime. The tokens supported are: 'A' for the application name, 'D' for the local datetime, 'H' for the system hostname, 'P' for the process ID , 'S' for the message source, and 'T' for the log message type.
forceSet to true to overwrite a previous definition.
Returns:
Zero if successful, otherwise a negative R error code.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rerror
PUBLIC void void rSetLogFilter (cchar *types, cchar *sources, bool force)

Define a filter for log messages.

Parameters:
typesComma separated list of types to emit. Can prefix a type with "!" to subtract from the list. Defaults to "error, info".
sourcesComma separated list of sources to emit. Can prefix a type with "!" to subtract from the list. Defaults to "all".
forceSet to true to overwrite a previous definition.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC RLogHandler RLogHandler rSetLogHandler (RLogHandler handler)

Define a log handler routine that will be invoked to process log messages.

Parameters:
handlerLog handler callback function.
Returns:
The previous log handler function.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rSetTimeouts (bool on)

Control timeouts.

Parameters:
onSet to false to disable timeouts for debugging.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rTermLog (void )

Terminate tracing.

API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror
PUBLIC void void rlog (cchar *source, cchar *fmt, ...)

Emit a log message to the log.

Parameters:
sourceModule emitting the log message.
fmtPrintf style format string. Variable number of arguments to.
...Variable arg list from va_list.
API Stability:
Evolving.
See Also:
RLogHandler, rGetLogFile, rGetLogHandler, rSetLog, rerror

RString

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.
See Also:
scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
API Stability:
Internal.
Fields:
PUBLIC char,* 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:
strPointer to the block to duplicate.
Returns:
Returns a newly allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC int 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:
s1First string to compare.
s2Second 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.
See Also:
RString, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC bool 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:
s1First string to compare.
s2Second string to compare.
Returns:
Returns true if the strings are equivalent, otherwise false.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
strString to examine.
cCharacter 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.
See Also:
RString, scaselesscmp, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* sclone (cchar *str)

Clone a string.

Description:
Copy a string into a newly allocated block.
Parameters:
strPointer to the block to duplicate.
Returns:
Returns a newly allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC int 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:
s1First string to compare.
s2Second 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.
See Also:
RString, scaselesscmp, schr, sclone, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* scontains (cchar *str, cchar *pattern)

Find a pattern in a string.

Description:
Locate the first occurrence of pattern in a string.
Parameters:
strPointer to the string to search.
patternString 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC ssize 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.
Parameters:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string in characters.
srcString to copy.
Returns:
The number of characters in the target string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC cchar,* cchar* sends (cchar *str, cchar *suffix)

Test if the string ends with a given pattern.

Parameters:
strString to examine.
suffixPattern to search for.
Returns:
Returns a pointer to the start of the pattern if found. Otherwise returns NULL.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
fmtPrintf style format string.
...Variable arguments for the format string.
Returns:
Returns a newly allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
bufPointer to the buffer.
maxSizeSize of the buffer.
fmtPrintf style format string.
...Variable arguments to format.
Returns:
The buffer.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
bufPointer to the buffer.
maxSizeSize of the buffer.
fmtPrintf style format string.
argsVarargs argument obtained from va_start.
Returns:
The buffer;.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
fmtPrintf style format string.
argsVarargs argument obtained from va_start.
Returns:
Returns a newly allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC uint uint shash (cchar *str, ssize len)

Compute a hash code for a string.

Parameters:
strString to examine.
lenLength in characters of the string to include in the hash code.
Returns:
Returns an unsigned integer hash code.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC uint 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:
strString to examine.
lenLength in characters of the string to include in the hash code.
Returns:
Returns an unsigned integer hash code.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* sitos (int64 value)

Conver an integer to a string.

Description:
This call convers the supplied 64 bit integer to a string using base 10.
Parameters:
valueInteger value to conver.
Returns:
An allocated string with the convered number.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* sitosbuf (char *buf, ssize size, int64 value, int radix)

Conver 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:
bufPointer to the buffer that will hold the string.
sizeSize of the buffer.
valueInteger value to conver.
radixThe base radix to use when encoding the number.
Returns:
Returns a reference to the string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* sitosradix (int64 value, int radix)

Conver an integer to a string.

Description:
This call convers the supplied 64 bit integer to a string according to the specified radix.
Parameters:
valueInteger value to conver.
radixThe base radix to use when encoding the number.
Returns:
An allocated string with the convered number.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
strFirst string to catentate.
...Variable number of string arguments to append. Terminate list with NULL.
Returns:
Returns an allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC cchar,* cchar* sjoinArgs (int argc, cchar **argv, cchar *sep)

Join an array of strings.

Parameters:
argcnumber of strings to join.
argvArray of strings.
sepSeparator string to use. If NULL, then no separator is used.
Returns:
A single joined string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
strFirst string to catentate.
fmtFirst string to catentate.
...Varargs argument obtained from va_start.
Returns:
Returns an allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* sjoinv (cchar *str, va_list args)

Catenate strings.

Description:
This catenates strings together.
Parameters:
strFirst string to catentate.
argsVarargs argument obtained from va_start.
Returns:
Returns an allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC ssize 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:
strString to measure.
Returns:
The length of the string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* slower (char *str)

Conver a string to lower case.

Description:
Conver a string to its lower case equivalent.
Parameters:
strString to conver.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC bool bool smatch (cchar *s1, cchar *s2)

Compare strings.

Description:
Compare two strings. This is similar to scmp but it returns a boolean.
Parameters:
s1First string to compare.
s2Second string to compare.
Returns:
Returns true if the strings are equivalent, otherwise false.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC int 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:
s1First string to compare.
s2Second string to compare.
lenLength 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* sncaselesscontains (cchar *str, cchar *pattern, ssize limit)

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

Description:
Locate the first occurrence of pattern in a string, but do not search more than the given character limit. Use a caseless comparision.
Parameters:
strPointer to the string to search.
patternString pattern to search for.
limitCount 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* snclone (cchar *str, ssize len)

Clone a substring.

Description:
Copy a substring into a newly allocated block.
Parameters:
strPointer to the block to duplicate.
lenNumber 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC int 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:
s1First string to compare.
s2Second string to compare.
lenLength 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
strPointer to the string to search.
patternString pattern to search for.
limitCount 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC ssize 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:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string in characters.
srcString to copy.
lenMaximum 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
strString to examine.
setSet 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* sptok (char *str, cchar *pattern, char **last)

Tokenize a string.

Description:
Split a string into tokens using a string pattern as delimiters.
Parameters:
strString to tokenize.
patternString pattern to use for token delimiters.
lastLast token pointer.
Returns:
Returns a pointer to the next token.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
strString to examine.
cCharacter to scan for.
Returns:
Returns a reference in the string to the requested character. Returns NULL if none found.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* 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:
strString to tokenize.
delimSet of characters that are used as token separators.
lastReference 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC ssize 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:
strString to examine.
setSet 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.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC bool bool sstarts (cchar *str, cchar *prefix)

Test if the string starts with a given pattern.

Parameters:
strString to examine.
prefixPattern to search for.
Returns:
Returns true if the pattern was found. Otherwise returns zero.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* ssub (cchar *str, ssize offset, ssize length)

Create a substring.

Parameters:
strString to examine.
offsetStaring offset within str for the beginning of the substring.
lengthLength of the substring in characters.
Returns:
Returns a newly allocated substring.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* stemplate (cchar *str, void *tokens, bool json)

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

Tokens are ${variable} references
Parameters:
strString to expand.
tokensHash table of token values to use.
jsonReserved and unused.
Returns:
An expanded string. May return the original string if no "$" references are present.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stitle, stok, strim, supper
PUBLIC char,* 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:
strPointer to the block to duplicate.
Returns:
Returns a newly allocated string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stok, strim, supper
PUBLIC double double stof (cchar *str)

Conver a string to a double.

Description:
This call convers the supplied string to a double.
Parameters:
strPointer to the string to parse.
Returns:
The double equivalent value of the string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC int64 int64 stoi (cchar *str)

Conver a string to an integer.

Description:
This call convers the supplied string to an integer using base 10.
Parameters:
strPointer to the string to parse.
Returns:
The integer equivalent value of the string.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC int64 int64 stoiradix (cchar *str, int radix, int *err)

Conver a string to an integer.

Description:
This call convers the supplied string to an integer using the specified radix (base).
Parameters:
strPointer to the string to parse.
radixBase to use when parsing the string.
errReturn error code. Set to 0 if successful.
Returns:
The integer equivalent value of the string.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* stok (char *str, cchar *delim, char **last)

Tokenize a string.

Description:
Split a string into tokens using a character set as delimiters.
Parameters:
strString to tokenize.
delimSet of characters that are used as token separators.
lastLast token pointer.
Returns:
Returns a pointer to the next token.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, strim, supper
PUBLIC struct,RList,* struct RList* stolist (cchar *src)

String to list.

This parses the string into space separated arguments. Single and double quotes are supported
Parameters:
srcSource string to parse.
Returns:
List of arguments.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper
PUBLIC char,* char* strim (char *str, cchar *set, int where)

Trim a string.

Description:
Trim leading and trailing characters off a string. The original string is not modified and the return value is a newly allocated string.
Parameters:
strString to trim.
setString of characters to remove.
whereFlags to indicate trim from the start, end or both. Use R_TRIM_START, R_TRIM_END, R_TRIM_BOTH.
Returns:
Returns a newly allocated trimmed string. May not equal str.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, supper
PUBLIC char,* char* supper (char *str)

Conver a string to upper case.

Description:
Conver a string to its upper case equivalent.
Parameters:
strString to conver.
Returns:
Returns a pointer to the convered string. Will always equal str.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim
PUBLIC void void szero (char *str)

Erase the contents of a string.

Parameters:
strString to erase.
API Stability:
Evolving.
See Also:
RString, scaselesscmp, schr, sclone, scmp, scontains, scopy, sends, sfmt, sfmtbuf, sfmtbufv, sfmtv, shash, shashlower, sjoin, sjoinv, slen, slower, smatch, sncaselesscmp, snclone, sncmp, sncontains, sncopy, spbrk, srchr, sspn, sstarts, ssub, stemplate, stitle, stok, strim, supper

RWait

RWait

Wait object.

Description:
The RWait service provides a flexible IO waiting mechansim.
API Stability:
Evolving.
Fields:
cvoid *arg Argument to pass to the handler.
Ticksdeadline System deadline time to wait until.
intfd File descriptor to wait upon.
RFiber *fiber Fiber coroutine.
RWaitProchandler Handler function to invoke as the entrypoint in the fiber coroute.
PUBLIC RWait,* RWait* rAllocWait (int fd)

Allocate a wait object for a file descriptor.

Returns:
A RWait object.
API Stability:
Evolving.
See Also:
PUBLIC void void rFreeWait (RWait *wp)

Free a wait object.

API Stability:
Evolving.
See Also:
PUBLIC int int rInitWait (void )

Initialize the I/O wait subsystem.

Returns:
Zero if successful.
API Stability:
Evolving.
See Also:
PUBLIC void void rSetWaitHandler (RWait *wp, RWaitProc handler, cvoid *arg, int64 mask)

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:
wpRWait object.
handlerFunction handler to invoke as the entrypoint in the new coroutine fiber.
argParameter argument to pass to the handler.
maskSet to R_READABLE or R_WRITABLE or both.
API Stability:
Evolving.
See Also:
PUBLIC void void rTermWait (void )

Terminate the I/O wait subsystem.

API Stability:
Evolving.
See Also:

Functions

PUBLIC void,* 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:
sizeSize 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 void 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:
causeSet to R_MEM_WARNING, R_MEM_LIMIT, R_MEM_FAIL or R_MEM_TO_BIG.
sizeSize in bytes of the failing allocation.
API Stability:
Evolving.
PUBLIC RFiber,* RFiber* rAllocFiber (RFiberProc fn, cvoid *data)

Allocate a fiber coroutine object.

Description:
This allocates a new fiber coroutine. Use rStartFiber to launch.
Parameters:
fnFiber entry point.
dataEntry point argument.
Returns:
A fiber object.
API Stability:
Internal.
PUBLIC RSocket,* RSocket* rAllocSocket (void )

Allocate a socket object.

Returns:
A socket object instance.
API Stability:
Evolving.
PUBLIC void,* void* ralloct (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:
typeRType 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 void 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 void rCloseSocket (RSocket *sp)

Close a socket.

Description:
Close a socket.
Parameters:
spSocket object returned from rAllocSocket.
API Stability:
Evolving.
PUBLIC int 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:
spSocket object returned via rAllocSocket.
hostHost or IP address to connect to.
portTCP/IP port number to connect to.
deadlineMaximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a deadline.
Returns:
Zero if successful.
API Stability:
Evolving.
PUBLIC char,* char* rFormatLocalTime (cchar *format, Time time)

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

Description:
R replacement for ctime.
Parameters:
formatTime format string. See rFormatUniversalTime for time formats.
timeTime to format. Use rGetTime to retrieve the current time.
Returns:
The formatting time string. Caller msut free.
API Stability:
Evolving.
PUBLIC char,* char* rFormatUniversalTime (cchar *format, Time time)

Conver 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:
formatTime 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"
"%T %F "12:12:21 2007-01-03"
"%v "07-Jul-2003"
RFC3399: "%FT%TZ" "1985-04-12T23:20:50.52Z" which is April 12 1985, 23:20.50 and 52 msec

timeTime to format. Use rGetTime to retrieve the current time.
Returns:
The formatting time string. Caller must free.
API Stability:
Evolving.
PUBLIC void void rfree (void *ptr)

Free a block of memory allocated via ralloc.

Description:
This releases a block of memory allocated via rAllocMem.
Parameters:
ptrPointer 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 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:
fiberFiber to free.
API Stability:
Internal.
PUBLIC void void rFreeSocket (RSocket *sp)

Free a socket object.

API Stability:
Evolving.
PUBLIC cchar,* 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 char,* 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. This routine is not thread r.
Parameters:
formatDate 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 Ticks rGetElapsedTicks (Ticks mark)

Get the elapsed time since a ticks mark.

Create the ticks mark with rGetTicks()
Parameters:
markStaring time stamp.
Returns:
The time elapsed since the mark was taken.
API Stability:
Evolving.
PUBLIC cchar,* cchar* rGetError (int error)

Return a string representation of an R error code.

Parameters:
errorAn 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,* RFiber* rGetFiber (void )

Get the current fiber object.

Returns:
Fiber Fiber object.
API Stability:
Evolving.
PUBLIC void,* void* rGetFiberStack (void )

Get the base address of the fiber stack.

Returns:
A pointer to the base of the fiber stack.
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 int 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 Ticks rGetRemainingTicks (Ticks mark, Ticks timeout)

Return the time remaining until a timeout has elapsed.

Parameters:
markStaring time stamp.
timeoutTime in milliseconds.
Returns:
Time in milliseconds until the timeout elapses.
API Stability:
Evolving.
PUBLIC cchar,* cchar* rGetServerName (void )

Get the application server name string.

Returns:
A string containing the application server name string.
API Stability:
Evolving.
PUBLIC Socket Socket rGetSocketHandle (RSocket *sp)

Get the socket file descriptor.

Description:
Get the file descriptor associated with a socket.
Parameters:
spSocket object returned from rAllocSocket.
Returns:
The Socket file descriptor used by the O/S for the socket.
API Stability:
Evolving.
PUBLIC int int rGetState (void )

Get the current R state.

Returns:
Returns R_RUNNING, R_STOPPING or R_STOPPED.
API Stability:
Evolving.
PUBLIC Ticks 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 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 bool rGetTimeouts (void )

Return true if timeouts are enabled.

Returns:
True if timeouts are enabled.
API Stability:
Evolving.
PUBLIC int int rGetWaitFd (void )

Get the global wait descriptor.

Returns:
The wait file descriptor used by epoll and kqueue.
API Stability:
Evolving.
PUBLIC void void rGracefulStop (void )

Gracefully stop the app.

Description:
Queued events will be serviced.
API Stability:
Evolving.
PUBLIC int int rGrowList (RList *list, int size)

Grow the list to be at least the requested size in elements.

Parameters:
listList pointer returned from rAllocList.
sizeRequired minimum size for the list.
API Stability:
Evolving.
PUBLIC int int rInit (RFiberProc fn, cvoid *arg, ssize stackSize)

Initialize the runtime.

Description:
This routine should be called at startup from main().
Parameters:
fnFiber function to start.
argArgument to the fiber function.
stackSizeSize of the fiber coroutine stacks.
Returns:
Zero if successful.
API Stability:
Evolving.
PUBLIC int int rInitFibers (ssize stackSize)

Initialize the fiber coroutine module.

Parameters:
stackSizeDefault size of fiber stacks in bytes.
Returns:
Zero if successful.
API Stability:
Evolving.
PUBLIC int 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 bool 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 bool rIsSocketClosed (RSocket *sp)

Test if the socket has been closed.

Description:
Determine if rCloseSocket has been called.
Parameters:
spSocket object returned from rAllocSocket.
Returns:
True if the socket is at end-of-file.
API Stability:
Evolving.
PUBLIC bool bool rIsSocketConnected (RSocket *sp)

Determine if the socket has connected to a remote pper.

Parameters:
spSocket object returned from rAllocSocket.
Returns:
True if the socket is connected.
API Stability:
Evolving.
PUBLIC bool 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:
spSocket object returned from rAllocSocket.
Returns:
True if the socket is at end-of-file.
API Stability:
Evolving.
PUBLIC bool bool rIsSocketHandshaking (RSocket *sp)

Determine if the socket is partway through a TLS handshake.

Parameters:
spSocket object returned from rAllocSocket.
Returns:
True if the socket is handshaking.
API Stability:
Evolving.
PUBLIC bool bool rIsSocketSecure (RSocket *sp)

Determine if the socket is secure.

Description:
Determine if the socket is using SSL to provide enhanced security.
Parameters:
spSocket object returned from rAllocSocket.
Returns:
True if the socket is using SSL, otherwise zero.
API Stability:
Evolving.
PUBLIC int 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:
spSocket object returned via rAllocSocket.
hostHost name or IP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
portTCP/IP port number to connect to.
handlerFunction callback to invoke for incoming connections. The function is invoked on a new fiber coroutine.
argArgument to handler.
Returns:
Zero if successful.
API Stability:
Evolving.
PUBLIC void,* void* rMemdup (cvoid *ptr, size_t size)

Duplicate a block of memory.

Description:
Copy a block of memory into a newly allocated block.
Parameters:
ptrPointer to the block to duplicate.
sizeSize of the block to copy.
Returns:
Returns an allocated block.
API Stability:
Evolving.
PUBLIC ssize 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:
spSocket object returned from rAllocSocket.
bufPointer to a buffer to hold the read data.
bufsizeSize of the buffer.
deadlineMaximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a 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 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 untill 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:
spSocket object returned from rAllocSocket.
bufPointer to a buffer to hold the read data.
bufsizeSize 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 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:
spSocket object returned from rAllocSocket.
API Stability:
Evolving.
PUBLIC void,* void* rResumeFiber (RFiber *fiber, void *result)

Resume a fiber.

Description:
Resume a fiber. Generally only called from the main fiber. If called from a non-main fiber the target fiber is resumed via an event to the main fiber.
Parameters:
fiberFiber object.
resultResult to pass to the fiber and will be the value returned from rYieldFiber.
API Stability:
Evolving.
PUBLIC int int rSetAppName (cchar *name, cchar *title, cchar *version)

Set the application name, title and version.

Parameters:
nameOne word, lower case name for the app.
titlePascal case multi-word descriptive name.
versionVersion of the app. Major-Minor-Patch. E.g. 1.2.3.
Returns:
Zero if successful. Otherwise a negative RT error code.
API Stability:
Evolving.
PUBLIC void void rSetDefaultSocketCa (cchar *ca)

Set the default CA root certificate bundle.

Parameters:
caFile containing the root certificates.
API Stability:
Evolving.
PUBLIC void void rSetFiberStack (ssize size)

Set the default fiber stack size.

Parameters:
sizeSize of fiber stack in bytes.
API Stability:
Internal.
PUBLIC void void rSetMemHandler (RMemProc handler)

Define a global memory exhaustion handler.

Description:
The memory handler will be invoked for memory allocation errors.
Parameters:
handlerCallback function invoked with the signature: void fn(int cause, size_t size).
API Stability:
Evolving.
PUBLIC void void rSetOsError (int error)

Set the O/S error code.

Description:
Set errno or equivalent.
API Stability:
Evolving.
PUBLIC void 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:
spSocket object returned from rAllocSocket.
onSet to true to enable blocking mode.
API Stability:
Evolving.
PUBLIC void void rSetSocketCerts (RSocket *sp, cchar *key, cchar *cert, cchar *ca, cchar *revoke)

Configure the socket TLS certificates.

Description:
This call is a wrapper over rSetTLSCerts.
Parameters:
spSocket object returned from rAllocSocket.
keyPrivate key for the certificate.
certCertificate to use for TLS.
caCertificate authority to use when verifying peer connections.
revokeList of revoked certificates.
API Stability:
Evolving.
PUBLIC void void rSetSocketCiphers (RSocket *sp, cchar *ciphers)

Set the ciphers to use for communications.

Parameters:
spSocket object returned from rAllocSocket.
ciphersString of suitable ciphers.
API Stability:
Evolving.
PUBLIC void void rSetSocketVerify (RSocket *sp, int verifyPeer, int verifyIssuer)

Set the socket TLS verification parameters.

Description:
This call is a wrapper over rSetTlsCerts.
Parameters:
spSocket object returned from rAllocSocket.
verifyPeerSet to true to verify peer certificates.
verifyIssuerSet to true to verify the issuer of the peer certificate.
API Stability:
Evolving.
PUBLIC void void rSetSocketWaitMask (RSocket *sp, int64 mask, Ticks deadline)

Update the wait mask for a socket.

Parameters:
spSocket object returned from rAllocSocket.
maskSet to R_READABLE or R_WRITABLE or both.
deadlineSystem time in ticks to wait until.
API Stability:
Evolving.
PUBLIC void void rSetState (int state)

Set the R state.

Parameters:
stateSet to R_RUNNING, R_STOPPING or R_STOPPED.
API Stability:
Evolving.
PUBLIC void 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:
ticksTime period in milliseconds to sleep.
API Stability:
Evolving.
PUBLIC int int rSpawnFiber (RFiberProc fn, void *arg)

Spawn a fiber coroutine.

Description:
This allocates a new fiber and resumes it.
Parameters:
fnFiber entry point.
argEntry point argument.
Returns:
Zero if successful.
API Stability:
Evolving.
PUBLIC void 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.
Parameters:
fiberThe fiber object.
dataValue to pass to the fiber entry point.
API Stability:
Internal.
PUBLIC void void rStop (void )

Immediately stop the app.

Description:
Queued events will not be serviced.
API Stability:
Evolving.
PUBLIC void void rTermFibers (void )

Terminate the fiber coroutine module.

API Stability:
Evolving.
PUBLIC void void rTermOs (void )

Stop the O/S dependent subsystem.

API Stability:
Internal.
PUBLIC ssize 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:
spSocket object returned from rAllocSocket.
bufReference to a block to write to the socket.
bufsizeLength 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.
deadlineSystem time in ticks to wait until.
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 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:
spSocket object returned from rAllocSocket.
bufReference to a block to write to the socket.
lenLength 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,* 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:
valueValue to provide as a result to the main fiber that called rResumeFiber.
API Stability:
Evolving.

Typedefs

typedef libucontext_ucontext_t RFiberContext.

Fiber coroutine stack context.

API Stability:
Evolving.
typedef void(* RFiberProc) (void *data).

Fiber entry point function.

Parameters:
dataCustom function argument.
API Stability:
Evolving.
typedef uint(* RHashProc) (cvoid *name, ssize len).

Hashing function to use for the table.

Parameters:
nameName to hash.
lenLength 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:
causeThe cause of the memory failure.
sizeThe size of the failing block allocation.
typedef long size_t.

Unsigned integral type.

Equivalent in size to void*
typedef int Socket.

Argument for sockets.

typedef void(* REventProc) (void *data).

Callback function for events.

Parameters:
dataOpaque data argument.
idEvent ID.
API Stability:
Evolving.
See Also:
typedef int(* RWalkDirProc) (void *arg, cchar *path, int flags).

Callback function for rWalkDir

Parameters:
argArgument supplied to rWalkDir.
pathCurrent filename path to walk.
flagsFlags supplied to rWalkDir.
API Stability:
Evolving.
See Also:
RFile
typedef int(* RListCompareProc) (cvoid *arg1, cvoid *arg2).

List comparison procedure for soring.

Description:
Callback function signature used by rSorList
Parameters:
arg1First list item to compare.
arg2Second list item to compare.
Returns:
Return zero if the items are equal. Return -1 if the first arg is less than the second. Otherwise return 1.
API Stability:
Evolving.
See Also:
RList, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
typedef int(* RSortProc) (cvoid *p1, cvoid *p2, void *ctx).

Quicksor callback function.

Description:
This is a quicksor callback with a context argument.
Parameters:
p1Pointer to first element.
p2Pointer to second element.
ctxContext argument to provide to comparison function.
Returns:
-1, 0, or 1, depending on if the elements are p1 < p2, p1 == p2 or p1 > p2.
API Stability:
Evolving.
See Also:
RList, RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetListLength, rGetNextItem, rInserItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSorList
typedef void(* RLogHandler) (cchar *type, cchar *source, cchar *msg).

Log handler callback type.

Description:
Callback prototype for the log handler. Used by rSetLogHandler to define a message tracing handler to process log and error messages. See rLog for more details.
Parameters:
typeThe message type: 'code', 'error', 'info', 'log'.
sourceThe message source.
msgLog message.
API Stability:
Evolving.
See Also:
rGetLogFile, rGetLogHandler, rSetLog, rerror
typedef void(* RWaitProc) (cvoid *data, int mask).

Callback function for IO wait events.

Parameters:
dataOpaque data argument.
idIO event selection mask.
API Stability:
Evolving.
See Also:
RFiber

Fiber state.

API Stability:
Evolving.
Fields:
RName

Per item structure.

Fields:
uintcustom Custom data bits.
void *data Pointer to name data.
uintflags Name was allocated.
char *name Hash name.
intnext Next name in hash chain or next free if on free list.

© Embedthis Software. All rights reserved.