Mpr - Portable Runtime Native API

Michael's Portable Runtime (MPR) is a portable runtime core for embedded applications.

The MPR provides management for logging, error handling, events, files, http, memory, ssl, sockets, strings, xml parsing, 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. It is correctly handles null arguments without crashing. The MPR is a library and a C API that can be used in both C and C++ programs.

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

The MPR includes a memory manager to minimize memory leaks and maximize allocation efficiency. It utilizes a heap and slab allocators with tree links. All memory allocated is connected to a parent memory block thus forming a tree. When any block is freed, all child blocks are also freed. Most MPR APIs take a memory parent context as the first parameter.

Many of these APIs are not thread-safe. If utilizing multithreaded programming on a supporting operating system, be careful if you modify or delete the underlying data while accessing the resource from another thread.

Components

Mpr Primary MPR application control structure.
MprBuf Dynamic Buffer Module.
MprDate Date and Time Service.
MprEvent Event object.
MprFile File I/O Module.
MprHash Hash table entry structure.
MprList List Module.
MprLog Logging Services.
MprMem Memory Allocation Service.
MprModule Loadable Module Service.
MprPath Path (filename) Services Module.
MprPoolService Thread Pool Service.
MprSocket Socket Service.
MprSynch Multithreaded Synchronization Services.
MprThread Thread Service.
MprUri URI management.
MprWaitHandler Wait Handler Service.

Functions

char*mprAsprintf(MprCtx ctx, int maxSize, cchar *fmt, ...)
 Format a string into an allocated buffer.
intmprAtoi(cchar *str, int radix)
 Convert a string to an integer.
MprFile*mprAttachFd(MprCtx ctx, int fd, cchar *name, int omode)
 Attach to an existing file descriptor.
intmprAvailablePoolThreads(MprCtx ctx)
 Get the count of available pool threads Return the count of free threads in the thread pool.
voidmprBreakpoint()
 Trigger a breakpoint.
voidmprClearList(MprList *list)
 Clears the list of all items.
voidmprCloseSocket(MprSocket *sp, bool graceful)
 Close a socket.
voidmprCompactBuf(MprBuf *buf)
 Compact the buffer contents.
MprHashTable*mprCopyHash(MprCtx ctx, MprHashTable *table)
 Copy a hash table.
intmprCopyList(MprList *dest, MprList *src)
 Copy a list.
intmprCopyPath(MprCtx ctx, cchar *from, cchar *to, int omode)
 Copy a file.
Mpr*mprCreate(int argc, char **argv, MprAllocNotifier cback)
 Create an instance of the MPR.
MprBuf*mprCreateBuf(MprCtx ctx, int initialSize, int maxSize)
 Create a new buffer.
MprCond*mprCreateCond(MprCtx ctx)
 Create a condition lock variable.
MprEvent*mprCreateEvent(MprCtx ctx, MprEventProc proc, int period, int priority, void *data, int flags)
 Create a new event.
Mpr*mprCreateEx(int argc, char **argv, MprAllocNotifier cback, void *shell)
 Create an instance of the MPR.
MprHashTable*mprCreateHash(MprCtx ctx, int hashSize)
 Create a hash table.
MprKeyValue*mprCreateKeyPair(MprCtx ctx, cchar *key, cchar *value)
 Create a key / value pair.
MprList*mprCreateList(MprCtx ctx)
 Create a list.
MprMutex*mprCreateLock(MprCtx ctx)
 Create a Mutex lock object.
MprModule*mprCreateModule(MprCtx ctx, cchar *name, cchar *version, void *moduleData, MprModuleProc start, MprModuleProc stop)
 Create a module.
MprSocket*mprCreateSocket(MprCtx ctx, struct MprSsl *ssl)
 Create a socket.
MprSpin*mprCreateSpinLock(MprCtx ctx)
 Create a spin lock lock object.
MprThread*mprCreateThread(MprCtx ctx, cchar *name, MprThreadProc proc, void *data, int priority, int stackSize)
 Create a new thread.
MprEvent*mprCreateTimerEvent(MprCtx ctx, MprEventProc proc, int period, int priority, void *data, int flags)
 Create a timer event.
MprWaitHandler*mprCreateWaitHandler(MprCtx ctx, int fd, int mask, MprWaitProc proc, void *data, int priority, int flags)
 Create a wait handler.
intmprCtime(MprCtx ctx, char *buf, int bufsize, MprTime time)
 Convert time to local time and format as a string.
intmprDeletePath(MprCtx ctx, cchar *path)
 Delete a file.
voidmprDisableFileBuffering(MprFile *file)
 Disable file buffering.
voidmprDisableWaitEvents(MprWaitHandler *wp, bool wakeup)
 Disable wait events.
MprList*mprDupList(MprCtx ctx, MprList *src)
 Duplicate a list.
intmprEnableFileBuffering(MprFile *file, int size, int maxSize)
 Enable file buffering.
voidmprEnableWaitEvents(MprWaitHandler *wp, bool wakeup)
 Enable wait events.
voidmprError(MprCtx ctx, cchar *fmt, ...)
 Log an error message.
char*mprEscapeCmd(MprCtx ctx, cchar *cmd, int escChar)
 Encode a string escaping typical command (shell) characters.
char*mprEscapeHtml(MprCtx ctx, cchar *html)
 Encode a string by escaping typical HTML characters.
voidmprFatalError(MprCtx ctx, cchar *fmt, ...)
 Log a fatal error message and exit.
intmprFlush(MprFile *file)
 Flush any buffered write data.
voidmprFlushBuf(MprBuf *buf)
 Flush the buffer contents.
intmprFlushSocket(MprSocket *sp)
 Flush a socket.
char*mprFormatUri(MprCtx ctx, cchar *protocol, cchar *host, int port, cchar *path, cchar *query)
 Format a URI.
intmprFprintf(struct MprFile *file, cchar *fmt, ...)
 Print a formatted message to a file descriptor.
intmprFree(void *ptr)
 Free a block of memory.
char*mprGetAbsPath(MprCtx ctx, cchar *path)
 Convert a path to an absolute path.
intmprGetBlockFromBuf(MprBuf *buf, uchar *blk, int count)
 Get a block of data from the buffer.
char*mprGetBufEnd(MprBuf *buf)
 Get a reference to the end of the buffer contents.
intmprGetBufLength(MprBuf *buf)
 Get the buffer content length.
char*mprGetBufOrigin(MprBuf *buf)
 Get the origin of the buffer content storage.
MprBufProcmprGetBufRefillProc(MprBuf *buf)
 Get the buffer refill procedure.
intmprGetBufSize(MprBuf *buf)
 Get the current size of the buffer content storage.
intmprGetBufSpace(MprBuf *buf)
 Get the space available to store content.
char*mprGetBufStart(MprBuf *buf)
 Get the start of the buffer contents.
intmprGetc(MprFile *file)
 Read a character from the file.
intmprGetCharFromBuf(MprBuf *buf)
 Get a character from the buffer.
MprOsThreadmprGetCurrentOsThread()
 Get the O/S thread.
char*mprGetCurrentPath(MprCtx ctx)
 Return the current working directory.
MprThread*mprGetCurrentThread(MprCtx ctx)
 Get the currently executing thread.
boolmprGetDebugMode(MprCtx ctx)
 Get the debug mode.
MprOffsetmprGetFilePosition(MprFile *file)
 Return the current file position.
MprOffsetmprGetFileSize(MprFile *file)
 Get the size of the file.
MprHash*mprGetFirstHash(MprHashTable *table)
 Return the first symbol in a symbol entry.
void*mprGetFirstItem(MprList *list)
 Get the first item in the list.
intmprGetHashCount(MprHashTable *table)
 Return the count of symbols in a symbol entry.
cchar*mprGetHttpCodeString(MprCtx ctx, int code)
 Get the Http reponse code as a string.
void*mprGetItem(MprList *list, int index)
 Get an list item.
void*mprGetLastItem(MprList *list)
 Get the last item in the list.
intmprGetListCapacity(MprList *list)
 Get the current capacity of the list.
intmprGetListCount(MprList *list)
 Get the number of items in the list.
MprLogHandlermprGetLogHandler(MprCtx ctx)
 Get the current MPR debug log handler.
intmprGetMaxPoolThreads(MprCtx ctx)
 Get the maximum count of pool threads Get the maximum limit of pool threads.
cchar*mprGetModuleSearchPath(MprCtx ctx)
 Get the module search path.
char*mprGetNativePath(MprCtx ctx, cchar *path)
 Get a path formatted according to the native O/S conventions.
MprHash*mprGetNextHash(MprHashTable *table, MprHash *last)
 Return the next symbol in a symbol entry.
void*mprGetNextItem(MprList *list, int *lastIndex)
 Get the next item in the list.
char*mprGetNormalizedPath(MprCtx ctx, cchar *path)
 Normalize a path.
intmprGetOsError()
 Return the O/S error code.
void*mprGetParent(MprCtx ctx)
 Get the memory parent of a block.
char*mprGetPathBase(MprCtx ctx, cchar *path)
 Get the base portion of a path.
char*mprGetPathDir(MprCtx ctx, cchar *path)
 Get the directory portion of a path.
cchar*mprGetPathExtension(MprCtx ctx, cchar *path)
 Get the file extension portion of a path.
MprList*mprGetPathFiles(MprCtx ctx, cchar *dir, bool enumDirs)
 Create a directory list of files.
intmprGetPathInfo(MprCtx ctx, cchar *path, MprPath *info)
 Return information about a file represented by a path.
cchar*mprGetPathNewline(MprCtx ctx, cchar *path)
 Get the file newline character string for a given path.
char*mprGetPathParent(MprCtx ctx, cchar *path)
 Get the parent directory of a path.
cchar*mprGetPathSeparators(MprCtx ctx, cchar *path)
 Get the path directory separator.
char*mprGetPortablePath(MprCtx ctx, cchar *path)
 Get a portable path.
void*mprGetPrevItem(MprList *list, int *lastIndex)
 Get the previous item in the list.
char*mprGetRelPath(MprCtx ctx, cchar *path)
 Get a relative path.
char*mprGets(MprFile *file, char *buf, uint size)
 Read a line from the file.
boolmprGetSocketBlockingMode(MprSocket *sp)
 Get the socket blocking mode.
boolmprGetSocketEof(MprSocket *sp)
 Test if the other end of the socket has been closed.
intmprGetSocketError(MprSocket *sp)
 Get a socket error code.
intmprGetSocketFd(MprSocket *sp)
 Get the socket file descriptor.
intmprGetSocketPort(MprSocket *sp)
 Get the port used by a socket.
char*mprGetTempPath(MprCtx ctx, cchar *tmpDir)
 Make a temporary file.
cchar*mprGetThreadName(MprThread *thread)
 Get the thread name.
intmprGetThreadPriority(MprThread *thread)
 Get the thread priroity.
MprTimemprGetTime(MprCtx ctx)
 Get the system time.
char*mprGetTransformedPath(MprCtx ctx, cchar *path, int flags)
 Transform a path.
char*mprGetWordTok(char *buf, int bufsize, cchar *str, cchar *delim, cchar **tok)
 Get the next word token.
voidmprGlobalLock(MprCtx ctx)
 Globally lock the application.
voidmprGlobalUnlock(MprCtx ctx)
 Unlock the global mutex.
struct tm*mprGmtime(MprCtx ctx, struct tm *timep, MprTime time)
 Convert time to UTC and parse into a time structure.
intmprGrowBuf(MprBuf *buf, int count)
 Grow the buffer.
voidmprInitList(MprList *list)
 Initialize a list structure.
MprMutex*mprInitLock(MprCtx ctx, MprMutex *mutex)
 Initialize a statically allocated Mutex lock object.
MprSpin*mprInitSpinLock(MprCtx ctx, MprSpin *lock)
 Initialize a statically allocated spinlock object.
intmprInsertCharToBuf(MprBuf *buf, int c)
 Insert a character into the buffer.
intmprInsertItemAtPos(MprList *list, int index, cvoid *item)
 Insert an item into a list at a specific position.
boolmprIsAbsPath(MprCtx ctx, cchar *path)
 Determine if a path is absolute.
boolmprIsExiting(MprCtx ctx)
 Determine if the MPR should exit.
boolmprIsRelPath(MprCtx ctx, cchar *path)
 Determine if a path is relative.
char*mprItoa(char *buf, int size, int value, int radix)
 Convert an integer to a string.
char*mprJoinPath(MprCtx ctx, cchar *dir, cchar *other)
 Join paths.
char*mprJoinPathExt(MprCtx ctx, cchar *dir, cchar *ext)
 Join an extension to a path.
MprModule*mprLoadModule(MprCtx ctx, cchar *filename, cchar *entryPoint)
 Load a module.
struct tm*mprLocaltime(MprCtx ctx, struct tm *timep, MprTime time)
 Convert time to local representation.
voidmprLock(MprMutex *lock)
 Lock access.
voidmprLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a message to the diagnostic log file.
intmprLookAtLastCharInBuf(MprBuf *buf)
 Peek at the last character in the buffer.
intmprLookAtNextCharInBuf(MprBuf *buf)
 Peek at the next character in the buffer.
