R API
The Safe Runtime (R) is a portable runtime library for embedded applications.
The R library provides management for binary searching, buffering, error handling, events, events, files, hashing, lists, logging, memory, ssl, sockets, strings, and date/time functions. It also provides a foundation of safe routines for secure programming, that help to prevent buffer overflows and other security threats. The library can be used in both C and C++ programs.
The R library uses a set extended typedefs for common types. These include: bool, cchar, cvoid, uchar, short, ushort, int, uint, long, ulong, int32, uint32, int64, uint64, float, and double. The cchar type is a const char, cvoid is const void. Several types have "u" prefixes to denote unsigned qualifiers.
The library includes a memory allocator and global memory allocation handler.
The library provides support for fiber coroutines to enable parallel programming without callbacks or complex threads. The network APIs use fibers to transparently block the fiber and resume other fibers automatically. This enables a straight-line "blocking" programming paradigm while enabling other fibers to run as required.
Extensions
RBuf | Dynamic Buffer Module. |
REvent | Event Subsystem. |
RFile | R File Module. |
RHash | Hash table structure. |
RList | List data structure. |
RLog | Log Services. |
RString | R String Module. |
RWait | Wait object. |
RbTree | Red/Black Tree. |
Functions
PUBLIC void | assert(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 int | rAddItem(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 int | rAddNullItem(RList *list) |
Add a null item to the list. | |
PUBLIC void | rAddNullToBuf(RBuf *buf) |
Add a null character to the buffer contents. | |
PUBLIC void | rAdjustBufEnd(RBuf *buf, ssize count) |
Adjust the buffer end position. | |
PUBLIC void | rAdjustBufStart(RBuf *buf, ssize count) |
Adjust the buffer start position. | |
PUBLIC void * | rAlloc(size_t size) |
Allocate a block of memory. | |
PUBLIC RBuf * | rAllocBuf(ssize initialSize) |
Create a new buffer. | |
PUBLIC REvent | rAllocEvent(RFiber *fiber, REventProc proc, void *data, Ticks delay) |
Allocate and schedule a new event to be run from the event loop. | |
PUBLIC void | rAllocException(int cause, size_t size) |
Signal a memory allocation exception. | |
PUBLIC RFiber * | rAllocFiber(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 RLock * | rAllocLock(void) |
Allocate a lock object. | |
PUBLIC RSocket * | rAllocSocket(void) |
Allocate a socket object. | |
PUBLIC void * | rAllocType(RType type) |
Allocate an object of a given type. | |
PUBLIC RWait * | rAllocWait(int fd) |
Allocate a wait object for a file descriptor. | |
PUBLIC void | rAssert(cchar *loc, cchar *msg) |
Output an assert failed message. | |
PUBLIC int | rBackupFile(cchar *path, int count) |
Backup the given file. | |
PUBLIC void | rBackupLog(void) |
Backup a log. | |
PUBLIC cchar * | rBasename(cchar *path) |
Return the basename (filename) portion of a filename. | |
PUBLIC void | rBreakpoint(void) |
Trigger a breakpoint. | |
PUBLIC char * | rBufToString(RBuf *buf) |
Return a reference to the buffer contents. | |
PUBLIC char * | rBufToStringAndFree(RBuf *buf) |
Convert the buffer contents to a string. | |
PUBLIC void | rClearList(RList *list) |
Clears the list of all items. | |
PUBLIC RHash * | rCloneHash(RHash *master) |
Copy a hash table. | |
PUBLIC void | rCloseSocket(RSocket *sp) |
Close a socket. | |
PUBLIC void | rCompactBuf(RBuf *buf) |
Compact the buffer contents. | |
PUBLIC int | rConnectSocket(RSocket *sp, cchar *host, int port, Ticks deadline) |
Connect a client socket. | |
PUBLIC ssize | rCopyFile(cchar *from, cchar *to, int mode) |
Copy a file. | |
PUBLIC int | rCreateThread(cchar *name, void *proc, void *data) |
Create an O/S thread. | |
PUBLIC int | rDaemonize(void) |
For the current process and run as a daemon. | |
PUBLIC void | rDebug(cchar *source, cchar *fmt, ...) |
Emit a debug message to the log. | |
PUBLIC void | rDefaultLogHandler(cchar *type, cchar *source, cchar *msg) |
The default log handler. | |
PUBLIC bool | rEmitLog(cchar *type, cchar *source) |
Test if a log message should be emitted. | |
PUBLIC void | rError(cchar *source, cchar *fmt, ...) |
Emit an error message to the log. | |
PUBLIC void | rFlushBuf(RBuf *buf) |
Flush the buffer contents. | |
PUBLIC char * | rFormatLocalTime(cchar *format, Time time) |
Convert a time value to local time and format as a string. | |
PUBLIC RBuf * | rFormatLog(RBuf *buf, cchar *type, cchar *source, cchar *msg) |
Format a log message into a buffer. | |
PUBLIC char * | rFormatUniversalTime(cchar *format, Time time) |
Convert a time value to universal time and format as a string. | |
PUBLIC void | rFree(void *ptr) |
Free a block of memory allocated via rAlloc. | |
PUBLIC void | rFreeBuf(RBuf *buf) |
Free a buffer. | |
PUBLIC void | rFreeFiber(RFiber *fiber) |
Free a fiber coroutine. | |
PUBLIC void | rFreeHash(RHash *hash) |
Free a hash table. | |
PUBLIC void | rFreeList(RList *list) |
Free a list. | |
PUBLIC void | rFreeLock(RLock *mutex) |
Free a dynamically allocated lock object. | |
PUBLIC void | rFreeSocket(RSocket *sp) |
Free a socket object. | |
PUBLIC void | rFreeWait(RWait *wp) |
Free a wait object. | |
PUBLIC char * | rGetAppDir(void) |
Get the directory containing the application executable. | |
PUBLIC cchar * | rGetAppName(void) |
Get the application name defined via rSetAppName. | |
PUBLIC ssize | rGetBlockFromBuf(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 ssize | rGetBufLength(RBuf *buf) |
Get the buffer content length. | |
PUBLIC ssize | rGetBufSize(RBuf *buf) |
Get the current size of the buffer content storage. | |
PUBLIC ssize | rGetBufSpace(RBuf *buf) |
Get the space available to store content. | |
PUBLIC cchar * | rGetBufStart(RBuf *buf) |
Get the start of the buffer contents. | |
PUBLIC int | rGetCharFromBuf(RBuf *buf) |
Get a character from the buffer. | |
PUBLIC RThread | rGetCurrentThread(void) |
Get the current Thread. | |
PUBLIC char * | rGetCwd(void) |
Get the current application working directory. | |
PUBLIC char * | rGetDate(cchar *format) |
Get a string representation of the current date/time. | |
PUBLIC Ticks | rGetElapsedTicks(Ticks mark) |
Get the elapsed time since a ticks mark. | |
PUBLIC cchar * | rGetError(int error) |
Return a string representation of an R error code. | |
PUBLIC RFiber * | rGetFiber(void) |
Get the current fiber object. | |
PUBLIC void * | rGetFiberStack(void) |
Get the base address of the fiber stack. | |
PUBLIC RList * | rGetFiles(cchar *base, cchar *pattern, int flags) |
Create a list of files in a directory or subdirectories that match the given wildcard pattern. | |
PUBLIC RList * | rGetFilesEx(RList *results, cchar *base, cchar *pattern, int flags) |
Get a list of files in a directory or subdirectories that match the given wildcard pattern. | |
PUBLIC int | rGetHashLength(RHash *hash) |
Return the count of symbols in a symbol entry. | |
uint64 | rGetHiResTicks(void) |
Get the CPU tick count. | |
PUBLIC char * | rGetIsoDate(Time time) |
Get an ISO Date string representation of the given date/time. | |
PUBLIC void * | rGetItem(RList *list, int index) |
Get an list item. | |
PUBLIC int | rGetListLength(RList *list) |
Get the number of items in the list. | |
PUBLIC int | rGetLogFile(void) |
Get the log file file handle. | |
PUBLIC RLogHandler | rGetLogHandler(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 int | rGetOsError(void) |
Return the native O/S error code. | |
PUBLIC Ticks | rGetRemainingTicks(Ticks mark, Ticks timeout) |
Return the time remaining until a timeout has elapsed. | |
PUBLIC cchar * | rGetServerName(void) |
Get the application server name string. | |
PUBLIC int | rGetSocketAddr(RSocket *sp, char *ipbuf, int ipbufLen, int *port) |
Get the locally bound socket IP address and port for the socket. | |
PUBLIC Socket | rGetSocketHandle(RSocket *sp) |
Get the socket file descriptor. | |
PUBLIC int | rGetState(void) |
Get the current R state. | |
PUBLIC char * | rGetTempFile(cchar *dir, cchar *prefix) |
Get a temp filename. | |
PUBLIC Ticks | rGetTicks(void) |
Get the system time. | |
PUBLIC Time | rGetTime(void) |
Get the time. | |
PUBLIC bool | rGetTimeouts(void) |
Return true if timeouts are enabled. | |
PUBLIC int | rGetWaitFd(void) |
Get the global wait descriptor. | |
PUBLIC void | rGlobalLock(void) |
Globally lock the application. | |
PUBLIC void | rGlobalUnlock(void) |
Unlock the global mutex. | |
PUBLIC void | rGracefulStop(void) |
Gracefully stop the app. | |
PUBLIC int | rGrowBuf(RBuf *buf, ssize count) |
Grow the buffer. | |
PUBLIC int | rGrowList(RList *list, int size) |
Grow the list to be at least the requested size in elements. | |
PUBLIC char * | rHashToJson(RHash *hash, int pretty) |
Convert a hash into JSON. | |
PUBLIC RBuf * | rHashToJsonBuf(RHash *hash, RBuf *buf, int pretty) |
Convert a hash into JSON in the given buffer. | |
PUBLIC char * | rHashToString(RHash *hash, cchar *join) |
Convert a hash of strings to a single string. | |
PUBLIC void | rInfo(cchar *source, cchar *fmt, ...) |
Emit an informational message to the log. | |
PUBLIC int | rInit(RFiberProc fn, cvoid *arg, ssize stackSize) |
Initialize the runtime. | |
PUBLIC int | rInitBuf(RBuf *buf, ssize size) |
Initialize the buffer and set the initial buffer size. | |
PUBLIC int | rInitFibers(ssize stackSize) |
Initialize the fiber coroutine module. | |
PUBLIC RLock * | rInitLock(RLock *mutex) |
Initialize a statically allocated lock object. | |
PUBLIC int | rInitLog(void) |
Initialize the logging subsystem. | |
PUBLIC int | rInitOs(void) |
Create and initialze the O/S dependent subsystem. | |
PUBLIC int | rInitWait(void) |
Initialize the I/O wait subsystem. | |
PUBLIC int | rInserCharToBuf(RBuf *buf, int c) |
Inser a character into the buffer. | |
PUBLIC int | rInsertItemAt(RList *list, int index, cvoid *item) |
Inser an item into a list at a specific position. | |
PUBLIC bool | rIsFileAbs(cchar *path) |
Determine if a file path is an absolute path. | |
PUBLIC bool | rIsLogSet(void) |
Test if the log has been configured. | |
PUBLIC bool | rIsMain(void) |
Test if a fiber is the main fiber. | |
PUBLIC bool | rIsSocketClosed(RSocket *sp) |
Test if the socket has been closed. | |
PUBLIC bool | rIsSocketConnected(RSocket *sp) |
Determine if the socket has connected to a remote pper. | |
PUBLIC bool | rIsSocketEof(RSocket *sp) |
Test if the other end of the socket has been closed. | |
PUBLIC bool | rIsSocketHandshaking(RSocket *sp) |
Determine if the socket is partway through a TLS handshake. | |
PUBLIC bool | rIsSocketSecure(RSocket *sp) |
Determine if the socket is secure. | |
PUBLIC char * | rJoinFile(cchar *base, cchar *other) |
Join file paths. | |
PUBLIC char * | rJoinFileBuf(char *buf, ssize bufsize, cchar *base, cchar *other) |
Join paths into a buffer. | |
PUBLIC char * | rListToString(RList *list, cchar *join) |
Convert a list of strings to a single string. | |
PUBLIC int | rListenSocket(RSocket *sp, cchar *host, int port, RSocketProc handler, void *arg) |
Listen on a server socket for incoming connections. | |
PUBLIC void | rLock(RLock *lock) |
Lock access. | |
PUBLIC void | rLog(char *type, cchar *source, cchar *fmt, ...) |
Write a message to the error log file. | |
PUBLIC void | rLogConfig(void) |
Print the product configuration at the start of the log file. | |
PUBLIC void | rLogv(cchar *type, cchar *source, cchar *fmt, va_list args) |
Write a message to the log file. | |
PUBLIC int | rLookAtLastCharInBuf(RBuf *buf) |
Peek at the last character in the buffer. | |
PUBLIC int | rLookAtNextCharInBuf(RBuf *buf) |
Peek at the next character in the buffer. | |
PUBLIC bool | rLookupEvent(REvent id) |
Lookup an event ID. | |
PUBLIC int | rLookupItem(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 int | rLookupStringItem(RList *list, cchar *str) |
Find a string item and return its index. | |
PUBLIC bool | rMatchFile(cchar *path, cchar *pattern) |
Matach a file against a glob pattern. | |
PUBLIC void * | rMemdup(cvoid *ptr, size_t size) |
Duplicate a block of memory. | |
PUBLIC void | rMetrics(cchar *message, cchar *namespace, cchar *dimensions, cchar *values, ...) |
Emit an EMF metrics message suitable for AWS CloudWatch Metrics. | |
PUBLIC Time | rParseIsoDate(cchar *when) |
Parse an ISO date string. | |
PUBLIC void * | rPopItem(RList *list) |
Pop an item. | |
PUBLIC void | rPushItem(RList *list, void *item) |
Push an item onto the list. | |
PUBLIC ssize | rPutBlockToBuf(RBuf *buf, cchar *ptr, ssize size) |
Put a block to the buffer. | |
PUBLIC int | rPutCharToBuf(RBuf *buf, int c) |
Put a character to the buffer. | |
PUBLIC ssize | rPutIntToBuf(RBuf *buf, int64 i) |
Put an integer to the buffer. | |
PUBLIC ssize | rPutStringToBuf(RBuf *buf, cchar *str) |
Put a string to the buffer. | |
PUBLIC ssize | rPutSubToBuf(RBuf *buf, cchar *str, ssize count) |
Put a substring to the buffer. | |
PUBLIC ssize | rPutToBuf(RBuf *buf, cchar *fmt, ...) |
Put a formatted string to the buffer. | |
PUBLIC char * | rReadFile(cchar *path, ssize *lenp) |
Read data from a file. | |
PUBLIC ssize | rReadSocket(RSocket *sp, char *buf, ssize bufsize, Ticks deadline) |
Read from a socket. | |
PUBLIC ssize | rReadSocketSync(RSocket *sp, char *buf, ssize bufsize) |
Read from a socket. | |
PUBLIC int | rRemoveItem(RList *list, cvoid *item) |
Remove an item from the list. | |
PUBLIC int | rRemoveItemAt(RList *list, int index) |
Remove an item from the list. | |
PUBLIC int | rRemoveName(RHash *hash, cchar *name) |
Remove a symbol entry from the hash table. | |
PUBLIC int | rRemoveStringItem(RList *list, cchar *str) |
Remove a string item from the list. | |
PUBLIC int | rReserveBufSpace(RBuf *buf, ssize need) |
Grow the buffer so that there is at least the needed minimum space available. | |
PUBLIC void | rResetBufIfEmpty(RBuf *buf) |
Reset the buffer. | |
PUBLIC void | rResetSocket(RSocket *sp) |
Reset a socket. | |
PUBLIC void * | rResumeFiber(RFiber *fiber, void *result) |
Resume a fiber. | |
PUBLIC Ticks | rRunEvents(void) |
Run due events. | |
PUBLIC int | rServiceEvents(void) |
Service events. | |
PUBLIC int | rSetAppName(cchar *name, cchar *title, cchar *version) |
Set the application name, title and version. | |
PUBLIC void | rSetDefaultSocketCa(cchar *ca) |
Set the default CA root certificate bundle. | |
PUBLIC void | rSetError(int error) |
Set the error code. | |
PUBLIC void | rSetFiberStack(ssize size) |
Set the default fiber stack size. | |
PUBLIC void * | rSetItem(RList *list, int index, cvoid *item) |
Set a list item. | |
PUBLIC int | rSetLog(cchar *spec, cchar *format, bool force) |
Initialize logging. | |
PUBLIC void | rSetLogFilter(cchar *types, cchar *sources, bool force) |
Define a filter for log messages. | |
PUBLIC RLogHandler | rSetLogHandler(RLogHandler handler) |
Define a log handler routine that will be invoked to process log messages. | |
PUBLIC void | rSetMemHandler(RMemProc handler) |
Define a global memory exhaustion handler. | |
PUBLIC void | rSetOsError(int error) |
Set the O/S error code. | |
PUBLIC void | rSetSocketBlocking(RSocket *sp, bool on) |
Set a socket into blocking I/O mode. | |
PUBLIC void | rSetSocketCerts(RSocket *sp, cchar *key, cchar *cert, cchar *ca, cchar *revoke) |
Configure the socket TLS certificates. | |
PUBLIC void | rSetSocketCiphers(RSocket *sp, cchar *ciphers) |
Set the ciphers to use for communications. | |
PUBLIC void | rSetSocketVerify(RSocket *sp, int verifyPeer, int verifyIssuer) |
Set the socket TLS verification parameters. | |
PUBLIC void | rSetSocketWaitMask(RSocket *sp, int64 mask, Ticks deadline) |
Update the wait mask for a socket. | |
PUBLIC void | rSetState(int state) |
Set the R state. | |
PUBLIC void | rSetTimeouts(bool on) |
Control timeouts. | |
PUBLIC void | rSetWaitHandler(RWait *wp, RWaitProc handler, cvoid *arg, int64 mask) |
Define a wait handler function on a wait object. | |
PUBLIC void | rSetWaitMask(RWait *wp, int64 mask, Ticks deadline) |
Update the wait mask for a wait handler. | |
PUBLIC void | rSignal(cchar *name, cvoid *arg) |
Signal watches of a named event. | |
PUBLIC void | rSleep(Ticks ticks) |
Sleep a fiber for the requested number of milliseconds. | |
PUBLIC void * | rSort(void *base, ssize num, ssize width, RSortProc compare, void *ctx) |
Quicksort. | |
PUBLIC RList * | rSortList(RList *list, RSortProc compare, void *ctx) |
Sor a list. | |
PUBLIC int | rSpawnFiber(RFiberProc fn, void *arg) |
Spawn a fiber coroutine. | |
PUBLIC void * | rSpawnThread(RThreadProc fn, void *arg) |
Spawn an O/S thread. | |
PUBLIC REvent | rStartEvent(REventProc proc, void *data, Ticks delay) |
Start a callback event. | |
PUBLIC void | rStartFiber(RFiber *fiber, void *data) |
Start a fiber coroutine. | |
PUBLIC void | rStop(void) |
Immediately stop the app. | |
PUBLIC int | rStopEvent(REvent id) |
Stop an event. | |
PUBLIC void | rTermBuf(RBuf *buf) |
Terminate a buffer. | |
PUBLIC void | rTermFibers(void) |
Terminate the fiber coroutine module. | |
PUBLIC void | rTermLock(RLock *mutex) |
Terminate a statically allocated lock object. | |
PUBLIC void | rTermLog(void) |
Terminate logging. | |
PUBLIC void | rTermOs(void) |
Stop the O/S dependent subsystem. | |
PUBLIC void | rTermWait(void) |
Terminate the I/O wait subsystem. | |
PUBLIC bool | rTryLock(RLock *lock) |
Attempt to lock access. | |
PUBLIC void | rUnlock(RLock *lock) |
Unlock a mutex. | |
PUBLIC int | rWait(Ticks timeout) |
Wait for an I/O event. | |
PUBLIC void * | rWaitForIO(RWait *wp, int mask, Ticks deadline) |
Wait for an IO event on a wait object. | |
PUBLIC int | rWalkDir(cchar *dir, cchar *pattern, RWalkDirProc callback, void *arg, int flags) |
Walk a directory tree and invoke a callback for each path that matches a given pattern. | |
PUBLIC void | rWatch(cchar *name, RWatchProc proc, void *data) |
Watch for a named event to happen. | |
PUBLIC void | rWatchOff(cchar *name, RWatchProc proc, void *data) |
Stop watching for a named event to happen. | |
PUBLIC ssize | rWriteFile(cchar *path, cchar *buf, ssize len, int mode) |
Write data to a file. | |
PUBLIC int | rWritePid(void) |
Write the current process pid to /var/run. | |
PUBLIC ssize | rWriteSocket(RSocket *sp, cvoid *buf, ssize bufsize, Ticks deadline) |
Write to a socket. | |
PUBLIC ssize | rWriteSocketSync(RSocket *sp, cvoid *buf, ssize len) |
Write to a socket. | |
PUBLIC void * | rYieldFiber(void *value) |
Yield a fiber back to the main fiber. | |
PUBLIC RbTree * | rbAlloc(int flags, RbFree free, RbCompare compare) |
Allocate a red/black tree. | |
PUBLIC RbNode * | rbFirst(RbTree *rbt) |
Return the lexically first node. | |
PUBLIC void | rbFree(RbTree *rbt) |
Free a red/black tree. | |
PUBLIC RbNode * | rbInsert(RbTree *rbt, void *data) |
Insert a new data item in the tree. | |
PUBLIC RbNode * | rbLookup(RbTree *rbt, void *data, void *ctx) |
Lookup a data item. | |
PUBLIC RbNode * | rbLookupFirst(RbTree *rbt, void *data, void *ctx) |
Return the lexically first matching node. | |
PUBLIC RbNode * | rbLookupNext(RbTree *rbt, RbNode *node, void *data, void *ctx) |
Return the next matching node after the given node. | |
PUBLIC RbNode * | rbNext(RbTree *rbt, RbNode *node) |
Return the next node in sequence. | |
PUBLIC void * | rbRemove(RbTree *rbt, RbNode *node, int keep) |
Remove a data item from the tree. | |
PUBLIC char * | scamel(cchar *str) |
Create a camel case version of the string. | |
PUBLIC int | scaselesscmp(cchar *s1, cchar *s2) |
Compare strings ignoring case. | |
PUBLIC bool | scaselessmatch(cchar *s1, cchar *s2) |
Compare strings ignoring case. | |
PUBLIC char * | schr(cchar *str, int c) |
Find a character in a string. | |
PUBLIC char * | sclone(cchar *str) |
Clone a string. | |
PUBLIC int | scmp(cchar *s1, cchar *s2) |
Compare strings. | |
PUBLIC char * | scontains(cchar *str, cchar *pattern) |
Find a pattern in a string. | |
PUBLIC ssize | scopy(char *dest, ssize destMax, cchar *src) |
Copy a string. | |
PUBLIC cchar * | sends(cchar *str, cchar *suffix) |
Test if the string ends with a given pattern. | |
PUBLIC char * | sfmt(cchar *fmt, ...) |
Format a string. | |
PUBLIC char * | sfmtbuf(char *buf, ssize maxSize, cchar *fmt, ...) |
Format a string into a static buffer. | |
PUBLIC char * | sfmtbufv(char *buf, ssize maxSize, cchar *fmt, va_list args) |
Format a string into a statically allocated buffer. | |
PUBLIC char * | sfmtv(cchar *fmt, va_list args) |
Format a string. | |
PUBLIC uint | shash(cchar *str, ssize len) |
Compute a hash code for a string. | |
PUBLIC uint | shashlower(cchar *str, ssize len) |
Compute a caseless hash code for a string. | |
PUBLIC char * | sitos(int64 value) |
Convert an integer to a string. | |
PUBLIC char * | sitosbuf(char *buf, ssize size, int64 value, int radix) |
Convert an integer to a string buffer. | |
PUBLIC char * | sitosradix(int64 value, int radix) |
Convert an integer to a string. | |
PUBLIC char * | sjoin(cchar *str, ...) |
Catenate strings. | |
PUBLIC 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 ssize | slen(cchar *str) |
Return the length of a string. | |
PUBLIC char * | slower(char *str) |
Convert a string to lower case. | |
PUBLIC bool | smatch(cchar *s1, cchar *s2) |
Compare strings. | |
PUBLIC int | sncaselesscmp(cchar *s1, cchar *s2, ssize len) |
Compare strings ignoring case. | |
PUBLIC char * | sncaselesscontains(cchar *str, cchar *pattern, ssize limit) |
Find a pattern in a string with a limit using a caseless comparison. | |
PUBLIC char * | snclone(cchar *str, ssize len) |
Clone a substring. | |
PUBLIC int | sncmp(cchar *s1, cchar *s2, ssize len) |
Compare strings. | |
PUBLIC char * | sncontains(cchar *str, cchar *pattern, ssize limit) |
Find a pattern in a string with a limit. | |
PUBLIC ssize | sncopy(char *dest, ssize destMax, cchar *src, ssize len) |
Copy characters from a string. | |
PUBLIC char * | spbrk(cchar *str, cchar *set) |
Locate the a character from a set in a string. | |
PUBLIC char * | sptok(char *str, cchar *pattern, char **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 ssize | sspn(cchar *str, cchar *set) |
Find the end of a spanning prefix. | |
PUBLIC bool | sstarts(cchar *str, cchar *prefix) |
Test if the string starts with a given pattern. | |
PUBLIC char * | ssub(cchar *str, ssize offset, ssize length) |
Create a substring. | |
PUBLIC char * | stemplate(cchar *str, void *tokens) |
Replace template tokens in a string with values from a lookup table. | |
PUBLIC char * | stitle(cchar *str) |
Create a Title Case version of the string. | |
PUBLIC double | stof(cchar *str) |
Convert a string to a double. | |
PUBLIC int64 | stoi(cchar *str) |
Convert a string to an integer. | |
PUBLIC int64 | stoiradix(cchar *str, int radix, int *err) |
Convert a string to an integer. | |
PUBLIC char * | stok(char *str, cchar *delim, char **last) |
Tokenize a string. | |
PUBLIC struct RList * | stolist(cchar *src) |
String to list. | |
PUBLIC char * | strim(char *str, cchar *set, int where) |
Trim a string. | |
PUBLIC char * | supper(char *str) |
Convert a string to upper case. | |
PUBLIC void | szero(char *str) |
Erase the contents of a string. |
Typedefs
REventProc | Callback function for events. |
RFiber | Fiber state. |
RFiberContext | Fiber coroutine stack context. |
RFiberProc | Fiber entry point function. |
RHashProc | Hashing function to use for the table. |
RListCompareProc | List comparison procedure for soring. |
RLock | Multithreading lock control structure. |
RLogHandler | Log handler callback type. |
RMemProc | Memory exhaustion callback procedure. |
RName | Per item structure. |
RSortProc | Quicksort callback function. |
RThreadProc | Thread entry point function. |
RWaitProc | Callback function for IO wait events. |
RWalkDirProc | Callback function for rWalkDir |
RWatchProc | Callback function for watched events. |
RbCompare | Callback to compare a data nodes. |
RbFree | Callback to free a nodes associated data. |
Socket | Argument for sockets. |
size_t | Unsigned integral type. |
time_t | Unsigned time type. |
Defines
#define | ITERATE_INDEX |
Traverse an index over matching nodes. | |
#define | ME_R_LOGGING 1 |
Default for logging is "on". | |
#define | R_DEFAULT_DATE "%a %b %d %T %Y %Z" |
Default date format used in rFormatLocalTime/rFormatUniversalTime when no format supplied E.g. | |
#define | R_DYNAMIC_NAME 0x8 |
Dynamic name provided, hash will free. | |
#define | R_DYNAMIC_VALUE 0x1 |
Dynamic (allocated) value provided, hash will free. | |
#define | R_EVENT_ASYNC 1 |
Windows async select. | |
#define | R_EVENT_EPOLL 2 |
epoll_wait. | |
#define | R_EVENT_KQUEUE 3 |
BSD kqueue. | |
#define | R_EVENT_SELECT 4 |
traditional select(). | |
#define | R_HASH_CASELESS 0x40 |
Ignore case in comparisons. | |
#define | R_IO 0x6 |
Wait mask for readable or writeable events. | |
#define | R_MEM_FAIL 0x4 |
Memory allocation failed - immediate exit. | |
#define | R_MEM_LIMIT 0x2 |
Memory use exceeds memory limit - invoking policy. | |
#define | R_MEM_TOO_BIG 0x8 |
Memory allocation request is too big - immediate exit. | |
#define | R_MEM_WARNING 0x1 |
Memory use exceeds warnHeap level limit. | |
#define | R_MODIFIED 0x200 |
Wait mask for modify events. | |
#define | R_READABLE 0x2 |
Wait mask for readable events. | |
#define | R_SOCKET_CLOSED 0x1 |
RSocket has been closed. | |
#define | R_SOCKET_EOF 0x2 |
Seen end of file. | |
#define | R_SOCKET_LISTENER 0x4 |
RSocket is server listener. | |
#define | R_SOCKET_SERVER 0x8 |
Socket is on the server-side. | |
#define | R_STATIC_NAME 0x10 |
Static name provided no need to clone or free. | |
#define | R_STATIC_VALUE 0x2 |
Static value provided, no need to clone or free. | |
#define | R_TEMPORAL_NAME 0x20 |
Temporal name provided, hash will clone and free. | |
#define | R_TEMPORAL_VALUE 0x4 |
Temporal value provided, hash will clone and free. | |
#define | R_TRIM_BOTH 0x3 |
Flag for strim to trim from both the start and the end of the string. | |
#define | R_TRIM_END 0x2 |
Flag for strim to trim from the end of the string. | |
#define | R_TRIM_START 0x1 |
Flag for strim to trim from the start of the string. | |
#define | R_WALK_DEPTH_FIRST 0x1 |
Flag for rGetFiles to do a depth-first traversal. | |
#define | R_WALK_DIRS 0x4 |
Include hidden files starting with "." except for "." and "..". | |
#define | R_WALK_FILES 0x8 |
Include hidden files starting with "." except for "." and "..". | |
#define | R_WALK_HIDDEN 0x2 |
Include hidden files starting with "." except for "." and "..". | |
#define | R_WALK_MISSING 0x20 |
Allow walking missing paths. | |
#define | R_WALK_RELATIVE 0x10 |
Return paths relative to the original path. | |
#define | R_WRITABLE 0x4 |
Wait mask for writable events. | |
#define | RB_DUP 0x1 |
Flags for rbAlloc to permit duplicate keys. | |
#define | ITERATE_INDEX |
Traverse an index over matching nodes. |
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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
- API Stability:
- Internal.
- Fields:
-
char * buf Actual buffer for data. ssize buflen 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.
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:
-
buf Buffer created via rAllocBuf.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. count Positive or negative count of bytes to adjust the end position.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. count Positive or negative count of bytes to adjust the start position.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Create a new buffer.
- Description:
- Create a new buffer.
- Parameters:
-
initialSize Initial size of the buffer.
- Returns:
- A new buffer.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Return a reference to the buffer contents.
- Parameters:
-
buf Buffer 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Convert the buffer contents to a string.
The string is allocated and the buffer is freed- Parameters:
-
buf Buffer created via rAllocBuf.
- Returns:
- Allocated string.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Compact the buffer contents.
- Description:
- Compact the buffer contents by copying the contents down to start the the buffer origin.
- Parameters:
-
buf Buffer created via rAllocBuf.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Flush the buffer contents.
- Description:
- Discard the buffer contents and reset the start end content pointers.
- Parameters:
-
buf Buffer created via rAllocBuf.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Free a buffer.
- Parameters:
-
buf Buffere created via rAllocBuf
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. blk Destination block for the read data. count Count 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Get the space available to store content.
- Description:
- Get the number of bytes available to store content in the buffer.
- Parameters:
-
buf Buffer created via rAllocBuf.
- Returns:
- The number of bytes available.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Get a character from the buffer.
- Description:
- Get the next byte from the buffer start and advance the start position.
- Parameters:
-
buf Buffer 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, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. count Count 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, rGetCharFromBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. size Size 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, rGetCharFromBuf, rGrowBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Inser a character into the buffer.
- Description:
- Inser a character into to the buffer prior to the current buffer start point.
- Parameters:
-
buf Buffer created via rAllocBuf. c Character 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf.
- Returns:
- Zero if successful and otherwise a negative error code.
- API Stability:
- Evolving.
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:
-
buf Buffer created via rAllocBuf.
- Returns:
- Zero if successful and otherwise a negative error code.
- API Stability:
- Evolving.
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:
-
buf Buffer created via rAllocBuf. ptr Block to append. size Size 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Put a character to the buffer.
- Description:
- Append a character to the buffer at the end position and increment the end pointer.
- Parameters:
-
buf Buffer created via rAllocBuf. c Character 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Put an integer to the buffer.
- Description:
- Append a integer to the buffer at the end position and increment the end pointer.
- Parameters:
-
buf Buffer created via rAllocBuf. i Integer 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. str String 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. str String to append. count Put 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. fmt Printf 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
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:
-
buf Buffer created via rAllocBuf. need Required 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, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
Reset the buffer.
- Description:
- If the buffer is empty, reset the buffer start and end pointers to the beginning of the buffer.
- Parameters:
-
buf Buffer created via rAllocBuf.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf
Terminate a buffer.
- Description:
- This frees memory allocated by the buffer. This call should be used for buffers initialized via rInitBuf
- Parameters:
-
buf Buffer created via rAllocBuf.
- API Stability:
- Evolving.
- See Also:
- RBuf, rAddNullToBuf, rAdjustBufEnd, rAdjustBufStart, rAllocBuf, rBufToString, rCompactBuf, rFlushBuf, rGetBlockFromBuf, rGetCharFromBuf, rGrowBuf, rInitBuf, rInserCharToBuf, rLookAtLastCharInBuf, rLookAtNextCharInBuf, rPutBlockToBuf, rPutCharToBuf, rPutIntToBuf, rPutStringToBuf, rPutSubToBuf, rResetBufIfEmpty
REvent
Event Subsystem.
- Description:
- R provides a simple based eventing mechanism. Events are described by REvent objects which are created and queued via rStartEvent. Events are scheduled once unless restarted via rRestartEvent.
- API Stability:
- Internal.
- Fields:
-
Lookup an event ID.
- Parameters:
-
id Event id allocated by rStartEvent.
- Returns:
- True if the event exists.
- API Stability:
- Evolving.
Run due events.
- Returns:
- Time delay till the next event.
- API Stability:
- Evolving.
Service events.
- Description:
- This call blocks and continually services events on the event loop until the app is instructed to exit via $rStop. An app should call rServiceEvents from the main program.
- Returns:
- The current R state.
- API Stability:
- Evolving.
Update the wait mask for a wait handler.
- Parameters:
-
wp RWait object. mask Set to R_READABLE or R_WRITABLE or both. deadline System time in ticks to wait until.
- API Stability:
- Evolving.
Signal watches of a named event.
- Parameters:
-
name Named event. arg Data argument to pass to the watch function.
- API Stability:
- Evolving.
Start a callback event.
- Description:
- This schedules an event to run once. The event can be rescheduled in the callback by invoking rRestartEvent.
- Parameters:
-
proc Callback procedure function. Signature is: void (*fn)(void *data, int id). data Data reference to pass to the callback. delay Delay in milliseconds in which to run the callback.
- Returns:
- A positive integer event ID.
- API Stability:
- Evolving.
Stop an event.
- Parameters:
-
id Event id allocated by rStartEvent.
- Returns:
- Integer handle index. Otherwise return -1 on allocation errors.
- API Stability:
- Evolving.
Wait for an I/O event.
- Description:
- This is typically called by $rServiceEvents to wait for I/O events.
- Parameters:
-
timeout Maximum time in milliseconds to wait for an I/O event.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Wait for an IO event on a wait object.
- Description:
- Wait for an IO event by yielding the current coroutine fiber until the IO event arrives. When the IO event occurs, the wait handler will be invoked on the fiber.
- Parameters:
-
wp RWait object. mask Set to R_READABLE or R_WRITABLE or both. deadline System time in ticks to wait until.
- API Stability:
- Evolving.
Watch for a named event to happen.
- Parameters:
-
name Named event. proc Function to call. data Data argument to pass to the function.
- API Stability:
- Evolving.
Stop watching for a named event to happen.
This will remove the watch for a previous rWatch call with exactly the same proc and data arguments- Parameters:
-
name Named event. proc Function provided to a previous rWatch call. data Data argument supplied to a previous rWatch call.
- API Stability:
- Evolving.
RFile
R File Module.
- See Also:
- API Stability:
- Internal.
- Fields:
-
Backup the given file.
- Description:
- This creates backup copies of the file using the form: filename-d.ext.
- Parameters:
-
path Filename to backup. count Number of backup copies to keep.
- API Stability:
- Evolving.
- See Also:
- RFile
Return the basename (filename) portion of a filename.
- Parameters:
-
path Filename to examine.
- Returns:
- A pointer to the basename portion of the supplied filename path. This call does not allocate a new string.
- API Stability:
- Evolving.
- See Also:
- RFile
Copy a file.
- Description:
- Copy a file to a destination path.
- Parameters:
-
from Source file name. to Destination file name. mode Posix file mode on created file.
- Returns:
- Number of bytes copied or negative error code.
- API Stability:
- Evolving.
- See Also:
- RFile
Get the directory containing the application executable.
- Returns:
- An allocated string containing the application directory. Caller must free.
- API Stability:
- Evolving.
- See Also:
- RFile
Get the current application working directory.
- Returns:
- An allocated string containing the working directory. Caller must free.
- API Stability:
- Evolving.
- See Also:
- RFile
Create a list of files in a directory or subdirectories that match the given wildcard pattern.
This call returns a list of filenames- Description:
- Get the list of files in a directory and return a list. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.
If the pattern is absolute.
- Parameters:
-
base Base directory from which to interpret the pattern. If the patternDirectory to list. pattern Wild card patterns to match. flags Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.
- Returns:
- A list (RList) of filenames.
- API Stability:
- Evolving.
- See Also:
- RFile
Get a list of files in a directory or subdirectories that match the given wildcard pattern.
This call adds the files to the supplied results list- Description:
- Get the list of files in a directory and return a list. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.
- Parameters:
-
results Instance of RList. See rAllocList base Base directory from which to interpret the pattern. If the patternDirectory to list. pattern Wild card patterns to match. flags Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.
- Returns:
- A list (RList) of filenames.
- API Stability:
- Evolving.
- See Also:
- RFile
Get a temp filename.
- Description:
- Create a temp file name in the given directory with the specified prefix.
- Parameters:
-
dir Directory to contain the temporary file. If null, use system default temp directory (/tmp). prefix Optional filename prefix.
- Returns:
- An allocated string containing the file name. Caller must free.
- API Stability:
- Evolving.
- See Also:
- RFile
Determine if a file path is an absolute path.
- Parameters:
-
path Filename path to test.
- Returns:
- True if the path is an absolute path.
- API Stability:
- Evolving.
- See Also:
- RFile
Join file paths.
- Description:
- Join a path to a base path. If the other path is absolute, it will be returned.
- Parameters:
-
base Directory filename to use as the base. other Other filename path to join to the base filename.
- Returns:
- Allocated string containing the resolved filename. Caller must free.
- API Stability:
- Evolving.
- See Also:
- RFile
Join paths into a buffer.
- Description:
- Join a path to a base path. If path is absolute, it will be returned.
- Parameters:
-
buf Destination path buffer. bufsize Size of buf. base Directory filename to use as the base. other Other filename path to join to the base filename.
- Returns:
- Allocated string containing the resolved filename.
- API Stability:
- Evolving.
- See Also:
- RFile
Matach a file against a glob pattern.
- Description:
- This tests a filename against a file pattern. The pattern list may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories,and a trailing "/" matches directories only.
If the pattern is absolute.
- Parameters:
-
path Filename to test. pattern Wild card patterns to match.
- Returns:
- True if the path matches the pattern.
- API Stability:
- Evolving.
- See Also:
- RFile
Read data from a file.
- Description:
- Reads data from a file.
- Parameters:
-
path Filename to read. lenp Pointer to receive the length of the file read.
- Returns:
- The contents of the file in an allocated string.
- API Stability:
- Evolving.
- See Also:
- RFile
Walk a directory tree and invoke a callback for each path that matches a given pattern.
- Description:
- The pattern may contain wildcards. The supported wildcard patterns are: "?" Matches any single character, "*" matches zero or more characters of the file or directory, "**"/ matches zero or more directories, "**" matches zero or more files or directories.
- Parameters:
-
dir Base directory from which to interpret the pattern. pattern Wild card patterns to match. callback Callback function of the signature RWalkDirProc arg Argument to callback function. flags Set to R_FILES_HIDDEN to include hidden files that start with ".". Set to R_FILES_DEPTH_FIRST to do a depth-first traversal, i.e. traverse subdirectories before considering adding the directory to the list. Set R_FILES_RELATIVE to return files relative to the given base. Set R_FILES_NO_DIRS to omit directories. Use R_FILES_DIRS_ONLY to omit regular files.
- API Stability:
- Evolving.
- See Also:
- RFile
Write data to a file.
- Description:
- Write data from a file. The file will be created if required.
- Parameters:
-
path Filename to write. buf Buffer of data to write to the file. len Length of the buffer. mode Create file mode.
- Returns:
- The length of bytes written to the file. Should equal len.
- API Stability:
- Evolving.
- See Also:
- RFile
RHash
Hash 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.
Add a name and formatted string value into the hash table.
- Description:
- Associate an arbitrary value with a string name and inser into the hash table.
- Parameters:
-
hash Hash table returned via rAllocHash. name String name to associate with the data. flags Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. If flags are zero, the flags provided to rAllocHash are used. fmt Printf style format string. ... Variable arguments for the format string.
- Returns:
- Added RName reference.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
Add a name and integer value.
- Parameters:
-
hash Hash table returned via rAllocHash. name String name to associate with the data. value A 64 bit integer value.
- Returns:
- Added RName reference.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
Add a name and value into the hash table.
- Description:
- Associate an arbitrary value with a string name and inser into the hash table.
- Parameters:
-
table Hash table returned via rAllocHash. name String name to associate with the data. ptr Arbitrary pointer to associate with the name in the table. flags Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. If flags are zero, the flags provided to rAllocHash are used.
- Returns:
- Added RName reference.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
Add a name and value substring into the hash table.
- Description:
- Associate an arbitrary value with a string name and inser into the hash table. The flags used are: R_DYNAMIC_NAME | R_DYNAMIC_VALUE.
- Parameters:
-
hash Hash table returned via rAllocHash. name String name to associate with the data. nameSize Size of the name string. value Value string to store. valueSize Length of string value.
- Returns:
- Added RName reference.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
Create a hash table.
- Description:
- Creates a hash table that can store arbitrary objects associated with string names.
- Parameters:
-
size Estimated number of names in the hash table. Set to 0 or -1 to get a default (small) hash table. flags Set flags to R_STATIC_NAME if providing statically allocated names. Set to R_TEMPORAL_NAME if the hash must copy the names. Set to R_DYNAMIC_NAME when providing allocated names that the hash may use, own and ultimately free when the hash is free. Set flags to R_STATIC_VALUE if providing statically allocated values. Set to R_DYNAMIC_VALUE when providing allocated values that the hash may use, own and ultimately free when the hash is free. Set to R_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
Copy a hash table.
- Parameters:
-
master Original 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
Free a hash table.
- Parameters:
-
hash Hash table to free.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
Return the count of symbols in a symbol entry.
- Description:
- Returns the number of symbols currently existing in a symbol table.
- Parameters:
-
hash Symbol table returned via rAllocHash.
- Returns:
- Integer count of the number of entries.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
Return the next symbol in a symbol entry.
- Description:
- Continues walking the contents of a symbol table by returning the next entry in the symbol table. A previous call to rGetFirstSymbol or rGetNextSymbol is required to supply the value of the last argument.
- Parameters:
-
hash Hash table hash returned via rAllocHash. next Index of next name.
- Returns:
- Pointer to the first entry in the symbol table.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rLookupName, rLookupNameEntry, rRemoveName
Convert a hash of strings to a single string.
- Parameters:
-
hash Hash pointer returned from rCreateHash. join String to use as the element join string.
- Returns:
- String consisting of the joined hash values.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry, rRemoveName
Lookup a symbol in the hash table.
- Description:
- Lookup a name and return the value associated with that name.
- Parameters:
-
hash Symbol table returned via rAllocHash. name String name of the symbole entry to delete.
- Returns:
- Value associated with the name when the entry was insered via rInserSymbol.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupNameEntry, rRemoveName
Lookup a symbol in the hash table and return the hash entry.
- Description:
- Lookup a name and return the hash table descriptor associated with that name.
- Parameters:
-
hash Symbol table returned via rAllocHash. name String name of the symbole entry to delete.
- Returns:
- RName for the entry.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rRemoveName
Remove a symbol entry from the hash table.
- Description:
- Removes a symbol entry from the symbol table. The entry is looked up via the supplied name.
- Parameters:
-
hash Symbol table returned via rAllocHash. name String name of the symbole entry to delete.
- Returns:
- Returns zero if successful, otherwise a negative RT error code is returned.
- API Stability:
- Evolving.
- See Also:
- RHash, RName, rAddName, rGetHashLength, rGetNextName, rLookupName, rLookupNameEntry
RList
List data structure.
- Description:
- The RList is a dynamic, growable list suitable for storing simple primitive data types or pointers to arbitrary objects.
- See Also:
- RListCompareProc, rAddItem, rAddNullItem, rAllocList, rClearList, rGetItem, rGetNextItem, rInsertItemAt, rLookupItem, rLookupStringItem, rRemoveItem, rRemoveItemAt, rRemoveStringItem, rSetItem, rSortList
- API Stability:
- Internal.
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:
-
list List pointer returned from rAllocList item Pointer 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.
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.
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:
-
size Initial 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. flags Set 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.
Clears the list of all items.
- Description:
- Resets the list length to zero and clears all items.
- Parameters:
-
list List pointer returned from rAllocList.
- API Stability:
- Evolving.
Get an list item.
- Description:
- Get an list item specified by its index.
- Parameters:
-
list List pointer returned from rAllocList. index Item index into the list. Indexes have a range from zero to the lenghth of the list - 1.
- API Stability:
- Evolving.
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:
-
list List pointer returned from rAllocList.
- API Stability:
- Evolving.
Get the next item in the list.
- Description:
- Returns the value of the next item in the list.
- Parameters:
-
list List pointer returned from rAllocList. lastIndex Pointer 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.
Inser an item into a list at a specific position.
- Description:
- Insert the item into the list before the specified position. The list will grow as required to store the item.
- Parameters:
-
list List pointer returned from rAllocList index Location at which to store the item. The previous item at this index is moved to make room. item Pointer 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.
Convert a list of strings to a single string.
This uses the specified join string between the elements- Parameters:
-
list List pointer returned from rAllocList. join String to use as the element join string. May be null.
- API Stability:
- Evolving.
Find an item and return its index.
- Description:
- Search for an item in the list and return its index.
- Parameters:
-
list List pointer returned from rAllocList. item Pointer to value stored in the list.
- Returns:
- Positive list index if found, otherwise a negative RT error code.
- API Stability:
- Evolving.
Find a string item and return its index.
- Description:
- Search for the first matching string in the list and return its index.
- Parameters:
-
list List pointer returned from rAllocList. str Pointer to string to look for.
- Returns:
- Positive list index if found, otherwise a negative RT error code.
- API Stability:
- Evolving.
Pop an item.
- Description:
- Treat the list as a stack and pop the last pushed item.
- Parameters:
-
list List pointer returned from rAllocList.
- Returns:
- The last pushed item. If the list is empty, returns NULL.
- API Stability:
- Evolving.
Push an item onto the list.
- Description:
- Treat the list as a stack and push the last pushed item.
- Parameters:
-
list List pointer returned from rAllocList. item Item to push onto the list.
- API Stability:
- Evolving.
Remove an item from the list.
- Description:
- Search for a specified item and then remove it from the list.
- Parameters:
-
list List pointer returned from rAllocList. item Item pointer to remove.
- Returns:
- The positive index of the removed item, otherwise a negative RT error code.
- API Stability:
- Evolving.
Remove an item from the list.
- Description:
- Removes the element specified by index, from the list. The list index is provided by rInsertItem.
- Returns:
- The positive index of the removed item, otherwise a negative RT error code.
- API Stability:
- Evolving.
Remove a string item from the list.
- Description:
- Search for the first matching string and then remove it from the list.
- Parameters:
-
list List pointer returned from rAllocList. str String value to remove.
- Returns:
- The positive index of the removed item, otherwise a negative RT error code.
- API Stability:
- Evolving.
Set a list item.
- Description:
- Update the list item stored at the specified index.
- Parameters:
-
list List pointer returned from rAllocList. index Location to update. item Pointer to item to store.
- Returns:
- The old item previously at that location index.
- API Stability:
- Evolving.
Quicksort.
- Description:
- This is a quicksor with a context argument.
- Parameters:
-
base Base of array to sor. num Number of array elements. width Width of array elements. compare Comparison function. ctx Context argument to provide to comparison function.
- Returns:
- The base array for chaining.
- API Stability:
- Evolving.
Sor a list.
- Description:
- Sor a list using the sor ordering dictated by the supplied compare function.
- Parameters:
-
list List pointer returned from rAllocList. compare Comparison function. If null, then a default string comparison is used. ctx Context to provide to comparison function.
- Returns:
- The sorted list.
- API Stability:
- Evolving.
RLog
Log Services.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
- API Stability:
- Internal.
- Fields:
-
Asser that a condition is true.
- Parameters:
-
cond Boolean result of a conditional test.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Output an assert failed message.
- Description:
- This will emit an assert failed message to the standard error output. It may bypass the logging system.
- Parameters:
-
loc Source code location string. Use R_LOC to define a file name and line number string suitable for this parameter. msg Simple string message to output.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Backup a log.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
For the current process and run as a daemon.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Emit a debug message to the log.
- Parameters:
-
source Module emitting the log message. fmt Printf style format string. Variable number of arguments to. ... Variable arg list from va_list.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
The default log handler.
- Parameters:
-
type Log message type. source Source of the message. msg Log message.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Test if a log message should be emitted.
- Description:
- This call enables routines to test if messages should be logd for a given type/source pair.
- Parameters:
-
type Log message type string. If null, check "all". source Log message source. If null, chek "all".
- Returns:
- True if the message should be logd.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Emit an error message to the log.
- Parameters:
-
source Module emitting the log message. fmt Printf style format string. Variable number of arguments to. ... Variable arg list from va_list.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rGetLogFile, rGetLogHandler, rLog, rSetLog
Format a log message into a buffer.
- Description:
- This formats the log message according to the current log format string.
- Parameters:
-
buf RBuf instance. type Log message type string. source Log message source. msg Message to log.
- Returns:
- The buffer suitable for chaining calls.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Get the log file file handle.
- Description:
- Returns the file handle used for logging.
- Returns:
- An file handle.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogHandler, rLog, rSetLog
Return the currently configured log handler defined via rSetLogHandler
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rLog, rSetLog
Emit an informational message to the log.
- Parameters:
-
source Module emitting the log message. fmt Printf style format string. Variable number of arguments to. ... Variable arg list from va_list.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Initialize the logging subsystem.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Test if the log has been configured.
- Returns:
- True if the log has been defined.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Emit a log message to the log.
- Parameters:
-
source Module emitting the log message. fmt Printf style format string. Variable number of arguments to. ... Variable arg list from va_list.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rSetLog
Write a message to the error log file.
- Description:
- Send a message to the error log file. The purpose of the error log is to record essential configuration and error conditions. Per-request log typically is sent to a separate 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 "logging: true".
- Parameters:
-
type Message type. source Module emitting the log message. fmt Printf 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, rError, rGetLogFile, rGetLogHandler, rSetLog
Print the product configuration at the start of the log file.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Write a message to the log file.
- Description:
- Send a message to the logging subsystem. The purpose of the log is to record essential configuration and error conditions. Per-request log typically is sent to a separate log.
By default, error 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 "logging: true".
- Parameters:
-
type Message type. source Module emitting the log message. fmt Printf style format string. Variable number of arguments to. args Variable arg list from va_list.
- Remarks:
- RLog is highly useful as a debugging aid.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Emit an EMF metrics message suitable for AWS CloudWatch Metrics.
- Parameters:
-
message Prefix message string. namespace Metric namespace. dimensions Metric dimensions. values Format string of values. ... Arguments for values format string.
- API Stability:
- Prototype.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Set the error code.
- Description:
- Set errno or equivalent.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Initialize logging.
- Parameters:
-
spec The 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. format The 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. force Set to true to overwrite a previous definition.
- Returns:
- Zero if successful, otherwise a negative R error code.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog
Define a filter for log messages.
- Parameters:
-
types Comma separated list of types to emit. Can prefix a type with "!" to subtract from the list. Defaults to "error, info". sources Comma separated list of sources to emit. Can prefix a type with "!" to subtract from the list. Defaults to "all". force Set to true to overwrite a previous definition.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Define a log handler routine that will be invoked to process log messages.
- Parameters:
-
handler Log handler callback function.
- Returns:
- The previous log handler function.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Control timeouts.
- Parameters:
-
on Set to false to disable timeouts for debugging.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Terminate logging.
- API Stability:
- Evolving.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Write the current process pid to /var/run.
- Returns:
- Zero on success, otherwise a negative status code.
- See Also:
- RLogHandler, rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
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:
-
Create a camel case version of the string.
- Description:
- Copy a string into a newly allocated block and make the first character lower case.
- Parameters:
-
str Pointer to the block to duplicate.
- Returns:
- Returns a newly allocated string.
- API Stability:
- Evolving.
Compare strings ignoring case.
This is a r replacement for strcasecmp. It can handle NULL args- Description:
- Compare two strings ignoring case differences. This call operates similarly to strcmp.
- Parameters:
-
s1 First string to compare. s2 Second string to compare.
- Returns:
- Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.
- API Stability:
- Evolving.
Compare strings ignoring case.
This is similar to scaselesscmp but it returns a boolean- Description:
- Compare two strings ignoring case differences.
- Parameters:
-
s1 First string to compare. s2 Second string to compare.
- Returns:
- Returns true if the strings are equivalent, otherwise false.
- API Stability:
- Evolving.
Find a character in a string.
- Description:
- This is a r replacement for strchr. It can handle NULL args.
- Parameters:
-
str String to examine. c Character to search for.
- Returns:
- If the character is found, the call returns a reference to the character position in the string. Otherwise, returns NULL.
- API Stability:
- Evolving.
Clone a string.
- Description:
- Copy a string into a newly allocated block.
- Parameters:
-
str Pointer to the block to duplicate.
- Returns:
- Returns a newly allocated string.
- API Stability:
- Evolving.
Compare strings.
- Description:
- Compare two strings. This is a r replacement for strcmp. It can handle null args.
- Parameters:
-
s1 First string to compare. s2 Second string to compare.
- Returns:
- Returns zero if the strings are identical. Return -1 if the first string is less than the second. Return 1 if the first string is greater than the second.
- API Stability:
- Evolving.
Find a pattern in a string.
- Description:
- Locate the first occurrence of pattern in a string.
- Parameters:
-
str Pointer to the string to search. pattern String pattern to search for.
- Returns:
- Returns a reference to the start of the pattern in the string. If not found, returns NULL.
- API Stability:
- Evolving.
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:
-
dest Pointer to a pointer that will hold the address of the allocated block. destMax Maximum size of the target string in characters. src String to copy.
- Returns:
- The number of characters in the target string.
- API Stability:
- Evolving.
Test if the string ends with a given pattern.
- Parameters:
-
str String to examine. suffix Pattern to search for.
- Returns:
- Returns a pointer to the start of the pattern if found. Otherwise returns NULL.
- API Stability:
- Evolving.
Format a string.
This is a secure verion of printf that can handle null args- Description:
- Format the given arguments according to the printf style format. See rPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.
- Parameters:
-
fmt Printf style format string. ... Variable arguments for the format string.
- Returns:
- Returns a newly allocated string.
- API Stability:
- Evolving.
Format a string into a static buffer.
- Description:
- This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.
- Parameters:
-
buf Pointer to the buffer. maxSize Size of the buffer. fmt Printf style format string. ... Variable arguments to format.
- Returns:
- The buffer.
- API Stability:
- Evolving.
Format a string into a statically allocated buffer.
- Description:
- This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.
- Parameters:
-
buf Pointer to the buffer. maxSize Size of the buffer. fmt Printf style format string. args Varargs argument obtained from va_start.
- Returns:
- The buffer;.
- API Stability:
- Evolving.
Format a string.
This is a secure verion of printf that can handle null args- Description:
- Format the given arguments according to the printf style format. See rPrintf for a full list of the format specifies. This is a secure replacement for sprintf, it can handle null arguments without crashes.
- Parameters:
-
fmt Printf style format string. args Varargs argument obtained from va_start.
- Returns:
- Returns a newly allocated string.
- API Stability:
- Evolving.
Compute a hash code for a string.
- Parameters:
-
str String to examine. len Length in characters of the string to include in the hash code.
- Returns:
- Returns an unsigned integer hash code.
- API Stability:
- Evolving.
Compute a caseless hash code for a string.
- Description:
- This computes a hash code for the string after convering it to lower case.
- Parameters:
-
str String to examine. len Length in characters of the string to include in the hash code.
- Returns:
- Returns an unsigned integer hash code.
- API Stability:
- Evolving.
Convert an integer to a string.
- Description:
- This call convers the supplied 64 bit integer to a string using base 10.
- Parameters:
-
value Integer value to conver.
- Returns:
- An allocated string with the convered number.
- API Stability:
- Evolving.
Convert an integer to a string buffer.
- Description:
- This call convers the supplied 64 bit integer into a string formatted into the supplied buffer according to the specified radix.
- Parameters:
-
buf Pointer to the buffer that will hold the string. size Size of the buffer. value Integer value to conver. radix The base radix to use when encoding the number.
- Returns:
- Returns a reference to the string.
- API Stability:
- Evolving.
Convert an integer to a string.
- Description:
- This call convers the supplied 64 bit integer to a string according to the specified radix.
- Parameters:
-
value Integer value to conver. radix The base radix to use when encoding the number.
- Returns:
- An allocated string with the convered number.
- API Stability:
- Evolving.
Catenate strings.
- Description:
- This catenates strings together with an optional string separator. If the separator is NULL, not separator is used. This call accepts a variable list of strings to append, terminated by a null argument.
- Parameters:
-
str First string to catentate. ... Variable number of string arguments to append. Terminate list with NULL.
- Returns:
- Returns an allocated string.
- API Stability:
- Evolving.
Join an array of strings.
- Parameters:
-
argc number of strings to join. argv Array of strings. sep Separator string to use. If NULL, then no separator is used.
- Returns:
- A single joined string.
- API Stability:
- Evolving.
Join a formatted string to an existing string.
- Description:
- This uses the format and args to create a string that is joined to the first string.
- Parameters:
-
str First string to catentate. fmt First string to catentate. ... Varargs argument obtained from va_start.
- Returns:
- Returns an allocated string.
- API Stability:
- Evolving.
Catenate strings.
- Description:
- This catenates strings together.
- Parameters:
-
str First string to catentate. args Varargs argument obtained from va_start.
- Returns:
- Returns an allocated string.
- API Stability:
- Evolving.
Return the length of a string.
- Description:
- R replacement for strlen. This call returns the length of a string and tests if the length is less than a given maximum. It will return zero for NULL args.
- Parameters:
-
str String to measure.
- Returns:
- The length of the string.
- API Stability:
- Evolving.
Convert a string to lower case.
- Description:
- Convert a string to its lower case equivalent.
- Parameters:
-
str String to conver.
- API Stability:
- Evolving.
Compare strings.
- Description:
- Compare two strings. This is similar to scmp but it returns a boolean.
- Parameters:
-
s1 First string to compare. s2 Second string to compare.
- Returns:
- Returns true if the strings are equivalent, otherwise false.
- API Stability:
- Evolving.
Compare strings ignoring case.
- Description:
- Compare two strings ignoring case differences for a given string length. This call operates similarly to strncasecmp.
- Parameters:
-
s1 First string to compare. s2 Second string to compare. len Length of characters to compare.
- Returns:
- Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.
- API Stability:
- Evolving.
Find a pattern in a string with a limit using a caseless comparison.
- Description:
- Locate the first occurrence of pattern in a string, but do not search more than the given character limit. Use a caseless comparison.
- Parameters:
-
str Pointer to the string to search. pattern String pattern to search for. limit Count of characters in the string to search.
- Returns:
- Returns a reference to the start of the pattern in the string. If not found, returns NULL.
- API Stability:
- Evolving.
Clone a substring.
- Description:
- Copy a substring into a newly allocated block.
- Parameters:
-
str Pointer to the block to duplicate. len Number of bytes to copy. The actual length copied is the minimum of the given length and the length of the supplied string. The result is null terminated.
- Returns:
- Returns a newly allocated string.
- API Stability:
- Evolving.
Compare strings.
- Description:
- Compare two strings for a given string length. This call operates similarly to strncmp.
- Parameters:
-
s1 First string to compare. s2 Second string to compare. len Length of characters to compare.
- Returns:
- Returns zero if the strings are equivalent, < 0 if s1 sors lower than s2 in the collating sequence or > 0 if it sors higher.
- API Stability:
- Evolving.
Find a pattern in a string with a limit.
- Description:
- Locate the first occurrence of pattern in a string, but do not search more than the given character limit.
- Parameters:
-
str Pointer to the string to search. pattern String pattern to search for. limit Count of characters in the string to search.
- Returns:
- Returns a reference to the start of the pattern in the string. If not found, returns NULL.
- API Stability:
- Evolving.
Copy characters from a string.
- Description:
- R replacement for strncpy. Copy bytes from a string and ensure the target string is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is terminated with a null.
- Parameters:
-
dest Pointer to a pointer that will hold the address of the allocated block. destMax Maximum size of the target string in characters. src String to copy. len Maximum count of characters to copy.
- Returns:
- Returns a reference to the destination if successful or NULL if the string won't fit.
- API Stability:
- Evolving.
Locate the a character from a set in a string.
- Description:
- This locates in the string the first occurence of any character from a given set of characters.
- Parameters:
-
str String to examine. set Set of characters to scan for.
- Returns:
- Returns a reference to the first character from the given set. Returns NULL if none found.
- API Stability:
- Evolving.
Tokenize a string.
- Description:
- Split a string into tokens using a string pattern as delimiters.
- Parameters:
-
str String to tokenize. pattern String pattern to use for token delimiters. last Last token pointer.
- Returns:
- Returns a pointer to the next token.
- API Stability:
- Evolving.
Find a character in a string by searching backwards.
- Description:
- This locates in the string the last occurence of a character.
- Parameters:
-
str String to examine. c Character to scan for.
- Returns:
- Returns a reference in the string to the requested character. Returns NULL if none found.
- API Stability:
- Evolving.
Split a string at a delimiter.
- Description:
- Split a string and return pars. The string is modified. This routiner never returns null. If there are leading delimiters, the empty string will be returned and *last will be set to the portion after the delimiters. If str is null, a managed reference to the empty string will be returned. If there are no characters after the delimiter, then *last will be set to the empty string.
- Parameters:
-
str String to tokenize. delim Set of characters that are used as token separators. last Reference to the portion after the delimiters. Will return an empty string if is not trailing portion.
- Returns:
- Returns a pointer to the first par before the delimiters. If the string begins with delimiters, the empty string will be returned.
- API Stability:
- Evolving.
Find the end of a spanning prefix.
- Description:
- This scans the given string for characters from the set and returns an index to the first character not in the set.
- Parameters:
-
str String to examine. set Set of characters to span.
- Returns:
- Returns an index to the first character after the spanning set. If not found, returns the index of the first null.
- API Stability:
- Evolving.
Test if the string starts with a given pattern.
- Parameters:
-
str String to examine. prefix Pattern to search for.
- Returns:
- Returns true if the pattern was found. Otherwise returns zero.
- API Stability:
- Evolving.
Create a substring.
- Parameters:
-
str String to examine. offset Staring offset within str for the beginning of the substring. length Length of the substring in characters.
- Returns:
- Returns a newly allocated substring.
- API Stability:
- Evolving.
Replace template tokens in a string with values from a lookup table.
Tokens are ${variable} references- Parameters:
-
str String to expand. tokens Hash table of token values to use.
- Returns:
- An expanded string. May return the original string if no "$" references are present.
- API Stability:
- Evolving.
Create a Title Case version of the string.
- Description:
- Copy a string into a newly allocated block and make the first character upper case.
- Parameters:
-
str Pointer to the block to duplicate.
- Returns:
- Returns a newly allocated string.
- API Stability:
- Evolving.
Convert a string to a double.
- Description:
- This call convers the supplied string to a double.
- Parameters:
-
str Pointer to the string to parse.
- Returns:
- The double equivalent value of the string.
- API Stability:
- Evolving.
Convert a string to an integer.
- Description:
- This call convers the supplied string to an integer using base 10.
- Parameters:
-
str Pointer to the string to parse.
- Returns:
- The integer equivalent value of the string.
- API Stability:
- Evolving.
Convert a string to an integer.
- Description:
- This call convers the supplied string to an integer using the specified radix (base).
- Parameters:
-
str Pointer to the string to parse. radix Base to use when parsing the string. err Return error code. Set to 0 if successful.
- Returns:
- The integer equivalent value of the string.
Tokenize a string.
- Description:
- Split a string into tokens using a character set as delimiters.
- Parameters:
-
str String to tokenize. delim Set of characters that are used as token separators. last Last token pointer.
- Returns:
- Returns a pointer to the next token inside the original string. Caller must not free the result.
- API Stability:
- Evolving.
String to list.
This parses the string of space separated arguments. Single and double quotes are supported- Parameters:
-
src Source string to parse.
- Returns:
- List of arguments.
- API Stability:
- Evolving.
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:
-
str String to trim. set String of characters to remove. where Flags to indicate trim from the start, end or both. Use R_TRIM_START, R_TRIM_END, R_TRIM_BOTH.
- Returns:
- Returns a newly allocated trimmed string. May not equal str.
- API Stability:
- Evolving.
Convert a string to upper case.
- Description:
- Convert a string to its upper case equivalent.
- Parameters:
-
str String to conver.
- Returns:
- Returns a pointer to the convered string. Will always equal str.
- API Stability:
- Evolving.
Erase the contents of a string.
- Parameters:
-
str String to erase.
- API Stability:
- Evolving.
RWait
Wait object.
- Description:
- The RWait service provides a flexible IO waiting mechansim.
- API Stability:
- Evolving.
Allocate a wait object for a file descriptor.
- Returns:
- A RWait object.
- API Stability:
- Evolving.
Free a wait object.
- API Stability:
- Evolving.
Initialize the I/O wait subsystem.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Define a wait handler function on a wait object.
- Description:
- This will run the designated handler on a coroutine fiber in response to matching I/O events.
- Parameters:
-
wp RWait object. handler Function handler to invoke as the entrypoint in the new coroutine fiber. arg Parameter argument to pass to the handler. mask Set to R_READABLE or R_WRITABLE or both.
- API Stability:
- Evolving.
Terminate the I/O wait subsystem.
- API Stability:
- Evolving.
RbTree
Red/Black Tree.
- Description:
- Self-balancing binary search tree.
- API Stability:
- Evolving.
- Fields:
-
Allocate a red/black tree.
- Parameters:
-
flags Set to RB_DUP if you wish to store duplicate nodes. free Callback to free a node's item data. compare Callback to compare two nodes.
- Returns:
- An RbTree instance.
- API Stability:
- Evolving.
Return the lexically first node.
- Parameters:
-
rbt RbTree allocated via rbAlloc.
- Returns:
- The first node.
- API Stability:
- Evolving.
Free a red/black tree.
- Parameters:
-
rbt RbTree to free. Allocated via rbAlloc.
- API Stability:
- Evolving.
Insert a new data item in the tree.
- Parameters:
-
rbt RbTree allocated via rbAlloc. data User data to store in the tree. The data should contain the lookup key value for the data. The comparison callback will be passed the data and it should be able to extract the key from the data.
- Returns:
- The inserted node.
- API Stability:
- Evolving.
Lookup a data item.
- Parameters:
-
rbt RbTree allocated via rbAlloc. data User data item to search for. This is passed to the comparison callback supplied when calling rbOpen. ctx Context to provide to the comparison callback.
- Returns:
- The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.
- API Stability:
- Evolving.
Return the lexically first matching node.
- Parameters:
-
rbt RbTree allocated via rbAlloc. data User data item to search for. This is passed to the comparison callback supplied when calling rbOpen. ctx Context to provide to the comparison callback.
- Returns:
- The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.
- API Stability:
- Evolving.
Return the next matching node after the given node.
- Parameters:
-
rbt RbTree allocated via rbAlloc. node Starting node for the search. data User data item to search for. This is passed to the comparison callback supplied when calling rbOpen. ctx Context to provide to the comparison callback.
- Returns:
- The located node or NULL if not found. If there are multiple matching nodes, the first node encountered is returned which may not be the first lexically. If you need the first item lexically, use rbLookupFirst.
- API Stability:
- Evolving.
Return the next node in sequence.
- Parameters:
-
rbt RbTree allocated via rbAlloc. node Starting node.
- Returns:
- The next node in the tree.
- API Stability:
- Evolving.
Remove a data item from the tree.
- Parameters:
-
rbt RbTree allocated via rbAlloc. node Node to remove. The node is identified by calling rbLookup. keep If true, the data item will not be freed. Otherwise the free callback will be invoked on the data item.
- API Stability:
- Evolving.
Functions
Allocate a block of memory.
- Description:
- This is the lowest level of memory allocation routine. Memory is freed via rFree.
- Parameters:
-
size Size of the memory block to allocate.
- Returns:
- Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler will be invoked.
- Remarks:
- Do not mix calls to rAlloc and malloc.
- API Stability:
- Evolving.
Allocate and schedule a new event to be run from the event loop.
- Description:
- Allocate an event to run a callback via the event loop. The safe runtime (R) is not thread-safe in general. A few APIs are thread-safe to enable data interchange between R and foreign threads.
This API is thread-safe and may be called by foreign threads. This routine is the only safe way to invoke R services from a foreign-thread.
- Parameters:
-
fiber Fiber object. proc Function to invoke when the event is run. data Data to associate with the event and stored in event->data. delay Time in milliseconds used by continuous events between firing of the event.
- Returns:
- The event object. If called from a foreign thread, note that the event may have already run n return.
- API Stability:
- Internal.
Signal a memory allocation exception.
- Description:
- R uses a global memory allocaction error handler. If doing direct malloc() allocations that fail, call this routine to signal the memory failure and run the allocation handler.
- Parameters:
-
cause Set to R_MEM_WARNING, R_MEM_LIMIT, R_MEM_FAIL or R_MEM_TO_BIG. size Size in bytes of the failing allocation.
- API Stability:
- Evolving.
Allocate a fiber coroutine object.
- Description:
- This allocates a new fiber coroutine. Use rStartFiber to launch.
- Parameters:
-
fn Fiber entry point. data Entry point argument.
- Returns:
- A fiber object.
- API Stability:
- Internal.
Allocate a lock object.
- Description:
- This call creates a lock object that can be used in rLock rTryLock and rUnlock calls.
- API Stability:
- Evolving.
Allocate a socket object.
- Returns:
- A socket object instance.
- API Stability:
- Evolving.
Allocate an object of a given type.
- Description:
- Allocates a zeroed block of memory large enough to hold an instance of the specified type.
- Parameters:
-
type RType of the object to allocate.
- Returns:
- Returns a pointer to the allocated block. If memory is not available the memory allocation handler will be invoked.
- API Stability:
- Evolving.
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.
Close a socket.
- Description:
- Close a socket.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- API Stability:
- Evolving.
Connect a client socket.
- Description:
- Open a client connection. May be called from a fiber or from main.
- If using TLS, this must only be called from a fiber.
- Parameters:
-
sp Socket object returned via rAllocSocket. host Host or IP address to connect to. port TCP/IP port number to connect to. deadline Maximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a deadline.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Create an O/S thread.
- Parameters:
-
name Descriptive name for the thread. proc Thread main function to invoke. data Argument to proc.
- API Stability:
- Evolving.
Convert a time value to local time and format as a string.
- Description:
- R replacement for ctime.
- Parameters:
-
format Time format string. See rFormatUniversalTime for time formats. time Time to format. Use rGetTime to retrieve the current time.
- Returns:
- The formatting time string. Caller msut free.
- API Stability:
- Evolving.
Convert a time value to universal time and format as a string.
- Description:
- Format a time string. This uses strftime if available and so the supported formats vary from platform to platform. Strftime should supports some of these these formats described below.
- Parameters:
-
format Time format string
A ... full weekday name (Monday)
a ... abbreviated weekday name (Mon)
B ... full month name (January)
b ... abbreviated month name (Jan)
C ... century. Year / 100. (0-N)
c ... standard date and time representation
D ... date (m/d/y)
d ... day-of-month (01-31)
e ... day-of-month with a leading space if only one digit ( 1-31)
F ... same as Y-m-d
H ... hour (24 hour clock) (00-23)
h ... same as b
I ... hour (12 hour clock) (01-12)
j ... day-of-year (001-366)
k ... hour (24 hour clock) (0-23)
l ... the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.
M ... minute (00-59)
m ... month (01-12)
n ... a newline
P ... lower case am / pm
p ... AM / PM
R ... same as H:M
r ... same as H:M:S p
S ... second (00-59)
s ... seconds since epoch
T ... time (H:M:S)
t ... a tab.
U ... week-of-year, first day sunday (00-53)
u ... the weekday (Monday as the first day of the week) as a decimal number (1-7).
v ... is equivalent to `e-b-Y '.
W ... week-of-year, first day monday (00-53)
w ... weekday (0-6, sunday is 0)
X ... standard time representation
x ... standard date representation
Y ... year with century
y ... year without century (00-99)
Z ... timezone name
z ... offset from UTC (-hhmm or +hhmm)
%+ ... national representation of the date and time (the format is similar to that produced by date(1)).
%% ... percent sign
Some platforms may also support the following format extensions:
E* ... POSIX locale extensions. Where "*" is one of the characters: c, C, x, X, y, Y.
G ... a year as a decimal number with century. This year is the one that contains the greater par of the week (Monday as the first day of the week).
g ... the same year as in `G ', but as a decimal number without century (00-99).
O* ... POSIX locale extensions. Where "*" is one of the characters: d, e, H, I, m, M, S, u, U, V, w, W, y. Additionly OB implemented to represent alternative months names (used standalone, without day mentioned).
V ... the week number of the year (Monday as the first day of the week) as a decimal number (01-53). If the week containing January 1 has four or more days in the new year, then it is week 1; otherwise it is the last week of the previous year, and the next week is week 1.
Useful formats:
RFC822: "%a, %d %b %Y %H:%M:%S %Z "Fri, 07 Jan 2003 12:12:21 PDT" \n "T F "12:12:21 2007-01-03"
"%v "07-Jul-2003" \n RFC3399: "FTTZ" "1985-04-12T23:20:50.52Z" which is April 12 1985, 23:20.50 and 52 msectime Time to format. Use rGetTime to retrieve the current time.
- Returns:
- The formatting time string. Caller must free.
- API Stability:
- Evolving.
Free a block of memory allocated via rAlloc.
- Description:
- This releases a block of memory allocated via rAllocMem.
- Parameters:
-
ptr Pointer to the block. If ptr is null, the call is skipped.
- Remarks:
- The rFree routine is a macro over rFreeMem. Do not mix calls to rFreeMem and free.
- API Stability:
- Evolving.
Free a fiber coroutine.
- Description:
- The fiber must have already completed before invoking this routine. This routine is typically only called internally by the fiber module.
- Parameters:
-
fiber Fiber to free.
- API Stability:
- Internal.
Free a dynamically allocated lock object.
- Parameters:
-
mutex Reference to an RLock structure to initialize.
- API Stability:
- Evolving.
Free a socket object.
- API Stability:
- Evolving.
Get the application name defined via rSetAppName.
- Returns:
- The one-word lower case application name defined via rSetAppName.
- API Stability:
- Evolving.
Get the current Thread.
- Returns:
- The currently executing thread.
- API Stability:
- Evolving.
Get a string representation of the current date/time.
- Description:
- Get the current date/time as a string according to the given format.
- Parameters:
-
format Date formatting string. See strftime for acceptable date format specifiers. If null, then this routine uses the R_DEFAULT_DATE format.
- Returns:
- A date string. Caller must free.
- API Stability:
- Evolving.
Get the elapsed time since a ticks mark.
Create the ticks mark with rGetTicks()- Parameters:
-
mark Staring time stamp.
- Returns:
- The time elapsed since the mark was taken.
- API Stability:
- Evolving.
Return a string representation of an R error code.
- Parameters:
-
error An R error code. These codes are always negative for errors and zero for R_OK.
- Returns:
- A static string error representation.
- API Stability:
- Evolving.
Get the current fiber object.
- Returns:
- Fiber Fiber object.
- API Stability:
- Evolving.
Get the base address of the fiber stack.
- Returns:
- A pointer to the base of the fiber stack.
- API Stability:
- Evolving.
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.
Get an ISO Date string representation of the given date/time.
- Description:
- Get the date/time as an ISO string.
- Parameters:
-
time Given time to convert.
- Returns:
- A date string. Caller must free.
- API Stability:
- Evolving.
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.
Return the time remaining until a timeout has elapsed.
- Parameters:
-
mark Staring time stamp. timeout Time in milliseconds.
- Returns:
- Time in milliseconds until the timeout elapses.
- API Stability:
- Evolving.
Get the application server name string.
- Returns:
- A string containing the application server name string.
- API Stability:
- Evolving.
Get the locally bound socket IP address and port for the socket.
- Description:
- Get the file descriptor associated with a socket.
- Parameters:
-
sp Socket object returned from rAllocSocket. ipbuf Buffer to receive the IP address. ipbufLen Size of the ipbuf. port Address of an integer to receive the port unumber.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Get the socket file descriptor.
- Description:
- Get the file descriptor associated with a socket.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- Returns:
- The Socket file descriptor used by the O/S for the socket.
- API Stability:
- Evolving.
Get the current R state.
- Returns:
- Returns R_RUNNING, R_STOPPING or R_STOPPED.
- API Stability:
- Evolving.
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.
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.
Return true if timeouts are enabled.
- Returns:
- True if timeouts are enabled.
- API Stability:
- Evolving.
Get the global wait descriptor.
- Returns:
- The wait file descriptor used by epoll and kqueue.
- API Stability:
- Evolving.
Globally lock the application.
- Description:
- This call asserts the application global lock so that other threads calling rGlobalLock will block until the current thread calls rGlobalUnlock. WARNING: Use this API very sparingly.
- API Stability:
- Evolving.
Unlock the global mutex.
- Description:
- This call unlocks the global mutex previously locked via rGlobalLock.
- API Stability:
- Evolving.
Gracefully stop the app.
- Description:
- Queued events will be serviced.
- API Stability:
- Evolving.
Grow the list to be at least the requested size in elements.
- Parameters:
-
list List pointer returned from rAllocList. size Required minimum size for the list.
- API Stability:
- Evolving.
Convert a hash into JSON.
- Parameters:
-
hash Hash table to use for the result. pretty Set to true to have a prettier JSON representation.
- Returns:
- A JSON string. Caller must free.
- API Stability:
- Evolving.
Convert a hash into JSON in the given buffer.
- Parameters:
-
hash Hash table to use for the result. buf RBuf instance to store the json text. pretty Set to true to have a prettier JSON representation.
- Returns:
- The given buffer.
- API Stability:
- Evolving.
Initialize the runtime.
- Description:
- This routine should be called at startup from main().
- Parameters:
-
fn Fiber function to start. arg Argument to the fiber function. stackSize Size of the fiber coroutine stacks.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Initialize the fiber coroutine module.
- Parameters:
-
stackSize Default size of fiber stacks in bytes.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Initialize a statically allocated lock object.
- Description:
- This call initialized a lock object without allocation. The object can then be used used in rLock rTryLock and rUnlock calls.
- Parameters:
-
mutex Reference to an RLock structure to initialize.
- Returns:
- A reference to the supplied mutex. Returns null on errors.
- API Stability:
- Evolving.
Create and initialze the O/S dependent subsystem.
- Description:
- Called internally by the RT. Should not be called by users.
- API Stability:
- Internal.
Test if a fiber is the main fiber.
- Returns:
- True if the fiber is the main fiber.
- API Stability:
- Evolving.
Test if the socket has been closed.
- Description:
- Determine if rCloseSocket has been called.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- Returns:
- True if the socket is at end-of-file.
- API Stability:
- Evolving.
Determine if the socket has connected to a remote pper.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- Returns:
- True if the socket is connected.
- API Stability:
- Evolving.
Test if the other end of the socket has been closed.
- Description:
- Determine if the other end of the socket has been closed and the socket is at end-of-file.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- Returns:
- True if the socket is at end-of-file.
- API Stability:
- Evolving.
Determine if the socket is partway through a TLS handshake.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- Returns:
- True if the socket is handshaking.
- API Stability:
- Evolving.
Determine if the socket is secure.
- Description:
- Determine if the socket is using SSL to provide enhanced security.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- Returns:
- True if the socket is using SSL, otherwise zero.
- API Stability:
- Evolving.
Listen on a server socket for incoming connections.
- Description:
- Open a server socket and listen for client connections. If host is null, then this will listen on both IPv6 and IPv4.
- Parameters:
-
sp Socket object returned via rAllocSocket. host Host name or IP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port. port TCP/IP port number to connect to. handler Function callback to invoke for incoming connections. The function is invoked on a new fiber coroutine. arg Argument to handler.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Lock access.
- Description:
- This call asserts a lock on the given lock mutex so that other threads calling rLock will block until the current thread calls rUnlock.
- Parameters:
-
lock object.
- API Stability:
- Evolving.
Duplicate a block of memory.
- Description:
- Copy a block of memory into a newly allocated block.
- Parameters:
-
ptr Pointer to the block to duplicate. size Size of the block to copy.
- Returns:
- Returns an allocated block.
- API Stability:
- Evolving.
Parse an ISO date string.
- Returns:
- The time in milliseconds since Jan 1, 1970.
- API Stability:
- Evolving.
Read from a socket.
- Description:
- Read data from a socket. The read will return with whatever bytes are available. If none is available, this call will yield the current fiber and resume the main fiber. When data is available, the fiber will resume.
- Must be called from a fiber.
- Parameters:
-
sp Socket object returned from rAllocSocket. buf Pointer to a buffer to hold the read data. bufsize Size of the buffer. deadline Maximum system time for connect to wait until completion. Use rGetTicks() + elapsed to create a deadline.
- 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.
Read from a socket.
- Description:
- Read data from a socket. The read will return with whatever bytes are available. If none and the socket is in blocking mode, it will block until there is some data available or the socket is disconnected. Use rSetSocketBlocking to change the socket blocking mode. It is preferable to use rReadSocket which can wait without blocking via fiber coroutines.
- Parameters:
-
sp Socket object returned from rAllocSocket. buf Pointer to a buffer to hold the read data. bufsize Size of the buffer.
- Returns:
- A count of bytes actually read. Return a negative R error code on errors.
- Returns:
- Return -1 for EOF and errors. On success, return the number of bytes read. Use rIsSocketEof to distinguision between EOF and errors.
- API Stability:
- Evolving.
Reset a socket.
- Description:
- Reset a socket by closing the underlying socket file descriptor. The Socket instance can be reused by rConnectSocket.
- Parameters:
-
sp Socket object returned from rAllocSocket.
- API Stability:
- Evolving.
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:
-
fiber Fiber object. result Result to pass to the fiber and will be the value returned from rYieldFiber.
- API Stability:
- Evolving.
Set the application name, title and version.
- Parameters:
-
name One word, lower case name for the app. title Pascal case multi-word descriptive name. version Version of the app. Major-Minor-Patch. E.g. 1.2.3.
- Returns:
- Zero if successful. Otherwise a negative RT error code.
- API Stability:
- Evolving.
Set the default CA root certificate bundle.
- Parameters:
-
ca File containing the root certificates.
- API Stability:
- Evolving.
Set the default fiber stack size.
- Parameters:
-
size Size of fiber stack in bytes.
- API Stability:
- Internal.
Define a global memory exhaustion handler.
- Description:
- The memory handler will be invoked for memory allocation errors.
- Parameters:
-
handler Callback function invoked with the signature: void fn(int cause, size_t size).
- API Stability:
- Evolving.
Set the O/S error code.
- Description:
- Set errno or equivalent.
- API Stability:
- Evolving.
Set a socket into blocking I/O mode.
from a socket- Description:
- Sockets are opened in non-blocking mode by default.
- Parameters:
-
sp Socket object returned from rAllocSocket. on Set to true to enable blocking mode.
- API Stability:
- Evolving.
Configure the socket TLS certificates.
- Description:
- This call is a wrapper over rSetTLSCerts.
- Parameters:
-
sp Socket object returned from rAllocSocket. key Private key for the certificate. cert Certificate to use for TLS. ca Certificate authority to use when verifying peer connections. revoke List of revoked certificates.
- API Stability:
- Evolving.
Set the ciphers to use for communications.
- Parameters:
-
sp Socket object returned from rAllocSocket. ciphers String of suitable ciphers.
- API Stability:
- Evolving.
Set the socket TLS verification parameters.
- Description:
- This call is a wrapper over rSetTlsCerts.
- Parameters:
-
sp Socket object returned from rAllocSocket. verifyPeer Set to true to verify peer certificates. verifyIssuer Set to true to verify the issuer of the peer certificate.
- API Stability:
- Evolving.
Update the wait mask for a socket.
- Parameters:
-
sp Socket object returned from rAllocSocket. mask Set to R_READABLE or R_WRITABLE or both. deadline System time in ticks to wait until.
- API Stability:
- Evolving.
Set the R state.
- Parameters:
-
state Set to R_RUNNING, R_STOPPING or R_STOPPED.
- API Stability:
- Evolving.
Sleep a fiber for the requested number of milliseconds.
- Must be called from a fiber.
- Description:
- Pause a fiber for the requested duration and then resume via the main fiber. Other fibers continue to run.
- Parameters:
-
ticks Time period in milliseconds to sleep.
- API Stability:
- Evolving.
Spawn a fiber coroutine.
- Description:
- This allocates a new fiber and resumes it.
- Parameters:
-
fn Fiber entry point. arg Entry point argument.
- Returns:
- Zero if successful.
- API Stability:
- Evolving.
Spawn an O/S thread.
- Description:
- This creates a new thread and runs the given function.
- Parameters:
-
fn Thread main function entry point. arg Argument provided to the thread.
- Returns:
- Value returned from fn().
- API Stability:
- Evolving.
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:
-
fiber The fiber object. data Value to pass to the fiber entry point.
- API Stability:
- Internal.
Immediately stop the app.
- Description:
- Queued events will not be serviced.
- API Stability:
- Evolving.
Terminate the fiber coroutine module.
- API Stability:
- Evolving.
Terminate a statically allocated lock object.
- Parameters:
-
mutex Reference to an RLock structure to initialize.
- API Stability:
- Evolving.
Stop the O/S dependent subsystem.
- API Stability:
- Internal.
Attempt to lock access.
- Description:
- This call attempts to assert a lock on the given lock mutex so that other threads calling rLock or rTryLock will block until the current thread calls rUnlock.
- Returns:
- Returns zero if the successful in locking the mutex. Returns a negative error code if unsuccessful.
- API Stability:
- Evolving.
Unlock a mutex.
- Description:
- This call unlocks a mutex previously locked via rLock or rTryLock.
- Parameters:
-
lock object.
- API Stability:
- Evolving.
Write to a socket.
- Description:
- Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. If no data can be written, this call will yield the current fiber and resume the main fiber. When data is available, the fiber will resume.
- Must be called from a fiber.
- Parameters:
-
sp Socket object returned from rAllocSocket. buf Reference to a block to write to the socket. bufsize Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative error code on errors. deadline System time in ticks to wait until.
- 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.
Write to a socket.
- Description:
- Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. It is preferable to use rWriteSocket which can wait without blocking via fiber coroutines.
- Parameters:
-
sp Socket object returned from rAllocSocket. buf Reference to a block to write to the socket. len Length of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative error code on errors.
- Returns:
- A count of bytes actually written. Return a negative error code on errors and if the socket cannot absorb any more data. If the transport is saturated, will return a negative error and rGetError() returns EAGAIN or EWOULDBLOCK.
- API Stability:
- Evolving.
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. This routine is thread safe when invoked from a non-main thread.
- Parameters:
-
value Value to provide as a result to the main fiber that called rResumeFiber.
- API Stability:
- Evolving.
Typedefs
Fiber coroutine stack context.
- API Stability:
- Evolving.
Fiber entry point function.
- Parameters:
-
data Custom function argument.
- API Stability:
- Evolving.
Hashing function to use for the table.
- Parameters:
-
name Name to hash. len Length of the name to hash.
- Returns:
- An integer hash index.
- API Stability:
- Internal.
Memory exhaustion callback procedure.
- Parameters:
-
cause The cause of the memory failure. size The size of the failing block allocation.
Thread entry point function.
- Parameters:
-
data Custom function argument.
- Returns:
- Value to pass back from rSpawnThread.
- API Stability:
- Evolving.
Unsigned integral type.
Equivalent in size to void*Argument for sockets.
Unsigned time type.
Time in seconds since Jan 1, 1970Callback function for events.
- Parameters:
-
data Opaque data argument.
- API Stability:
- Evolving.
Callback function for watched events.
- Parameters:
-
data Opaque data argument supplied via rWatchEvent. arg Watched event arg.
- API Stability:
- Evolving.
List comparison procedure for soring.
- Description:
- Callback function signature used by rSortList
- Parameters:
-
arg1 First list item to compare. arg2 Second 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.
Quicksort callback function.
- Description:
- This is a quicksor callback with a context argument.
- Parameters:
-
p1 Pointer to first element. p2 Pointer to second element. ctx Context 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.
Log handler callback type.
- Description:
- Callback prototype for the log handler. Used by rSetLogHandler to define a message logging handler to process log and error messages. See rLog for more details.
- Parameters:
-
type The message type: 'code', 'error', 'info', 'log'. source The message source. msg Log message.
- API Stability:
- Evolving.
- See Also:
- rError, rGetLogFile, rGetLogHandler, rLog, rSetLog
Callback function for IO wait events.
- Parameters:
-
data Opaque data argument. mask IO event selection mask.
- API Stability:
- Evolving.
Callback to compare a data nodes.
- Description:
- The comparison function may perform a simple "strcmp" style comparison function or it may perform a modified comparison using the supplied context information. For example: a comparison could perform a "startsWith" style comparison. The context argument can control the type of comparison that is performed.
- Parameters:
-
n1 Reference to first item. n2 Reference to item to compare. ctx Context provided to rbLookup.
- Returns:
- Return -1 if n1 is lexically less than n2. Zero if equal and 1 if n1 is greater than n2.
- API Stability:
- Evolving.
Callback to free a nodes associated data.
- Parameters:
-
data Reference to the associated data for a node.
- API Stability:
- Evolving.
Fiber state.
- API Stability:
- Evolving.
- Fields:
-
Multithreading lock control structure.
- Description:
- RLock is used for multithread locking in multithreaded applications.
- Fields:
-
- API Stability:
- Evolving.