cvoid*mprLookupHash(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table.
MprHash*mprLookupHashEntry(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table and return the hash entry.
intmprLookupItem(MprList *list, cvoid *item)
 Find an item and return its index.
MprModule*mprLookupModule(MprCtx ctx, cchar *name)
 Lookup a module.
intmprMakeDir(MprCtx ctx, cchar *path, int perms, bool makeMissing)
 Make a directory.
voidmprMapSeparators(MprCtx ctx, char *path, int separator)
 Map the separators in a path.
intmprMemcmp(cvoid *b1, int b1Len, cvoid *b2, int b2Len)
 Compare two byte strings.
intmprMemcpy(void *dest, int destMax, cvoid *src, int nbytes)
 Safe copy for a block of data.
void*mprMemdup(MprCtx ctx, cvoid *ptr, uint size)
 Duplicate a block of memory.
voidmprMemoryError(MprCtx ctx, cchar *fmt, ...)
 Log a memory error message.
MprFile*mprOpen(MprCtx ctx, cchar *filename, int omode, int perms)
 Open a file.
intmprOpenClientSocket(MprSocket *sp, cchar *hostName, int port, int flags)
 Open a client socket.
intmprOpenServerSocket(MprSocket *sp, cchar *ipAddr, int port, MprSocketAcceptProc acceptFn, void *data, int flags)
 Open a server socket.
MprUri*mprParseUri(MprCtx ctx, cchar *uri)
 Parse a URI.
boolmprPathExists(MprCtx ctx, cchar *path, int omode)
 Determine if a file exists for a path name and can be accessed.
intmprPeekc(MprFile *file)
 Non-destructively read a character from the file.
intmprPrintf(MprCtx ctx, cchar *fmt, ...)
 Formatted print.
intmprPrintfError(MprCtx ctx, cchar *fmt, ...)
 Print a formatted message to the standard error channel.
intmprPutBlockToBuf(MprBuf *buf, cchar *ptr, int size)
 Put a block to the buffer.
intmprPutc(MprFile *file, int c)
 Write a character to the file.
intmprPutCharToBuf(MprBuf *buf, int c)
 Put a character to the buffer.
intmprPutFmtToBuf(MprBuf *buf, cchar *fmt, ...)
 Put a formatted string to the buffer.
intmprPutIntToBuf(MprBuf *buf, int i)
 Put an integer to the buffer.
intmprPuts(MprFile *file, cchar *buf, uint size)
 Write a line to the file.
intmprPutStringToBuf(MprBuf *buf, cchar *str)
 Put a string to the buffer.
voidmprRawLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a raw log message to the diagnostic log file.
intmprRead(MprFile *file, void *buf, uint size)
 Read data from a file.
intmprReadSocket(MprSocket *sp, void *buf, int size)
 Read from a socket.
void*mprRealloc(MprCtx ctx, void *ptr, uint size)
 Reallocate a block.
char*mprReallocStrcat(MprCtx ctx, int max, char *buf, cchar *src, ...)
 Append strings to an existing string and reallocate as required.
voidmprRecallWaitHandler(MprWaitHandler *wp)
 Recall a wait handler.
intmprRefillBuf(MprBuf *buf)
 Refill the buffer with data.
voidmprRemoveEvent(MprEvent *event)
 Remove an event.
intmprRemoveHash(MprHashTable *table, cchar *key)
 Remove a symbol entry from the hash table.
intmprRemoveItem(MprList *list, void *item)
 Remove an item from the list.
intmprRemoveItemAtPos(MprList *list, int index)
 Remove an item from the list.
intmprRemoveLastItem(MprList *list)
 Remove the last item from the list.
intmprRemoveRangeOfItems(MprList *list, int start, int end)
 Remove a range of items from the list.
voidmprRescheduleEvent(MprEvent *event, int period)
 Reschedule an event.
voidmprResetAllocError(MprCtx ctx)
 Reset the memory allocation error flag.
voidmprResetBufIfEmpty(MprBuf *buf)
 Reset the buffer.
voidmprRestartContinuousEvent(MprEvent *event)
 Restart an event.
intmprRfctime(MprCtx ctx, char *buf, int bufsize, const struct tm *timep)
 Format time according to RFC822.
intmprSamePath(MprCtx ctx, cchar *path1, cchar *path2)
 Compare two paths if they are the same.
intmprSamePathCount(MprCtx ctx, cchar *path1, cchar *path2, int len)
 Compare two paths if they are the same for a given length.
char*mprSearchPath(MprCtx ctx, cchar *path, int flags, cchar *search, ...)
 Search for a path.
longmprSeek(MprFile *file, int seekType, long distance)
 Seek the I/O pointer to a new location in the file.
MprOffsetmprSendFileToSocket(MprFile *file, MprSocket *sock, MprOffset offset, int bytes, MprIOVec *beforeVec, int beforeCount, MprIOVec *afterVec, int afterCount)
 Send a file to a socket.
intmprServiceEvents(MprCtx ctx, int delay, int flags)
 Service events.
voidmprSetAllocLimits(MprCtx ctx, uint redline, uint maxMemory)
 Configure the application memory limits.
voidmprSetBufMax(MprBuf *buf, int maxSize)
 Set the maximum buffer size.
voidmprSetBufRefillProc(MprBuf *buf, MprBufProc fn, void *arg)
 Set the buffer refill procedure.
intmprSetBufSize(MprBuf *buf, int size, int maxSize)
 Set the buffer size.
voidmprSetCurrentThreadPriority(MprCtx ctx, int priority)
 Set the thread priroity for the current thread.
voidmprSetDebugMode(MprCtx ctx, bool on)
 Turn on debug mode.
voidmprSetDestructor(void *ptr, MprDestructor destructor)
 Update the destructor for a block of memory.
void*mprSetItem(MprList *list, int index, cvoid *item)
 Set a list item.
intmprSetListLimits(MprList *list, int initialSize, int maxSize)
 Define the list size limits.
voidmprSetLogHandler(MprCtx ctx, MprLogHandler handler, void *handlerData)
 Set an MPR debug log handler.
voidmprSetLogLevel(MprCtx ctx, int level)
 Set the current logging level.
voidmprSetMaxPoolThreads(MprCtx ctx, int count)
 Set the maximum count of pool threads Set the maximum number of pool threads for the MPR.
voidmprSetMinPoolThreads(MprCtx ctx, int count)
 Set the minimum count of pool threads Set the count of threads the pool will have.
voidmprSetModuleSearchPath(MprCtx ctx, char *searchPath)
 Set the module search path.
intmprSetSocketBlockingMode(MprSocket *sp, bool on)
 Set the socket blocking mode.
voidmprSetSocketCallback(MprSocket *sp, MprSocketProc fn, void *data, void *data2, int mask, int priority)
 Set the socket callback.
voidmprSetSocketEventMask(MprSocket *sp, int mask)
 Define the events of interest for a socket.
intmprSetSocketNoDelay(MprSocket *sp, bool on)
 Set the socket delay mode.
voidmprSetThreadPriority(MprThread *thread, int priority)
 Set the thread priroity.
voidmprSetWaitCallback(MprWaitHandler *wp, MprWaitProc proc, int mask)
 Define the wait handler callback.
voidmprSetWaitInterest(MprWaitHandler *wp, int mask)
 Define the events of interest for a wait handler.
voidmprSignalCond(MprCond *cond)
 Signal a condition lock variable.
voidmprSignalExit(MprCtx ctx)
 Signal the MPR to exit gracefully.
boolmprSocketIsSecure(MprSocket *sp)
 Determine if the socket is secure.
voidmprSortList(MprList *list, MprListCompareProc compare)
 Sort a list.
voidmprSpinLock(MprSpin *lock)
 Lock a spinlock.
voidmprSpinUnlock(MprSpin *lock)
 Unlock a spinlock.
char*mprSprintf(char *buf, int maxSize, cchar *fmt, ...)
 Format a string into a statically allocated buffer.
intmprStartThread(MprThread *thread)
 Start a thread.
voidmprStaticAssert(cchar *loc, cchar *msg)
 Output an assertion failed message.
voidmprStaticError(MprCtx ctx, cchar *fmt, ...)
 Write a message to the diagnostic log file without allocating any memory.
intmprStaticPrintf(MprCtx ctx, cchar *fmt, ...)
 Print a message to the applications standard output without allocating memory.
intmprStaticPrintfError(MprCtx ctx, cchar *fmt, ...)
 Print a message to the standard error channel without allocating memory.
char*mprStealBuf(MprCtx ctx, MprBuf *buf)
 Steal the buffer memory from a buffer.
voidmprStopContinuousEvent(MprEvent *event)
 Stop an event.
char*mprStrcat(MprCtx ctx, int max, cchar *src, ...)
 Catenate strings.
intmprStrcmp(cchar *str1, cchar *str2)
 Compare strings.
intmprStrcmpAnyCase(cchar *str1, cchar *str2)
 Compare strings ignoring case.
intmprStrcmpAnyCaseCount(cchar *str1, cchar *str2, int len)
 Compare strings ignoring case.
intmprStrcpy(char *dest, int destMax, cchar *src)
 Copy a string.
intmprStrcpyCount(char *dest, int destMax, cchar *src, int count)
 Copy characters from a string.
char*mprStrdup(MprCtx ctx, cchar *str)
 Safe replacement for strdup.
intmprStrlen(cchar *src, int max)
 Return the length of a string.
char*mprStrLower(char *str)
 Convert a string to lower case.
char*mprStrndup(MprCtx ctx, cchar *str, uint size)
 Duplicate a string.
char*mprStrnstr(cchar *str, cchar *pattern, int len)
 Find a substring.
char*mprStrTok(char *str, cchar *delim, char **last)
 Tokenize a string.
char*mprStrTrim(char *str, cchar *set)
 Trim a string.
char*mprStrUpper(char *str)
 Convert a string to upper case.
voidmprTerminate(MprCtx ctx, bool graceful)
 Terminate the MPR.
char*mprTrimPathExtension(MprCtx ctx, cchar *path)
 Trim an extension from a path.
intmprTruncatePath(MprCtx ctx, cchar *path, int size)
 Truncate a path.
boolmprTryLock(MprMutex *lock)
 Attempt to lock access.
boolmprTrySpinLock(MprSpin *lock)
 Attempt to lock access on a spin lock.
voidmprUnloadModule(MprModule *mp)
 Unload a module.
voidmprUnlock(MprMutex *lock)
 Unlock a mutex.
char*mprUrlDecode(MprCtx ctx, cchar *url)
 Decode a URL string by de-scaping URL characters.
char*mprUrlEncode(MprCtx ctx, cchar *url)
 Encode a string by escaping URL characters.
voidmprUserError(MprCtx ctx, cchar *fmt, ...)
 Display an error message to the user.
char*mprValidateUrl(MprCtx ctx, char *url)
 Validate a URL.
char*mprVasprintf(MprCtx ctx, int maxSize, cchar *fmt, va_list arg)
 Allocate a buffer of sufficient length to hold the formatted string.
char*mprVsprintf(char *buf, int maxSize, cchar *fmt, va_list args)
 Format a string into a statically allocated buffer.
intmprWaitForCond(MprCond *cond, int timeout)
 Wait for a condition lock variable.
intmprWaitForSingleIO(MprWaitHandler *wp, int fd, int mask, int timeout)
 Wait for I/O on an event handler.
intmprWrite(MprFile *file, cvoid *buf, uint count)
 Write data to a file.
intmprWriteFormat(MprFile *file, cchar *fmt, ...)
 Write formatted data to a file.
intmprWriteSocket(MprSocket *sp, void *buf, int len)
 Write to a socket.
intmprWriteSocketString(MprSocket *sp, cchar *str)
 Write to a string to a socket.
intmprWriteSocketVector(MprSocket *sp, MprIOVec *iovec, int count)
 Write a vector to a socket.
intmprWriteString(MprFile *file, cchar *str)
 Write a string to a file.
voidmprBreakpoint()
 Trigger a breakpoint.
Mpr*mprCreate(int argc, char **argv, MprAllocNotifier cback)
 Create an instance of the MPR.
Mpr*mprCreateEx(int argc, char **argv, MprAllocNotifier cback, void *shell)
 Create an instance of the MPR.
boolmprGetDebugMode(MprCtx ctx)
 Get the debug mode.
intmprGetOsError()
 Return the O/S error code.
boolmprIsExiting(MprCtx ctx)
 Determine if the MPR should exit.
voidmprSignalExit(MprCtx ctx)
 Signal the MPR to exit gracefully.
voidmprTerminate(MprCtx ctx, bool graceful)
 Terminate the MPR.
voidmprAddNullToBuf(MprBuf *buf)
 Add a null character to the buffer contents.
voidmprAdjustBufEnd(MprBuf *buf, int count)
 Adjust the buffer end position.
voidmprAdjustBufStart(MprBuf *buf, int count)
 Adjust the buffer start position.
voidmprCompactBuf(MprBuf *buf)
 Compact the buffer contents.
MprBuf*mprCreateBuf(MprCtx ctx, int initialSize, int maxSize)
 Create a new buffer.
voidmprFlushBuf(MprBuf *buf)
 Flush the buffer contents.
intmprGetBlockFromBuf(MprBuf *buf, uchar *blk, int count)
 Get a block of data from the buffer.
char*mprGetBufEnd(MprBuf *buf)
 Get a reference to the end of the buffer contents.
intmprGetBufLength(MprBuf *buf)
 Get the buffer content length.
char*mprGetBufOrigin(MprBuf *buf)
 Get the origin of the buffer content storage.
MprBufProcmprGetBufRefillProc(MprBuf *buf)
 Get the buffer refill procedure.
intmprGetBufSize(MprBuf *buf)
 Get the current size of the buffer content storage.
intmprGetBufSpace(MprBuf *buf)
 Get the space available to store content.
char*mprGetBufStart(MprBuf *buf)
 Get the start of the buffer contents.
intmprGetCharFromBuf(MprBuf *buf)
 Get a character from the buffer.
intmprGrowBuf(MprBuf *buf, int count)
 Grow the buffer.
intmprInsertCharToBuf(MprBuf *buf, int c)
 Insert a character into the buffer.
intmprLookAtLastCharInBuf(MprBuf *buf)
 Peek at the last character in the buffer.
intmprLookAtNextCharInBuf(MprBuf *buf)
 Peek at the next character in the buffer.
intmprPutBlockToBuf(MprBuf *buf, cchar *ptr, int size)
 Put a block to the buffer.
intmprPutCharToBuf(MprBuf *buf, int c)
 Put a character to the buffer.
intmprPutFmtToBuf(MprBuf *buf, cchar *fmt, ...)
 Put a formatted string to the buffer.
intmprPutIntToBuf(MprBuf *buf, int i)
 Put an integer to the buffer.
intmprPutStringToBuf(MprBuf *buf, cchar *str)
 Put a string to the buffer.
intmprRefillBuf(MprBuf *buf)
 Refill the buffer with data.
voidmprResetBufIfEmpty(MprBuf *buf)
 Reset the buffer.
voidmprSetBufMax(MprBuf *buf, int maxSize)
 Set the maximum buffer size.
voidmprSetBufRefillProc(MprBuf *buf, MprBufProc fn, void *arg)
 Set the buffer refill procedure.
intmprSetBufSize(MprBuf *buf, int size, int maxSize)
 Set the buffer size.
char*mprStealBuf(MprCtx ctx, MprBuf *buf)
 Steal the buffer memory from a buffer.
intmprAsctime(MprCtx ctx, char *buf, int bufsize, const struct tm *timeptr)
 Format time as a string.
intmprCtime(MprCtx ctx, char *buf, int bufsize, MprTime time)
 Convert time to local time and format as a string.
MprTimemprGetTime(MprCtx ctx)
 Get the system time.
struct tm*mprGmtime(MprCtx ctx, struct tm *timep, MprTime time)
 Convert time to UTC and parse into a time structure.
struct tm*mprLocaltime(MprCtx ctx, struct tm *timep, MprTime time)
 Convert time to local representation.
MprEvent*mprCreateEvent(MprCtx ctx, MprEventProc proc, int period, int priority, void *data, int flags)
 Create a new event.
MprEvent*mprCreateTimerEvent(MprCtx ctx, MprEventProc proc, int period, int priority, void *data, int flags)
 Create a timer event.
voidmprRemoveEvent(MprEvent *event)
 Remove an event.
voidmprRescheduleEvent(MprEvent *event, int period)
 Reschedule an event.
voidmprRestartContinuousEvent(MprEvent *event)
 Restart an event.
intmprServiceEvents(MprCtx ctx, int delay, int flags)
 Service events.
voidmprStopContinuousEvent(MprEvent *event)
 Stop an event.
MprFile*mprAttachFd(MprCtx ctx, int fd, cchar *name, int omode)
 Attach to an existing file descriptor.
voidmprDisableFileBuffering(MprFile *file)
 Disable file buffering.
intmprEnableFileBuffering(MprFile *file, int size, int maxSize)
 Enable file buffering.
intmprFlush(MprFile *file)
 Flush any buffered write data.
intmprGetc(MprFile *file)
 Read a character from the file.
MprOffsetmprGetFilePosition(MprFile *file)
 Return the current file position.
MprOffsetmprGetFileSize(MprFile *file)
 Get the size of the file.
char*mprGets(MprFile *file, char *buf, uint size)
 Read a line from the file.
MprFile*mprOpen(MprCtx ctx, cchar *filename, int omode, int perms)
 Open a file.
intmprPeekc(MprFile *file)
 Non-destructively read a character from the file.
intmprPutc(MprFile *file, int c)
 Write a character to the file.
intmprPuts(MprFile *file, cchar *buf, uint size)
 Write a line to the file.
intmprRead(MprFile *file, void *buf, uint size)
 Read data from a file.
longmprSeek(MprFile *file, int seekType, long distance)
 Seek the I/O pointer to a new location in the file.
intmprWrite(MprFile *file, cvoid *buf, uint count)
 Write data to a file.
intmprWriteFormat(MprFile *file, cchar *fmt, ...)
 Write formatted data to a file.
intmprWriteString(MprFile *file, cchar *str)
 Write a string to a file.
MprHash*mprAddDuplicateHash(MprHashTable *table, cchar *key, cvoid *ptr)
 Add a duplicate symbol value into the hash table.
MprHash*mprAddHash(MprHashTable *table, cchar *key, cvoid *ptr)
 Add a symbol value into the hash table.
MprHashTable*mprCopyHash(MprCtx ctx, MprHashTable *table)
 Copy a hash table.
MprHashTable*mprCreateHash(MprCtx ctx, int hashSize)
 Create a hash table.
MprHash*mprGetFirstHash(MprHashTable *table)
 Return the first symbol in a symbol entry.
intmprGetHashCount(MprHashTable *table)
 Return the count of symbols in a symbol entry.
MprHash*mprGetNextHash(MprHashTable *table, MprHash *last)
 Return the next symbol in a symbol entry.
cvoid*mprLookupHash(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table.
MprHash*mprLookupHashEntry(MprHashTable *table, cchar *key)
 Lookup a symbol in the hash table and return the hash entry.
intmprRemoveHash(MprHashTable *table, cchar *key)
 Remove a symbol entry from the hash table.
intmprAddItem(MprList *list, cvoid *item)
 Add an item to a list.
MprList*mprAppendList(MprList *list, MprList *add)
 Append a list.
voidmprClearList(MprList *list)
 Clears the list of all items.
intmprCopyList(MprList *dest, MprList *src)
 Copy a list.
MprKeyValue*mprCreateKeyPair(MprCtx ctx, cchar *key, cchar *value)
 Create a key / value pair.
MprList*mprCreateList(MprCtx ctx)
 Create a list.
MprList*mprDupList(MprCtx ctx, MprList *src)
 Duplicate a list.
void*mprGetFirstItem(MprList *list)
 Get the first item in the list.
void*mprGetItem(MprList *list, int index)
 Get an list item.
void*mprGetLastItem(MprList *list)
 Get the last item in the list.
intmprGetListCapacity(MprList *list)
 Get the current capacity of the list.
intmprGetListCount(MprList *list)
 Get the number of items in the list.
void*mprGetNextItem(MprList *list, int *lastIndex)
 Get the next item in the list.
void*mprGetPrevItem(MprList *list, int *lastIndex)
 Get the previous item in the list.
voidmprInitList(MprList *list)
 Initialize a list structure.
intmprInsertItemAtPos(MprList *list, int index, cvoid *item)
 Insert an item into a list at a specific position.
intmprLookupItem(MprList *list, cvoid *item)
 Find an item and return its index.
intmprRemoveItem(MprList *list, void *item)
 Remove an item from the list.
intmprRemoveItemAtPos(MprList *list, int index)
 Remove an item from the list.
intmprRemoveLastItem(MprList *list)
 Remove the last item from the list.
intmprRemoveRangeOfItems(MprList *list, int start, int end)
 Remove a range of items from the list.
void*mprSetItem(MprList *list, int index, cvoid *item)
 Set a list item.
intmprSetListLimits(MprList *list, int initialSize, int maxSize)
 Define the list size limits.
voidmprSortList(MprList *list, MprListCompareProc compare)
 Sort a list.
voidmprError(MprCtx ctx, cchar *fmt, ...)
 Log an error message.
voidmprFatalError(MprCtx ctx, cchar *fmt, ...)
 Log a fatal error message and exit.
MprLogHandlermprGetLogHandler(MprCtx ctx)
 Get the current MPR debug log handler.
voidmprLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a message to the diagnostic log file.
voidmprMemoryError(MprCtx ctx, cchar *fmt, ...)
 Log a memory error message.
voidmprRawLog(MprCtx ctx, int level, cchar *fmt, ...)
 Write a raw log message to the diagnostic log file.
voidmprSetLogHandler(MprCtx ctx, MprLogHandler handler, void *handlerData)
 Set an MPR debug log handler.
voidmprSetLogLevel(MprCtx ctx, int level)
 Set the current logging level.
voidmprStaticAssert(cchar *loc, cchar *msg)
 Output an assertion failed message.
voidmprStaticError(MprCtx ctx, cchar *fmt, ...)
 Write a message to the diagnostic log file without allocating any memory.
voidmprUserError(MprCtx ctx, cchar *fmt, ...)
 Display an error message to the user.
void*mprAlloc(MprCtx ctx, uint size)
 Allocate a block of memory.
void*mprAllocObj(MprCtx ctx, Type type)
 Allocate an object of a given type.
void*mprAllocObjWithDestructor(MprCtx ctx, Type type, MprDestructor destructor) void *mprAllocObjWithDestructorZeroed(MprCtx ctx
 Allocate an object of a given type with a destructor.
void*mprAllocObjZeroed(MprCtx ctx, Type type)
 Allocate a zeroed object of a given type.
void*mprAllocWithDestructor(MprCtx ctx, uint size, MprDestructor destructor)
 Allocate an object block of memory.
void*mprAllocWithDestructorZeroed(MprCtx ctx, uint size, MprDestructor destructor)
 Allocate an object block of memory and zero it.
void*mprAllocZeroed(MprCtx ctx, uint size)
 Allocate a zeroed block of memory.
intmprFree(void *ptr)
 Free a block of memory.
void*mprGetParent(MprCtx ctx)
 Get the memory parent of a block.
void*mprMemdup(MprCtx ctx, cvoid *ptr, uint size)
 Duplicate a block of memory.
void*mprRealloc(MprCtx ctx, void *ptr, uint size)
 Reallocate a block.
voidmprResetAllocError(MprCtx ctx)
 Reset the memory allocation error flag.
voidmprSetAllocLimits(MprCtx ctx, uint redline, uint maxMemory)
 Configure the application memory limits.
voidmprSetDestructor(void *ptr, MprDestructor destructor)
 Update the destructor for a block of memory.
char*mprStrdup(MprCtx ctx, cchar *str)
 Safe replacement for strdup.
char*mprStrndup(MprCtx ctx, cchar *str, uint size)
 Duplicate a string.
MprModule*mprCreateModule(MprCtx ctx, cchar *name, cchar *version, void *moduleData, MprModuleProc start, MprModuleProc stop)
 Create a module.
cchar*mprGetModuleSearchPath(MprCtx ctx)
 Get the module search path.
MprModule*mprLoadModule(MprCtx ctx, cchar *filename, cchar *entryPoint)
 Load a module.
MprModule*mprLookupModule(MprCtx ctx, cchar *name)
 Lookup a module.
voidmprSetModuleSearchPath(MprCtx ctx, char *searchPath)
 Set the module search path.
voidmprUnloadModule(MprModule *mp)
 Unload a module.
intmprCopyPath(MprCtx ctx, cchar *from, cchar *to, int omode)
 Copy a file.
intmprDeletePath(MprCtx ctx, cchar *path)
 Delete a file.
char*mprGetAbsPath(MprCtx ctx, cchar *path)
 Convert a path to an absolute path.
char*mprGetNativePath(MprCtx ctx, cchar *path)
 Get a path formatted according to the native O/S conventions.
char*mprGetNormalizedPath(MprCtx ctx, cchar *path)
 Normalize a path.
char*mprGetPathBase(MprCtx ctx, cchar *path)
 Get the base portion of a path.
char*mprGetPathDir(MprCtx ctx, cchar *path)
 Get the directory portion of a path.
cchar*mprGetPathExtension(MprCtx ctx, cchar *path)
 Get the file extension portion of a path.
MprList*mprGetPathFiles(MprCtx ctx, cchar *dir, bool enumDirs)
 Create a directory list of files.
intmprGetPathInfo(MprCtx ctx, cchar *path, MprPath *info)
 Return information about a file represented by a path.
cchar*mprGetPathNewline(MprCtx ctx, cchar *path)
 Get the file newline character string for a given path.
char*mprGetPathParent(MprCtx ctx, cchar *path)
 Get the parent directory of a path.
cchar*mprGetPathSeparators(MprCtx ctx, cchar *path)
 Get the path directory separator.
char*mprGetPortablePath(MprCtx ctx, cchar *path)
 Get a portable path.
char*mprGetRelPath(MprCtx ctx, cchar *path)
 Get a relative path.
char*mprGetTempPath(MprCtx ctx, cchar *tmpDir)
 Make a temporary file.
char*mprGetTransformedPath(MprCtx ctx, cchar *path, int flags)
 Transform a path.
boolmprIsAbsPath(MprCtx ctx, cchar *path)
 Determine if a path is absolute.
boolmprIsRelPath(MprCtx ctx, cchar *path)
 Determine if a path is relative.
char*mprJoinPath(MprCtx ctx, cchar *dir, cchar *other)
 Join paths.
char*mprJoinPathExt(MprCtx ctx, cchar *dir, cchar *ext)
 Join an extension to a path.
intmprMakeDir(MprCtx ctx, cchar *path, int perms, bool makeMissing)
 Make a directory.
voidmprMapSeparators(MprCtx ctx, char *path, int separator)
 Map the separators in a path.
boolmprPathExists(MprCtx ctx, cchar *path, int omode)
 Determine if a file exists for a path name and can be accessed.
intmprSamePath(MprCtx ctx, cchar *path1, cchar *path2)
 Compare two paths if they are the same.
intmprSamePathCount(MprCtx ctx, cchar *path1, cchar *path2, int len)
 Compare two paths if they are the same for a given length.
char*mprSearchPath(MprCtx ctx, cchar *path, int flags, cchar *search, ...)
 Search for a path.
char*mprTrimPathExtension(MprCtx ctx, cchar *path)
 Trim an extension from a path.
intmprTruncatePath(MprCtx ctx, cchar *path, int size)
 Truncate a path.
intmprAvailablePoolThreads(MprCtx ctx)
 Get the count of available pool threads Return the count of free threads in the thread pool.
intmprGetMaxPoolThreads(MprCtx ctx)
 Get the maximum count of pool threads Get the maximum limit of pool threads.
voidmprSetMaxPoolThreads(MprCtx ctx, int count)
 Set the maximum count of pool threads Set the maximum number of pool threads for the MPR.
voidmprSetMinPoolThreads(MprCtx ctx, int count)
 Set the minimum count of pool threads Set the count of threads the pool will have.
voidmprCloseSocket(MprSocket *sp, bool graceful)
 Close a socket.
MprSocket*mprCreateSocket(MprCtx ctx, struct MprSsl *ssl)
 Create a socket.
intmprFlushSocket(MprSocket *sp)
 Flush a socket.
boolmprGetSocketBlockingMode(MprSocket *sp)
 Get the socket blocking mode.
boolmprGetSocketEof(MprSocket *sp)
 Test if the other end of the socket has been closed.
intmprGetSocketError(MprSocket *sp)
 Get a socket error code.
intmprGetSocketFd(MprSocket *sp)
 Get the socket file descriptor.
intmprGetSocketPort(MprSocket *sp)
 Get the port used by a socket.
intmprOpenClientSocket(MprSocket *sp, cchar *hostName, int port, int flags)
 Open a client socket.
intmprOpenServerSocket(MprSocket *sp, cchar *ipAddr, int port, MprSocketAcceptProc acceptFn, void *data, int flags)
 Open a server socket.
intmprReadSocket(MprSocket *sp, void *buf, int size)
 Read from a socket.
MprOffsetmprSendFileToSocket(MprFile *file, MprSocket *sock, MprOffset offset, int bytes, MprIOVec *beforeVec, int beforeCount, MprIOVec *afterVec, int afterCount)
 Send a file to a socket.
intmprSetSocketBlockingMode(MprSocket *sp, bool on)
 Set the socket blocking mode.
voidmprSetSocketCallback(MprSocket *sp, MprSocketProc fn, void *data, void *data2, int mask, int priority)
 Set the socket callback.
voidmprSetSocketEventMask(MprSocket *sp, int mask)
 Define the events of interest for a socket.
intmprSetSocketNoDelay(MprSocket *sp, bool on)
 Set the socket delay mode.
boolmprSocketIsSecure(MprSocket *sp)
 Determine if the socket is secure.
intmprWriteSocket(MprSocket *sp, void *buf, int len)
 Write to a socket.
intmprWriteSocketString(MprSocket *sp, cchar *str)
 Write to a string to a socket.
intmprWriteSocketVector(MprSocket *sp, MprIOVec *iovec, int count)
 Write a vector to a socket.
MprCond*mprCreateCond(MprCtx ctx)
 Create a condition lock variable.
MprMutex*mprCreateLock(MprCtx ctx)
 Create a Mutex lock object.
MprSpin*mprCreateSpinLock(MprCtx ctx)
 Create a spin lock lock object.
voidmprGlobalLock(MprCtx ctx)
 Globally lock the application.
voidmprGlobalUnlock(MprCtx ctx)
 Unlock the global mutex.
MprMutex*mprInitLock(MprCtx ctx, MprMutex *mutex)
 Initialize a statically allocated Mutex lock object.
MprSpin*mprInitSpinLock(MprCtx ctx, MprSpin *lock)
 Initialize a statically allocated spinlock object.
voidmprLock(MprMutex *lock)
 Lock access.
voidmprSignalCond(MprCond *cond)
 Signal a condition lock variable.
voidmprSpinLock(MprSpin *lock)
 Lock a spinlock.
voidmprSpinUnlock(MprSpin *lock)
 Unlock a spinlock.
boolmprTryLock(MprMutex *lock)
 Attempt to lock access.
boolmprTrySpinLock(MprSpin *lock)
 Attempt to lock access on a spin lock.
voidmprUnlock(MprMutex *lock)
 Unlock a mutex.
intmprWaitForCond(MprCond *cond, int timeout)
 Wait for a condition lock variable.
MprThread*mprCreateThread(MprCtx ctx, cchar *name, MprThreadProc proc, void *data, int priority, int stackSize)
 Create a new thread.
MprOsThreadmprGetCurrentOsThread()
 Get the O/S thread.
MprThread*mprGetCurrentThread(MprCtx ctx)
 Get the currently executing thread.
cchar*mprGetThreadName(MprThread *thread)
 Get the thread name.
intmprGetThreadPriority(MprThread *thread)
 Get the thread priroity.
voidmprSetCurrentThreadPriority(MprCtx ctx, int priority)
 Set the thread priroity for the current thread.
voidmprSetThreadPriority(MprThread *thread, int priority)
 Set the thread priroity.
intmprStartThread(MprThread *thread)
 Start a thread.
char*mprEscapeCmd(MprCtx ctx, cchar *cmd, int escChar)
 Encode a string escaping typical command (shell) characters.
char*mprEscapeHtml(MprCtx ctx, cchar *html)
 Encode a string by escaping typical HTML characters.
char*mprFormatUri(MprCtx ctx, cchar *protocol, cchar *host, int port, cchar *path, cchar *query)
 Format a URI.
MprUri*mprParseUri(MprCtx ctx, cchar *uri)
 Parse a URI.
char*mprUrlDecode(MprCtx ctx, cchar *url)
 Decode a URL string by de-scaping URL characters.
char*mprUrlEncode(MprCtx ctx, cchar *url)
 Encode a string by escaping URL characters.
char*mprValidateUrl(MprCtx ctx, char *url)
 Validate a URL.
MprWaitHandler*mprCreateWaitHandler(MprCtx ctx, int fd, int mask, MprWaitProc proc, void *data, int priority, int flags)
 Create a wait handler.
voidmprDisableWaitEvents(MprWaitHandler *wp, bool wakeup)
 Disable wait events.
voidmprEnableWaitEvents(MprWaitHandler *wp, bool wakeup)
 Enable wait events.
voidmprRecallWaitHandler(MprWaitHandler *wp)
 Recall a wait handler.
voidmprSetWaitCallback(MprWaitHandler *wp, MprWaitProc proc, int mask)
 Define the wait handler callback.
voidmprSetWaitInterest(MprWaitHandler *wp, int mask)
 Define the events of interest for a wait handler.
intmprWaitForSingleIO(MprWaitHandler *wp, int fd, int mask, int timeout)
 Wait for I/O on an event handler.

Typedefs

MprAllocNotifier Memory allocation error callback.
MprBufProc Buffer refill callback function.
MprCtx Memory context type.
MprDestructor Mpr memory block destructors prototype.
MprEventProc Event callback function.
MprListCompareProc List comparison procedure for sorting.
MprLogHandler Log handler callback type.
MprModuleEntry Loadable module entry point signature.
MprModuleProc Module start/stop point function signature.
MprSocketAcceptProc Socket connection acceptance callback procedure.
MprSocketProc Socket I/O callback procedure.
MprTime Mpr time structure.
MprBufProc Buffer refill callback function.
MprTime Mpr time structure.
MprEventProc Event callback function.
MprListCompareProc List comparison procedure for sorting.
MprLogHandler Log handler callback type.
MprAllocNotifier Memory allocation error callback.
MprCtx Memory context type.
MprDestructor Mpr memory block destructors prototype.
MprModuleEntry Loadable module entry point signature.
MprBlk Memory Allocation Block Header.
MprCond Condition variable for multi-thread synchronization.
MprDirEntry Directory entry description.
MprFileSystem File system service.
MprHashTable Hash table control structure.
MprKeyValue Key value pairs for use with MprList or MprHash.
MprMutex Multithreading lock control structure.
MprPath Path information structure.
MprSpin Multithreading spin lock control structure.
MprString Safe String Module.
MprThreadLocal Thread local data storage.

Defines

#defineMPR_BACKGROUND_PRIORITY   15
 May only get CPU if idle.
#defineMPR_BUF_INCR   1024
 Default buffer growth inc.
#defineMPR_BUFSIZE   1024
 Reasonable size for buffers.
#defineMPR_CRITICAL_PRIORITY   99
 May not yield.
#defineMPR_DEFAULT_ALLOC   64
 Default small alloc size.
#defineMPR_DEFAULT_HASH_SIZE   23
 Default size of hash table.
#defineMPR_DEFAULT_MAX_THREADS   10
 Default max threads (10).
#defineMPR_DEFAULT_MIN_THREADS   0
 Default min threads (0).
#defineMPR_DEFAULT_STACK   32768
 Default stack size (32K).
#defineMPR_ERR   -1
 Default error code.
#defineMPR_ERR_ABORTED   -2
 Action aborted.
#defineMPR_ERR_ALREADY_EXISTS   -3
 Item already exists.
#defineMPR_ERR_BAD_ARGS   -4
 Bad arguments or paramaeters.
#defineMPR_ERR_BAD_FORMAT   -5
 Bad input format.
#defineMPR_ERR_BAD_STATE   -7
 Module is in a bad state.
#defineMPR_ERR_BAD_SYNTAX   -8
 Input has bad syntax.
#defineMPR_ERR_CANT_ACCESS   -12
 Can't access the file or resource.
#defineMPR_ERR_CANT_CREATE   -14
 Can't create the file or resource.
#defineMPR_ERR_CANT_OPEN   -16
 Can't open the file or resource.
#defineMPR_ERR_CANT_READ   -17
 Can't read from the file or resource.
#defineMPR_ERR_CANT_WRITE   -18
 Can't write to the file or resource.
#defineMPR_ERR_GENERAL   -1
 General error.
#defineMPR_ERR_NO_MEMORY   -30
 Memory allocation error.
#defineMPR_ERR_NOT_INITIALIZED   -22
 Module or resource is not initialized.
#defineMPR_ERR_OK   0
 Standard MPR return and error codes.
#defineMPR_ERR_READ_ONLY   -24
 The operation timed out.
#defineMPR_ERROR   1
 Standard logging trace levels are 0 to 9 with 0 being the most verbose.
#defineMPR_EVENT_CONTINUOUS   0x1
 Auto reschedule the event.
#defineMPR_EVENT_PRIORITY   75
 Run service event thread at higher priority.
#defineMPR_EVENT_RUNNING   0x4
 Event currently executing.
#defineMPR_EVENT_THREAD   0x2
 Run proc using pool thread.
#defineMPR_HTTP_BUFSIZE   2048
 HTTP buffer size.
#defineMPR_HTTP_MAX_PASS   64
 Size of password.
#defineMPR_HTTP_MAX_SECRET   32
 Random bytes to use.
#defineMPR_HTTP_MAX_USER   64
 Size of user name.
#defineMPR_HTTP_TIMEOUT   60000
 HTTP Request timeout (60 sec).
#defineMPR_LIST_INCR   8
 Default list growth inc.
#defineMPR_MAX_ARGC   128
 Reasonable max of args.
#defineMPR_MAX_BUF   4194304
 Max buffer size.
#defineMPR_MAX_FNAME   128
 Reasonable filename size.
#defineMPR_MAX_LOG_STRING   512
 Maximum log message.
#defineMPR_MAX_PATH   256
 Reasonable path name size.
#defineMPR_MAX_STRING   1024
 Maximum (stack) string size.
#defineMPR_NORMAL_PRIORITY   50
 Normal (default) priority.
#defineMPR_POOL_PRIORITY   60
 Slightly elevated priority.
#defineMPR_REQUEST_PRIORITY   50
 Normal priority.
#defineMPR_SECURE_CLIENT   ((struct MprSsl*) 1)
 Flag for mprCreateSocket to use the default SSL provider.
#defineMPR_SERVICE_ONE_THING   0x1
 Wait for one event or one I/O.
#defineMPR_SOCKET_BLOCK   0x1
 Use blocking I/O.
#defineMPR_SOCKET_BROADCAST   0x2
 Broadcast mode.
#defineMPR_SOCKET_CLIENT   0x800
 Socket is a client.
#defineMPR_SOCKET_CLOSED   0x4
 MprSocket has been closed.
#defineMPR_SOCKET_CONNECTING   0x8
 MprSocket has been closed.
#defineMPR_SOCKET_DATAGRAM   0x10
 Use datagrams.
#defineMPR_SOCKET_EOF   0x20
 Seen end of file.
#defineMPR_SOCKET_LISTENER   0x40
 MprSocket is server listener.
#defineMPR_SOCKET_NODELAY   0x100
 Disable Nagle algorithm.
#defineMPR_SOCKET_NOREUSE   0x80
 Dont set SO_REUSEADDR option.
#defineMPR_SOCKET_THREAD   0x400
 Process callbacks on a pool thread.
#defineMPR_SSL_BUFSIZE   2048
 SSL has 16K max.
#defineMPR_TICKS_PER_SEC   1000
 Time ticks per second.
#defineMPR_TIMEOUT_LINGER   2000
 Close socket linger timeout.
#defineMPR_TIMEOUT_LOG_STAMP   3600000
 Time between log time stamps (1 hr).
#defineMPR_TIMEOUT_PRUNER   600000
 Time between pruner runs (10 min).
#defineMPR_TIMEOUT_START_TASK   2000
 Time to start tasks running.
#defineMPR_TIMEOUT_STOP   5000
 Wait when stopping resources.
#defineMPR_TIMEOUT_STOP_TASK   10000
 Time to stop running tasks.
#defineMPR_TIMEOUT_STOP_THREAD   10000
 Time to stop running threads.
#defineMPR_XML_BUFSIZE   512
 XML read buffer size.

Mpr

Mpr

Primary MPR application control structure.

Description:
The Mpr structure stores critical application state information and is the root memory allocation context block. It is used as the MprCtx context for other memory allocations and is thus the ultimate parent of all allocated memory.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
Fields:
longappInstance Application instance (windows).
intargc Count of command line args.
char *args Command line args.
char **argv Application command line args.
uintclassId Brew class ID.
struct MprCmdService *cmdService Command service object.
booldebugMode Run in debug mode (no timers).
IDisplay *display Brew display object.
intdisplayHeight Display height.
intdisplayWidth Display width.
char *domainName Domain portion.
struct MprEventService *eventService Event service object.
struct MprFileSystem *fileSystem File system service object.
intflags Processing state.
inthasEventsThread Running an events thread. Service pointers.
MprHeapheap Top level memory pool.
char *hostName Host name (fully qualified name).
struct MprHttpService *httpService HTTP service object.
char *ipAddr Public IP Address.
MprLogHandlerlogHandler Current log handler callback.
void *logHandlerData Handle data for log handler.
intlogLevel Log trace level.
struct MprModuleService *moduleService Module service object.
MprMutex *mutex Thread synchronization.
char *name Product name.
struct MprOsService *osService O/S service object.
MprHeappageHeap Heap for arenas and slabs. Always page oriented.
struct MprPoolService *poolService Pool service object.
char *serverName Server name portion (no domain).
IShell *shell Brew shell object.
struct MprSocketService *socketService Socket service object.
MprSpin *spin Quick thread synchronization.
ITAPI *tapi TAPI object.
struct MprThreadService *threadService Thread service object.
MprHashTable *timeTokens Date/Time parsing tokens.
inttimezone Minutes west of Greenwich.
char *title Product title.
char *version Product version.
struct MprWaitService *waitService IO Waiting service object.
void mprBreakpoint ()

Trigger a breakpoint.

Description:
Triggers a breakpoint and traps to the debugger.
See Also:
mprCreateEx, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
Mpr * mprCreate (int argc, char **argv, MprAllocNotifier cback)

Create an instance of the MPR.

Description:
Initializes the MPR and creates an Mpr control object. The Mpr Object manages Mpr facilities and is the top level memory context. It may be used wherever a MprCtx parameter is required. This function must be called prior to calling any other Mpr API.
Parameters:
argcCount of command line args.
argvCommand line arguments for the application. Arguments may be passed into the Mpr for retrieval by the unit test framework.
cbackMemory allocation failure notification callback.
Returns:
Returns a pointer to the Mpr object.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
Mpr * mprCreateEx (int argc, char **argv, MprAllocNotifier cback, void *shell)

Create an instance of the MPR.

Description:
Alternate API to create and initialize the MPR. The Mpr object manages Mpr facilities and is the top level memory context. It may be used wherever a MprCtx parameter is required. This function, or mprCreate must be called prior to calling any other Mpr API.
Parameters:
argcCount of arguments supplied in argv.
argvProgram arguments. The MPR can store the program arguments for retrieval by other parts of the program.
cbackCallback function to be invoked on memory allocation errors. Set to null if not required.
shellOptional reference to an O/S implementation dependent shell object. Used by Brew.
Returns:
Returns a pointer to the Mpr object.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
bool mprGetDebugMode (MprCtx ctx)

Get the debug mode.

Description:
Returns whether the debug mode is enabled. Some modules observe debug mode and disable timeouts and timers so that single-step debugging can be used.
Parameters:
ctxAny memory context allocated by the MPR.
Returns:
Returns true if debug mode is enabled, otherwise returns false.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
int mprGetOsError ()

Return the 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.
See Also:
mprBreakpoint, mprCreateEx, mprIsExiting, mprSetDebugMode, mprSignalExit, mprTerminate
bool mprIsExiting (MprCtx ctx)

Determine if the MPR should exit.

Description:
Returns true if the MPR should exit gracefully.
Parameters:
ctxAny memory context allocated by the MPR.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetOsError, mprSetDebugMode, mprSignalExit, mprTerminate
void mprSignalExit (MprCtx ctx)

Signal the MPR to exit gracefully.

Description:
Set the must exit flag for the MPR.
Parameters:
ctxAny memory context allocated by the MPR.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetOsError, mprIsExiting, mprSetDebugMode, mprTerminate
void mprTerminate (MprCtx ctx, bool graceful)

Terminate the MPR.

Description:
Terminates the MPR and disposes of all allocated resources. The mprTerminate function will recursively free all memory allocated by the MPR.
Parameters:
ctxAny memory context object returned by mprAlloc.
gracefulShutdown gracefully waiting for all events to drain. Otherise exit immediately without waiting for any threads or events to complete.
API Stability:
Evolving.
See Also:
mprBreakpoint, mprCreateEx, mprGetOsError, mprIsExiting, mprSetDebugMode, mprSignalExit

MprBuf

MprBuf

Dynamic Buffer Module.

Description:
MprBuf 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 MprBuf is deliberately exposed. All members of MprBuf are implicitly public. However, it is still recommended that wherever possible, you use the accessor routines provided.
API Stability:
Evolving.
See Also:
MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
Fields:
intbuflen Current size of buffer.
uchar *data Actual buffer for data.
uchar *end Pointer one past the last data chr.
uchar *endbuf Pointer one past the end of buffer.
intgrowBy Next growth increment to use.
intmaxsize Max size the buffer can ever grow.
void *refillArg Refill arg.
MprBufProcrefillProc Auto-refill procedure.
uchar *start Pointer to next data char.
void mprAddNullToBuf (MprBuf *buf)

Add a null character to the buffer contents.

Description:
Add a null byte but do not change the buffer content lengths. The null is added outside the "official" content length. This is useful when calling mprGetBufStart and using the returned pointer as a "C" string pointer.
Parameters:
bufBuffer created via mprCreateBuf.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
void mprAdjustBufEnd (MprBuf *buf, int count)

Adjust the buffer end position.

Description:
Adjust the buffer start 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 mprGetBufLength. If using the mprPutBlock or mprPutChar routines, adjusting the end position is done automatically.
Parameters:
bufBuffer created via mprCreateBuf.
countPositive or negative count of bytes to adjust the start position.
See Also:
MprBuf, MprBufProc, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
void mprAdjustBufStart (MprBuf *buf, int count)

Adjust the buffer start position.

Description:
Adjust the buffer start position by the specified amount. This is typically used to advance the start position as content is consumed. Adjusting the start or end position will change the value returned by mprGetBufLength. If using the mprGetBlock or mprGetChar routines, adjusting the start position is done automatically.
Parameters:
bufBuffer created via mprCreateBuf.
countPositive or negative count of bytes to adjust the start position.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
void mprCompactBuf (MprBuf *buf)

Compact the buffer contents.

Description:
Compact the buffer contents by copying the contents down to start the the buffer origin.
Parameters:
bufBuffer created via mprCreateBuf.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
MprBuf * mprCreateBuf (MprCtx ctx, int initialSize, int maxSize)

Create a new buffer.

Description:
Create a new buffer. Use mprFree to free the buffer.
Parameters:
ctxAny memory context allocated by the MPR.
initialSizeInitial size of the buffer.
maxSizeMaximum size the buffer can grow to.
Returns:
A new buffer.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
void mprFlushBuf (MprBuf *buf)

Flush the buffer contents.

Description:
Discard the buffer contents and reset the start end content pointers.
Parameters:
bufBuffer created via mprCreateBuf.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprGetBlockFromBuf (MprBuf *buf, uchar *blk, int count)

Get a block of data from the buffer.

Description:
Get a block of data from the buffer start and advance the start position. If the requested length is greater than the available buffer content, then return whatever data is available.
Parameters:
bufBuffer created via mprCreateBuf.
blkDestination block for the read data.
countCount of bytes to read from the buffer.
Returns:
The count of bytes rread into the block or -1 if the buffer is empty.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
char * mprGetBufEnd (MprBuf *buf)

Get a reference to the end of the buffer contents.

Description:
Get a pointer to the location immediately after the end of the buffer contents.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Pointer to the end of the buffer data contents. Points to the location one after the last data byte.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprGetBufLength (MprBuf *buf)

Get the buffer content length.

Description:
Get the length of the buffer contents. This is not the same as the buffer size which may be larger.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The length of the content stored in the buffer.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
char * mprGetBufOrigin (MprBuf *buf)

Get the origin of the buffer content storage.

Description:
Get a pointer to the start of the buffer content storage. This may not be equal to the start of the buffer content if mprAdjustBufStart has been called. Use mprGetBufSize to determine the length of the buffer content storage array.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
A pointer to the buffer content storage.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
MprBufProc mprGetBufRefillProc (MprBuf *buf)

Get the buffer refill procedure.

Description:
Return the buffer refill callback function.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The refill call back function if defined.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprGetBufSize (MprBuf *buf)

Get the current size of the buffer content storage.

Description:
This returns the size of the memory block allocated for storing the buffer contents.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The size of the buffer content storage.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprGetBufSpace (MprBuf *buf)

Get the space available to store content.

Description:
Get the number of bytes available to store content in the buffer.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The number of bytes available.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
char * mprGetBufStart (MprBuf *buf)

Get the start of the buffer contents.

Description:
Get a pointer to the start of the buffer contents. Use mprGetBufLength to determine the length of the content. Use mprGetBufEnd to get a pointer to the location after the end of the content.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Pointer to the start of the buffer data contents.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprGetCharFromBuf (MprBuf *buf)

Get a character from the buffer.

Description:
Get the next byte from the buffer start and advance the start position.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
The character or -1 if the buffer is empty.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprGrowBuf (MprBuf *buf, int count)

Grow the buffer.

Description:
Grow the storage allocated for content for the buffer. The new size must be less than the maximum limit specified via mprCreateBuf or mprSetBufSize.
Parameters:
bufBuffer created via mprCreateBuf.
countCount of bytes by which to grow the buffer content size.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprInsertCharToBuf (MprBuf *buf, int c)

Insert a character into the buffer.

Description:
Insert a character into to the buffer prior to the current buffer start point.
Parameters:
bufBuffer created via mprCreateBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprLookAtLastCharInBuf (MprBuf *buf)

Peek at the last character in the buffer.

Description:
Non-destructively return the last character from just prior to the end position in the buffer. The character is returned and the end position is not altered.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprLookAtNextCharInBuf (MprBuf *buf)

Peek at the next character in the buffer.

Description:
Non-destructively return the next character from the start position in the buffer. The character is returned and the start position is not altered.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprPutBlockToBuf (MprBuf *buf, cchar *ptr, int size)

Put a block to the buffer.

Description:
Append a block of data to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
ptrBlock to append.
sizeSize of block to append.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprPutCharToBuf (MprBuf *buf, int c)

Put a character to the buffer.

Description:
Append a character to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
cCharacter to append.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprPutFmtToBuf (MprBuf *buf, cchar *fmt, ...)

Put a formatted string to the buffer.

Description:
Format a string and Append to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
fmtPrintf style format string.
...Variable arguments for the format string.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprPutIntToBuf (MprBuf *buf, int i)

Put an integer to the buffer.

Description:
Append a integer to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
iInteger to append to the buffer.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprPutStringToBuf (MprBuf *buf, cchar *str)

Put a string to the buffer.

Description:
Append a null terminated string to the buffer at the end position and increment the end pointer.
Parameters:
bufBuffer created via mprCreateBuf.
strString to append.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
int mprRefillBuf (MprBuf *buf)

Refill the buffer with data.

Description:
Refill the buffer by calling the refill procedure specified via mprSetBufRefillProc.
Parameters:
bufBuffer created via mprCreateBuf.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
void mprResetBufIfEmpty (MprBuf *buf)

Reset the buffer.

Description:
If the buffer is empty, reset the buffer start and end pointers to the beginning of the buffer.
Parameters:
bufBuffer created via mprCreateBuf.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
void mprSetBufMax (MprBuf *buf, int maxSize)

Set the maximum buffer size.

Description:
Update the maximum buffer size set when the buffer was created.
Parameters:
bufBuffer created via mprCreateBuf.
maxSizeNew maximum size the buffer can grow to.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
void mprSetBufRefillProc (MprBuf *buf, MprBufProc fn, void *arg)

Set the buffer refill procedure.

Description:
Define a buffer refill procedure. The MprBuf module will not invoke or manage this refill procedure. It is simply stored to allow upper layers to use and provide their own auto-refill mechanism.
Parameters:
bufBuffer created via mprCreateBuf.
fnCallback function to store.
argCallback data argument.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufSize, mprStealBuf
int mprSetBufSize (MprBuf *buf, int size, int maxSize)

Set the buffer size.

Description:
Set the current buffer content size and maximum size limit. Setting a current size will immediately grow the buffer to be this size. If the size is less than the current buffer size, the requested size will be ignored. ie. this call will not shrink the buffer. Setting a maxSize will define a maximum limit for how big the buffer contents can grow. Set either argument to -1 to be ignored.
Parameters:
bufBuffer created via mprCreateBuf.
sizeSize to immediately make the buffer. If size is less than the current buffer size, it will be ignored. Set to -1 to ignore this parameter.
maxSizeMaximum size the buffer contents can grow to.
Returns:
Zero if successful and otherwise a negative error code.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprStealBuf
char * mprStealBuf (MprCtx ctx, MprBuf *buf)

Steal the buffer memory from a buffer.

Description:
Steal ownership of the buffer memory from the buffer structure. All MPR memory is owned by a memory context and the contents of the buffer is owned by the MprBuf object. Stealing the buffer content memory is useful to preserve the buffer contents after the buffer is freed.
Parameters:
ctxMemory context to won the memory for the buffer.
bufBuffer created via mprCreateBuf.
Returns:
Pointer to the buffer contents. Use mprGetBufLength before calling mprStealBuf to determine the resulting size of the contents.
See Also:
MprBuf, MprBufProc, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize

MprDate

MprDate

Date and Time Service.

API Stability:
Evolving.
See Also:
MprTime, mprAsctime, mprCtime, mprGetTime, mprLocaltime
Fields:
int mprAsctime (MprCtx ctx, char *buf, int bufsize, const struct tm *timeptr)

Format time as a string.

Description:
Safe replacement for asctime. This call formats the time value supplied via timeptr into the supplied buffer. The supplied buffer size will be observed and the formatted time string will always have a terminating null.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
timeptrTime to format.
bufBuffer to hold the formatted string.
bufsizeMaximum length for the string.
Returns:
The length of the string or MPR_ERR_WONT_FIT if the length is greater than max.
See Also:
MprTime, mprCtime, mprGetTime, mprLocaltime
int mprCtime (MprCtx ctx, char *buf, int bufsize, MprTime time)

Convert time to local time and format as a string.

Description:
Safe replacement for ctime. This call formats the time value supplied via timer into the supplied buffer. The supplied buffer size will be observed and the formatted time string will always have a terminating null.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
bufBuffer to hold the formatted string.
bufsizeMaximum length for the string.
timeTime to format. Use mprGetTime to retrieve the current time.
Returns:
The length of the string or MPR_ERR_WONT_FIT if the length is greater than max.
See Also:
MprTime, mprAsctime, mprGetTime, mprLocaltime
MprTime mprGetTime (MprCtx ctx)

Get the system time.

Description:
Get the system time in milliseconds.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
The time in milliseconds since boot.
See Also:
MprTime, mprAsctime, mprCtime, mprLocaltime
struct tm * tm* mprGmtime (MprCtx ctx, struct tm *timep, MprTime time)

Convert time to UTC and parse into a time structure.

Description:
Safe replacement for gmtime. This call converts the supplied time value to UTC time and parses the result into a tm structure.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
timepPointer to a tm structure to hold the result.
timeThe time to format.
Returns:
The tm structure reference.
See Also:
MprTime, mprAsctime, mprCtime, mprGetTime, mprLocaltime
struct tm * tm* mprLocaltime (MprCtx ctx, struct tm *timep, MprTime time)

Convert time to local representation.

Description:
Safe replacement for localtime. This call converts the time value to local time and formats the as a struct tm.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
timepPointer to a tm structure to hold the result.
timeTime to format.
Returns:
Returns a pointer to the tmBuf.
See Also:
MprTime, mprAsctime, mprCtime, mprGetTime

MprEvent

MprEvent

Event object.

Description:
The MPR provides a powerful priority based eventing mechanism. Events are described by MprEvent objects which are created and queued via mprCreateEvent. Each event may have a priority and may be one-shot or be continuously rescheduled according to a specified period. The event subsystem provides the basis for callback timers.
See Also:
MprEventProc, mprCreateEvent, mprCreateTimerEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprStopContinuousEvent
Fields:
void *data Event private data.
MprTimedue When is the event due.
intflags Event flags.
struct MprEvent *next Next event linkage.
intperiod Reschedule period.
struct MprEvent *prev Previous event linkage.
intpriority Priority 0-99. 99 is highest.
MprEventProcproc Callback procedure.
MprTimetimestamp When was the event created.
MprEvent * mprCreateEvent (MprCtx ctx, MprEventProc proc, int period, int priority, void *data, int flags)

Create a new event.

Description:
Create and queue a new event for service.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
procFunction to invoke when the event is run.
periodTime in milliseconds used by continuous events between firing of the event.
priorityPriority to associate with the event. Priorities are integer values between 0 and 100 inclusive with 50 being a normal priority. Useful constants are:
  • MPR_LOW_PRIORITY
  • MPR_NORMAL_PRIORITY
  • MPR_HIGH_PRIORITY
.
dataData to associate with the event and stored in event->data.
flagsFlags to modify the behavior of the event. Valid values are: MPR_EVENT_CONTINUOUS to create an event which will be automatically rescheduled accoring to the specified period.
See Also:
MprEvent, MprEventProc, mprCreateTimerEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprStopContinuousEvent
MprEvent * mprCreateTimerEvent (MprCtx ctx, MprEventProc proc, int period, int priority, void *data, int flags)

Create a timer event.

Description:
Create and queue a timer event for service. This is a convenience wrapper to create continuous events over the mprCreateEvent call.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
procFunction to invoke when the event is run.
periodTime in milliseconds used by continuous events between firing of the event.
priorityPriority to associate with the event. Priorities are integer values between 0 and 100 inclusive with 50 being a normal priority. Useful constants are:
  • MPR_LOW_PRIORITY
  • MPR_NORMAL_PRIORITY
  • MPR_HIGH_PRIORITY
.
dataData to associate with the event and stored in event->data.
flagsNot used.
See Also:
MprEvent, MprEventProc, mprCreateEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprStopContinuousEvent
void mprRemoveEvent (MprEvent *event)

Remove an event.

Description:
Remove a queued event. This is useful to remove continuous events from the event queue.
Parameters:
eventEvent object returned from mprCreateEvent.
See Also:
MprEvent, MprEventProc, mprCreateEvent, mprCreateTimerEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprStopContinuousEvent
void mprRescheduleEvent (MprEvent *event, int period)

Reschedule an event.

Description:
Reschedule a continuous event by modifying its period.
Parameters:
eventEvent object returned from mprCreateEvent.
periodTime in milliseconds used by continuous events between firing of the event.
See Also:
MprEvent, MprEventProc, mprCreateEvent, mprCreateTimerEvent, mprRestartContinuousEvent, mprStopContinuousEvent
void mprRestartContinuousEvent (MprEvent *event)

Restart an event.

Description:
Restart a continuous event after it has been stopped via mprStopContinuousEvent. This call will add the event to the event queue and it will run after the configured event period has expired.
Parameters:
eventEvent object returned from mprCreateEvent.
See Also:
MprEvent, MprEventProc, mprCreateEvent, mprCreateTimerEvent, mprRescheduleEvent, mprStopContinuousEvent
int mprServiceEvents (MprCtx ctx, int delay, int flags)

Service events.

Description:
Service the event queue. This call will block for the given delay until an event is ready to be serviced. Flags may modify the calls behavior.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
delayTime in milliseconds to block until an event occurs.
flagsIf set to MPR_SERVICE_ONE_THING, this call will service at most one event. Otherwise set to zero.
Returns:
A count of the number of events serviced.
See Also:
MprEvent, MprEventProc, mprCreateEvent, mprCreateTimerEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprStopContinuousEvent
void mprStopContinuousEvent (MprEvent *event)

Stop an event.

Description:
Stop a continuous event and remove from the queue. The event object is not freed, but simply removed from the event queue.
Parameters:
eventEvent object returned from mprCreateEvent.
See Also:
MprEvent, MprEventProc, mprCreateEvent, mprCreateTimerEvent, mprRescheduleEvent, mprRestartContinuousEvent

MprFile

MprFile

File I/O Module.

Description:
MprFile is the cross platform File I/O abstraction control structure. An instance will be created when a file is created or opened via mprOpen.
API Stability:
Evolving.
See Also:
mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
Fields:
MprBuf *buf Buffer for I/O if buffered.
MprFileSystem *fileSystem File system owning this file.
MprRomInode *inode Reference to ROM file.
intmode File open mode.
intperms File permissions.
MprOffsetpos Current read position.
MprOffsetsize Current file size.
MprFile * mprAttachFd (MprCtx ctx, int fd, cchar *name, int omode)

Attach to an existing file descriptor.

Description:
Attach a file to an open file decriptor and return a file object.
Parameters:
ctxAny memory context allocated by the MPR.
fdFile descriptor to attach to.
nameDescriptive name for the file.
omodePosix style file open mode mask. The open mode may contain the following mask values ored together:
  • O_RDONLY Open read only
  • O_WRONLY Open write only
  • O_RDWR Open for read and write
  • O_CREAT Create or re-create
  • O_TRUNC Truncate
  • O_BINARY Open for binary data
  • O_TEXT Open for text data
  • O_EXCL Open with an exclusive lock
  • O_APPEND Open to append
.
Returns:
Returns an MprFile object to use in other file operations.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
void mprDisableFileBuffering (MprFile *file)

Disable file buffering.

Description:
Disable any buffering of data when using the buffer.
Parameters:
fileFile instance returned from mprOpen.
See Also:
MprFile, MprFile, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
int mprEnableFileBuffering (MprFile *file, int size, int maxSize)

Enable file buffering.

Description:
Enable data buffering when using the buffer.
Parameters:
fileFile instance returned from mprOpen.
sizeSize to allocate for the buffer.
maxSizeMaximum size the data buffer can grow to.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
int mprFlush (MprFile *file)

Flush any buffered write data.

Description:
Write buffered write data and then reset the internal buffers.
Parameters:
filePointer to an MprFile object returned via MprOpen.
Returns:
Zero if successful, otherwise a negative MPR error code.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
int mprGetc (MprFile *file)

Read a character from the file.

Description:
Read a single character from the file and advance the read position.
Parameters:
filePointer to an MprFile object returned via MprOpen.
Returns:
If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
MprOffset mprGetFilePosition (MprFile *file)

Return the current file position.

Description:
Return the current read/write file position.
Parameters:
fileA file object returned from mprOpen.
Returns:
The current file offset position if successful. Returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
MprOffset mprGetFileSize (MprFile *file)

Get the size of the file.

Description:
Return the current file size.
Parameters:
fileA file object returned from mprOpen.
Returns:
The current file size if successful. Returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
char * mprGets (MprFile *file, char *buf, uint size)

Read a line from the file.

Description:
Read a single line from the file and advance the read position. Lines are delimited by the newline character. The newline is not included in the returned buffer.
Parameters:
filePointer to an MprFile object returned via MprOpen.
bufPre-allocated buffer to contain the line of data.
sizeSize of buf.
Returns:
The number of characters read into buf.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
MprFile * mprOpen (MprCtx ctx, cchar *filename, int omode, int perms)

Open a file.

Description:
Open a file and return a file object.
Parameters:
ctxAny memory context allocated by the MPR.
filenameString containing the filename to open or create.
omodePosix style file open mode mask. The open mode may contain the following mask values ored together:
  • O_RDONLY Open read only
  • O_WRONLY Open write only
  • O_RDWR Open for read and write
  • O_CREAT Create or re-create
  • O_TRUNC Truncate
  • O_BINARY Open for binary data
  • O_TEXT Open for text data
  • O_EXCL Open with an exclusive lock
  • O_APPEND Open to append
.
permsPosix style file permissions mask.
Returns:
Returns an MprFile object to use in other file operations.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
int mprPeekc (MprFile *file)

Non-destructively read a character from the file.

Description:
Read a single character from the file without advancing the read position.
Parameters:
filePointer to an MprFile object returned via MprOpen.
Returns:
If successful, return the character just read. Otherwise return a negative MPR error code. End of file is signified by reading 0.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
int mprPutc (MprFile *file, int c)

Write a character to the file.

Description:
Writes a single character to the file. Output is buffered and is flushed as required or when mprClose is called.
Parameters:
filePointer to an MprFile object returned via MprOpen.
cCharacter to write.
Returns:
One if successful, otherwise returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
int mprPuts (MprFile *file, cchar *buf, uint size)

Write a line to the file.

Description:
Writes a single line to the file. Output is buffered and is flushed as required or when mprClose is called.
Parameters:
filePointer to an MprFile object returned via MprOpen.
bufBuffer containing the line to write.
sizeSize of buf in characters to write.
Returns:
The number of characters written to the file. Returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprRead, mprSeek, mprWrite, mprWriteFormat, mprWriteString
int mprRead (MprFile *file, void *buf, uint size)

Read data from a file.

Description:
Reads data from a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
bufBuffer to contain the read data.
sizeSize of buf in characters.
Returns:
The number of characters read from the file. Returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprSeek, mprWrite, mprWriteFormat, mprWriteString
long mprSeek (MprFile *file, int seekType, long distance)

Seek the I/O pointer to a new location in the file.

Description:
Move the position in the file to/from which I/O will be performed in the file. Seeking prior to a read or write will cause the next I/O to occur at that location.
Parameters:
filePointer to an MprFile object returned via MprOpen.
seekTypeSeek type may be one of the following three values:
  • SEEK_SET Seek to a position relative to the start of the file
  • SEEK_CUR Seek relative to the current position
  • SEEK_END Seek relative to the end of the file
.
distanceA positive or negative byte offset.
Returns:
The new file position if successful otherwise a negative MPR error code is returned.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprWrite, mprWriteFormat, mprWriteString
int mprWrite (MprFile *file, cvoid *buf, uint count)

Write data to a file.

Description:
Writes data to a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
bufBuffer containing the data to write.
countCound of characters in buf to write.
Returns:
The number of characters actually written to the file. Returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWriteFormat, mprWriteString
int mprWriteFormat (MprFile *file, cchar *fmt, ...)

Write formatted data to a file.

Description:
Writes a formatted string to a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
fmtFormat string.
Returns:
The number of characters actually written to the file. Returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteString
int mprWriteString (MprFile *file, cchar *str)

Write a string to a file.

Description:
Writes a string to a file.
Parameters:
filePointer to an MprFile object returned via MprOpen.
strString to write.
Returns:
The number of characters actually written to the file. Returns a negative MPR error code on errors.
See Also:
MprFile, MprFile, mprDisableFileBuffering, mprEnableFileBuffering, mprFlush, mprGetFilePosition, mprGetFileSize, mprGetc, mprGets, mprOpen, mprPeekc, mprPutc, mprPuts, mprRead, mprSeek, mprWrite, mprWriteFormat

MprHash

MprHash

Hash table entry structure.

Description:
Each hash entry has a descriptor entry. This is used to manage the hash table link chains.
See Also:
mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
API Stability:
Evolving.
Fields:
intbucket Hash bucket index.
cvoid *data Pointer to symbol data.
char *key Hash key.
struct MprHash *next Next symbol in hash chain.
MprHash * mprAddDuplicateHash (MprHashTable *table, cchar *key, cvoid *ptr)

Add a duplicate symbol value into the hash table.

Description:
Add a symbol to the hash which may clash with an existing entry. Duplicate symbols can be added to the hash, but only one may be retrieved via mprLookupHash. To recover duplicate entries walk the hash using mprGetNextHash.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
keyString key of the symbole entry to delete.
ptrArbitrary pointer to associate with the key in the table.
Returns:
Integer count of the number of entries.
See Also:
MprHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
MprHash * mprAddHash (MprHashTable *table, cchar *key, cvoid *ptr)

Add a symbol value into the hash table.

Description:
Associate an arbitrary value with a string symbol key and insert into the symbol table.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
keyString key of the symbole entry to delete.
ptrArbitrary pointer to associate with the key in the table.
Returns:
Integer count of the number of entries.
See Also:
MprHash, mprAddDuplicateHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
MprHashTable * mprCopyHash (MprCtx ctx, MprHashTable *table)

Copy a hash table.

Description:
Create a new hash table and copy all the entries from an existing table.
Parameters:
ctxAny memory context allocated by the MPR.
tableSymbol table returned via mprCreateSymbolTable.
Returns:
A new hash table initialized with the contents of the original hash table.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
MprHashTable * mprCreateHash (MprCtx ctx, int hashSize)

Create a hash table.

Description:
Creates a hash table that can store arbitrary objects associated with string key values.
Parameters:
ctxAny memory context allocated by the MPR.
hashSizeSize of the hash table for the symbol table. Should be a prime number.
Returns:
Returns a pointer to the allocated symbol table. Caller should use mprFree to dispose of the table when complete.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
MprHash * mprGetFirstHash (MprHashTable *table)

Return the first symbol in a symbol entry.

Description:
Prepares for walking the contents of a symbol table by returning the first entry in the symbol table.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
Returns:
Pointer to the first entry in the symbol table.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
int mprGetHashCount (MprHashTable *table)

Return the count of symbols in a symbol entry.

Description:
Returns the number of symbols currently existing in a symbol table.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
Returns:
Integer count of the number of entries.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
MprHash * mprGetNextHash (MprHashTable *table, MprHash *last)

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 mprGetFirstSymbol or mprGetNextSymbol is required to supply the value of the last argument.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
lastSymbol table entry returned via mprGetFirstSymbol or mprGetNextSymbol.
Returns:
Pointer to the first entry in the symbol table.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprLookupHash, mprLookupHashEntry, mprRemoveHash
cvoid * mprLookupHash (MprHashTable *table, cchar *key)

Lookup a symbol in the hash table.

Description:
Lookup a symbol key and return the value associated with that key.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
keyString key of the symbole entry to delete.
Returns:
Value associated with the key when the entry was inserted via mprInsertSymbol.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHashEntry, mprRemoveHash
MprHash * mprLookupHashEntry (MprHashTable *table, cchar *key)

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

Description:
Lookup a symbol key and return the hash table descriptor associated with that key.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
keyString key of the symbole entry to delete.
Returns:
MprHash table structure for the entry.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprRemoveHash
int mprRemoveHash (MprHashTable *table, cchar *key)

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 key.
Parameters:
tableSymbol table returned via mprCreateSymbolTable.
keyString key of the symbole entry to delete.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
See Also:
MprHash, mprAddDuplicateHash, mprAddHash, mprCopyHash, mprCreateHash, mprCreateKeyPair, mprFree, mprGetFirstHash, mprGetNextHash, mprLookupHash, mprLookupHashEntry

MprList

MprList

List Module.

Description:
The MprList is a dynamic growable list suitable for storing pointers to arbitrary objects.
API Stability:
Evolving.
See Also:
MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
Fields:
intcapacity Current list size.
void **items List item data.
intlength Current length of the list contents.
intmaxSize Maximum capacity.
int mprAddItem (MprList *list, cvoid *item)

Add an item to a list.

Description:
Add the specified item to the list. The list must have been previously created via mprCreateList. The list will grow as required to store the item.
Parameters:
listList pointer returned from mprCreateList.
itemPointer to item to store.
Returns:
Returns a positive integer list index for the inserted item. If the item cannot be inserted due to a memory allocation failure, -1 is returned.
See Also:
MprList, MprListCompareProc, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
MprList * mprAppendList (MprList *list, MprList *add)

Append a list.

Description:
Append the contents of one list to another. The list will grow as required to store the item.
Parameters:
listList pointer returned from mprCreateList.
addList whose contents are added.
Returns:
Returns a pointer to the original list if successful. Returns NULL on memory allocation errors.
See Also:
MprList, MprListCompareProc, mprAddItem, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void mprClearList (MprList *list)

Clears the list of all items.

Description:
Resets the list length to zero and clears all items. Existing items are not freed, they are only removed from the list.
Parameters:
listList pointer returned from mprCreateList.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprCopyList (MprList *dest, MprList *src)

Copy a list.

Description:
Copy the contents of a list into an existing list. The destination list is cleared first and has its dimensions set to that of the source clist.
Parameters:
destDestination list for the copy.
srcSource list.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
MprKeyValue * mprCreateKeyPair (MprCtx ctx, cchar *key, cchar *value)

Create a key / value pair.

Description:
Allocate and initialize a key value pair for use by the MprList or MprHash modules.
Parameters:
ctxAny memory context allocated by the MPR.
keyKey string.
valueKey value string.
Returns:
An initialized MprKeyValue.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
MprList * mprCreateList (MprCtx ctx)

Create a list.

Description:
Creates an empty list. MprList's can store generic pointers. They automatically grow as required when items are added to the list. Callers should invoke mprFree when finished with the list to release allocated storage.
Parameters:
ctxAny memory context allocated by the MPR.
Returns:
Returns a pointer to the list.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
MprList * mprDupList (MprCtx ctx, MprList *src)

Duplicate a list.

Description:
Copy the contents of a list into a new list.
Parameters:
ctxMemory context from which to allocate the list. See mprAlloc.
srcSource list to copy.
Returns:
Returns a new list reference.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void * mprGetFirstItem (MprList *list)

Get the first item in the list.

Description:
Returns the value of the first item in the list. After calling this routine, the remaining list items can be walked using mprGetNextItem.
Parameters:
listList pointer returned from mprCreateList.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void * mprGetItem (MprList *list, int index)

Get an list item.

Description:
Get an list item specified by its index.
Parameters:
listList pointer returned from mprCreateList.
indexItem index into the list. Indexes have a range from zero to the lenghth of the list - 1.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void * mprGetLastItem (MprList *list)

Get the last item in the list.

Description:
Returns the value of the last item in the list. After calling this routine, the remaining list items can be walked using mprGetPrevItem.
Parameters:
listList pointer returned from mprCreateList.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprGetListCapacity (MprList *list)

Get the current capacity of the list.

Description:
Returns the capacity of the list. This will always be equal to or greater than the list length.
Parameters:
listList pointer returned from mprCreateList.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprGetListCount (MprList *list)

Get the number of items in the list.

Description:
Returns the number of items in the list. This will always be less than or equal to the list capacity.
Parameters:
listList pointer returned from mprCreateList.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void * mprGetNextItem (MprList *list, int *lastIndex)

Get the next item in the list.

Description:
Returns the value of the next item in the list. Before calling this routine, mprGetFirstItem must be called to initialize the traversal of the list.
Parameters:
listList pointer returned from mprCreateList.
lastIndexPointer to an integer that will hold the last index retrieved.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void * mprGetPrevItem (MprList *list, int *lastIndex)

Get the previous item in the list.

Description:
Returns the value of the previous item in the list. Before calling this routine, mprGetFirstItem and/or mprGetNextItem must be called to initialize the traversal of the list.
Parameters:
listList pointer returned from mprCreateList.
lastIndexPointer to an integer that will hold the last index retrieved.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void mprInitList (MprList *list)

Initialize a list structure.

Description:
If a list is statically declared inside another structure, mprInitList can be used to initialize it before use.
Parameters:
listReference to the MprList struct.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprInsertItemAtPos (MprList *list, int index, cvoid *item)

Insert 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:
listList pointer returned from mprCreateList.
indexLocation at which to store the item. The previous item at this index is moved up to make room.
itemPointer to item to store.
Returns:
The position index (positive integer) if successful. If the item cannot be inserted due to a memory allocation failure, -1 is returned.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprLookupItem (MprList *list, cvoid *item)

Find an item and return its index.

Description:
Search for an item in the list and return its index.
Parameters:
listList pointer returned from mprCreateList.
itemPointer to value stored in the list.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprRemoveItem (MprList *list, void *item)

Remove an item from the list.

Description:
Search for a specified item and then remove it from the list. Existing items are not freed, they are only removed from the list.
Parameters:
listList pointer returned from mprCreateList.
itemItem pointer to remove.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveRangeOfItems, mprSortList
int mprRemoveItemAtPos (MprList *list, int index)

Remove an item from the list.

Description:
Removes the element specified by index, from the list. The list index is provided by mprInsertItem.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprRemoveLastItem (MprList *list)

Remove the last item from the list.

Description:
Remove the item at the highest index position. Existing items are not freed, they are only removed from the list.
Parameters:
listList pointer returned from mprCreateList.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprRemoveRangeOfItems (MprList *list, int start, int end)

Remove a range of items from the list.

Description:
Remove a range of items from the list. The range is specified from the start index up to and including the end index.
Parameters:
listList pointer returned from mprCreateList.
startStarting item index to remove (inclusive).
endEnding item index to remove (inclusive).
Returns:
Returns zero if successful, otherwise a negative MPR error code.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprSortList
void * mprSetItem (MprList *list, int index, cvoid *item)

Set a list item.

Description:
Update the list item stored at the specified index.
Parameters:
listList pointer returned from mprCreateList.
indexLocation to update.
itemPointer to item to store.
Returns:
The old item previously at that location index.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
int mprSetListLimits (MprList *list, int initialSize, int maxSize)

Define the list size limits.

Description:
Define the list initial size and maximum size it can grow to.
Parameters:
listList pointer returned from mprCreateList.
initialSizeInitial size for the list. This call will allocate space for at least this number of items.
maxSizeSet the maximum limit the list can grow to become.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
void mprSortList (MprList *list, MprListCompareProc compare)

Sort a list.

Description:
Sort a list using the sort ordering dictated by the supplied compare function.
Parameters:
listList pointer returned from mprCreateList.
compareComparison function. If null, then a default string comparison is used.
See Also:
MprList, MprListCompareProc, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems

MprLog

MprLog

Logging Services.

API Stability:
Evolving.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
Fields:
void mprError (MprCtx ctx, cchar *fmt, ...)

Log an error message.

Description:
Send an error message to the MPR debug logging subsystem. The message will be to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately and log the message.
Parameters:
ctxAny memory context allocated by the MPR.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
See Also:
MprLogHandler, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
void mprFatalError (MprCtx ctx, cchar *fmt, ...)

Log a fatal error message and exit.

Description:
Send a fatal error message to the MPR debug logging subsystem and then exit the application by calling exit(). The message will be to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately and log the message.
Parameters:
ctxAny memory context allocated by the MPR.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
See Also:
MprLogHandler, mprError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
MprLogHandler mprGetLogHandler (MprCtx ctx)

Get the current MPR debug log handler.

Description:
Get the log handler defined via mprSetLogHandler.
Parameters:
ctxAny memory context allocated by the MPR.
Returns:
A function of the signature MprLogHandler.
See Also:
MprLogHandler, mprError, mprFatalError, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
void mprLog (MprCtx ctx, int level, cchar *fmt, ...)

Write a message to the diagnostic log file.

Description:
Send a message to the MPR logging subsystem.
Parameters:
levelLogging level for this message. The level is 0-9 with zero being the most verbose.
ctxAny memory context allocated by the MPR.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
Remarks:
MprLog is highly useful as a debugging aid when integrating or when developing new modules.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
void mprMemoryError (MprCtx ctx, cchar *fmt, ...)

Log a memory error message.

Description:
Send a memory error message to the MPR debug logging subsystem. The message will be passed to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately to the fatal message, the MPR takes no other action other than logging the message. Typically, a memory message will be logged and the application will be shutdown. The preferred method of operation is to define a memory depletion callback via mprCreate. This will be invoked whenever a memory allocation error occurs.
Parameters:
ctxAny memory context allocated by the MPR.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
void mprRawLog (MprCtx ctx, int level, cchar *fmt, ...)

Write a raw log message to the diagnostic log file.

Description:
Send a raw message to the MPR logging subsystem. Raw messages do not have any application prefix attached to the message and do not append a newline to the message.
Parameters:
levelLogging level for this message. The level is 0-9 with zero being the most verbose.
ctxAny memory context allocated by the MPR.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
Remarks:
MprLog is highly useful as a debugging aid when integrating or when developing new modules.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
void mprSetLogHandler (MprCtx ctx, MprLogHandler handler, void *handlerData)

Set an MPR debug log handler.

Description:
Defines a callback handler for MPR debug and error log messages. When output is sent to the debug channel, the log handler will be invoked to accept the output message.
Parameters:
ctxAny memory context allocated by the MPR.
handlerCallback handler.
handlerDataCallback handler data.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
void mprSetLogLevel (MprCtx ctx, int level)

Set the current logging level.

Description:
This call defines the maximum level of messages that will be logged. Calls to mprLog specify a message level. If the message level is greater than the defined logging level, the message is ignored.
Parameters:
ctxAny memory context allocated by the MPR.
levelNew logging level. Must be 0-9 inclusive.
Returns:
The previous logging level.
API Stability:
Evolving.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprStaticAssert, mprStaticError, mprUserError
void mprStaticAssert (cchar *loc, cchar *msg)

Output an assertion failed message.

Description:
This will emit an assertion failed message to the standard error output. It will bypass the logging system.
Parameters:
locSource code location string. Use MPR_LOC to define a file name and line number string suitable for this parameter.
msgSimple string message to output.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticError, mprUserError
void mprStaticError (MprCtx ctx, cchar *fmt, ...)

Write a message to the diagnostic log file without allocating any memory.

Useful for log messages from within the memory allocator
Description:
Send a message to the MPR logging subsystem. This will not allocate any memory while formatting the message. The formatted message string will be truncated in size to MPR_MAX_STRING bytes.
Parameters:
ctxAny memory context allocated by the MPR.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprUserError
void mprUserError (MprCtx ctx, cchar *fmt, ...)

Display an error message to the user.

Description:
Display an error message to the user and then send it to the MPR debug logging subsystem. The message will be passed to the log handler defined by mprSetLogHandler. It is up to the log handler to respond appropriately and display the message to the user.
Parameters:
ctxAny memory context allocated by the MPR.
fmtPrintf style format string. Variable number of arguments to.
...Variable number of arguments for printf data.
See Also:
MprLogHandler, mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError

MprMem

MprMem

Memory Allocation Service.

Description:
The MPR provides a memory manager that sits above malloc. This layer provides arena and slab based allocations with a tree structured allocation mechanism. The goal of the layer is to provide a fast, secure, scalable memory allocator suited for embedded applications in multithreaded environments.

By using a tree structured network of memory contexts, error recovery in applications and memory freeing becomes much easier and more reliable. When a memory block is allocated a parent memory block must be specified. When the parent block is freed, all its children are automatically freed.

The MPR handles memory allocation errors globally. The application can configure a memory limits and redline so that memory depletion can be proactively detected and handled. This relieves most cost from detecting and handling allocation errors.
API Stability:
Evolving.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
Fields:
void * mprAlloc (MprCtx ctx, uint size)

Allocate a block of memory.

Description:
Allocates a block of memory using the supplied memory context ctx as the parent. mprAlloc manages a tree structure of memory blocks. Freeing a block via mprFree will release the allocated block and all child blocks.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
sizeSize of the memory block to allocate.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
See Also:
MprCtx, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprAllocObj (MprCtx ctx, Type type)

Allocate an object of a given type.

Description:
Allocates a block of memory large enough to hold an instance of the specified type. This uses the supplied memory context ctx as the parent. This is implemented as a macro.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
typeType of the object to allocate.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
API Stability:
Prototype. This function names are highly likely to be refactored.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprAllocObjWithDestructor (MprCtx ctx, Type type, MprDestructor destructor)

Allocate an object of a given type with a destructor.

Description:
Allocates a block of memory large enough to hold an instance of the specified type with a destructor. This uses the supplied memory context ctx as the parent. This is implemented as a macro. this call associates a destructor function with an object. This function will be invoked when the object is freed. Freeing a block will first call the destructor and if that returns zero, mprFree will release the allocated block and all child blocks.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
typeType of the object to allocate.
destructorDestructor function to invoke when the allocation is freed via mprFree.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
API Stability:
Prototype. This function names are highly likely to be refactored. Allocate a zeroed object of a given type with a destructor.
Description:
Allocates a zeroed block of memory large enough to hold an instance of the specified type with a destructor. This uses the supplied memory context ctx as the parent. This is implemented as a macro. this call associates a destructor function with an object. This function will be invoked when the object is freed. Freeing a block will first call the destructor and if that returns zero, mprFree will release the allocated block and all child blocks.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
typeType of the object to allocate.
destructorDestructor function to invoke when the allocation is freed via mprFree.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
API Stability:
Prototype. This function names are highly likely to be refactored.
See Also:
MprCtx, mprAlloc, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprAllocObjZeroed (MprCtx ctx, Type type)

Allocate a zeroed object of a given type.

Description:
Allocates a zeroed block of memory large enough to hold an instance of the specified type. This uses the supplied memory context ctx as the parent. This is implemented as a macro.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
typeType of the object to allocate.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
API Stability:
Prototype. This function names are highly likely to be refactored.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprAllocWithDestructor (MprCtx ctx, uint size, MprDestructor destructor)

Allocate an object block of memory.

Description:
Allocates a block of memory using the supplied memory context ctx as the parent. mprAllocWithDestructor associates a destructor function with an object. This function will be invoked when the object is freed. Freeing a block will first call the destructor and if that returns zero, mprFree will release the allocated block and all child blocks.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
sizeSize of the memory block to allocate.
destructorDestructor function to invoke when the allocation is freed via mprFree.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
API Stability:
Prototype. This function names are highly likely to be refactored.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprAllocWithDestructorZeroed (MprCtx ctx, uint size, MprDestructor destructor)

Allocate an object block of memory and zero it.

Description:
Allocates a zeroed block of memory using the supplied memory context ctx as the parent. mprAllocWithDestructor associates a destructor function with an object. This function will be invoked when the object is freed. Freeing a block will first call the destructor and if that returns zero, mprFree will release the allocated block and all child blocks.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
sizeSize of the memory block to allocate.
destructorDestructor function to invoke when the allocation is freed via mprFree.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
API Stability:
Prototype. This function names are highly likely to be refactored.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprAllocZeroed (MprCtx ctx, uint size)

Allocate a zeroed block of memory.

Description:
Allocates a zeroed block of memory using the supplied memory context ctx as the parent. mprAlloc manages a tree structure of memory blocks. Freeing a block via mprFree will release the allocated block and all child blocks.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
sizeSize of the memory block to allocate.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to malloc and mprAlloc.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
int mprFree (void *ptr)

Free a block of memory.

Description:
MprFree should be used to free memory allocated by mprAlloc, or mprRealloc. This call will ignore calls to free a null pointer, thus it is an acceptable idiom to free a pointer without testing its value for null. When mprFree is called it will first invoke any object destructor function for the allocated block. If this destructor returns zero, it will then proceed and free all allocated children before finally releasing the block.
Parameters:
ptrMemory to free. If NULL, take no action.
Returns:
Returns zero if the block was actually freed. If the destructor prevented the freeing, a non-zero value will be returned.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprGetParent (MprCtx ctx)

Get the memory parent of a block.

Description:
Return the parent memory context for a block.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Returns:
The memory owning this block.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprMemdup (MprCtx ctx, cvoid *ptr, uint size)

Duplicate a block of memory.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Description:
Copy a block of memory into a newly allocated block.
Parameters:
ptrPointer to the block to duplicate.
sizeSize of the block to copy.
Returns:
Returns an allocated block. Caller must free via mprFree.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
void * mprRealloc (MprCtx ctx, void *ptr, uint size)

Reallocate a block.

Description:
Reallocates a block increasing its size. If the specified size is less than the current block size, the call will ignore the request and simply return the existing block.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
ptrMemory to reallocate. If NULL, call malloc.
sizeNew size of the required memory block.
Returns:
Returns a pointer to the allocated block. If memory is not available the memory exhaustion handler specified via mprCreate will be called to allow global recovery.
Remarks:
Do not mix calls to realloc and mprRealloc.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprResetAllocError, mprSetAllocLimits, mprStrndup
void mprResetAllocError (MprCtx ctx)

Reset the memory allocation error flag.

Description:
Reset the alloc error flag triggered.
Parameters:
ctxAny memory context allocated by the MPR.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprSetAllocLimits, mprStrndup
void mprSetAllocLimits (MprCtx ctx, uint redline, uint maxMemory)

Configure the application memory limits.

Description:
Configure memory limits to constrain memory usage by the application. The memory allocation subsystem will check these limits before granting memory allocation requrests. The redLine is a soft limit that if exceeded will invoke the memory allocation callback, but will still honor the request. The maxMemory limit is a hard limit. The MPR will prevent allocations which exceed this maximum. The memory callback handler is defined via the mprCreate call.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
redlineSoft memory limit. If exceeded, the request will be granted, but the memory handler will be invoked.
maxMemoryHard memory limit. If exceeded, the request will not be granted, and the memory handler will be invoked.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprStrndup
void mprSetDestructor (void *ptr, MprDestructor destructor)

Update the destructor for a block of memory.

Description:
This call updates the destructor for a block of memory allocated via mprAllocWithDestructor.
Parameters:
ptrMemory to free. If NULL, take no action.
destructorDestructor function to invoke when mprFree is called.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
char * mprStrdup (MprCtx ctx, cchar *str)

Safe replacement for strdup.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Description:
mprStrdup() should be used as a replacement for strdup wherever possible. It allows the strdup to be copied to be NULL, in which case it will allocate an empty string.
Parameters:
strPointer to string to duplicate. If str is NULL, allocate a new string containing only a trailing NULL character.
Returns:
Returns an allocated string including trailing null.
Remarks:
Memory allocated via mprStrdup() must be freed via mprFree().
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
char * mprStrndup (MprCtx ctx, cchar *str, uint size)

Duplicate a string.

Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
Description:
Copy a string into a newly allocated block. The new block will be sized to the maximum of the length of the existing string (plus a null) and the requested size.
Parameters:
strPointer to the block to duplicate.
sizeRequested minimum size of the allocated block holding the duplicated string.
Returns:
Returns an allocated block. Caller must free via mprFree.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits

MprModule

MprModule

Loadable Module Service.

Description:
The MPR provides services to load and unload shared libraries.
See Also:
MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprSetModuleSearchPath, mprUnloadModule
API Stability:
Evolving.
Fields:
void *handle O/S shared library load handle.
void *moduleData Module specific data.
char *name Unique module name.
MprModuleProcstart Start the module service.
MprModuleProcstop Stop the module service.
char *version Module version.
MprModule * mprCreateModule (MprCtx ctx, cchar *name, cchar *version, void *moduleData, MprModuleProc start, MprModuleProc stop)

Create a module.

Description:
This call will create a module object for a loadable module. This should be invoked by the module itself in its module entry point to register itself with the MPR.
Parameters:
ctxAny memory context allocated by the MPR.
nameName of the module.
versionVersion string of the form: Major.Minor.patch.
moduleDatato associate with this module.
startStart function to invoke to start module services.
stopStop function to invoke to stop module services.
Returns:
A module object for this module.
See Also:
MprModule, MprModuleProc, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprSetModuleSearchPath, mprUnloadModule
cchar * mprGetModuleSearchPath (MprCtx ctx)

Get the module search path.

Description:
Get the directory search path used by the MPR when loading dynamic modules. This is a colon separated (or semicolon on Windows) set of directories.
Parameters:
ctxAny memory context allocated by the MPR.
Returns:
The module search path. Caller must not free.
See Also:
MprModule, MprModuleProc, mprCreateModule, mprLoadModule, mprLookupModule, mprSetModuleSearchPath, mprUnloadModule
MprModule * mprLoadModule (MprCtx ctx, cchar *filename, cchar *entryPoint)

Load a module.

Description:
Load a module into the MPR. This will load a dynamic shared object (shared library) and call the modules entry point. If the module has already been loaded, it this call will do nothing and will just return the already defined module object.
Parameters:
ctxAny memory context allocated by the MPR.
filenameName of the module to load. The module will be searched using the defined module search path (see mprSetModuleSearchPath). The filename may or may not include a platform specific shared library extension such as .dll, .so or .dylib. By omitting the library extension, code can portably load shared libraries.
entryPointName of function to invoke after loading the module.
Returns:
A module object for this module created in the module entry point by calling mprCreateModule.
See Also:
MprModule, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLookupModule, mprSetModuleSearchPath, mprUnloadModule
MprModule * mprLookupModule (MprCtx ctx, cchar *name)

Lookup a module.

Description:
Lookup a module by name and return the module object.
Parameters:
ctxAny memory context allocated by the MPR.
nameName of the module specified to mprCreateModule.
Returns:
A module object for this module created in the module entry point by calling mprCreateModule.
See Also:
MprModule, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprSetModuleSearchPath, mprUnloadModule
void mprSetModuleSearchPath (MprCtx ctx, char *searchPath)

Set the module search path.

Description:
Set the directory search path used by the MPR when loading dynamic modules. This path string must should be a colon separated (or semicolon on Windows) set of directories.
Parameters:
ctxAny memory context allocated by the MPR.
searchPathColon separated set of directories.
Returns:
The module search path. Caller must not free.
See Also:
MprModule, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprUnloadModule
void mprUnloadModule (MprModule *mp)

Unload a module.

Description:
Unload a module from the MPR. This will unload a dynamic shared object (shared library). This routine is not fully supported by the MPR and is often fraught with issues. A module must usually be completely inactive with no allocated memory when it is unloaded.
Parameters:
mpModule object returned via mprLookupModule.
See Also:
MprModule, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprSetModuleSearchPath

MprPath

MprPath

Path (filename) Services Module.

Description:
MprPath is the filename abstraction control structure.
API Stability:
Evolving.
See Also:
MprFile, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
Fields:
MprTimeatime Access time.
boolcaseMatters Case comparisons matter.
MprTimectime Create time.
uintinode Inode number.
boolisDir Set if directory.
boolisReg Set if a regular file.
MprTimemtime Modified time.
intperms Permission mask.
int64size File length.
intvalid Valid data bit.
int mprCopyPath (MprCtx ctx, cchar *from, cchar *to, int omode)

Copy a file.

Description:
Create a new copy of a file with the specified open permissions mode.
Parameters:
ctxAny memory context allocated by the MPR.
fromPath of the existing file to copy.
toName of the new file copy.
omodePosix style file open mode mask. See mprOpen for the various modes.
Returns:
True if the file exists and can be accessed.
See Also:
MprFile, MprPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
int mprDeletePath (MprCtx ctx, cchar *path)

Delete a file.

Description:
Delete a file or directory.
Parameters:
ctxAny memory context allocated by the MPR.
pathString containing the path to delete.
Returns:
Returns zero if successful otherwise a negative MPR error code is returned.
See Also:
MprFile, MprPath, mprCopyPath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetAbsPath (MprCtx ctx, cchar *path)

Convert a path to an absolute path.

Description:
Get an absolute (canonical) equivalent representation of a path.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath to examine.
Returns:
An absolute path. Caller should free via mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetNativePath (MprCtx ctx, cchar *path)

Get a path formatted according to the native O/S conventions.

Description:
Get an equivalent absolute path formatted using the directory separators native to the O/S platform. On Windows, it will use backward slashes ("\") as the directory separator and will contain a drive specification.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
An allocated string containing the new path. Caller must free using mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetNormalizedPath (MprCtx ctx, cchar *path)

Normalize a path.

Description:
A path is normalized by redundant segments such as "./" and "../dir" and duplicate path separators. Path separators are mapped. Paths are not converted to absolute paths.
Parameters:
ctxAny memory context allocated by the MPR.
pathFirst path to compare.
Returns:
A newly allocated, clean path. Caller should free via mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetPathBase (MprCtx ctx, cchar *path)

Get the base portion of a path.

Description:
Get the base portion of a path by stripping off all directory components.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
A path without any directory portion. The path is a reference into the original file string and should not be freed.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetPathDir (MprCtx ctx, cchar *path)

Get the directory portion of a path.

Description:
Get the directory portion of a path by stripping off the base name.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
A new string containing the directory name. Caller must free.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
cchar * mprGetPathExtension (MprCtx ctx, cchar *path)

Get the file extension portion of a path.

Description:
Get the file extension portion of a path. The file extension is the portion after the last "." in the path.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
A path extension. The extension is a reference into the original file string and should not be freed.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
MprList * mprGetPathFiles (MprCtx ctx, cchar *dir, bool enumDirs)

Create a directory list of files.

Description:
Get the list of files in a directory and return a list.
Parameters:
ctxAny memory context allocated by the MPR.
dirDirectory to list.
enumDirsSet to true to enumerate directory entries as well as regular paths.
Returns:
A list (MprList) of directory paths. Each path is a regular string owned by the list object. Use mprFree to free the memory for the list and directory paths.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
int mprGetPathInfo (MprCtx ctx, cchar *path, MprPath *info)

Return information about a file represented by a path.

Description:
Returns file status information regarding the path.
Parameters:
ctxAny memory context allocated by the MPR.
pathString containing the path to query.
infoPointer to a pre-allocated MprPath structure.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
cchar * mprGetPathNewline (MprCtx ctx, cchar *path)

Get the file newline character string for a given path.

Return the character string used to delimit new lines in text files
Parameters:
ctxAny memory context allocated by the MPR.
pathUse this path to specify either the root of the file system or a file on the file system.
Returns:
A string used to delimit new lines. This is typically "\n" or "\r\n".
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetPathParent (MprCtx ctx, cchar *path)

Get the parent directory of a path.

Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
An allocated string containing the parent directory. Caller must free using mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
cchar * mprGetPathSeparators (MprCtx ctx, cchar *path)

Get the path directory separator.

Return the directory separator characters used to separate directories on a given file system. Typically "/" or "\" The first entry is the default separator
Parameters:
ctxAny memory context allocated by the MPR.
pathUse this path to specify either the root of the file system or a file on the file system.
Returns:
The string of path separators. The first entry is the default separator.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetPortablePath (MprCtx ctx, cchar *path)

Get a portable path.

Description:
Get an equivalent absolute path that is somewhat portable. This means it will use forward slashes ("/") as the directory separator.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
An allocated string containing the new path. Caller must free using mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetRelPath (MprCtx ctx, cchar *path)

Get a relative path.

Description:
Get an equivalent path that is relative to the application's current working directory.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
An allocated string containing the relative directory. Caller must free using mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetTempPath (MprCtx ctx, cchar *tmpDir)

Make a temporary file.

Description:
Thread-safe way to make a unique temporary file.
Parameters:
ctxAny memory context allocated by the MPR.
tmpDirBase directory in which the temp file will be allocated.
Returns:
An allocated string containing the path of the temp file.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprGetTransformedPath (MprCtx ctx, cchar *path, int flags)

Transform a path.

Description:
A path is transformed by cleaning and then transforming according to the flags.
Parameters:
ctxAny memory context allocated by the MPR.
pathFirst path to compare.
flagsFlags to modify the path representation.
Returns:
A newly allocated, clean path. Caller should free via mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
bool mprIsAbsPath (MprCtx ctx, cchar *path)

Determine if a path is absolute.

Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
True if the path is absolue.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
bool mprIsRelPath (MprCtx ctx, cchar *path)

Determine if a path is relative.

Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
Returns:
True if the path is relative.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprJoinPath (MprCtx ctx, cchar *dir, cchar *other)

Join paths.

Description:
Resolve one path relative to another.
Parameters:
ctxAny memory context allocated by the MPR.
dirDirectory path name to test use as the base/dir.
otherOther path name to resolve against path.
Returns:
Allocated string containing the resolved path.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprJoinPathExt (MprCtx ctx, cchar *dir, cchar *ext)

Join an extension to a path.

Description:
Add an extension to a path if it does not already have one.
Parameters:
ctxAny memory context allocated by the MPR.
dirDirectory path name to test use as the base/dir.
extExtension to add. Must have period prefix.
Returns:
Allocated string containing the resolved path.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
int mprMakeDir (MprCtx ctx, cchar *path, int perms, bool makeMissing)

Make a directory.

Description:
Make a directory using the supplied path. Intermediate directories are created as required.
Parameters:
ctxAny memory context allocated by the MPR.
pathString containing the directory pathname to create.
makeMissingIf true make all required intervening directory segments.
permsPosix style file permissions mask.
Returns:
Returns zero if successful, otherwise a negative MPR error code is returned.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
void mprMapSeparators (MprCtx ctx, char *path, int separator)

Map the separators in a path.

Description:
Map the directory separators in a path to the specified separators. This is useful to change from backward to forward slashes when dealing with Windows paths.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to examine.
separatorSeparator character to use.
Returns:
An allocated string containing the parent directory. Caller must free using mprFree.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprPathExists, mprSearchPath, mprTruncatePath
bool mprPathExists (MprCtx ctx, cchar *path, int omode)

Determine if a file exists for a path name and can be accessed.

Description:
Test if a file can be accessed for a given mode.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to test.
omodePosix style file open mode mask. See mprOpen for the various modes.
Returns:
True if the file exists and can be accessed.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprSearchPath, mprTruncatePath
int mprSamePath (MprCtx ctx, cchar *path1, cchar *path2)

Compare two paths if they are the same.

Description:
Compare two paths to see if they are equal. This normalizes the paths to absolute paths first before comparing. It does handle case sensitivity appropriately.
Parameters:
ctxAny memory context allocated by the MPR.
path1First path to compare.
path2Second path to compare.
Returns:
True if the file exists and can be accessed.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
int mprSamePathCount (MprCtx ctx, cchar *path1, cchar *path2, int len)

Compare two paths if they are the same for a given length.

Description:
Compare two paths to see if they are equal. This normalizes the paths to absolute paths first before comparing. It does handle case sensitivity appropriately. The len parameter if non-zero, specifies how many characters of the paths to compare.
Parameters:
ctxAny memory context allocated by the MPR.
path1First path to compare.
path2Second path to compare.
lenHow many characters to compare.
Returns:
True if the file exists and can be accessed.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
char * mprSearchPath (MprCtx ctx, cchar *path, int flags, cchar *search, ...)

Search for a path.

Description:
Search for a file using a given set of search directories.
Parameters:
ctxAny memory context allocated by the MPR.
pathPath name to locate. Must be an existing file or directory.
flagsFlags.
searchVariable number of directories to search.
Returns:
Allocated string containing the full path name of the located file.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprTruncatePath
char * mprTrimPathExtension (MprCtx ctx, cchar *path)

Trim an extension from a path.

Description:
Trim a file extension (".ext") from a path name.
Parameters:
ctxAny memory context allocated by the MPR.
pathFirst path to compare.
Returns:
An allocated string with the trimmed path.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath, mprTruncatePath
int mprTruncatePath (MprCtx ctx, cchar *path, int size)

Truncate a path.

Description:
Truncate a file to a given size.
Parameters:
ctxAny memory context allocated by the MPR.
pathFirst path to compare.
sizeNew maximum size for the file.
Returns:
Zero if successful.
See Also:
MprFile, MprPath, mprCopyPath, mprDeletePath, mprGetAbsPath, mprGetCurrentPath, mprGetNormalizedPath, mprGetPathBase, mprGetPathDir, mprGetPathExtension, mprGetPathFiles, mprGetPathNewline, mprGetPathParent, mprGetPathSeparators, mprGetPortablePath, mprGetRelPath, mprGetTempPath, mprGetTransformedPath, mprIsAbsPath, mprIsRelPath, mprJoinPath, mprJoinPathExt, mprMakeDir, mprMapSeparators, mprPathExists, mprSearchPath

MprPoolService

MprPoolService

Thread Pool Service.

Description:
The MPR provides a thread pool for rapid starting and assignment of threads to tasks.
API Stability:
Evolving.
See Also:
mprAvailablePoolThreads, mprSetMaxPoolThreads, mprSetMinPoolThreads
Fields:
int mprAvailablePoolThreads (MprCtx ctx)

Get the count of available pool threads Return the count of free threads in the thread pool.

Parameters:
ctxAny memory allocation context created by MprAlloc.
Returns:
An integer count of pool threads.
See Also:
MprPoolService, mprSetMaxPoolThreads, mprSetMinPoolThreads
int mprGetMaxPoolThreads (MprCtx ctx)

Get the maximum count of pool threads Get the maximum limit of pool threads.

Parameters:
ctxAny memory allocation context created by MprAlloc.
Returns:
The maximum count of pool threads.
See Also:
MprPoolService, mprAvailablePoolThreads, mprSetMaxPoolThreads, mprSetMinPoolThreads
void mprSetMaxPoolThreads (MprCtx ctx, int count)

Set the maximum count of pool threads Set the maximum number of pool threads for the MPR.

If this number if less than the current number of threads, excess threads will be gracefully pruned as they exit
Parameters:
ctxAny memory allocation context created by MprAlloc.
countMaximum limit of threads to define.
See Also:
MprPoolService, mprAvailablePoolThreads, mprSetMinPoolThreads
void mprSetMinPoolThreads (MprCtx ctx, int count)

Set the minimum count of pool threads Set the count of threads the pool will have.

This will cause the pool to pre-create at least this many threads
Parameters:
ctxAny memory allocation context created by MprAlloc.
countMinimum count of threads to use.
See Also:
MprPoolService, mprAvailablePoolThreads, mprSetMaxPoolThreads

MprSocket

MprSocket

Socket Service.

Description:
The MPR Socket service provides IPv4 and IPv6 capabilities for both client and server endpoints. Datagrams, Broadcast and point to point services are supported. The APIs can be used in both blocking and non-blocking modes.

The socket service integrates with the MPR thread pool and eventing services. Socket connections can be handled by threads from the thread pool for scalable, multithreaded applications.
API Stability:
Evolving.
See Also:
mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
Fields:
MprSocketAcceptProcacceptCallback Accept callback.
void *acceptData User accept callback data.
char *clientIpAddr Client side ip address.
intcurrentEvents Mask of ready events (FD_x).
interror Last error.
intfd Actual socket file handle.
intflags Current state flags.
MprWaitHandler *handler Wait handler.
inthandlerMask Handler events of interest.
inthandlerPriority Handler priority.
intinterestEvents Mask of events to watch for.
MprSocketProcioCallback User I/O callback.
void *ioData User io callback data.
void *ioData2 Secondary user io callback data.
char *ipAddr Server side ip address.
struct MprSocket *listenSock Listening socket.
MprMutex *mutex Multi-thread sync.
intport Port to listen on.
MprSocketProvider *provider Socket implementation provider.
MprSocketService *service Socket service.
struct MprSsl *ssl SSL configuration.
struct MprSslSocket *sslSocket Extended ssl socket state. If set, then using ssl.
intwaitForEvents Events being waited on.
void mprCloseSocket (MprSocket *sp, bool graceful)

Close a socket.

Description:
Close a socket. If the graceful option is true, the socket will first wait for written data to drain before doing a graceful close.
Parameters:
spSocket object returned from mprCreateSocket.
gracefulSet to true to do a graceful close. Otherwise, an abortive close will be performed.
See Also:
MprSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
MprSocket * mprCreateSocket (MprCtx ctx, struct MprSsl *ssl)

Create a socket.

Description:
Create a new socket.
Parameters:
ctxAny memory allocation context created by MprAlloc.
sslAn optional SSL context if the socket is to support SSL. Use the MPR_SECURE_CLIENT define to specify that mprCreateSocket should use the default SSL provider.
Returns:
A new socket object.
See Also:
MprSocket, mprCloseSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprFlushSocket (MprSocket *sp)

Flush a socket.

Description:
Flush any buffered data in a socket. Standard sockets do not use buffering and this call will do nothing. SSL sockets do buffer and calling mprFlushSocket will write pending written data.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
bool mprGetSocketBlockingMode (MprSocket *sp)

Get the socket blocking mode.

Description:
Return the current blocking mode setting.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
True if the socket is in blocking mode. Otherwise false.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
bool mprGetSocketEof (MprSocket *sp)

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

Description:
Determine if the other end of the socket has been closed and the socket is at end-of-file.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
True if the socket is at end-of-file.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprGetSocketError (MprSocket *sp)

Get a socket error code.

Description:
This will map a Windows socket error code into a posix error code.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
A posix error code.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprGetSocketFd (MprSocket *sp)

Get the socket file descriptor.

Description:
Get the file descriptor associated with a socket.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
The integer file descriptor used by the O/S for the socket.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprGetSocketPort (MprSocket *sp)

Get the port used by a socket.

Description:
Get the TCP/IP port number used by the socket.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
The integer TCP/IP port number used by the socket.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprOpenClientSocket (MprSocket *sp, cchar *hostName, int port, int flags)

Open a client socket.

Description:
Open a client connection.
Parameters:
spSocket object returned via mprCreateSocket.
hostNameHost or IP address to connect to.
portTCP/IP port number to connect to.
flagsSocket flags may use the following flags ored together:
  • MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking.
  • MPR_SOCKET_BROADCAST - Use IPv4 broadcast
  • MPR_SOCKET_DATAGRAM - Use IPv4 datagrams
  • MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket
  • MPR_SOCKET_NODELAY - Set NODELAY on the socket
  • MPR_SOCKET_THREAD - Process callbacks on a separate thread.
.
Returns:
Zero if the connection is successful. Otherwise a negative MPR error code.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprOpenServerSocket (MprSocket *sp, cchar *ipAddr, int port, MprSocketAcceptProc acceptFn, void *data, int flags)

Open a server socket.

Description:
Open a server socket and listen for client connections.
Parameters:
spSocket object returned via mprCreateSocket.
ipAddrIP address to bind to. Set to 0.0.0.0 to bind to all possible addresses on a given port.
portTCP/IP port number to connect to.
acceptFnCallback function to invoke to accept incoming client connections.
dataOpaque data reference to pass to the accept function.
flagsSocket flags may use the following flags ored together:
  • MPR_SOCKET_BLOCK - to use blocking I/O. The default is non-blocking.
  • MPR_SOCKET_BROADCAST - Use IPv4 broadcast
  • MPR_SOCKET_DATAGRAM - Use IPv4 datagrams
  • MPR_SOCKET_NOREUSE - Set NOREUSE flag on the socket
  • MPR_SOCKET_NODELAY - Set NODELAY on the socket
  • MPR_SOCKET_THREAD - Process callbacks on a separate thread.
.
Returns:
Zero if the connection is successful. Otherwise a negative MPR error code.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprReadSocket (MprSocket *sp, void *buf, int size)

Read from a socket.

Description:
Read data from a socket. The read will return with whatever bytes are available. If none and the socket is in blocking mode, it will block untill there is some data available or the socket is disconnected.
Parameters:
spSocket object returned from mprCreateSocket.
bufPointer to a buffer to hold the read data.
sizeSize of the buffer.
Returns:
A count of bytes actually read. Return a negative MPR error code on errors.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
MprOffset mprSendFileToSocket (MprFile *file, MprSocket *sock, MprOffset offset, int bytes, MprIOVec *beforeVec, int beforeCount, MprIOVec *afterVec, int afterCount)

Send a file to a socket.

Description:
Write the contents of a file to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes. This API permits the writing of data before and after the file contents.
Parameters:
fileFile to write to the socket.
sockSocket object returned from mprCreateSocket.
offsetoffset within the file from which to read data.
bytesLength of file data to write.
beforeVecVector of data to write before the file contents.
beforeCountCount of entries in beforeVect.
afterVecVector of data to write after the file contents.
afterCountCount of entries in afterCount.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprSetSocketBlockingMode (MprSocket *sp, bool on)

Set the socket blocking mode.

Description:
Set the blocking mode for a socket. By default a socket is in non-blocking mode where read / write calls will not block.
Parameters:
spSocket object returned from mprCreateSocket.
onSet to zero to put the socket into non-blocking mode. Set to non-zero to enable blocking mode.
Returns:
The old blocking mode if successful or a negative MPR error code.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
void mprSetSocketCallback (MprSocket *sp, MprSocketProc fn, void *data, void *data2, int mask, int priority)

Set the socket callback.

Description:
Define a socket callback function to invoke in response to socket I/O events.
Parameters:
spSocket object returned from mprCreateSocket.
fnCallback function.
dataData to pass with the callback.
data2More data to pass with the callback.
maskBit mask of events of interest. Set to MPR_READABLE and/or MPR_WRITABLE.
priorityPriority to associate with the event. Priorities are integer values between 0 and 100 inclusive with 50 being a normal priority. (See MPR_NORMAL_PRIORITY).
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
void mprSetSocketEventMask (MprSocket *sp, int mask)

Define the events of interest for a socket.

Description:
Define an event mask of interest for a socket. The mask is made by oring the MPR_READABLE and MPR_WRITEABLE flags as requried.
Parameters:
spSocket object returned from mprCreateSocket.
maskSet to true to do a graceful close. Otherwise, an abortive close will be performed.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprSetSocketNoDelay (MprSocket *sp, bool on)

Set the socket delay mode.

Description:
Set the socket delay behavior (nagle algorithm). By default a socket will partial packet writes a little to try to accumulate data and coalesce TCP/IP packages. Setting the delay mode to false may result in higher performance for interactive applications.
Parameters:
spSocket object returned from mprCreateSocket.
onSet to non-zero to put the socket into no delay mode. Set to zero to enable the nagle algorithm.
Returns:
The old delay mode if successful or a negative MPR error code.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
bool mprSocketIsSecure (MprSocket *sp)

Determine if the socket is secure.

Description:
Determine if the socket is using SSL to provide enhanced security.
Parameters:
spSocket object returned from mprCreateSocket.
Returns:
True if the socket is using SSL, otherwise zero.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprWriteSocket, mprWriteSocketString, mprWriteSocketVector
int mprWriteSocket (MprSocket *sp, void *buf, int len)

Write to a socket.

Description:
Write a block of data to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes.
Parameters:
spSocket object returned from mprCreateSocket.
bufReference to a block to write to the socket.
lenLength of data to write. This may be less than the requested write length if the socket is in non-blocking mode. Will return a negative MPR error code on errors.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocketString, mprWriteSocketVector
int mprWriteSocketString (MprSocket *sp, cchar *str)

Write to a string to a socket.

Description:
Write a string to a socket. If the socket is in non-blocking mode (the default), the write may return having written less than the required bytes.
Parameters:
spSocket object returned from mprCreateSocket.
strNull terminated string to write.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketVector
int mprWriteSocketVector (MprSocket *sp, MprIOVec *iovec, int count)

Write a vector to a socket.

Description:
Do scatter/gather I/O by writing a vector of buffers to a socket.
Parameters:
spSocket object returned from mprCreateSocket.
iovecVector of data to write before the file contents.
countCount of entries in beforeVect.
Returns:
A count of bytes actually written. Return a negative MPR error code on errors.
See Also:
MprSocket, mprCloseSocket, mprCreateSocket, mprFlushSocket, mprFree, mprGetSocketBlockingMode, mprGetSocketBlockingMode, mprGetSocketEof, mprGetSocketError, mprGetSocketFd, mprGetSocketPort, mprOpenClientSocket, mprOpenServerSocket, mprReadSocket, mprSendFileToSocket, mprSetSocketCallback, mprSetSocketEventMask, mprSetSocketNoDelay, mprSocketIsSecure, mprWriteSocket, mprWriteSocketString

MprSynch

MprSynch

Multithreaded Synchronization Services.

See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
API Stability:
Evolving.
Fields:
MprCond * mprCreateCond (MprCtx ctx)

Create a condition lock variable.

Description:
This call creates a condition variable object that can be used in mprWaitForCond and mprSignalCond calls. Use mprFree to destroy the condition variable.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
See Also:
MprCond, MprMutex, MprSpin, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
MprMutex * mprCreateLock (MprCtx ctx)

Create a Mutex lock object.

Description:
This call creates a Mutex lock object that can be used in mprLock, mprTryLock and mprUnlock calls. Use mprFree to destroy the lock.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
MprSpin * mprCreateSpinLock (MprCtx ctx)

Create a spin lock lock object.

Description:
This call creates a spinlock object that can be used in mprSpinLock, and mprSpinUnlock calls. Spin locks using MprSpin are much faster than MprMutex based locks on some systems. Use mprFree to destroy the lock.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
void mprGlobalLock (MprCtx ctx)

Globally lock the application.

Description:
This call asserts the application global lock so that other threads calling mprGlobalLock will block until the current thread calls mprGlobalUnlock.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
void mprGlobalUnlock (MprCtx ctx)

Unlock the global mutex.

Description:
This call unlocks the global mutex previously locked via mprGlobalLock.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
MprMutex * mprInitLock (MprCtx ctx, MprMutex *mutex)

Initialize a statically allocated Mutex lock object.

Description:
This call initialized a Mutex lock object without allocation. The object can then be used used in mprLock, mprTryLock and mprUnlock calls.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
mutexReference to an MprMutex structure to initialize.
Returns:
A reference to the supplied mutex. Returns null on errors.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
MprSpin * mprInitSpinLock (MprCtx ctx, MprSpin *lock)

Initialize a statically allocated spinlock object.

Description:
This call initialized a spinlock lock object without allocation. The object can then be used used in mprSpinLock and mprSpinUnlock calls.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
lockReference to a static MprSpin object.
Returns:
A reference to the MprSpin object. Returns null on errors.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
void mprLock (MprMutex *lock)

Lock access.

Description:
This call asserts a lock on the given lock mutex so that other threads calling mprLock will block until the current thread calls mprUnlock.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
void mprSignalCond (MprCond *cond)

Signal a condition lock variable.

Description:
Signal a condition variable and set it to the triggered status. Existing or future callers of mprWaitForCond will be awakened.
Parameters:
condCondition variable object created via mprCreateCond.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprTryLock, mprUnlock, mprWaitForCond
void mprSpinLock (MprSpin *lock)

Lock a spinlock.

Description:
This call asserts a lock on the given spinlock so that other threads calling mprSpinLock will block until the curren thread calls mprSpinUnlock.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
void mprSpinUnlock (MprSpin *lock)

Unlock a spinlock.

Description:
This call unlocks a spinlock previously locked via mprSpinLock or mprTrySpinLock.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
bool mprTryLock (MprMutex *lock)

Attempt to lock access.

Description:
This call attempts to assert a lock on the given lock mutex so that other threads calling mprLock or mprTryLock will block until the current thread calls mprUnlock.
Returns:
Returns zero if the successful in locking the mutex. Returns a negative MPR error code if unsuccessful.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprUnlock, mprWaitForCond
bool mprTrySpinLock (MprSpin *lock)

Attempt to lock access on a spin lock.

Description:
This call attempts to assert a lock on the given spin lock so that other threads calling mprSpinLock or mprTrySpinLock will block until the current thread calls mprSpinUnlock.
Returns:
Returns zero if the successful in locking the spinlock. Returns a negative MPR error code if unsuccessful.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock, mprWaitForCond
void mprUnlock (MprMutex *lock)

Unlock a mutex.

Description:
This call unlocks a mutex previously locked via mprLock or mprTryLock.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprWaitForCond
int mprWaitForCond (MprCond *cond, int timeout)

Wait for a condition lock variable.

Description:
Wait for a condition lock variable to be signaled. If the condition is signaled before the timeout expires this call will reset the condition variable and return. This way, it automatically resets the variable for future waiters.
Parameters:
condCondition variable object created via mprCreateCond.
timeoutTime in milliseconds to wait for the condition variable to be signaled.
See Also:
MprCond, MprMutex, MprSpin, mprCreateCond, mprCreateSpinLock, mprFree, mprFree, mprGlobalLock, mprGlobalUnlock, mprLock, mprSignalCond, mprTryLock, mprUnlock

MprThread

MprThread

Thread Service.

Description:
The MPR provides a cross-platform thread abstraction above O/S native threads. It supports arbitrary thread creation, thread priorities, thread management and thread local storage. By using these thread primitives with the locking and synchronization primitives offered by MprMutex, MprSpin and MprCond - you can create cross platform multi-threaded applications.
API Stability:
Evolving.
See Also:
mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadName, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
Fields:
void *data Data argument.
MprThreadProcentry Users thread entry point.
MprMutex *mutex Multi-thread synchronization.
char *name Name of thead for trace.
MprOsThreadosThreadID O/S thread id.
ulongpid Owning process id.
intpriority Current priority.
intstackSize Only VxWorks implements.
handlethreadHandle Threads OS handle for WIN.
MprThread * mprCreateThread (MprCtx ctx, cchar *name, MprThreadProc proc, void *data, int priority, int stackSize)

Create a new thread.

Description:
MPR threads are usually real O/S threads and can be used with the various locking services (MprMutex, MprCond, MprSpin) to enable scalable multithreaded applications.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
nameUnique name to give the thread.
procEntry point function for the thread. mprStartThread will invoke this function to start the thread.
dataThread private data stored in MprThread.data.
priorityPriority to associate with the thread. Mpr thread priorities are are integer values between 0 and 100 inclusive with 50 being a normal priority. The MPR maps these priorities in a linear fashion onto native O/S priorites. Useful constants are:
  • MPR_LOW_PRIORITY
  • MPR_NORMAL_PRIORITY
  • MPR_HIGH_PRIORITY
.
stackSizeStack size to use for the thread. On VM based systems, increasing this value, does not necessarily incurr a real memory (working-set) increase. Set to zero for a default stack size.
Returns:
A MprThread object.
See Also:
MprThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadName, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
MprOsThread mprGetCurrentOsThread ()

Get the O/S thread.

Description:
Get the O/S thread ID for the currently executing thread.
Returns:
Returns a platform specific O/S thread ID. On Unix, this is a pthread reference. On other systems it is a thread integer value.
See Also:
MprThread, mprCreateThread, mprGetCurrentThread, mprGetThreadName, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
MprThread * mprGetCurrentThread (MprCtx ctx)

Get the currently executing thread.

Description:
Get the thread object for the currently executing O/S thread.
Parameters:
ctxAny memory context allocated by the MPR.
Returns:
Returns a thread object representing the current O/S thread.
See Also:
MprThread, mprCreateThread, mprGetCurrentOsThread, mprGetThreadName, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
cchar * mprGetThreadName (MprThread *thread)

Get the thread name.

Description:
MPR threads are usually real O/S threads and can be used with the various locking services (MprMutex, MprCond, MprSpin) to enable scalable multithreaded applications.
Parameters:
threadThread object returned from mprCreateThread.
Returns:
Returns a string name for the thread. Caller must not free.
See Also:
MprThread, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
int mprGetThreadPriority (MprThread *thread)

Get the thread priroity.

Description:
Get the current priority for the specified thread.
Parameters:
threadThread object returned by mprCreateThread.
Returns:
An integer MPR thread priority between 0 and 100 inclusive.
See Also:
MprThread, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadName, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
void mprSetCurrentThreadPriority (MprCtx ctx, int priority)

Set the thread priroity for the current thread.

Parameters:
ctxAny memory context allocated by the MPR.
Description:
Set the current priority for the specified thread.
Parameters:
priorityPriority to associate with the thread. Mpr thread priorities are are integer values between 0 and 100 inclusive with 50 being a normal priority. The MPR maps these priorities in a linear fashion onto native O/S priorites. Useful constants are:
  • MPR_LOW_PRIORITY
  • MPR_NORMAL_PRIORITY
  • MPR_HIGH_PRIORITY
.
See Also:
MprThread, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadName, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority, mprStartThread
void mprSetThreadPriority (MprThread *thread, int priority)

Set the thread priroity.

Description:
Set the current priority for the specified thread.
Parameters:
threadThread object returned by mprCreateThread.
priorityPriority to associate with the thread. Mpr thread priorities are are integer values between 0 and 100 inclusive with 50 being a normal priority. The MPR maps these priorities in a linear fashion onto native O/S priorites. Useful constants are:
  • MPR_LOW_PRIORITY
  • MPR_NORMAL_PRIORITY
  • MPR_HIGH_PRIORITY
.
See Also:
MprThread, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadName, mprGetThreadPriority, mprStartThread
int mprStartThread (MprThread *thread)

Start a thread.

Description:
Start a thread previously created via mprCreateThread. The thread will begin at the entry function defined in mprCreateThread.
Parameters:
threadThread object returned from mprCreateThread.
Returns:
Returns zero if successful, otherwise a negative MPR error code.
See Also:
MprThread, mprCreateThread, mprGetCurrentOsThread, mprGetCurrentThread, mprGetThreadName, mprGetThreadPriority, mprSetThreadPriority, mprSetThreadPriority

MprUri

MprUri

URI management.

Description:
The MPR provides routines for formatting and parsing URIs. Routines are also provided to escape dangerous characters for URIs as well as HTML content and shell commands.
API Stability:
Evolving.
See Also:
mprEscapeCmd, mprEscapeHtml, mprFormatUri, mprUrlDecode, mprUrlEncode, mprValidateUrl
Fields:
char *ext Document extension.
char *host Url host name.
char *originalUri Original URI.
char *parsedUriBuf Allocated storage for parsed uri.
intport Port number.
char *query Query string.
char *scheme URI scheme (http|https|. ).
boolsecure Using https.
char *url Url path name (without scheme, host, query or fragements).
char * mprEscapeCmd (MprCtx ctx, cchar *cmd, int escChar)

Encode a string escaping typical command (shell) characters.

Description:
Encode a string escaping all dangerous characters that have meaning for the unix or MS-DOS command shells.
Parameters:
ctxAny memory allocation context created by MprAlloc.
cmdCommand string to encode.
escCharEscape character to use when encoding the command.
Returns:
An allocated string containing the escaped command. Caller must free using mprFree.
See Also:
mprEscapeHtml, mprFormatUri, mprUrlDecode, mprUrlEncode, mprValidateUrl
char * mprEscapeHtml (MprCtx ctx, cchar *html)

Encode a string by escaping typical HTML characters.

Description:
Encode a string escaping all dangerous characters that have meaning in HTML documents.
Parameters:
ctxAny memory allocation context created by MprAlloc.
htmlHTML content to encode.
Returns:
An allocated string containing the escaped HTML. Caller must free using mprFree.
See Also:
mprEscapeCmd, mprFormatUri, mprUrlDecode, mprUrlEncode, mprValidateUrl
char * mprFormatUri (MprCtx ctx, cchar *protocol, cchar *host, int port, cchar *path, cchar *query)

Format a URI.

Description:
Format a URI string using the input components.
Parameters:
ctxAny memory allocation context created by MprAlloc.
protocolProtocol string for the uri. Example: "http".
hostHost or IP address.
portTCP/IP port number.
pathURL path.
queryAdditiona query parameters.
Returns:
A newly allocated uri string. Caller must free using mprFree.
See Also:
mprEscapeCmd, mprEscapeHtml, mprUrlDecode, mprUrlEncode, mprValidateUrl
MprUri * mprParseUri (MprCtx ctx, cchar *uri)

Parse a URI.

Description:
Parse a uri and return a tokenized MprUri structure.
Parameters:
ctxAny memory allocation context created by MprAlloc.
uriUri string to parse.
Returns:
A newly allocated MprUri structure. Caller must free using mprFree.
See Also:
mprEscapeCmd, mprEscapeHtml, mprFormatUri, mprUrlDecode, mprUrlEncode, mprValidateUrl
char * mprUrlDecode (MprCtx ctx, cchar *url)

Decode a URL string by de-scaping URL characters.

Description:
Decode a string with www-encoded characters that have meaning for URLs.
Parameters:
ctxAny memory allocation context created by MprAlloc.
urlURL to decode.
Returns:
A reference to the buf argument.
See Also:
mprEscapeCmd, mprEscapeHtml, mprFormatUri, mprUrlEncode, mprValidateUrl
char * mprUrlEncode (MprCtx ctx, cchar *url)

Encode a string by escaping URL characters.

Description:
Encode a string escaping all characters that have meaning for URLs.
Parameters:
ctxAny memory allocation context created by MprAlloc.
urlURL to encode.
Returns:
An allocated string containing the encoded URL. Caller must free using mprFree.
See Also:
mprEscapeCmd, mprEscapeHtml, mprFormatUri, mprUrlDecode, mprValidateUrl
char * mprValidateUrl (MprCtx ctx, char *url)

Validate a URL.

Description:
Validate and canonicalize a URL. This removes redundant "./" sequences and simplifies "../dir" references. This operates in-situ and modifies the existing string.
Parameters:
ctxAny memory allocation context created by MprAlloc.
urlUrl string to validate.
Returns:
A validated url.
See Also:
mprEscapeCmd, mprEscapeHtml, mprFormatUri, mprUrlDecode, mprUrlEncode

MprWaitHandler

MprWaitHandler

Wait Handler Service.

Description:
Wait handlers provide callbacks for when I/O events occur. They provide a wait to service many I/O file descriptors without requiring a thread per descriptor.
See Also:
MprEvent, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitInterest, mprWaitForSingleIO
Fields:
intdesiredMask Mask of desired events.
intdisableMask Mask of disabled events.
intfd O/S File descriptor (sp->sock).
intflags Control flags.
void *handlerData Argument to pass to proc.
struct MprWaitHandler *next List linkage.
intpresentMask Mask of current events.
intpriority Thread priority.
MprWaitProcproc Wait handler procedure.
struct MprEvent *threadEvent Event reference.
MprWaitService *waitService Wait service pointer.
MprWaitHandler * mprCreateWaitHandler (MprCtx ctx, int fd, int mask, MprWaitProc proc, void *data, int priority, int flags)

Create a wait handler.

Description:
Create a wait handler that will be invoked when I/O of interest occurs on the specified file handle The wait handler is registered with the MPR event I/O mechanism.
Parameters:
ctxAny memory allocation context created by MprAlloc.
fdFile descriptor.
maskMask of events of interest. This is made by oring MPR_READABLE and MPR_WRITEABLE.
procCallback function to invoke when an I/O event of interest has occurred.
dataData item to pass to the callback.
priorityMPR priority to associate with the callback. This is only used if the MPR_WAIT_THREAD is specified in the flags and the MPR is build multithreaded.
flagsFlags may be set to MPR_WAIT_THREAD if the callback function should be invoked using a thread from the thread pool.
Returns:
A new wait handler registered with the MPR event mechanism.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitInterest, mprWaitForSingleIO
void mprDisableWaitEvents (MprWaitHandler *wp, bool wakeup)

Disable wait events.

Description:
Disable wait events for a given file descriptor.
Parameters:
wpWait handler created vai mprCreateWaitHandler.
wakeupSet to true if it should wakeup the MPR service thread.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitInterest, mprWaitForSingleIO
void mprEnableWaitEvents (MprWaitHandler *wp, bool wakeup)

Enable wait events.

Description:
Enable wait events for a given file descriptor.
Parameters:
wpWait handler created vai mprCreateWaitHandler.
wakeupSet to true if it should wakeup the MPR service thread. This should normally be set to true.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitInterest, mprWaitForSingleIO
void mprRecallWaitHandler (MprWaitHandler *wp)

Recall a wait handler.

Description:
Signal that a wait handler should be recalled a the earliest opportunity. This is useful when a protocol stack has buffered data that must be processed regardless of whether more I/O occurs.
Parameters:
wpWait handler created vai mprCreateWaitHandler.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprServiceEvents, mprSetWaitCallback, mprSetWaitInterest, mprWaitForSingleIO
void mprSetWaitCallback (MprWaitHandler *wp, MprWaitProc proc, int mask)

Define the wait handler callback.

Description:
This updates the callback function for the wait handler. Callback functions are originally specified via mprCreateWaitHandler.
Parameters:
wpWait handler created vai mprCreateWaitHandler.
procCallback function to invoke when an I/O event of interest has occurred.
maskMask of MPR_READABLE and MPR_WRITEABLE.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitInterest, mprWaitForSingleIO
void mprSetWaitInterest (MprWaitHandler *wp, int mask)

Define the events of interest for a wait handler.

Description:
Define the events of interest for a wait handler. The mask describes whether readable or writable events should be signalled to the wait handler. Disconnection events are passed via read events.
Parameters:
wpWait handler created vai mprCreateWaitHandler.
maskMask of MPR_READABLE and MPR_WRITEABLE.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprWaitForSingleIO
int mprWaitForSingleIO (MprWaitHandler *wp, int fd, int mask, int timeout)

Wait for I/O on an event handler.

Description:
This call will block for a given timeout until I/O of interest occurs on the given serviced. Flags may modify the calls behavior.
Parameters:
wpWait handler created vai mprCreateWaitHandler.
fdFile descriptor to wait on.
maskMask of MPR_READABLE and MPR_WRITEABLE.
timeoutTime in milliseconds to block.
Returns:
Zero on success, otherwise a negative MPR error code.
See Also:
MprEvent, MprWaitHandler, mprCreateEvent, mprDisableWaitEvents, mprEnableWaitEvents, mprRecallWaitHandler, mprServiceEvents, mprSetWaitCallback, mprSetWaitInterest

Functions

char * mprAsprintf (MprCtx ctx, int maxSize, cchar *fmt, ...)

Format a string into an allocated buffer.

Description:
This call will dynamically allocate a buffer up to the specified maximum size and will format the supplied arguments into the buffer. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.
Parameters:
ctxAny memory context allocated by the MPR.
maxSizeMaximum size to allocate for the buffer including the trailing null.
fmtPrintf style format string.
Returns:
The number of characters in the string.
int mprAtoi (cchar *str, int radix)

Convert a string to an integer.

Description:
This call converts the supplied string to an integer using the specified radix (base).
Parameters:
strPointer to the string to parse.
radixBase to use when parsing the string.
Returns:
The integer equivalent value of the string.
int mprFprintf (struct MprFile *file, cchar *fmt, ...)

Print a formatted message to a file descriptor.

Description:
This is a replacement for fprintf as part of the safe string MPR library. It minimizes memory use and uses a file descriptor instead of a File pointer.
Parameters:
fileMprFile object returned via mprOpen.
fmtPrintf style format string.
Returns:
The number of bytes written.
char * mprGetCurrentPath (MprCtx ctx)

Return the current working directory.

Parameters:
ctxAny memory context allocated by the MPR.
Returns:
Returns an allocated string with the current working directory as an absolute path.
cchar * mprGetHttpCodeString (MprCtx ctx, int code)

Get the Http reponse code as a string.

Description:
Get the Http response code as a string.
Parameters:
ctxAny memory allocation context created by MprAlloc.
codeHttp status code.
Returns:
A reference to the response code string. Callers must not free this reference.
char * mprGetWordTok (char *buf, int bufsize, cchar *str, cchar *delim, cchar **tok)

Get the next word token.

Description:
Split a string into word tokens using the supplied separator.
Parameters:
bufBuffer to use to hold the word token.
bufsizeSize of the buffer.
strInput string to tokenize. Note this cannot be a const string. It will be written.
delimString of separator characters to use when tokenizing.
tokPointer to a word to hold a pointer to the next token in the original string.
Returns:
The number of bytes in the allocated block.
char * mprItoa (char *buf, int size, int value, int radix)

Convert an integer to a string.

Description:
This call converts the supplied integer into a string formatted into the supplied buffer.
Parameters:
bufPointer to the buffer that will hold the string.
sizeSize of the buffer.
valueInteger value to convert.
radixThe base radix to use when encoding the number.
Returns:
The number of characters in the string.
int mprMemcmp (cvoid *b1, int b1Len, cvoid *b2, int b2Len)

Compare two byte strings.

Description:
Safely compare two byte strings. This is a safe replacement for memcmp.
Parameters:
b1Pointer to the first byte string.
b1LenLength of the first byte string.
b2Pointer to the second byte string.
b2LenLength of the second byte string.
Returns:
Returns zero if the byte strings are identical. Otherwise returns -1 if the first string is less than the second. Returns 1 if the first is greater than the first.
int mprMemcpy (void *dest, int destMax, cvoid *src, int nbytes)

Safe copy for a block of data.

Description:
Safely copy a block of data into an existing memory block. The call ensures the destination block is not overflowed and returns the size of the block actually copied. This is similar to memcpy, but is a safer alternative.
Parameters:
destPointer to the destination block.
destMaxMaximum size of the destination block.
srcBlock to copy.
nbytesSize of the source block.
Returns:
The number of characters in the allocated block.
int mprPrintf (MprCtx ctx, cchar *fmt, ...)

Formatted print.

This is a secure verion of printf that can handle null args
Description:
This is a secure replacement for printf. It can handle null arguments without crashes. minimal footprint. The MPR can be build without using any printf routines.
Parameters:
ctxAny memory context allocated by the MPR.
fmtPrintf style format string.
Returns:
The number of bytes written.
int mprPrintfError (MprCtx ctx, cchar *fmt, ...)

Print a formatted message to the standard error channel.

Description:
This is a secure replacement for fprintf(stderr.
Parameters:
ctxAny memory context allocated by the MPR.
fmtPrintf style format string.
Returns:
The number of bytes written.
char * mprReallocStrcat (MprCtx ctx, int max, char *buf, cchar *src, ...)

Append strings to an existing string and reallocate as required.

Description:
Append a list of strings to an existing string. The list of strings is terminated by a null argument. The call returns the size of the allocated block.
Parameters:
ctxAny memory context allocated by the MPR.
maxMaximum size of the result string.
bufExisting string to reallocate. May be null.
srcVariable list of strings to append. The final string argument must be null.
Returns:
An allocated result string. Caller must free.
int mprRfctime (MprCtx ctx, char *buf, int bufsize, const struct tm *timep)

Format time according to RFC822.

Description:
Thread-safe formatting of time dates according to RFC822. For example: "Fri, 07 Jan 2003 12:12:21 GMT".
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
bufTime to format.
bufsizeSize of buf.
timepInput pointer to a tm structure holding the time to format.
Returns:
Returns zero on success. Returns MPR_ERR_WONT_FIT if the bufsize is too small.
void mprSetDebugMode (MprCtx ctx, bool on)

Turn on debug mode.

Description:
Debug mode disables timeouts and timers. This makes debugging much easier.
Parameters:
ctxAny memory context allocated by the MPR.
onSet to true to enable debugging mode.
API Stability:
Evolving.
char * mprSprintf (char *buf, int maxSize, cchar *fmt, ...)

Format a string into a statically allocated buffer.

Description:
This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.
Parameters:
bufPointer to the buffer.
maxSizeSize of the buffer.
fmtPrintf style format string.
Returns:
The buffer.
int mprStaticPrintf (MprCtx ctx, cchar *fmt, ...)

Print a message to the applications standard output without allocating memory.

Description:
This is a secure replacement for printf that will not allocate memory.
Parameters:
ctxAny memory context allocated by the MPR. This is used to locate the standard output channel and not to allocate memory.
fmtPrintf style format string.
Returns:
The number of bytes written.
Remarks:
The maximum output is MPR_MAX_STRING - 1.
int mprStaticPrintfError (MprCtx ctx, cchar *fmt, ...)

Print a message to the standard error channel without allocating memory.

Description:
This is a secure replacement for fprintf(stderr that will not allocate memory.
Parameters:
ctxAny memory context allocated by the MPR. This is used to locate the standard output channel and not to allocate memory.
fmtPrintf style format string.
Returns:
The number of bytes written.
Remarks:
The maximum output is MPR_MAX_STRING - 1.
char * mprStrcat (MprCtx ctx, int max, cchar *src, ...)

Catenate strings.

Description:
Safe replacement for strcat. Catenates a string onto an existing string. This call accepts a variable list of strings to append. The list of strings is terminated by a null argument. The call returns the length of the resulting string. This call is similar to strcat, but it will enforce a maximum size for the resulting string and will ensure it is terminated with a null.
Parameters:
ctxAny memory context allocated by mprAlloc or mprCreate.
maxMaximum size of the new block.
srcVariable list of strings to append. The final string argument must be null.
Returns:
Returns an allocated string.
int mprStrcmp (cchar *str1, cchar *str2)

Compare strings.

Description:
Compare two strings. This is a safe replacement for strcmp. It can handle null args.
Parameters:
str1First string to compare.
str2Second 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.
int mprStrcmpAnyCase (cchar *str1, cchar *str2)

Compare strings ignoring case.

Description:
Compare two strings ignoring case differences. This call operates similarly to strcmp.
Parameters:
str1First string to compare.
str2Second string to compare.
Returns:
Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.
int mprStrcmpAnyCaseCount (cchar *str1, cchar *str2, int len)

Compare strings ignoring case.

Description:
Compare two strings ignoring case differences for a given string length. This call operates similarly to strncmp.
Parameters:
str1First string to compare.
str2Second string to compare.
lenLength of characters to compare.
Returns:
Returns zero if the strings are equivalent, < 0 if s1 sorts lower than s2 in the collating sequence or > 0 if it sorts higher.
int mprStrcpy (char *dest, int destMax, cchar *src)

Copy a string.

Description:
Safe replacement for strcpy. Copy a string and ensure the target string is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is terminated with a null.
Parameters:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string.
srcString to copy.
Returns:
The number of characters in the target string.
int mprStrcpyCount (char *dest, int destMax, cchar *src, int count)

Copy characters from a string.

Description:
Safe replacement for strncpy. Copy bytes from a string and ensure the target string is not overflowed. The call returns the length of the resultant string or an error code if it will not fit into the target string. This is similar to strcpy, but it will enforce a maximum size for the copied string and will ensure it is terminated with a null.
Parameters:
destPointer to a pointer that will hold the address of the allocated block.
destMaxMaximum size of the target string.
srcString to copy.
countMaximum count of characters to copy.
Returns:
The number of characters in the target string.
int mprStrlen (cchar *src, int max)

Return the length of a string.

Description:
Safe replacement for strlen. This call returns the length of a string and tests if the length is less than a given maximum.
Parameters:
srcString to measure.
maxMaximum length for the string.
Returns:
The length of the string or MPR_ERR_WONT_FIT if the length is greater than max.
char * mprStrLower (char *str)

Convert a string to lower case.

Description:
Convert a string to its lower case equivalent.
Parameters:
strString to convert.
Returns:
Returns a pointer to the converted string. Will always equal str.
char * mprStrnstr (cchar *str, cchar *pattern, int len)

Find a substring.

Description:
Locate the first occurrence of pattern in a string, but do not search more than the given length.
Parameters:
strPointer to the string to search.
patternString pattern to search for.
lenCount of characters in the pattern to actually search for.
Returns:
The number of characters in the target string.
char * mprStrTok (char *str, cchar *delim, char **last)

Tokenize a string.

Description:
Split a string into tokens.
Parameters:
strString to tokenize.
delimString of characters to use as token separators.
lastLast token pointer.
Returns:
Returns a pointer to the next token.
char * mprStrTrim (char *str, cchar *set)

Trim a string.

Description:
Trim leading and trailing characters off a string.
Parameters:
strString to trim.
setString of characters to remove.
Returns:
Returns a pointer to the trimmed string. May not equal str. If str was dynamically allocated, do not call mprFree on the returned trimmed pointer. You must use str when calling mprFree.
char * mprStrUpper (char *str)

Convert a string to upper case.

Description:
Convert a string to its upper case equivalent.
Parameters:
strString to convert.
Returns:
Returns a pointer to the converted string. Will always equal str.
char * mprVasprintf (MprCtx ctx, int maxSize, cchar *fmt, va_list arg)

Allocate a buffer of sufficient length to hold the formatted string.

Description:
This call will dynamically allocate a buffer up to the specified maximum size and will format the supplied arguments into the buffer. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.
Parameters:
ctxAny memory context allocated by the MPR.
maxSizeMaximum size to allocate for the buffer including the trailing null.
fmtPrintf style format string.
argVarargs argument obtained from va_start.
Returns:
The number of characters in the string.
char * mprVsprintf (char *buf, int maxSize, cchar *fmt, va_list args)

Format a string into a statically allocated buffer.

Description:
This call format a string using printf style formatting arguments. A trailing null will always be appended. The call returns the size of the allocated string excluding the null.
Parameters:
bufPointer to the buffer.
maxSizeSize of the buffer.
fmtPrintf style format string.
argsVarargs argument obtained from va_start.
Returns:
The buffer;.

Typedefs

typedef int(* MprModuleProc)(struct MprModule *mp).

Module start/stop point function signature.

Parameters:
mpModule object reference returned from mprCreateModule.
Returns:
Zero if successful, otherwise return a negative MPR error code.
typedef void(* MprSocketAcceptProc)(void *data, struct MprSocket *sp, cchar *ip, int port).

Socket connection acceptance callback procedure.

typedef void(* MprSocketProc)(void *data, struct MprSocket *sp, int mask, bool isPoolThread).

Socket I/O callback procedure.

typedef int(* MprBufProc)(struct MprBuf *bp, void *arg).

Buffer refill callback function.

Description:
Function to call when the buffer is depleted and needs more data.
Parameters:
bufInstance of an MprBuf.
argData argument supplied to mprSetBufRefillProc.
Returns:
The callback should return 0 if successful, otherwise a negative error code.
See Also:
MprBuf, mprAdjustBufEnd, mprAdjustBufStart, mprCreateBuf, mprFlushBuf, mprFree, mprGetBlockFromBuf, mprGetBufEnd, mprGetBufLength, mprGetBufOrigin, mprGetBufRefillProc, mprGetBufSize, mprGetBufSpace, mprGetCharFromBuf, mprGrowBuf, mprInsertCharToBuf, mprLookAtLastCharInBuf, mprLookAtNextCharInBuf, mprPutBlockToBuf, mprPutCharToBuf, mprPutFmtToBuf, mprPutIntToBuf, mprPutStringToBuf, mprRefillBuf, mprResetBufIfEmpty, mprSetBufMax, mprSetBufRefillProc, mprSetBufSize, mprStealBuf
typedef int64 MprTime.

Mpr time structure.

Description:
MprTime is the cross platform time abstraction structure. Time is stored as milliseconds since the epoch: 00:00:00 UTC Jan 1 1970. MprTime is typically a 64 bit quantity.
See Also:
mprAsctime, mprCtime, mprGetTime, mprLocaltime
typedef void(* MprEventProc)(void *data, struct MprEvent *event).

Event callback function.

See Also:
MprEvent, mprCreateEvent, mprCreateTimerEvent, mprRescheduleEvent, mprRestartContinuousEvent, mprStopContinuousEvent
typedef int(* MprListCompareProc)(cvoid *arg1, cvoid *arg2).

List comparison procedure for sorting.

Description:
Callback function signature used by mprSortList.
Parameters:
arg1First list item to compare.
arg2Second list item to compare.
Returns:
Return zero if the items are equal. Return -1 if the first arg is less than the second. Otherwise return 1.
See Also:
MprList, mprAddItem, mprAppendList, mprClearList, mprCreateKeyPair, mprCreateList, mprDupList, mprFree, mprFree, mprGetFirstItem, mprGetItem, mprGetListCapacity, mprGetListCount, mprGetNextItem, mprGetPrevItem, mprLookupItem, mprRemoveItem, mprRemoveRangeOfItems, mprSortList
typedef void(* MprLogHandler)(MprCtx ctx, int flags, int level, cchar *msg).

Log handler callback type.

Description:
Callback prototype for the log handler. Used by mprSetLogHandler to define a message logging handler to process log and error messages.
Parameters:
fileSource filename. Derived by using __FILE__.
lineSource line number. Derived by using __LINE__.
flagsError flags.
levelMessage logging level. Levels are 0-9 with zero being the most verbose.
msgMessage being logged.
See Also:
mprError, mprFatalError, mprGetLogHandler, mprLog, mprMemoryError, mprRawLog, mprSetLogHandler, mprSetLogLevel, mprStaticAssert, mprStaticError, mprUserError
typedef void(* MprAllocNotifier)(MprCtx ctx, uint size, uint total, bool granted).

Memory allocation error callback.

Notifiers are called if mprSetNotifier has been called on a context and a memory allocation fails. All notifiers up the parent context chain are called in order
Parameters:
ctxAny memory context allocated by the MPR.
sizeSize of memory allocation request that failed.
totalTotal memory allocations so far.
grantedSet to true if the request was actually granted, but the application is now exceeding its redline memory limit.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
typedef void* MprCtx.

Memory context type.

Description:
Blocks of memory are allocated using a memory context as the parent. Any allocated memory block may serve as the memory context for subsequent memory allocations. Freeing a block via mprFree will release the allocated block and all child blocks.
See Also:
mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
typedef int(* MprDestructor)(MprCtx ctx).

Mpr memory block destructors prototype.

Parameters:
ctxAny memory context allocated by the MPR.
Returns:
Return zero if the memory was actually freed. Return non-zero to prevent the memory being freed.
See Also:
MprCtx, mprAlloc, mprAllocObjWithDestructor, mprAllocWithDestructor, mprAllocWithDestructorZeroed, mprAllocZeroed, mprCreate, mprFree, mprGetParent, mprMemcpy, mprMemdup, mprRealloc, mprResetAllocError, mprSetAllocLimits, mprStrndup
typedef MprModule*(* MprModuleEntry)(MprCtx ctx, cchar *path).

Loadable module entry point signature.

Description:
Loadable modules can have an entry point that is invoked automatically when a module is loaded.
Parameters:
ctxAny memory context allocated by the MPR.
pathActual path to the module.
Returns:
A new MprModule structure for the module. Return NULL if the module can't be initialized.
See Also:
MprModule, MprModuleProc, mprCreateModule, mprGetModuleSearchPath, mprLoadModule, mprLookupModule, mprSetModuleSearchPath, mprUnloadModule
MprBlk

Memory Allocation Block Header.

Fields:
MprCond

Condition variable for multi-thread synchronization.

Fields:
pthread_cond_tcv Unix pthreads condition variable.
MprMutex *mutex Thread synchronization mutex.
inttriggered Value of the condition.
MprDirEntry

Directory entry description.

Description:
The MprGetDirList will create a list of directory entries.
Fields:
boolisDir True if the file is a directory.
MprTimelastModified Time the file was last modified.
char *name Name of the file.
MprOffsetsize Size of the file.
MprFileSystem

File system service.

Description:
The MPR provides a file system abstraction to support non-disk based file access such as flash or other ROM based file systems. The MprFileSystem structure defines a virtual file system interface that will be invoked by the various MPR file routines.
Fields:
MprAccessFileProcaccessPath Virtual access file routine.
boolcaseSensitive Path comparisons are case sensitive.
MprCloseFileProccloseFile Virtual close file routine.
char *cygdrive Cygwin drive root.
MprDeleteFileProcdeletePath Virtual delete file routine.
MprGetPathInfoProcgetPathInfo Virtual get file information routine.
boolhasDriveSpecs Paths can have drive specifications.
MprMakeDirProcmakeDir Virtual make directory routine.
char *newline Newline for text files.
MprOpenFileProcopenFile Virtual open file routine.
char *portSeparators Portable path separators. Typically "/\\".
MprReadFileProcreadFile Virtual read file routine.
cchar *root Root file path.
MprSeekFileProcseekFile Virtual seek file routine.
char *separators Filename path separators. First separator is the preferred separator.
MprSetBufferedProcsetBuffered Virtual set buffered I/O routine.
struct MprFile *stdError Standard error file.
struct MprFile *stdInput Standard input file.
struct MprFile *stdOutput Standard output file.
MprWriteFileProcwriteFile Virtual write file routine.
MprHashTable

Hash table control structure.

Fields:
MprHash **buckets Hash collision bucket table.
intcount Number of symbols in the table.
inthashSize Size of the buckets array.
MprKeyValue

Key value pairs for use with MprList or MprHash.

Fields:
char *key Key string.
char *value Associated value for the key.
MprMutex

Multithreading lock control structure.

Description:
MprMutex is used for multithread locking in multithreaded applications.
Fields:
CRITICAL_SECTIONcs Internal mutex critical section.
MprPath

Path information structure.

Description:
MprPath is the cross platform Path information structure.
Fields:
MprTimeatime Access time.
boolcaseMatters Case comparisons matter.
MprTimectime Create time.
uintinode Inode number.
boolisDir Set if directory.
boolisReg Set if a regular file.
MprTimemtime Modified time.
intperms Permission mask.
int64size File length.
intvalid Valid data bit.
MprSpin

Multithreading spin lock control structure.

Description:
MprSpin is used for multithread locking in multithreaded applications.
Fields:
CRITICAL_SECTIONcs Internal mutex critical section.
MprString

Safe String Module.

Description:
The MPR provides a suite of safe string manipulation routines to help prevent buffer overflows and other potential security traps.
Fields:
See Also:
mprAsprintf, mprAtoi, mprItoa, mprMemcpy, mprPrintf, mprPrintfError, mprReallocStrcat, mprReallocStrcat, mprSprintf, mprStaticPrintf, mprStrLower, mprStrTok, mprStrTrim, mprStrUpper, mprStrcat, mprStrcmpAnyCase, mprStrcmpAnyCaseCount, mprStrcpy, mprStrlen, mprVasprintf, mprVsprintf
MprThreadLocal

Thread local data storage.

Fields:
pthread_key_tkey Data key.